CLI Commands¶
The primary commands are tform mars maps for 3-D output,
tform serve for browser GCM exploration and
tform mars compare for cached reference reports.
Start with the GCM quickstart.
Deprecated global-mean commands
tform mars run, its global-mean presets and fast/accurate ODE modes are
deprecated. They remain documented for compatibility. GCM resolution presets
and its IMEX solver are separate from these integration modes.
tform mars maps¶
Generate 3-D pressure, temperature, winds and frost over MOLA terrain. Requires
the gcm3d extra and staged MOLA raster.
rtk proxy .venv/bin/python -m cli.main mars maps --scale fast --name first-map
rtk proxy .venv/bin/python -m cli.main mars maps --diurnal --dt 300 --steps 100 --name diurnal-smoke
| Option | Default | Purpose |
|---|---|---|
--scale |
fast |
Resolution/layer/timestep/step preset |
--truncation, --layers, --dt, --steps |
Preset | Explicit overrides |
--hyperdiffusion/--no-hyperdiffusion |
Enabled | Eighth-order spectral damping of winds and temperature |
--hyperdiffusion-tau-seconds |
Automatic | Shortest-mode e-folding time: 0.1 rotations at T42, scaled by 42/truncation |
--physics/--no-physics |
Physics | Grey radiation versus dry dynamics |
--co2/--no-co2 |
CO₂ | Energy-limited frost exchange; requires physics |
--diurnal/--daily-mean |
Daily mean | Illumination sampling |
--surface-properties |
None | Staged TES-style surface NetCDF |
--albedo, --greenhouse-factor |
0.25, 1.02 | Scalar surface/radiation settings |
--ls |
0 degrees | Starting solar longitude |
--name |
mars |
Output folder under outputs/gcm3d_maps/ |
The defaults do not reproduce the browser's full correlated-k baseline. See GCM quickstart for Python configuration, data requirements, output units and restart. The diurnal timestep guard is necessary but does not establish stability or climate equilibrium.
Damping leaves surface pressure, particle/gas tracers, surface temperature, frost
and soil untouched. Its resolved timescale is recorded in the physics description
and NetCDF attributes. Use --no-hyperdiffusion only for explicit numerical
comparisons; a finite short run does not establish long-term stability.
tform serve¶
The browser GCM uses correlated-k CO₂ radiation, regolith, stability exchange, PBL diffusion, dry convection and conservative CO₂ exchange. It attaches TES and seasonal Ames dust when available and uses the same resolution-dependent spectral diffusion default as CLI maps (0.1 rotations at T42). Its baseline CO₂/dust longwave scales are 0.25, with surface exchange 1.0; the UI exposes bounded calibration controls. See the GCM overview for how this differs from CLI maps.
Start the tform visualisation web server.
Launches a FastAPI server that accepts simulation run requests from the browser UI,
streams per-step physics data back in real time via Server-Sent Events, and serves
the pre-built React app from cli/static/. A browser tab opens automatically
after one second.
Options¶
| Flag | Type | Default | Description |
|---|---|---|---|
--port N |
int | 8000 |
Port to bind the server to |
--host ADDR |
str | 127.0.0.1 |
Host address to bind |
--no-browser |
flag | — | Don't open a browser tab automatically |
--dev |
flag | — | Also start the Vite dev server from ui/ on port 5173 |
Examples¶
# Start the server and open the UI (default)
tform serve
# Use a custom port
tform serve --port 9000
# Development mode — starts FastAPI on :8000 and Vite on :5173
tform serve --dev
# Headless (useful on a remote machine)
tform serve --no-browser
API endpoints¶
The server exposes a REST + SSE API consumed by the React UI:
| Method | Path | Description |
|---|---|---|
POST |
/api/runs |
Create and start a simulation run |
GET |
/api/runs |
List all runs (metadata, no data arrays) |
GET |
/api/runs/{id} |
Get full run including all data points |
GET |
/api/runs/{id}/events |
SSE stream — emits data points as they are computed |
GET |
/api/presets |
List available Mars presets |
GET |
/api/compounds |
List available GHG compounds |
GET |
/api/docs |
Interactive Swagger UI |
Data flow¶
Every integration step in the physics engine fires a callback. That callback writes one data point to an in-memory list. The SSE generator polls the list with a cursor and pushes new points to the browser, where Recharts re-renders the chart in real time.
TimeController.step() → callback(planet, t) → _runs[id].data.append()
↓
SSE /events stream
↓
React state → Recharts
For intervention runs the natural granularity is one point per Mars year
(via InterventionController's per-year callback). For sol/year runs the
per-step callback is throttled to at most 2 000 chart points.
Requirements¶
fastapi and uvicorn are included in the standard cli dependencies.
No separate install step is required beyond the usual uv sync.
To build the UI from source (only needed when modifying the frontend):
Reference comparison report¶
tform mars compare --config cli/configs/reference-comparison.json --output outputs/reference-comparison-new
Produces an offline HTML report, four-season comparison/difference grids, MOLA terrain, parameter and metric CSVs, source hashes, and AmesCAP map exports from cached model/Ames/MCD/ARCO NetCDFs. See reference comparisons for matching limitations and CAP usage. This command does not run a simulation.
Global Options¶
tform [OPTIONS] COMMAND [ARGS]...
Options:
--version Show version and exit.
--help Show help message.
Deprecated global-mean command reference¶
The following commands are retained for existing users. Use GCM maps for new work.
tform mars run¶
Run a Mars climate simulation.
Options¶
| Flag | Type | Default | Description |
|---|---|---|---|
--preset NAME |
str | current-mars |
Use a built-in preset as base config |
--config FILE |
path | — | YAML config file (merged over preset) |
--lat FLOAT |
float | preset value | Override latitude (−90 to 90) |
--lon FLOAT |
float | preset value | Override longitude (0 to 360) |
--sols N |
int | preset value | Number of sols (Martian days) to simulate |
--accuracy |
fast|accurate |
accurate |
Integration mode |
--type |
sol|year|multi|spots|intervention |
year |
Experiment type |
--no-plot |
flag | — | Suppress matplotlib output |
Experiment Types¶
| Type | Description |
|---|---|
sol |
Single Martian day (diurnal cycle) at a given lat/lon |
year |
One full Martian year (~687 Earth days) with seasonal cycles |
multi |
Three canonical latitudes: 45°N, equator, 40°S (all at 137°E) |
spots |
Four landmark sites: Olympus Mons, Elysium Mons, Hellas Basin, South Polar Cap |
intervention |
Multi-year GHG injection run from the preset's intervention schedule |
Accuracy Modes¶
| Mode | Method | Use Case |
|---|---|---|
accurate |
4th-order Runge-Kutta on full ODE system | Science runs, publications |
fast |
Reduced-order analytic/relaxation updates | Parameter sweeps, interactive exploration |
Examples¶
# Diurnal cycle at Hellas Basin
tform mars run --preset hellas-basin --type sol
# 10-year intervention with accurate integration
tform mars run --preset terraforming-phase1 --type intervention --sols 3435
# Custom latitude, no plots
tform mars run --preset current-mars --type year --lat 60 --no-plot
# Fully custom config
tform mars run --config experiments/my-run.yaml
tform mars config list¶
List all available built-in presets.
tform mars config show¶
Show the full resolved config for a preset.
Example:
tform mars config validate¶
Validate a YAML config file against the schema without running a simulation.
Example:
tform man¶
Show reference information for a planet or subsystem.
Example:
Config Priority Chain¶
When multiple config sources are provided, later sources override earlier ones:
This means --lat 45 always wins over whatever latitude is in the YAML file.