Merge branch 'main' into fix-new-emitters

.amlignore

@@ -0,0 +1,11 @@
+docs/
+test/
+.git/
+.github/
+.vscode/
+*.md
+LICENSE
+Manifest.toml
+.gitignore
+src/Cloud/amlconf
+outputs/

.github/workflows/DocPreviewCleanup.yml

@@ -0,0 +1,28 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+
+      - name: Delete preview and history
+        run: |
+            git config user.name "Documenter.jl"
+            git config user.email "[email protected]"
+            git rm -rf "previews/PR$PRNUM"
+            git commit -m "delete preview"
+            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+        env:
+            PRNUM: ${{ github.event.number }}
+
+      - name: Push changes
+        run: |
+            git push --force origin gh-pages-new:gh-pages

.github/workflows/Documentation.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: 1.5
+          version: 1.6
       - name: Install dependencies
         run: |
           xvfb-run julia --project=docs/ -e '

.gitignore

@@ -50,3 +50,6 @@ docs/site/
 # committed for packages, but should be committed for applications that require a static
 # environment.
 Manifest.toml
+
+# Cloud config file
+src/Cloud/amlconf

Project.toml

@@ -2,17 +2,20 @@ name = "OpticSim"
 uuid = "24114763-4efb-45e7-af0e-cde916beb153"
 authors = ["Brian Guenter", "Charlie Hewitt", "Ran Gal", "Alfred Wong"]
 repository = "https://github.com/microsoft/OpticSim.jl"
-version = "0.4.0"
+version = "0.4.1"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
+Conda = "8f4d0f93-b110-5947-807f-2305c1781a2d"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+Format = "1fa38f19-a742-5d3f-a2b9-30dd87b9d5f8"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
+GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 ImageView = "86fae568-95e7-573e-a6b2-d8a6b900c9ef"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
@@ -29,12 +32,17 @@ Optim = "429524aa-4258-5aef-a3af-852621145aeb"
 PackageCompiler = "9b87118b-4619-50d2-8e1e-99f35a4d4d9d"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
+PlutoUI = "7f904dfe-b85e-4ff6-b463-dae2292396a8"
 Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
+PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
 SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 StringEncodings = "69024149-9ee7-55f6-a4c4-859efe599b68"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"
 ZipFile = "a5390f91-8eb1-5f08-bee0-b1d1ffed6cea"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
@@ -45,7 +53,7 @@ ColorTypes = "0.10"
 Colors = "0.12"
 DataFrames = "0.22"
 Distributions = "0.24"
-FileIO = "1.6"
+FileIO = "1.4"
 ForwardDiff = "0.10"
 HTTP = "0.8, 0.9"
 ImageView = "0.10"
@@ -59,6 +67,8 @@ NLopt = "0.6"
 Optim = "1.2"
 PackageCompiler = "1.2"
 Plots = "1.10"
+Pluto = "0.12"
+PlutoUI = "0.7"
 Polynomials = "2.0"
 ReverseDiff = "1.7"
 StaticArrays = "1.0"

deps/build.jl

@@ -25,7 +25,7 @@ const GLASSCAT_DIR = joinpath(@__DIR__, "..", "src", "GlassCat") # contains Glas
 const JL_DIR = joinpath(GLASSCAT_DIR, "data") # contains AGFGlasscat.jl, SCHOTT.jl, etc.
 
 const SOURCES_PATH = joinpath(@__DIR__, "sources.txt")
-const AGFGLASSCAT_PATH = joinpath(JL_DIR, "AGFGlassCat.jl")
+const AGFGLASSCAT_NAME = "AGFGlassCat.jl"
 
 include(joinpath(GLASSCAT_DIR, "GlassTypes.jl"))
 include("sources.jl")
@@ -40,6 +40,5 @@ verify_sources!(sources, AGF_DIR)
 verified_source_names = [source[1] for source in sources]
 
 # Use verified sources to generate required .jl files
-@info "$(isfile(AGFGLASSCAT_PATH) ? "Re-g" : "G")enerating $AGFGLASSCAT_PATH"
 @info "Using sources: $(join(verified_source_names, ", ", " and "))"
-generate_jls(verified_source_names, AGFGLASSCAT_PATH, JL_DIR, AGF_DIR)
+generate_jls(verified_source_names, AGFGLASSCAT_NAME, JL_DIR, AGF_DIR)

deps/generate.jl

@@ -46,8 +46,8 @@ function generate_jls(
 
         # parse the catalog into a module string and write it to a catalog file (.jl)
         id, modstring = catalog_to_modstring(id, catalogname, catalog)
-        push!(catalogfiles, joinpath(jldir, "$(catalogname).jl"))
-        open(catalogfiles[end], "w") do io
+        push!(catalogfiles, "$(catalogname).jl")
+        open(joinpath(jldir, catalogfiles[end]), "w") do io
             write(io, modstring)
         end
 
@@ -59,13 +59,13 @@ function generate_jls(
     agfstrings = [
         "export $(join(sourcenames, ", "))",
         "",
-        ["include(raw\"$(catalogfile)\")" for catalogfile in catalogfiles]...,
+        ["include(\"$(catalogfile)\")" for catalogfile in catalogfiles]...,
         "",
         "const AGF_GLASS_NAMES = [$(join(repr.(glassnames), ", "))]",
         "const AGF_GLASSES = [$(join(glassnames, ", "))]",
         ""
     ]
-    open(mainfile, "w") do io
+    open(joinpath(jldir, mainfile), "w") do io
         write(io, join(agfstrings, "\n"))
     end
 end

docs/make.jl

@@ -32,8 +32,7 @@ makedocs(
     modules = [OpticSim],
     pages = [
         "Home" => "index.md",
-        "Examples" => "examples.md",      
-        # "Glasses" => cat_pages,
+        "Examples" => "examples.md",
         "Geometry" => [
             "Basic Types" => "basic_types.md",
             "Primitives" => "primitives.md",
@@ -42,12 +41,14 @@ makedocs(
         "Optical" => [
             "Systems" => "systems.md",
             "Emitters" => "emitters.md",
+            "Emitters (NEW)" => "emitters_new.md",
             "Interfaces" => "interfaces.md",
             "Lenses" => "lenses.md"
         ],
         "Visualization" => "vis.md",
         "Glass Functions" => "glasscat.md",
         "Optimization" => "optimization.md",
+        "Cloud Execution" => "cloud.md",
         "Reference" => "ref.md",
         "Roadmap" => "roadmap.md"
     ],
@@ -56,12 +57,12 @@ makedocs(
 deploydocs(
     repo = "github.com/microsoft/OpticSim.jl.git",
     devbranch = "main",
+    push_preview = true,
 )
 
 # function children(m::Module)
 #     ns = names(m, imported = false, all = true)
 #     ms = []
-
 #     for n in ns
 #         try
 #             x = Core.eval(m, n)

docs/src/cloud.md

@@ -0,0 +1,54 @@
+# Cloud Execution
+
+## Azure
+
+A key benefit and design motivation of OpticSim is being able to execute many simulations/optimizations at once.
+This is best enabled through the use of cloud computing services such as Azure.
+
+As part of the base package, we provide support for cloud execution using an [Azure Machine Learning](https://azure.microsoft.com/en-gb/free/machine-learning) workspace.
+
+To use this functionally you'll first need to set up an AML workspace with a compute cluster. Then you'll need to provide a few bits of information to OpticSim:
+
+- Subscription ID, of the form `XXXXXXXX-XXX-XXX-XXXX-XXXXXXXXXXXX`
+- Resource group name
+- Workspace name
+- Compute cluster name
+
+This information can be cached either to a specific file, or globally:
+
+```@docs
+OpticSim.Cloud.cache_run_config
+OpticSim.Cloud.get_cached_run_config
+```
+
+You should also include an `.amlignore` file in the root of your project.
+This is similar to a `.gitignore` file and should include any files which should not be uploaded to AML as part of your source snapshot, for examples `test/`.
+
+!!! note
+    **`Manifest.toml` must be listed in your `.amlignore` file.**
+
+If an `.amlignore` doesn't already exist then one will be created on the first submission of a run to AML.
+
+Once everything is configured, you can submit a run:
+
+```@docs
+OpticSim.Cloud.submit_run_to_AML
+```
+
+To retrieve outputs from your run simply write files to the `outputs/` directory and the files will automatically appear as part of the AML run.
+
+### Examples
+
+```julia
+using OpticSim.Cloud
+
+cache_run_config([subscription_id], [resource_group_name], [workspace_name], [compute_name], [path_to_config])
+
+submit_run_to_AML("example-run", [path_to_script], ["--arg1", "1", "--arg2", "2"], nothing, [path_to_config])
+
+submit_run_to_AML("example-hyperdrive-run", [path_to_script], ["--arg1", "1"], Dict("--arg2" => ["1", "2", "3"]), [path_to_config])
+```
+
+## Other Cloud Services
+
+Currently no other services are supported, though it should be reasonably straightforward to add similar functionality to that for AML.

docs/src/examples.md

@@ -1,5 +1,18 @@
 # Examples
 
+## Pluto Notebooks
+
+The [`OpticSim`](index.html) package comes with several [`Pluto`](https://github.com/fonsp/Pluto.jl) notebooks (code snippets are coming soon) that allow the user to change and run sample code and view the results in real-time. We highly recommend for you to try these out.
+The notebooks are located in the **samples** folder, and you can try them by running:
+
+```julia
+import OpticSim.NotebooksUtils as NB    # the **as** option was added in Julia v1.6
+
+NB.run_sample("EmittersIntro.jl")
+```
+
+The **run_sample** method will **copy** the notebook to your current folder (if it does not exist) and launch Pluto to run the notebook in the browser.
+
 ## Cooke Triplet
 
 ```@example

docs/src/glasscat.md

@@ -68,7 +68,7 @@ OpticSim.GlassCat.modelglass
 
 ```@docs
 OpticSim.GlassCat.glasscatalogs
-OpticSim.GlassCat.glasses
+OpticSim.GlassCat.glassnames
 OpticSim.GlassCat.info
 OpticSim.GlassCat.findglass
 OpticSim.GlassCat.isair