Skip to content

Installation

CALLIOPE is a pure-Python package with four runtime dependencies (numpy, scipy, matplotlib, and cmcrameri for plotting). It supports CPython 3.12 and 3.13.

pip install fwl-calliope

This is what the PROTEUS install pulls in by default; you do not need to install CALLIOPE separately if you have already installed fwl-proteus.

Clone the repository and install in editable mode so that your changes are picked up without reinstalling:

git clone https://github.com/FormingWorlds/CALLIOPE.git
cd CALLIOPE
pip install -e .

To also install the optional development tooling (pytest, pytest-cov, pytest-timeout, ruff, pre-commit, coverage, pip-tools):

pip install -e .[develop]

To install the documentation tooling on top of that:

pip install -e .[develop,docs]

The docs extra pulls in Zensical (the static site generator from the Material for MkDocs team, used to build this site), mkdocs, mkdocs-material, mkdocstrings[python], and markdown-include. With these installed you can run zensical serve from the repository root to serve a live-reloading copy of this documentation locally.

Verifying the install

import calliope
print(calliope.__version__)

Should print the current CalVer version (e.g. 25.05.04).

A minimal smoke-test that exercises the equilibrium solver:

from calliope.solve import equilibrium_atmosphere
from calliope.constants import volatile_species

ddict = {
    'M_mantle': 4.03e24,    # kg, Earth mantle mass
    'gravity': 9.81,        # m s-2
    'radius': 6.371e6,      # m, planetary surface radius
    'Phi_global': 1.0,      # fully molten
    'T_magma': 2500.0,      # K
    'fO2_shift_IW': 0.0,    # at IW buffer
}
for sp in volatile_species:
    ddict[f'{sp}_included'] = 1
    ddict[f'{sp}_initial_bar'] = 0.0

target = {'H': 1e20, 'C': 1e17, 'N': 1e17, 'S': 3e17}    # kg
result = equilibrium_atmosphere(target, ddict, print_result=False)
print(f"Surface pressure: {result['P_surf']:.2f} bar")

A successful run prints Surface pressure: 0.36 bar and logs no warning. Any exception means the install or the runtime environment is broken; check that numpy and scipy import cleanly and that you are on Python 3.12 or newer.

Next step

Once the import works, head to Configuration to learn what each input field means, then to Usage for the end-to-end calling pattern.