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.

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.

For installing PROTEUS on a local machine (e.g. your laptop), follow the appropriate section in the Local machine guide.

If you are using a specific server, use the following guides:

Kapteyn cluster guide
Habrok cluster guide
Snellius cluster guide.

Setup a Python environment

We recommend that you use Python version 3.12 for running PROTEUS. Python is most easily obtained and managed using either miniconda

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh
# choose an install folder where you have plenty of disk space!
rm ~/miniconda3/miniconda.sh

or miniforge.

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

Install Julia

Some of the PROTEUS modules are written in Julia, which is broadly similar to Python. You should only obtain Julia using the official installer, not via your computer's package manager.

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

User install (default)

Requirements

conda either through miniconda or miniforge (see above). However, currently there seems to be a conflict between Julia and Conda versions of HDF5 and/or NetCDF libaries when using miniforge.
git. If you don't have git, you can install it through conda: conda install git.
Julia installation (see above)
20 GB of disk space; Conda (through miniconda) can take 9 GB, Julia 2 GB and a few GB for PROTEUS.
30 minutes of your time (mostly waiting)

Steps

git clone https://github.com/FormingWorlds/PROTEUS.git
cd PROTEUS
conda env create -f environment.yml
conda activate proteus
pip install -e .
proteus install-all --export-env

Before running PROTEUS

If you want to start running PROTEUS right away - i.e. from the same shell that you used to install PROTEUS - you can set your environment variables using e.g. source ~/.bashrc (for Bash). This deactivates your current conda environment, so you need to enter conda activate proteus as well. If you chose proteus install-all (i.e. without --export-env), you will need to set your PATH, FWL_DATA and RAD_DIR enviroment variables manually.

When you log into the machine that where you installed PROTEUS through proteus install-all --export-env, you will have the environment variables FWL_DATA, RAD_DIR set appropriately as your ~/.shellrc file (e.g. ~/.bashrc) has been updated during the install process. However, you still need to enter conda activate proteus.

Updating PROTEUS

conda activate proteus (if not already activated)
proteus update-all

Developer install

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 it is best to add this line to your shell rc file .
```
mkdir /your/local/path/FWL_DATA
echo "export FWL_DATA=/your/local/path/FWL_DATA/" >> "$HOME/.bashrc"
```
Reload your shell rc file to make the changes effective.
```
source "$HOME/.bashrc"
```

Download PROTEUS base

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

Create a virtual environment

conda create -n proteus python=3.12
conda activate proteus

Radiative transfer code (SOCRATES)

The code can be setup in ./socrates/ using the following script.
```
./tools/get_socrates.sh
```
The environment variable RAD_DIR must always point to the SOCRATES installation path. It is highly recommended that you add this to your shell rc file (e.g. ~/.bashrc), which can be done by running the following command.
```
echo "export RAD_DIR=$PWD/socrates/" >> "$HOME/.bashrc"
```
Reload your shell rc file to make the changes effective. Depending on your shell, you can do this by running:
```
source "$HOME/.bashrc"
```
Radiative-convective atmosphere model (AGNI)

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. It is important that AGNI is available at ./AGNI/ inside your PROTEUS folder. This can be either a symbolic link or the true location of the submodule.

The argument of provided to the script (integer from 0 to 20) indicates which tests AGNI should run. Here a value of 0 means that the tests are skipped.

Optional developer installation steps

Follow the steps in this section if you want to create editable installations of these submodules. Otherwise, go to the next step section.

MORS stellar evolution model

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

JANUS atmosphere model

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

CALLIOPE outgassing model

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

ARAGOG interior model

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

ZEPHYRUS escape model

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

Setup numerical computing library (PETSc)

You will need to do this particular step in an environment with Python <= 3.12.
```
./tools/get_petsc.sh
```
Setup interior evolution model (SPIDER)
```
./tools/get_spider.sh
```
Setup PROTEUS coupled framework
```
python -m pip install -e .
```
Enable pre-commit
```
pre-commit install -f
```
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 you should 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. To get PLATON and its dependencies, use the script below.

./tools/get_platon.sh

Note that 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 written in Python, however, it is not available in a cohesive package format. Obtain VULCAN using the script below.

./tools/get_vulcan.sh