Running and output

This page covers how to launch a single PROTEUS simulation from the command line, how to run it on a remote machine, where the results are written, and how to archive them. For running many simulations at once, see Parameter grids.

Running PROTEUS from the terminal

PROTEUS has a command-line interface (CLI) accessed by running proteus on the command line. Run proteus --help to list the available commands. To run a simulation:

proteus start -c [cfgfile]

where [cfgfile] is the path to the configuration file. A good first test is the all_options.toml config in the input folder:

proteus start -c input/all_options.toml

This writes its results to a timestamped output/run_<timestamp>_xxxx/ folder inside your PROTEUS directory, because the config sets params.out.path = "auto". Set path to a fixed string in the config to choose the folder name instead. See the configuration guide for how to edit configuration files and an explanation of their structure.

The most useful flags for proteus start are:

Flag	Effect
`-c, --config [cfgfile]`	Path to the configuration file (required).
`--offline`	Skip the check for lookup tables and reference data to download. Use when the data is already present.
`--resume`	Resume the simulation from the state saved on disk rather than starting from `t = 0`.
`--deterministic`	Pin the JAX/XLA reduction order on top of the always-on BLAS thread pins. Use this when a coupled run fails on noise-floor floating-point divergence between launches (see troubleshooting).

By default PROTEUS checks whether any lookup tables or data need to be downloaded before it runs; pass --offline to disable that check.

Long runs

A coupled simulation can run for hours. Detach it from the terminal so it survives disconnects, for example with nohup:

nohup proteus start --offline -c input/all_options.toml > output/launch.log 2>&1 &

On a remote machine, tmux is usually more convenient (see below).

Running PROTEUS on remote machines and servers

Using PROTEUS on a remote machine (for example Habrok or the Kapteyn cluster) is best done through tmux, which keeps programs running in the background for long periods. Full documentation is here.

Start a new tmux session:
```
tmux new -s <session_name>
```
Inside the session, start your simulation:
```
proteus start -c input/all_options.toml
```
Detach from the session with Ctrl + b, then d. Reattach later with:
```
tmux attach -t <session_name>
```
List all sessions with tmux ls, and kill one with tmux kill-session -t <session_name>.
The simulation stores its output in the PROTEUS output/ folder. Check progress by reading the log files there.
To see whether you are using CPUs on the cluster, run htop -u $USER; press Ctrl + c to exit.

For site-specific instructions, see the cluster guides: Kapteyn, Snellius, and Habrok.

Output and results

A PROTEUS simulation creates several types of output file. With params.out.path = "auto" (as in the all_options example) the results land in a timestamped output/run_<timestamp>_xxxx/ folder. The tree below outlines the purpose of the main files and subfolders:

run_<timestamp>_xxxx/
 ├─runtime_helpfile.csv         <---- table containing the main simulation results
 ├─proteus_00.log               <---- the log file from the simulation
 ├─init_coupler.toml            <---- a completed copy of the configuration file
 ├─status                       <---- status of the simulation
 ├─data/
 │ ├─files ending in _atm.nc    <---- atmosphere data
 │ ├─files ending in .json      <---- interior data
 │ └─data.tar                   <---- atmosphere & interior data archive
 ├─observe/
 │ └─files ending in .csv       <---- synthetic/simulated observations of the planet
 ├─offchem/
 │ ├─vulcan.csv                 <---- atmospheric mixing ratios (offline mode)
 │ └─vulcan_{year}.csv          <---- per-snapshot mixing ratios (online mode)
 ├─plots/
 │ ├─plot_chem_atmosphere.png   <---- plot of atmospheric mixing ratios
 │ ├─plot_escape.png            <---- plot of volatile inventories over time
 │ ├─plot_global_log.png        <---- plot containing an overview of the simulation
 │ └─other files                <---- any other plots

The full column layout of runtime_helpfile.csv and the data-file formats are documented in the output format reference.

To make plots manually, use proteus plot. For example, to plot the atmosphere temperature profiles:

proteus plot -c input/all_options.toml atmosphere

To make every available plot:

proteus plot -c input/all_options.toml all

Archiving output files

A simulation can generate a large number of files, which becomes a problem when running large parameter grids. The params.out.archive_mod configuration option tells PROTEUS when to gather a run's output files into .tar archives.

Archiving makes the files inaccessible for analysis or plotting. Extract the archives from a run using:

proteus extract-archives -c [cfgfile]

This is reversible. To pack the data files back into .tar archives:

proteus create-archives -c [cfgfile]