Skip to main content

Command line and options

🧠10% 🤖90%

This page lists the starsim command that comes with Starsim, and Starsim’s global options (ss.options), which can be set from Python or from the shell.

The starsim command

Installing Starsim also installs a starsim command, for setting up an environment and converting models (starsim lists these, and starsim <command> --help the options of each):

Command What it does
starsim init Once, after installing: starsim init ai if an AI coding agent is installed, then starsim init compile unless the Rust backend is in use (-y not to ask)
starsim init compile Compiles the Numba backend ahead of time, as ss.compile() does (a few minutes, once per install); optional, since it is otherwise compiled on first use. --rust builds the Rust backend instead, in a clone of Starsim; --check says which backend is in use and whether it is compiled, exiting with 1 if not
starsim init ai Links the Starsim skills for AI coding agents into this project, as starsim ai install does; --global installs a short skill for all projects, --to=claude,agents chooses the agents, and --force replaces a skill of the same name
starsim init dev For a clone of Starsim: also the development dependencies, Rust if it is missing, and both compiled backends (Rust and Numba)
starsim ai Where the skills are installed; list, show (the guide, or one skill), install and uninstall, and off and on (whether other commands suggest the skills)
starsim convert model.R Converts a model to Starsim code (model.py), telling the format from the file (or --from=); --to= another format, --out= the file, --force to replace it. starsim convert lists the formats
starsim convert laser_model.py --ai Has an AI coding agent do the conversion, with Starsim’s skills (--headless to run it on its own; --ai=claude names the agent, by default the one in STARSIM_AGENT or the only one installed)
starsim import model.camdl The same as starsim convert model.camdl --to=starsim; a second argument gives the format (starsim import model.json epipack), and other options go to the importer (--databook=data.xlsx)
starsim export model.py sbml Writes the sim that model.py makes (as sim, or --sim=) in another format
starsim --version The version of Starsim

Options

Starsim’s global options are in ss.options: set one for the session with ss.options(threads=1), for a block with with ss.options(threads=1):, or before Python starts with STARSIM_ and the option’s name in capitals (STARSIM_THREADS=1), which is the way to set it for every worker or every task of a cluster job. ss.options.help() lists them all, with what each does; they are also in the API reference. The ones most often changed:

Option What it does
verbose How much a sim prints: 0 for nothing, e.g. in a batch of runs
warnings What to do with a warning: 'warn' (default), 'print', 'error', or 'ignore'
backend How the numbers are computed: 'auto' (default), 'rust', 'numba', 'python', or 'jax'
threads Threads for the passes over the agents of a large sim; 1 on a cluster, where tasks already run in parallel
style The plotting style: 'starsim' (default), 'simple', or a Matplotlib style

Further reading

  • Speed and scale: compiling once, threads, and running on a cluster
  • Import/export: what starsim convert, import, and export do, format by format
  • Running sims: the settings of a sim, as opposed to the global options