Skip to content

install.md

Latest commit

 

History

History
343 lines (234 loc) · 14.3 KB

install.md

File metadata and controls

343 lines (234 loc) · 14.3 KB
Raw

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, IJulia kernels, and clone FuseExamples. Everything runs from the shell — no Julia REPL. A fresh install typically takes 20–45 minutes (Julia packages + conda environment + IJulia kernels).

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

NERSC (Perlmutter)

From a login node (run the depot symlink under [Home quota / memory pressure](@ref nersc-home-quota) first if $HOME is tight). Loads julia/1.11.7 and conda by default.

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. See [On NERSC (Perlmutter)](@ref nersc-install) 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.

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.

Step 2: verify fluxmatcher.ipynb

After the install finishes, confirm you can run the first two cells of FuseExamples/fluxmatcher.ipynb:

  • Cell 0 (code): using Revise, using Plots, using FUSE
  • Cell 1 (markdown): flux-matcher introduction (checked for presence, not executed)

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–1 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)](@ref nersc-install) for depot layout, fusebot, and Jupyter notes specific to NERSC.

[FUSE installation](@id 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

    !!! note "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)](@ref nersc-install) 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:

    ] 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).

!!! tip "Laptop quick-start (all-in-one)" On a personal machine with juliaup, the full sequence is (after typing julia at the terminal):

```julia
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

!!! tip "Developing FUSE (or any other package)" To edit FUSE itself, run:

```julia
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](https://github.com/ProjectTorreyPines/FuseRegistry.jl/)), 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.

!!! note "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):

    ] 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

Pages = ["install_nersc.md", "install_omega.md", "install_saga.md"]
Depth = 2

Troubleshooting

!!! note "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.

!!! warning "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).

!!! warning "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.

!!! warning "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.

!!! warning "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