Installation

These instructions will guide you through the typical installation process. The setup is written for macOS and Linux. Depending on your system settings and installed libraries your procedure may differ. If one or more of the steps below do not work for you we encourage you to first check the Troubleshooting page. If that does not help you further, please contact the developers.

1. System pre-configuration

Setting up PROTEUS and its submodules requires extra steps to be performed before following the rest of this guide. Follow the instructions below depending on your system configuration.

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

Compute cluster: use the dedicated guides:

• Kapteyn cluster
• Habrok cluster
• Snellius cluster

2. Setup a Python environment

We recommend Python version 3.12 for running PROTEUS. Python is most easily obtained and managed using either miniconda or miniforge.

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

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

3. Install Julia

Some PROTEUS modules are written in Julia. Install via the official installer:

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

juliaup add 1.11
juliaup default 1.11

Set the Julia environment variable:

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

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

4. Create and set environment variables

The environment variable FWL_DATA points to the folder where input data are stored. This variable must always be set, so add it to your shell config file.

mkdir /your/local/path/FWL_DATA
echo "export FWL_DATA=/your/local/path/FWL_DATA/" >> "$HOME/.bashrc"
source "$HOME/.bashrc"

mkdir /your/local/path/FWL_DATA
echo "export FWL_DATA=/your/local/path/FWL_DATA/" >> "$HOME/.zshrc"
source "$HOME/.zshrc"

5. Download PROTEUS

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

6. Create a virtual environment

conda create -n proteus python=3.12
conda activate proteus

7. Install SOCRATES (radiative transfer)

which gfortran
which nf-config
nf-config --version

Install SOCRATES:

./tools/get_socrates.sh

The environment variable RAD_DIR must always point to the SOCRATES installation path. Add it to your shell config file:

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

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

8. Install AGNI (radiative-convective atmosphere model)

Installation steps can be found at the AGNI wiki. They are also reproduced below.

which make
which unzip

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

Use this get_agni.sh script 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).

9. Install FastChem (equilibrium chemistry solver)

FastChem is used by AGNI for equilibrium chemistry calculations. It must be compiled from source inside the AGNI directory:

which cmake
which make

cd AGNI
bash src/get_fastchem.sh
cd ../

The environment variable FC_DIR must always point to the FastChem installation path. Add it to your shell config file:

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

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

10. Install submodules as editable

Clone and install each submodule in editable mode.

MORS (stellar evolution):

git clone git@github.com:FormingWorlds/MORS
python -m pip install -e MORS/.

JANUS (1D convective atmosphere):

git clone git@github.com:FormingWorlds/JANUS
python -m pip install -e JANUS/.

CALLIOPE (volatile in-/outgassing):

git clone git@github.com:FormingWorlds/CALLIOPE
python -m pip install -e CALLIOPE/.

ARAGOG (interior thermal evolution):

git clone git@github.com:FormingWorlds/aragog.git
python -m pip install -e aragog/.

ZEPHYRUS (atmospheric escape):

git clone git@github.com:FormingWorlds/ZEPHYRUS
python -m pip install -e ZEPHYRUS/.

Zalmoxis (planetary interior structure):

git clone git@github.com:FormingWorlds/Zalmoxis
python -m pip install -e Zalmoxis/.

The environment variable ZALMOXIS_ROOT must point to the Zalmoxis installation directory. Add it to your shell config file:

echo "export ZALMOXIS_ROOT=$PWD/Zalmoxis/" >> "$HOME/.bashrc"
source "$HOME/.bashrc"

echo "export ZALMOXIS_ROOT=$PWD/Zalmoxis/" >> "$HOME/.zshrc"
source "$HOME/.zshrc"

Download the required data files:

cd Zalmoxis
bash src/get_zalmoxis.sh
cd ../

11. Setup PETSc (numerical computing library)

./tools/get_petsc.sh

./tools/get_petsc.sh

12. Setup SPIDER (interior evolution model)

./tools/get_spider.sh

13. Install PROTEUS framework

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

14. Enable pre-commit hooks

pre-commit install -f

15. Done!

Any remaining dependencies will be downloaded when the model is first run.

Optional modules

Multi-phase tidal heating model (LovePy)

LovePy is written in Julia. You can use the same environment as AGNI if you wish, but make sure to follow the installation steps below.

./tools/get_lovepy.sh

Synthetic observations calculator (PLATON)

PLATON is a forward modelling and retrieval tool for exoplanet atmospheres. In PROTEUS, this tool is used to generate synthetic transmission and secondary eclipse observations.

./tools/get_platon.sh

Chemical kinetics atmosphere model (VULCAN)

VULCAN is not available as a standard Python package, so it is installed via a dedicated script:

./tools/get_vulcan.sh

For the legacy user install method (deprecated), see the User install page.