Diagnosing and updating your installation¶

PROTEUS provides two commands for keeping your installation healthy:

• proteus doctor checks your environment, reference data, and package versions against the requirements in pyproject.toml.
• proteus update runs the same checks, then executes the suggested fix commands automatically.

Quick reference¶

proteus doctor              # diagnose
proteus doctor --json       # machine-readable output
proteus update --dry-run    # preview fixes without executing
proteus update              # apply all fixes

proteus doctor¶

proteus doctor runs a sequence of checks grouped into three categories and reports each as pass, warn, or fail. Failing checks include a fix command you can run manually or let proteus update handle.

Environment¶

Reference data¶

Checks that the essential data directories inside $FWL_DATA are present and non-empty:

Package versions¶

For each required Python package (fwl-proteus, fwl-io, fwl-aragog, fwl-calliope, fwl-janus, fwl-mors, fwl-zephyrus, fwl-zalmoxis) and standard module package (fwl-morrigan, fwl-vulcan, atmodeller), the doctor checks the points below:

1. Is the package installed? If not, the check fails for a required package and warns for a standard module package, with the command that installs it: the setup script, or pip install "fwl-proteus[<extra>]" in a tree with no setup script.
2. Does the installed version satisfy the minimum bound in pyproject.toml? For example, if pyproject.toml requires fwl-aragog>=26.05.13 and you have 25.1.1 installed, the check fails.
3. Is this an editable install? If so, the output shows the checkout directory, git commit hash, and dirty state; for a folder that is not a git clone of its own (no .git, or an empty one inside the PROTEUS checkout), it says so in place of the hash and the dirty state.

For git-pinned modules (AGNI, SOCRATES, Obliqua), the doctor compares the checkout's HEAD commit against the commit SHA pinned in pyproject.toml under [tool.proteus.modules]. A mismatch produces a warning with a fix command. A missing or empty AGNI or SOCRATES folder is a failure; a missing or empty Obliqua folder is a warning with the fix bash tools/get_obliqua.sh. For a module folder with files that is not a git clone of its own, the doctor reads no commit (git would answer for the repository around the folder), marks the line [not a git clone of its own] and warns that the commit cannot be compared with the pin; the fix is advice that proteus update does not run: move the folder away or delete it, then run the setup script of the module. For a clone of its own whose commit git cannot read, at the path of a pinned module, the doctor warns that the commit cannot be read; the fix is advice too: it names git -C <folder> log -1 first and, for the case that this shows no commit, the same move-away advice. A file or a broken link at the path of a module counts as not installed, with the advice to delete it and run the setup script; an Obliqua path that holds a clone of another project gets the move-away advice too. For an Obliqua folder that is not at its pin the fix is advice that proteus update does not run: bash tools/get_obliqua.sh --force <folder> replaces the folder with a new clone at the pin; for a folder whose .git is a file (a git worktree or a submodule), which the forced form refuses, the fix is the move-away advice. With or without --force, the script refuses the PROTEUS folder, your home folder and a folder that holds one of them as its destination, a file or a broken link, a path that holds a line break, a path that goes through a folder that does not exist and then through . or .., and a folder with files that is not an Obliqua project. The forced form also refuses a folder with files that is not a git clone of its own with a commit, and a folder whose .git is a file (a git worktree or a submodule). An Obliqua clone at its pin with no Manifest.toml gives a warning that its Julia environment is not instantiated, with the fix bash tools/get_obliqua.sh. The AGNI fix is bash tools/get_agni.sh. The SOCRATES fix also rebuilds AGNI, because re-cloning the SOCRATES tree removes the wrappers AGNI compiles into socrates/julia, so it reads bash tools/get_socrates.sh "$RAD_DIR" && RAD_DIR="$RAD_DIR" bash tools/get_agni.sh 0.

Example output¶

Environment
  [ok] FWL_DATA: /home/user/FWL_DATA
  [ok] RAD_DIR: /home/user/PROTEUS/socrates
  [FAIL] FC_DIR: not set
       fix: conda env config vars set FC_DIR=<path>, then conda deactivate && conda activate proteus (without conda: source .proteus-env.sh in the PROTEUS folder)
  [ok] julia: 1.13.0

Reference data
  [ok] FWL_DATA/atmos_clim/spectral_files: present
  [ok] FWL_DATA/star/spectra: present

Package versions
  [ok] fwl-proteus: 25.10.15 [editable @ PROTEUS -> a1b2c3d]
  [ok] fwl-aragog: 26.5.13 [editable @ aragog -> d051902]
  [FAIL] fwl-janus: not installed
       fix: pip install fwl-janus
  [warn] AGNI: 1.10.1 (bf65a56c) differs from pin (b06a3fed)
       fix: bash tools/get_agni.sh

2 failed, 1 warnings

Run proteus update to fix 3 issue(s) automatically.

JSON output¶

For CI pipelines or scripted checks, use --json to get machine-readable output:

proteus doctor --json

Each check is a JSON object with five fields:

{
  "name": "fwl-aragog",
  "category": "versions",
  "status": "pass",
  "message": "26.5.13 [editable @ aragog -> d051902]",
  "fix_cmd": null
}

The status field is one of "pass", "warn", or "fail". The fix_cmd field is null for passing checks and a shell command string for failing ones.

proteus update¶

proteus update runs the same checks as proteus doctor, collects all fix commands from failing and warning checks, and executes them in sequence.

proteus update

After all fixes are applied, the doctor runs again to verify the result.

Dry run¶

To preview what proteus update would do without making changes:

proteus update --dry-run

This lists the fixable issues and their commands but does not execute anything.

What proteus update can fix¶

What proteus update cannot fix¶

• Missing environment variables (FWL_DATA, RAD_DIR, FC_DIR, PYTHON_JULIAPKG_EXE): set them in the conda environment with conda env config vars set NAME=<path>, then run conda deactivate && conda activate proteus, because conda loads them only at activation. Without conda, run source .proteus-env.sh in the PROTEUS folder. proteus update does not run this advice.
• Wrong Julia version: the doctor checks the Julia in PYTHON_JULIAPKG_EXE (the julia on PATH when it is unset) and suggests juliaup add 1.13, then setting PYTHON_JULIAPKG_EXE in the same way to the path that julia +1.13 -e 'print(joinpath(Sys.BINDIR, "julia"))' prints. Your default Julia stays as it is. The installer binds Julia 1.11 only when the import of PROTEUS fails on OpenSSL_jll because Python links an OpenSSL older than 3.5; after conda install -c conda-forge 'openssl>=3.5', Julia 1.13 can be used.
• Missing system packages (gfortran, cmake, netcdf): these require your system package manager (brew, apt, dnf). See the installation guide for platform-specific commands.
• Conda environment issues: proteus update runs inside the active conda environment. If the wrong environment is active or conda is not configured, activate the correct environment first: conda activate proteus.
• An outdated editable module clone that a setup script makes (MORS, JANUS, CALLIOPE, ZEPHYRUS, Aragog, Zalmoxis, Morrigan, VULCAN, atmodeller): no fix changes such a clone. The doctor shows as its fix the commands that fetch the tags, check out the release tag of the minimum version and reinstall the clone, and, for the clone in the module's folder of the PROTEUS root, the setup script with --force (for example bash tools/get_python_module.sh MORS --force), which replaces the clone with a new one; for atmodeller the commands check out the pinned commit, not a release tag. Run the one you want by hand. A folder that is not a git clone of its own gets no git command, which would act on the repository around it. When it is the module's own folder of the PROTEUS root, the doctor shows the --force replacement for a module with a release tag, and for atmodeller, which a commit pins, the advice to move it away or delete it and run the setup script again, as get_atmodeller.sh prints it; a folder elsewhere gets the advice to move it away. An Obliqua folder that is not at its pin is not changed either: the doctor shows bash tools/get_obliqua.sh --force <folder>, which replaces the folder with a new clone at the pin, or, for a folder whose .git is a file, the advice to move it away or delete it. bash tools/get_obliqua.sh prints the two git commands that move the clone to the pin by hand, and after them bash tools/get_obliqua.sh, which sets up the Julia environment at that commit.

proteus update-all¶

Where proteus update applies targeted fixes for the specific issues the doctor finds, proteus update-all performs a full refresh of the whole stack:

proteus update-all

It updates the PROTEUS Python package, recompiles SOCRATES, brings AGNI to the commit pinned in pyproject.toml (an AGNI clone with modified files or commits of your own stays as it is, and the command prints the commands that move it by hand), and refreshes the reference data, verifying environment variables and disk space before proceeding. Pass --export-env to set the environment variables again in the active conda environment and in .proteus-env.sh. It runs no git command in the Python module clones (MORS, JANUS, CALLIOPE, ZEPHYRUS, Aragog, Zalmoxis, Morrigan, VULCAN, atmodeller) and none in Obliqua, and for one of the last four that is not installed it prints the setup command; as with bash install.sh, its pip step installs the PyPI release in place of a clone of MORS, JANUS, CALLIOPE, ZEPHYRUS, Aragog or Zalmoxis that is older than the minimum version, and it does not touch Morrigan, VULCAN and atmodeller. To move a clone to its release tag after a version change, run the commands that bash install.sh prints for a clone that is not at its tag, or the module's setup script with --force. Use this after pulling new code when several components may have moved at once; use proteus update when you want to apply only the fixes the doctor has flagged.

Typical workflows¶

After a fresh install¶

Run proteus doctor to verify everything is set up correctly:

conda activate proteus
proteus doctor

If any checks fail, run proteus update to fix what can be fixed automatically, then address any remaining issues (environment variables, system packages) manually.

After pulling new code¶

When you pull changes that bump submodule versions in pyproject.toml:

git pull
proteus update

This updates any submodules whose installed version no longer satisfies the new bounds. It does not change an editable module clone that a setup script makes (MORS, JANUS, CALLIOPE, ZEPHYRUS, Aragog, Zalmoxis, Morrigan, VULCAN, atmodeller): for one below its minimum version it lists the commands that move it to the release tag by hand or replace it with --force. For another editable checkout that is a git clone of its own it runs git pull && pip install -e . in the checkout directory; any other editable folder gets the advice pip install -U "<name>>=<version>", which you run by hand.

Before submitting a simulation¶

A quick proteus doctor catches common issues (missing data, wrong Julia version, drifted AGNI checkout) before a long simulation fails at runtime:

proteus doctor
proteus start --offline -c input/my_config.toml

See also: Installation | Updating module pins | Troubleshooting | Configuration | Usage