Manual installation¶

If the automated installer does not work on your system, or if you prefer to control each step, follow the manual procedure below. These steps cover the same ground as the installer script.

On Windows, install PROTEUS under WSL2. Depending on your system configuration, some steps may differ. If you run into problems, check the Troubleshooting page or contact the developers.

1. System pre-configuration¶

Install the required system packages for your platform before proceeding.

Local machine (laptop/desktop): follow the Local machine guide.

Compute cluster: use the dedicated guides:

• Kapteyn cluster
• Habrok cluster
• Snellius cluster
• Cambridge IoA cluster

2. Set up a Python environment¶

Python 3.12 is required, and is installed via miniconda or miniforge. If you do not have miniconda or miniforge installed yet:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh
rm ~/miniconda3/miniconda.sh

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh
rm ~/miniconda3/miniconda.sh

Then create a conda environment with Python 3.12:

conda create -n proteus python=3.12
conda activate proteus

3. Install Julia¶

Some PROTEUS modules (AGNI, LovePy, Obliqua) are written in Julia. Install via the official installer:

curl -fsSL https://install.julialang.org | sh

juliaup add 1.13
juliaup default 1.13

Set the Julia environment variable:

echo "export PYTHON_JULIAPKG_EXE=$(which julia)" >> ~/.bashrc
source ~/.bashrc
conda activate proteus

echo "export PYTHON_JULIAPKG_EXE=$(which julia)" >> ~/.zshrc
source ~/.zshrc
conda activate proteus

4. Create environment variables and clone PROTEUS¶

The FWL_DATA environment variable points to the folder where PROTEUS stores reference data. This variable must always be set.

mkdir -p /your/local/path/FWL_DATA
echo "export FWL_DATA=/your/local/path/FWL_DATA/" >> "$HOME/.bashrc"
source "$HOME/.bashrc"
conda activate proteus

mkdir -p /your/local/path/FWL_DATA
echo "export FWL_DATA=/your/local/path/FWL_DATA/" >> "$HOME/.zshrc"
source "$HOME/.zshrc"
conda activate proteus

Clone the repository:

git clone git@github.com:FormingWorlds/PROTEUS.git
cd PROTEUS

5. Install SOCRATES (radiative transfer)¶

SOCRATES is a Fortran spectral radiative transfer code used by AGNI and JANUS.

which make
which gfortran
which nc-config
which nf-config
nf-config --version

bash tools/get_socrates.sh

Set RAD_DIR to point to the SOCRATES installation:

echo "export RAD_DIR=$PWD/socrates/" >> "$HOME/.bashrc"
source "$HOME/.bashrc"
conda activate proteus

echo "export RAD_DIR=$PWD/socrates/" >> "$HOME/.zshrc"
source "$HOME/.zshrc"
conda activate proteus

6. Install AGNI and FastChem¶

AGNI solves the atmospheric energy balance using Julia and the SOCRATES spectral library. FastChem provides equilibrium chemistry for AGNI. Installation steps are also documented at the AGNI wiki.

which make && which unzip && which cmake

git clone git@github.com:nichollsh/AGNI.git
cd AGNI
bash src/get_agni.sh 0
bash src/get_fastchem.sh
cd ../

Use get_agni.sh to keep AGNI and its data files up to date. AGNI must be available at ./AGNI/ inside your PROTEUS folder (either a symbolic link or the true location).

Set the FastChem environment variable:

echo "export FC_DIR=$PWD/AGNI/fastchem/" >> "$HOME/.bashrc"
source "$HOME/.bashrc"
conda activate proteus

echo "export FC_DIR=$PWD/AGNI/fastchem/" >> "$HOME/.zshrc"
source "$HOME/.zshrc"
conda activate proteus

7. Install Python submodules¶

Clone and install each submodule in editable mode:

# MORS - stellar evolution (https://proteus-framework.org/MORS/)
git clone git@github.com:FormingWorlds/MORS
python -m pip install -e MORS/.

# JANUS - 1D convective atmosphere (https://proteus-framework.org/JANUS/)
git clone git@github.com:FormingWorlds/JANUS
python -m pip install -e JANUS/.

# CALLIOPE - volatile outgassing (https://proteus-framework.org/CALLIOPE/)
git clone git@github.com:FormingWorlds/CALLIOPE
python -m pip install -e CALLIOPE/.

# ZEPHYRUS - atmospheric escape (https://github.com/FormingWorlds/ZEPHYRUS)
git clone git@github.com:FormingWorlds/ZEPHYRUS
python -m pip install -e ZEPHYRUS/.

# Aragog - interior thermal evolution (https://proteus-framework.org/aragog/)
bash tools/get_aragog.sh

# Zalmoxis - planetary interior structure (https://proteus-framework.org/Zalmoxis/)
bash tools/get_zalmoxis.sh

8. Install PROTEUS¶

python -m pip install -e ".[develop]"

The optional backends and the parameter-inference stack are not part of this install, and their tests skip without them. To match what CI runs:

python -m pip install -e ".[develop,vulcan,atmodeller,inference]"

9. Enable pre-commit hooks¶

pre-commit install -f

10. Download reference data¶

Download the essential reference data files (the default-config and tutorial k-tables, stellar spectra, and the interior tables, including the structure-solver EOS):

proteus get spectral -n Honeyside -b 48
proteus get spectral -n Dayspring -b 48
proteus get stellar
proteus get interiordata

Running proteus get spectral without arguments downloads every spectral file group (~10 GB).

For additional datasets (MUSCLES spectra, PHOENIX models), use:

proteus get muscles --all
proteus get phoenix --feh 0.0 --alpha 0.0
proteus get reference

11. Done!¶

Verify the installation:

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