Installation
Prerequisites
- macOS (Intel or Apple Silicon) or Linux
- ~20 GB disk space (conda, Julia, reference data, submodules)
- Git with SSH key configured (GitHub SSH setup)
- Internet connection for data downloads
- Allow ~60 minutes for a full installation including all submodules
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.
macOS users
macOS Catalina (10.15) and later uses zsh as the default shell. Replace .bashrc with .zshrc throughout these instructions if you are using the default shell.
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:
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.
Install miniconda:
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
Choose an install folder where you have plenty of disk space.
Install miniforge (recommended for Apple Silicon):
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. You should only obtain Julia using the official installer, not via your computer's package manager.
curl -fsSL https://install.julialang.org | sh
Pin Julia to version 1.11
Julia 1.12+ is not yet supported due to OpenSSL library incompatibilities with Python. After installing Julia, pin it to version 1.11:
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)
./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.
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).
The argument provided to the script (integer from 0 to 20) indicates which tests AGNI should run. A value of 0 means the tests are skipped.
9. 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 ../
10. Setup PETSc (numerical computing library)
Warning
PETSc requires Python <= 3.12. Make sure your active environment uses a compatible version.
./tools/get_petsc.sh
Fedora/RHEL users
If you encounter errors moving libraries, see Troubleshooting: PETSc on Fedora/RHEL.
./tools/get_petsc.sh
The script automatically detects Apple Silicon vs Intel, uses Homebrew's MPI, and applies the necessary compiler/linker workarounds. If you encounter issues, see Troubleshooting: PETSc on Apple Silicon.
11. Setup SPIDER (interior evolution model)
./tools/get_spider.sh
12. Install PROTEUS framework
python -m pip install -e ".[develop]"
13. Enable pre-commit hooks
pre-commit install -f
14. 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
Note
This script will take some time to run; PLATON will need to download about 10 GB of data from the internet.
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.