Setup the FUSE environment

This guide walks you through setting up everything you need to run FUSE: the Julia language, the FUSE package, the fusebot helper, and an optional JupyterLab environment with Julia kernels.

One-command install

These scripts install FUSE, Revise, fusebot, the Jupyter stack (fuse conda env), IJulia kernels, and clone FuseExamples.

They then activate the fuse env, run fusebot install_IJulia (or make install_IJulia / scripts/install_ijulia.sh if fusebot fails), and finish by executing the first three cells of FuseExamples/fluxmatcher.ipynb. A fresh install typically takes 20–40 minutes (Julia packages + conda + IJulia + the first flux-matcher solve; the notebook cells are often ~6 minutes on one thread).

Laptop (Linux or macOS)

From any directory on a personal machine. Installs juliaup when julia is missing and Miniconda when conda is missing.

curl -fsSL https://install.julialang.org | sh -s -- -y && \
bash <(curl -fsSL https://raw.githubusercontent.com/ProjectTorreyPines/FUSE.jl/master/scripts/install_fuse_laptop.sh)

From a local FUSE.jl clone: bash scripts/install_fuse_laptop.sh

Skip the notebook solve with FUSE_SKIP_VERIFY=1 bash scripts/install_fuse_laptop.sh if you only want packages + kernels.

NERSC (Perlmutter)

From a login node (run the depot symlink under Home quota / memory pressure first if $HOME is under memory pressure). Loads julia/1.11.7 and conda by default, then continues through IJulia, FuseExamples, and the fluxmatcher cells (fine on a login node — typically ~6 minutes on one thread for the notebook solve).

bash <(curl -fsSL https://raw.githubusercontent.com/ProjectTorreyPines/FUSE.jl/master/scripts/install_fuse_nersc.sh)

From a local FUSE.jl clone: bash scripts/install_fuse_nersc.sh

Override the Julia module with FUSE_JULIA_MODULE=julia/1.12.0 bash scripts/install_fuse_nersc.sh when needed. Skip the notebook solve with FUSE_SKIP_VERIFY=1 if desired. See On NERSC (Perlmutter) for depot layout, fusebot, and Jupyter notes.

Windows

From any directory in PowerShell. Installs Julia via winget (Microsoft Store) or the Julia App Installer when julia is missing, and Miniconda when conda is missing. Like the laptop and NERSC scripts, it finishes by running the first three fluxmatcher.ipynb cells unless you set FUSE_SKIP_VERIFY=1.

winget install julia -s msstore --accept-source-agreements --accept-package-agreements --disable-interactivity; `
irm https://raw.githubusercontent.com/ProjectTorreyPines/FUSE.jl/master/scripts/install_fuse_windows.ps1 | iex

From a local FUSE.jl clone: .\scripts\install_fuse_windows.ps1

If winget is unavailable, install Julia with Add-AppxPackage -AppInstallerFile https://install.julialang.org/Julia.appinstaller, open a new terminal, then run the install script.

Re-verify fluxmatcher.ipynb

The one-command installs already run the first three cells of FuseExamples/fluxmatcher.ipynb. To re-run them later:

• Cell 0 (code): using Revise, using Plots, using FUSE
• Cell 1 (markdown): flux-matcher introduction (checked for presence, not executed)
• Cell 2 (code): flux-matches the DIII-D L-mode case — often ~6 minutes on one thread the first time (compilation plus the solve)

Linux, macOS, and NERSC:

bash <(curl -fsSL https://raw.githubusercontent.com/ProjectTorreyPines/FUSE.jl/master/scripts/verify_fluxmatcher_notebook.sh)

Or from a FUSE.jl clone: bash scripts/verify_fluxmatcher_notebook.sh

Windows:

irm https://raw.githubusercontent.com/ProjectTorreyPines/FUSE.jl/master/scripts/verify_fluxmatcher_notebook.ps1 | iex

Or from a FUSE.jl clone: .\scripts\verify_fluxmatcher_notebook.ps1

Then start JupyterLab in the directory that contains FuseExamples/:

conda activate fuse
python -m jupyter lab

conda activate fuse
python -m jupyter lab

Open FuseExamples/fluxmatcher.ipynb and run cells 0–2 in the notebook UI.

Julia installation

Desktop and laptop (juliaup)

We recommend Juliaup on personal machines:

• Mac & Linux: curl -fsSL https://install.julialang.org | sh
• Windows: winget install julia -s msstore --accept-source-agreements --accept-package-agreements

After installation, restart your terminal so the julia command is available.

HPC systems (environment modules)

On many clusters—including NERSC Perlmutter—Julia is provided by the site module system instead of juliaup:

module load julia
julia --version

See On NERSC (Perlmutter) for depot layout, fusebot, and Jupyter notes specific to NERSC.

FUSE installation

FUSE and related packages are registered at the FuseRegistry. Start Julia (julia at the terminal), then:

1. Add the FuseRegistry and the FUSE package (a fresh install typically takes 15–30 minutes to download and precompile dependencies):

   using Pkg
   Pkg.Registry.add(RegistrySpec(url="https://github.com/ProjectTorreyPines/FuseRegistry.jl.git"))
   Pkg.Registry.add("General")
   Pkg.add("FUSE")

2. Import FUSE:

   using FUSE

   First import is slow

   Pkg.add("FUSE") already precompiles most dependencies. The first using FUSE and your first FUSE.init(...) smoke test can still take 5–15 minutes extra while remaining packages and actor code compile. This is normal and happens only once per Julia/FUSE version, not on every startup.

3. Install the fusebot helper (optional but recommended). fusebot is a small command-line tool bundled with FUSE; its main job is to install the Julia Jupyter kernels (fusebot install_IJulia), plus a few related utilities. Run fusebot --help for the list of user commands. Install directory is picked by install_fusebot() automatically - the juliaup bin directory on a laptop, or ~/.local/bin under module load julia on HPC:

   FUSE.install_fusebot()                                  # auto: juliaup bin, or ~/.local/bin on HPC
   FUSE.install_fusebot(; setup_shell=true)                # HPC: also add ~/.local/bin to your shell PATH
   FUSE.install_fusebot("/custom/bin"; setup_shell=true)   # optional: explicit install directory

   On HPC (module load julia), the site Julia module does not put user tools on PATH the way juliaup does, so pass setup_shell=true once to add the install directory to your shell startup file. See On NERSC (Perlmutter) for details.

4. Verify the install works with a quick smoke test:

   using FUSE
   ini, act = FUSE.case_parameters(:FPP)
   dd = FUSE.init(ini, act)   # if this completes without error, your install is working

5. Run the regression tests (optional; can take 1+ hour). At the Julia prompt, typing ] switches to the package prompt:

   julia ] test FUSE

6. Exit Julia and clone FuseExamples in your working directory:

   git clone https://github.com/ProjectTorreyPines/FuseExamples

   Update later with git fetch && git reset --hard origin/master (this discards local changes to those examples).

using Pkg
Pkg.Registry.add(RegistrySpec(url="https://github.com/ProjectTorreyPines/FuseRegistry.jl.git"))
Pkg.Registry.add("General")
Pkg.add("FUSE")
using FUSE
FUSE.install_fusebot()

Install Jupyter-Lab with Julia support

Python on PATH

fusebot install_IJulia runs Pkg.build("IJulia"), which requires a Python interpreter on your PATH. If build fails with a missing-Python error:

• Activate a conda environment, or
• Install Python and Jupyter, or
• On HPC, module load python (site-specific) before running the install.

A known-good optional stack is provided in docs/jupyter_environment.yml. That file ships inside the FUSE package, so its location depends on whether FUSE is installed under ~/.julia/packages (a normal Pkg.add) or ~/.julia/dev (a Pkg.develop checkout). Let Julia resolve the path for you with pkgdir(FUSE, ...) so the commands are copy-paste regardless of where FUSE lives. Run this in your terminal (it calls julia for you to locate the file - you do not need to start the Julia prompt yourself). julia must be on your PATH: with juliaup it already is, while on HPC you need module load julia first. The guarded line below loads the module on HPC and is a harmless no-op on a laptop:

command -v module >/dev/null && module load julia   # HPC only; skipped automatically on a laptop
conda env create -f "$(julia -e 'using FUSE; print(pkgdir(FUSE, "docs", "jupyter_environment.yml"))')"
conda activate fuse

using Pkg
Pkg.develop("FUSE")   # any package registered in the FuseRegistry or General registry

Install Jupyter / JupyterLab

Install JupyterLab if it is not already available.

Install IJulia kernels

In your terminal (with Python on your PATH, and fusebot installed earlier):

fusebot install_IJulia

This installs single- and multi-thread Julia kernels. Thread count for the multi-thread kernel follows JULIA_NUM_THREADS (default: number of CPUs). Re-run after installing a new Julia version.

Kernels are written directly under ~/.local/share/jupyter/kernels (or $JUPYTER_DATA_DIR/kernels), so registration does not depend on the jupyter command being on PATH. Listing kernels still requires Jupyter:

python -m jupyter kernelspec list

Start JupyterLab

Linux and macOS:

python -m jupyter lab

Windows (prefer the Python module form so the correct environment is used):

python -m jupyter lab

If python is not on PATH, use the launcher from your conda or Python install, for example py -m jupyter lab.

Open the cloned FuseExamples folder and run the tutorial notebooks.

Updating FUSE

1. Watch the FUSE repository for releases.

2. Update like any Julia package, from the ] package prompt (type ] at the Julia prompt):

   julia ] up

Updating Julia

With juliaup

1. juliaup update
2. In the new Julia version: using Pkg; Pkg.add("FUSE")
3. fusebot install_IJulia

With environment modules

Load the new Julia module, reinstall FUSE in that version's depot if needed, then run fusebot install_IJulia.

Cluster-specific notes

• On NERSC (Perlmutter)
• • NERSC one-command install
  • Julia
  • FUSE
  • Python and Jupyter
  • Running Jupyter on Perlmutter
  • Pre-built FUSE module (optional)
  • Troubleshooting
• On GA's OMEGA cluster
• • FUSE module
  • Connecting to a Jupyter-lab server running on OMEGA from your laptop
  • Three ways to run parallel jobs
  • Running Julia/FUSE via VScode
  • Using Revise on Omega
  • Using GACODE on Omega with Julia
• On SAGA cluster
• • Getting started on the SAGA cluster
  • Jupyter on SAGA cluster

Troubleshooting

Next steps

• Follow the introductory tutorial.
• Explore the FuseExamples notebooks.
• Stuck or have questions? Join the Discord community.