Merge branch 'master' into parallel_environment_return_pids

Author: AreWeDreaming

.github/workflows/runtests.yml

@@ -155,9 +155,9 @@ jobs:
       # Run tests
       - uses: julia-actions/julia-runtest@v1
 
-      # Code coverage
-      - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v5
-        if: github.ref != 'refs/heads/master'
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+    #   # Code coverage
+    #   - uses: julia-actions/julia-processcoverage@v1
+    #   - uses: codecov/codecov-action@v5
+    #     if: github.ref != 'refs/heads/master'
+    #     with:
+    #       token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -72,6 +72,9 @@ LocalPreferences.toml
 julia-*.out
 examples/Untitled.ipynb
 tmp.gif
+*.pyc
+*.log
 
 # Generated knowledge base files
-knowledge/actors/
+knowledge/actors/
+knowledge/mcp_server/start_server.sh

Makefile

@@ -692,6 +692,42 @@ install_playground: .PHONY
 	if [ -d playground ] && [ ! -f playground/.gitattributes ]; then mv playground playground_private ; fi
 	if [ ! -d "playground" ]; then git clone https://github.com/ProjectTorreyPines/FusePlayground.git playground ; else cd playground && git pull origin `git rev-parse --abbrev-ref HEAD` ; fi
 
+# @devs
+knowledge: .PHONY
+# Extract FUSE actor knowledge base using Claude analysis
+	@echo "Extracting FUSE actor knowledge base..."
+	@cd knowledge && julia --threads=$(JULIA_NUM_THREADS) -e 'include("extract_knowledge.jl"); extract_fuse_knowledge_parallel()'
+	@echo "Knowledge extraction complete! Check knowledge/fuse_knowledge_base.json"
+
+# @devs
+knowledge_clean: .PHONY
+# Clean up orphaned actor files in knowledge base
+	@echo "Checking for orphaned actor files..."
+	@cd knowledge && julia -e 'include("extract_knowledge.jl"); clean_orphaned_fuse_actors()'
+
+# @dev
+learn_usage:
+# Learn FUSE usage from Jupyter notebooks and update knowledge/how_to_use_fuse.md
+	cd knowledge ; ./learn_fuse_usage.sh ../examples/tutorial.ipynb ../examples/tutorial_imas.ipynb ../examples/fluxmatcher.ipynb ../examples/study_TGLFdb.ipynb ../examples/time_dependent_d3d.ipynb ../examples/time_dependent_iter.ipynb ../examples/study_database_generator.ipynb ../examples/study_multi_objective_optimizer.ipynb
+
+# @devs
+learn_init:
+# Create comprehensive guide on how to initialize FUSE by analyzing case files and parameter structures
+	claude "Write a how_to_init_fuse.md knowledge file, structured for users and LLMs to learn how to define FUSE use cases. You should looking at each individual *.jl files under FUSE/src/cases (don't skip any, they are all important!). Also add a note about the parameters definitions being in FUSE/src/parameters/parameters_inits.jl and use this file to build your .md documentation as necessary."
+
+# @devs
+learn_actors_docstrings:
+# update actors docstrings
+	claude "Go through each and every actor file (***_actor.jl) and (in parallel) spawn a claude session to improve the docstring of each. \
+	Don't add any docstring to the \`@actor_parameters_struct\` or the Actor constructor. \
+	Instead you should focus on the \`ActorXXX(dd,act)\` function which in the end is what is going to appear in the online documentation. \
+	You can add some extra details to the docstrings of \`_step()\` and \`_finalize()\`. \
+	NEVER document boilerplate arguments, like \`dd\`, \`par\`, \`act\`, \`kw...\`. \
+	To know what an actor does, look at the executable code. \
+	If there's already a docstring, verify it against the executable code. \
+	If there's any conflicting information the executable code should take precendence. \
+	To know what actors need documentation, search for \`actor_parameters_struct\`, and process them in parallel claude sessions."
+
 # @devs
 list_open_compats:
 # List compat patches PR on GitHub

Project.toml

@@ -1,7 +1,7 @@
 name = "FUSE"
 uuid = "e64856f0-3bb8-4376-b4b7-c03396503992"
 authors = ["Orso Meneghini <[email protected]>"]
-version = "0.9.1"
+version = "0.9.2"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
@@ -67,14 +67,15 @@ TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 TroyonBetaNN = "c0158764-c6e1-428b-a545-31826f389bc8"
 TurbulentTransport = "9bf5e8f4-5746-4003-bc69-ef83265c10ca"
 VacuumFields = "9d9223b5-c5da-4bf4-abee-2a8bb6775a49"
-Weave = "44d3d7a6-8a23-5bf8-98c5-b353f8df5ec9"
 YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 [weakdeps]
 ThermalSystemModels = "68b8b4ac-b179-4f07-8ae9-c1f1360acbca"
+Weave = "44d3d7a6-8a23-5bf8-98c5-b353f8df5ec9"
 
 [extensions]
 ThermalSystemModelsExt = "ThermalSystemModels"
+WeaveExt = "Weave"
 
 [compat]
 AbstractTrees = "0.4"

README.md

@@ -12,6 +12,7 @@ The figure below is a sneakpeak of the models implemented in FUSE:
 
 Here are some key resources for getting started with FUSE:
 
+* 📨 **[Sign up for more info](https://forms.gle/iQGYKWfgeNkw2fCZ7)**
 * 📚 **[Online documentation](https://fuse.help)**
 * 🎓 **[Intro tutorial](https://fuse.help/dev/tutorial.html)**
 * 🎤 **[Recent presentation](https://github.com/ProjectTorreyPines/FUSE_extra_files/raw/master/2025_D3D/SET_mar_2025.pdf)**

docs/Project.toml

@@ -1,15 +1,41 @@
 [deps]
+ADAS = "f4a0d185-1024-41e7-8ef7-3196bb2f6549"
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+BalanceOfPlantSurrogate = "001e48cb-5a1e-4e3c-a5d4-cdc3aa14f3de"
+BoundaryPlasmaModels = "2da5b0d0-c5e5-4f14-9caf-62d0020df410"
+CHEASE = "40781a8e-f1bb-11ec-24ef-0f6bc40c1567"
+CoordinateConventions = "7204ce3a-f536-43d2-be4a-fbed74e90d86"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+EGGO = "25cd7528-e4e3-46fe-8df7-7ec8e1454e14"
+EPEDNN = "e64856f0-3bb8-4376-b4b7-c03396503991"
+FRESCO = "f2db6eb9-2c54-4c18-912b-ce467796777a"
 FUSE = "e64856f0-3bb8-4376-b4b7-c03396503992"
+FiniteElementHermite = "6ce10167-d368-4c0e-af34-9787cdd175e5"
+FuseExchangeProtocol = "43dcb517-7681-482a-b959-351932bd0b36"
+FusionMaterials = "4c86da02-02c8-4634-8460-96566129f8e0"
+GACODE = "bb074124-7a58-47ce-bd41-6b7098184f23"
+HelpPlots = "5880b2e8-ad0a-48c9-bacd-30dc9c1357e0"
 IMAS = "13ead8c1-b7d1-41bb-a6d0-5b8b65ed587a"
 IMASdd = "c5a45a97-b3f9-491c-b9a7-aa88c3bc0067"
 IMASutils = "b8e4ee59-9bed-3a6a-a553-8dd24d6374ad"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+MXHEquilibrium = "8efa4e5a-7b9a-4eec-876e-01d13d5b5d75"
+MillerExtendedHarmonic = "c82744c2-dc08-461a-8c37-87ab04d0f9b8"
+NNeutronics = "a9424c20-d414-11ec-167b-9106c24d956c"
+NeoclassicalTransport = "e630bb45-bea9-4e62-953e-b44d0741ac01"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
+QED = "8bcbec86-48c7-11ec-16a6-c1bc83299373"
+RABBIT = "98960a00-302f-469e-9595-275b70d10766"
 SimulationParameters = "32ab26d3-25d6-405d-a295-367385e16093"
+TEQUILA = "a60c9cbd-e72f-4185-96b6-b8fc312c4d37"
+TJLF = "12ecd31c-256b-4db5-a799-cd5afeb0bd7d"
+TORBEAM = "b9bf819a-2a49-451a-b482-4ce9066e62e1"
+ThermalSystemModels = "68b8b4ac-b179-4f07-8ae9-c1f1360acbca"
+TroyonBetaNN = "c0158764-c6e1-428b-a545-31826f389bc8"
+TurbulentTransport = "9bf5e8f4-5746-4003-bc69-ef83265c10ca"
+VacuumFields = "9d9223b5-c5da-4bf4-abee-2a8bb6775a49"

docs/src/cases_docs.jl

@@ -25,7 +25,7 @@ pushfirst!(
 CurrentModule = FUSE
 ```
 
-FUSE comes with a set of pre-cookes used cases.
+FUSE comes with a set of pre-cooked use cases.
 The `case_parameters(:use_case, ...)` method returns the `ini` and `act` parameters for that specific `use_case`.
 These `ini` and `act` can then be further customized before running a FUSE simulation.
 

docs/src/install.md

@@ -68,9 +68,9 @@ For installation start your Julia interpreter by typing `julia` at the terminal,
    !!! note
        The WebIO jupyter-lab extension is needed for the [`Interact.jl`](https://github.com/JuliaGizmos/Interact.jl?tab=readme-ov-file#usage) package to work.
 
-       Make sure WebIO is working with `jupyter labextension list`.
+       Make sure WebIO is working with `jupyter labextension list`. If it is working properly, you should see something like: webio-jupyterlab-provider v0.1.0 enabled OK (python, webio_jupyter_extension). This can also be checked with `jupyter nbextension list`, which should show something like: webio-jupyter-nbextension/nbextension  enabled.
 
-       If the extension has compatibility issues, consider installing an older verision of Jupyter (eg. `conda install jupyterlab=3.6.7`).
+       If the extension has compatibility issues, consider installing an older verision of Jupyter (eg. `conda install jupyterlab=3.6.7`). Also ensure that the WebIO and Interact packages are fully up-to-date, and restart the notebook session before testing that it works. Finally, it may be necessary to downgrade your system's version of Python - the recommended version for compatibility with Interact is 3.11.11. 
 
 1. Start a new Jupyter-lab session (this should open a web-browser page with Jupyter running)
 

docs/src/tutorial.jl

@@ -210,185 +210,18 @@ FUSE.digest(dd)
 
 @checkin :awf dd ini act
 
-# # Getting into the weeds
+# # Working with the IMAS data structure
 
-# ## Saving and loading data
-
-tutorial_temp_dir = tempdir()
-filename = joinpath(tutorial_temp_dir, "$(ini.general.casename).json")
-
-# When saving data to be shared outside of FUSE, one can set `freeze=true` so that all expressions in the dd are evaluated and saved to file.
-
-IMAS.imas2json(dd, filename; freeze=false, strict=false);
-
-# Load from JSON
-
-dd1 = IMAS.json2imas(filename);
-
-# ## Exploring the data dictionary
-# * FUSE stores data following the IMAS data schema.
-# * The root of the data structure is `dd`, which stands for "Data Dictionary".
-# * More details are available in the [documentation](https://fuse.help/stable/dd.html).
-
-# Display part of the equilibrium data in `dd`
-
-dd.equilibrium.time_slice[1].boundary
-
-# this can be done up to a certain depth with `print_tree`
-
-print_tree(dd.equilibrium.time_slice[1].boundary; maxdepth=1)
-
-# ## Plotting data from `dd`
-# FUSE uses `Plots.jl` recipes for visualizing data from `dd`.
-# 
-# This allows different plots to be shown when calling `plot()` on different items in the data structure.
+# See the IMAS tutorial https://github.com/ProjectTorreyPines/FuseExamples/blob/master/tutorial_imas.ipynb
 # 
-# Learn more about Plots.jl [here](https://docs.juliaplots.org)
-
-# For example plotting the equilibrium...
-
-plot(dd.equilibrium)
-
-# ...or the core profiles
-
-plot(dd.core_profiles)
-
-# Whant to know what arguments can be passed? use `help_plot()` function
-
-help_plot(dd.equilibrium; core_profiles_overlay=true, levels_in=21, levels_out=5, show_secondary_separatrix=true, coordinate=:rho_tor_norm)
-
-# These plots can be composed by calling `plot!()` instead of `plot()`
-
-plot(dd.equilibrium; color=:gray, cx=true)
-plot!(dd.build.layer)
-plot!(dd.pf_active)
-plot!(dd.pf_passive)
-plot!(dd.pulse_schedule.position_control; color=:red)
-
-# Plotting an array...
-
-plot(dd.core_profiles.profiles_1d[1].pressure_thermal)
-
-# ...is different from plotting a field from the IDS (which plots the quantity against its coordinate and with units)
-
-plot(dd.core_profiles.profiles_1d[1], :pressure_thermal)
-
-# Customizing plot attributes:
-
-plot(dd.core_profiles.profiles_1d[1], :pressure_thermal; label="", linewidth=2, color=:red, labelfontsize=25)
-
-# Use `findall(ids, r"...")` to search for certain fields. In Julia, string starting with `r` are regular expressions.
-
-findall(dd, r"\.psi")
-
-# `findall(ids, r"...")` can be combined with `plot()` to plot multiple fields
-
-plot(findall(dd, r"\.psi"))
-
-# ## Working with time series
-
-# The IMAS data structure supports time-dependent data, and IMAS.jl provides ways to handle time data efficiently.
-
-# Each `dd` has a `global_time` attribute, which is used throughout FUSE and IMAS to indicate the time at which things should be operate.
-
-dd.global_time
-
-# For the sake of demonstrating handling of time, let's add a new time_slice to the equilibrium.
-# 
-# **NOTE:** in addition to the usual `resize!(ids, n::Int)`, time dependent arrays of structures can be resized with:
-# * `resize!(ids)` which will add a time-slice at the current global time (this is what you want to use in most cases)
-# * `resize!(ids, time0)` which will add a time-slice at `time0` seconds
-
-# resize the time dependent array of structure
-resize!(dd.equilibrium.time_slice, 1.0);
-
-# let's just populate it with the data from the previous time slice
-dd.equilibrium.time_slice[2] = deepcopy(dd.equilibrium.time_slice[1]);
-dd.equilibrium.time_slice[2].time = 1.0
-
-# Here we see that equilibrium has mulitiple time_slices
-
-dd.equilibrium.time
-
-# We can access time-dependent arrays of structures via integer index...
-
-eqt = dd.equilibrium.time_slice[2]
-eqt.time
-
-# ...or at a given time, by passing the time as a floating point number (in seconds)
-
-eqt = dd.equilibrium.time_slice[1.0]
-eqt.time
-
-# NOTE: If we ask a time that is not exactly in the arrays of structures, we'll get the closest (causal!) time-slice
-
-eqt = dd.equilibrium.time_slice[0.9]
-eqt.time
-
-eqt = dd.equilibrium.time_slice[1.1]
-eqt.time
-
-# ... or at the current `dd.global_time` by leaving the square brackets empty []
-# 
-# **NOTE:** using `[]` is what you want to use in most situations that involve time-dependent arrays of structures!
-
-dd.global_time = 0.0
-eqt = dd.equilibrium.time_slice[]
-eqt.time
-
-dd.global_time = 1.0
-eqt = dd.equilibrium.time_slice[]
-eqt.time
-
-# What we described above was for time-dependent arrays of structures.
-# 
-# The other place where time comes in, is when dealing with time-dependent arrays of data.
-# 
-# In this case, we can use the `@ddtime` macro to manipulate these time-dependent arrays at `dd.global_time`.
-# 
-# NOTE: Also in this case, `@ddtime` will operate on the closest (causal!) time point
-
-dd.equilibrium.vacuum_toroidal_field.b0
-
-dd.global_time = 1.0
-@ddtime(dd.equilibrium.vacuum_toroidal_field.b0 = 10.0)
-dd.equilibrium.vacuum_toroidal_field.b0
-
-dd.global_time = 0.0
-@ddtime(dd.equilibrium.vacuum_toroidal_field.b0)
-
-dd.global_time = 1.0
-@ddtime(dd.equilibrium.vacuum_toroidal_field.b0)
-
-# ## Expressions in `dd`
-
-# Some fields in the data dictionary are expressions (ie. Functions).
-# For example `dd.core_profiles.profiles_1d[].pressure` is dynamically calculated as the product of thermal densities and temperature with addition of fast ions contributions
-
-dd.global_time = 0.0
-print_tree(dd.core_profiles.profiles_1d[]; maxdepth=1)
-
-# accessing a dynamic expression, automatically evaluates it
-
-dd.core_profiles.profiles_1d[].conductivity_parallel
-
-# In addition to evaluating expressions by accessing them, expressions in the tree can be evaluated using `IMAS.freeze(ids)`
-# 
-# NOTE: `IMAS.freeze(ids, field::Symbol)` works on a single field and `IMAS.refreeze!(ids, field)` forces re-evaluation of an expression. Also, `IMAS.empty!(ids, field::Symbol)` can be used to revert a frozen field back into an expression.
-
-print_tree(IMAS.freeze(dd.core_profiles.profiles_1d[1]); maxdepth=1)
-
-# ## Comparing two IDSs
-# We can introduce a change in the `dd1` and spot it with the `diff` function
-
-dd1.equilibrium.time_slice[1].time = -100.0
-IMAS.diff(dd.equilibrium, dd1.equilibrium)
+# Understanding how to work with the IMAS data structure is a must for working within the FUSE ecosystem!
 
 # ## Summary
 # Snapshot of `dd` in 0D quantities (evaluated at `dd.global_time`).
 # 
 # Extract + plots saved to PDF (printed to screen if `filename` is omitted). NOTE: For PDF creation to work, one may need to install of `DejaVu Sans Mono` font.
 
+tutorial_temp_dir = tempdir()
 filename = joinpath(tutorial_temp_dir, "$(ini.general.casename).pdf")
 display(filename)
 FUSE.digest(dd)#, filename)