TOML Input Files

There are two ways to use Starlord: importing it in Python and using the API, or defining a model in a TOML file and passing it to Starlord on the command line. The latter is an easier place to start. Here’s a minimal example using the demo grid (created in Grid Management):

[model]
# Starting with the likelihood terms, based on demo grid outputs
# The demo grid is defined in Grid Management docs, but it's just:
# x, y -> out1, out2; ratio
demo_grid.out1 = ["normal", 30.5, 3.0]
demo_grid.ratio = ["normal", 0.3, 0.05]
# grid.output_name = [distribution name, the parameters]

# This implicitly defined x and y (the demogrid params),
# so we must set their priors:
prior.x = ["uniform", 0, 10.0]
prior.y = [5.0, 2.0]
# (An omitted distribution name implies "normal")

[sampling]
# Picking a sampler and settings its options
sampler = "emcee"
emcee_run.nsteps = 1000

[output]
# Print a summary to the terminal and write the samples to "demo.npz"
terminal = true
file = "demo.npz"

Notice that it has three sections: model, sampling, and output. The first sets up the statistical model to be fitted, including any likelihood terms, priors, and intermediate variable definitions (see Defining a Model). The next section, sampling lets you select the sampler and the options for it, as well as run-time constants (see Sampling). Finally, the output section defines what Starlord should actually do with the data. For now this is quite minimal – you can set terminal output on or off and select a file to write the results to in the npz format. If you omit this, no output file is written.

Note

When you specify a grid variable, Starlord will handle interpolation and set inputs automatically according to the grid’s defaults. This can including interpolating additional grids or defining new parameters. Use starlord -da your_model.toml to see how Starlord interprets your model.

Recommended Workflow

Starlord can do fairly complicated things with your model specification, so we suggest this workflow to best avoid errors:

1. Select or create the grid you wish to work with (see Grid Management). Use starlord -g to see available grids and starlord -g grid_name to examine one in detail.

2. Create a TOML file and list your constraints under the heading [models] like grid.var = ['normal', 3.4, 2.0] (distribution and parameters, see starlord.ModelBuilder).

3. Check that your model is being interpreted as you expect with starlord -da your_model.toml, and review the list of parameters.

4. For each model parameter, set a prior with prior.param_name = ['normal', 2.3, 5.3]

5. Check your model with a test case using starlord -dt 1.,2.,3. your_model.toml; parameters are comma-separated with no spaces, in order listed by step 3.

6. Run the sampler with starlord your_model.toml -o samples.npz.

Note

This mentions only the basic options. See Sampling for configuring the sampler and Defining a Model for other modelling options like grid input overrides and runtime constants.