Quick installation

This page outlines requirements and installation steps for the code. Currently, GNU/Linux and MacOS (including ARM) are supported.

Software requirements

Warning

Do not install Julia using your system package manager. Install only from julialang.org as below.

Installation

Install Julia's package manager (Mac and Linux):
```
curl -fsSL https://install.julialang.org | sh
```

Clone the repo

git clone https://github.com/FormingWorlds/Obliqua.git

Move to the repository directory
```
cd Obliqua
```
Open Julia package manager
```
julia
```
Install Obliqua
```
julia> ]
pkg> add .
```

Testing

If you want to run the tests manually, simply use the script located in the test/ folder. Run the follwoing command from the Obliqua root directory:

julia --project test/runtests.jl

This will print information on whether tests passed or failed.

Python environment (for output visualization)

Obliqua itself only needs Julia, but the visualize_output.ipynb notebook used to plot its results needs Python 3.12, installed via miniconda or miniforge.

Tip

If you already have a proteus conda environment set up (e.g. from installing PROTEUS), you can reuse it here instead of creating a new one — just conda activate proteus and skip to the last step below.

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

Install miniconda/miniforge in your personal directory

This gives you full control over your environment and is recommended even on shared/cluster systems.

Then, from the Obliqua repository directory, create and activate a Python 3.12 environment:

conda create -n obliqua python=3.12
conda activate obliqua

Install the notebook's plotting dependencies:

pip install numpy matplotlib netCDF4 jupyter cmcrameri proteus_mpl

Then launch the notebook:

jupyter lab visualize_output.ipynb