GitHub

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.

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 can take 5+ minutes):

    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

    The first using FUSE (and your first simulation run) triggers precompilation that can take several minutes. 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. 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(:ITER)
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).

Laptop quick-start (all-in-one)

On a personal machine with juliaup, the full sequence is (after typing julia at the terminal):

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
Developing FUSE (or any other package)

To edit FUSE itself, run:

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

This clones the source into the standard editable location ~/.julia/dev/FUSE and points your environment at it (instead of the read-only versioned copy under ~/.julia/packages), so local edits take effect immediately.

The same works for any package you want to develop - for example a FUSE dependency like IMAS or TJLF, or a third-party package. The package does not have to be registered; Pkg.develop accepts three forms:

  • By name (Pkg.develop("Foo")) - requires the package to be in a registry you have added (General or the FuseRegistry), since Julia reads the repo URL from there to clone it into ~/.julia/dev/Foo.
  • By URL (Pkg.develop(url="https://github.com/Org/Foo.jl")) - for unregistered packages; Julia clones directly from the given URL.
  • By path (Pkg.develop(path="/path/to/Foo")) - no registration needed; points the environment at an existing local checkout (clone it yourself first).

Run Pkg.free("Foo") to stop developing and return to the registered, versioned copy.

Install Jupyter / JupyterLab

Install JupyterLab if it is not already available.

WebIO and Interact

The WebIO JupyterLab extension is needed for Interact.jl.

  • JupyterLab 3.x: check with python -m jupyter labextension list. You should see webio-jupyterlab-provider enabled.
  • Classic Notebook below version 7: check with python -m jupyter nbextension list for webio-jupyter-nbextension.
  • Notebook 7+ no longer uses classic nbextension commands; use the Lab extension only.

If extensions conflict, pin JupyterLab 3.x (for example conda install jupyterlab=3.6.7) and keep WebIO/Interact up to date. Python 3.11 is a good compatibility target for Interact.

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

Tip

See Managing packages in the Julia manual.

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

Troubleshooting

Where to run each command

Commands in this guide run in one of two places, indicated by the code-block label and the lead-in text:

  • Terminal (your shell) - blocks marked bash/powershell, e.g. module load julia, git ..., conda ..., fusebot ..., python -m jupyter ....
  • Julia prompt - blocks marked julia, run after you start Julia's interactive session by typing julia in the terminal. These use using, Pkg, FUSE., or the ] package prompt.
`fusebot: command not found`

The install directory is not on your PATH in the current shell. Either open a new login shell, or add it now and re-run, for example export PATH="$HOME/.local/bin:$PATH". To make this permanent, run FUSE.install_fusebot(; setup_shell=true) (or FUSE.setup_fusebot_shell!() if fusebot is already installed).

`fusebot install_IJulia` fails with a missing-Python error

Pkg.build("IJulia") needs a Python interpreter on your PATH. Activate a conda environment, install Python/Jupyter, or on HPC module load python (site-specific) before re-running.

`Pkg.Registry.add` fails

Make sure git is installed and that you can reach GitHub. Behind a proxy or offline node, configure your proxy first. You can re-run the registry/add commands; they are safe to repeat.

Wrong Jupyter kernel

fusebot install_IJulia registers single- and multi-thread Julia kernels. In JupyterLab pick the kernel matching the Julia version you installed FUSE into; list them with python -m jupyter kernelspec list.

Next steps