Run multiple Autory models

Use autory run multiple to start multiple Autory runs from one batch config. The config can be a YAML file, a JSON file, or an Excel workbook containing a RunMultipleRuns table and, optionally, a RunMultipleOptions table.

Start a batch

Start the batch in one of these ways:

• Use the autory run multiple command and provide the path to a YAML file, JSON file, or workbook.
• The command accepts more than one input file. Each file is loaded and run as a separate batch config.
• The --parallel command-line option overrides the parallel option from each input config.
• Click Save & run multiple in the Autory Excel ribbon while a workbook is open.

Stop a batch

To stop a batch after it has started, see how to stop a run.

YAML and JSON config format

YAML and JSON configs use the same schema. The top-level type must be autory_run_multiple, and version is currently 1.

For config files read from disk, relative model paths and script paths are resolved relative to the config file's parent folder.

Example

type: autory_run_multiple
version: 1
options:
  parallel: 3
  pre_run_scripts:
    - python -m autory_cli dev no-op
    - [cmd.exe, /c, echo done]
  post_run_scripts: []
runs:
  - active: true
    group: 0
    weight: 0
    description: Baseline
    model: models/baseline.yaml
    run_control:
      AutoryEngine: pyxl
      RunDate: "2026-12-31"
      RunHierarchyLevel: 3
      RunHierarchyPath: ExampleHoldings
      RunStartValnType: Summary
      OutputFolder: "%temp%/autory/baseline"
    global_overrides:
      DiscountRate: "0.04"
      ScenarioLabel: '"baseline"'

The model field is required in YAML and JSON files.

Fields

Field	Data type	Default	Description
type	Text	Required	Must be autory_run_multiple.
version	Integer	Required	Must be 1.
options.parallel	Integer	1	Number of simultaneous runs.
options.pre_run_scripts	Text, list of text commands, or list of argv lists	[]	Scripts to run before any models.
options.post_run_scripts	Text, list of text commands, or list of argv lists	[]	Scripts to run after all models.
runs[].active	Boolean	true	Whether to execute the run.
runs[].group	Integer	0	Runs in lower groups finish before runs in higher groups start.
runs[].weight	Number	0	Runs within a group start in ascending weight order.
runs[].description	Text	Model file name	Text shown in progress bars and logs.
runs[].model	Text	Required	Model file path.
runs[].run_control	Object	{}	Run control overrides for this run.
runs[].global_overrides	Object	{}	Global scalar formula overrides for this run.

run_control values are validated like other Autory run-control overrides.

global_overrides values are converted to global scalar formula strings in the same way as workbook Global → columns.

Inline and stdin configs

Use --config-json or --config-yaml to pass a short config directly on the command line:

autory run multiple --config-json '{"type":"autory_run_multiple","version":1,"runs":[{"model":"model.yaml"}]}' --base-dir C:\path\to\models
autory run multiple --config-yaml 'type: autory_run_multiple
version: 1
runs:
  - model: model.yaml' --base-dir C:\path\to\models

--config-json and --config-yaml can be specified more than once.

Use --stdin json or --stdin yaml to pipe a config from another process.

File paths, inline configs, and stdin configs can be mixed in one command; each source is loaded and run as a separate batch config.

PowerShell example:

Get-Content batch.yaml | autory run multiple --stdin yaml --base-dir C:\path\to\models
Get-Content batch.json | autory run multiple --stdin json --base-dir C:\path\to\models

POSIX example:

autory run multiple --stdin yaml --base-dir /path/to/models < batch.yaml
autory run multiple --stdin json --base-dir /path/to/models < batch.json

For inline and stdin configs, --base-dir is required. It controls how relative model paths and script paths are resolved. --base-dir has no effect when the config is read from a file.

Workbook format

Excel run-multiple workbooks use named tables. The RunMultipleRuns table defines the model runs, and the optional RunMultipleOptions table defines options for the whole batch.

RunMultipleRuns table

Column name	Data type	Example	Required
Active	Boolean	TRUE	Yes
Group	Integer	0	Yes
Weight	Number	0	Yes
Description	Text	Baseline	Yes
Model	Text	model.xlsx	Sometimes
RunControl →	-	-	No
Global →	-	-	No
Starting with _	-	-	No

RunMultipleRuns table example

Active	Group	Weight	Description	Model	RunControl →	RunDate	RunHierarchyLevel	Global →	DiscountRate	ScenarioLabel
TRUE	0	0	Example 1	model1.xlsm		2026/12/31	3		0.04	"baseline"
FALSE	0	1	Example 2	model2.xlsm		2027/12/31	3		0.05	"stress"

Active column

This column controls whether a run is executed or skipped.

• Runs for which this column evaluates to something truthy, such as TRUE or 1, are executed.
• Runs for which this column evaluates to something falsy, such as FALSE or 0, are skipped.

Group column

Runs with the same group number are executed in parallel, if parallel execution is enabled. Runs with different group numbers are executed sequentially, in ascending order of the group number.

Runs that depend on the results of previous runs should have a higher group number than the runs they depend on. See reusing results from previous runs for how Autory reads those results from .feather output files.

Weight column

Runs within a group are started in ascending weight order.

For example, if the maximum number of parallel runs is 2 and there are four runs in group 0 with weights 0, 1, 2, and 3, then the runs with weights 0 and 1 start first. As soon as either finishes, the run with weight 2 starts, and so on.

Description column

A short description to help you identify the run in terminal progress bars and log files.

Model column

The path to the Autory model file to run. This may be an absolute path or a path relative to the current workbook's parent folder.

The Model cell may be left blank if the current workbook doubles as a model workbook. Otherwise, it is required.

Run control columns

The RunControl → column itself is only a marker. Columns to the right of this marker, until the next marker column or the end of the table, are treated as run control columns.

Use these columns to override run control options for individual runs.

Changes from Autory 2 to Autory 3

Run control columns must use Autory 3 names. If an Autory 2 RunMultiple workbook has columns such as RunFromHLevel, ValnTypesToOutput, or LoopWriteIterationsToSqlite, replace them with the current filter options: RunProjectionNodesFilter, OutputProjectionNodeFilter, OutputTimeStepFilter, or post-run autory convert results commands.

Global columns

The Global → column itself is only a marker. Columns to the right of this marker, until the next marker column or the end of the table, are treated as global scalar override columns.

Use these columns to override global scalar formulas for individual runs. The column name is the global scalar name, and the cell value is converted to a formula string. For text scalars, include quotes in the cell value, for example "baseline". Blank cells are ignored.

Columns starting with underscore

Columns starting with _ are always ignored. Use them for notes, formulas, checks, or any other workbook-only information.

RunMultipleOptions table

A table named RunMultipleOptions configures options for the entire batch of runs. It has at least two columns, Name and Value, forming key-value pairs.

The following options are supported:

Name	Example
parallel	2
PreRunScripts	one two
PostRunScripts

parallel option

The number of simultaneous runs to do. This can make better use of multicore CPUs when there are multiple runs.

Warning

Making this number too high may cause bottlenecks that slow down all runs instead of speeding them up. The ideal number depends on your CPU, RAM, disk speed, network speed, and the models being run.

PreRunScripts and PostRunScripts options

These options are similar to the PreRunScripts and PostRunScripts run control options, except that they run before or after the whole batch instead of before or after each model.

Tip

To change PreRunScripts or PostRunScripts for individual runs, add columns called PreRunScripts or PostRunScripts to the right of RunControl → in the RunMultipleRuns table.

Convert between formats

Use autory convert run-multiple to convert between YAML, JSON, and workbook formats:

autory convert run-multiple batch.xlsx --output-format yaml
autory convert run-multiple batch.yaml --output-path batch.json
autory convert run-multiple batch.yaml --output-path batch.xlsx

Conversion preserves the run/options table values, row order, scripts, run-control values, global scalar overrides, and relative paths. Conversion does not preserve ignored workbook _... columns, workbook styling, comments, formulas, or arbitrary sheet layout when writing a new workbook.

If the output file already exists, --existing controls what happens:

• error: Leave the file unchanged and exit with an error. This is the default.
• skip: Leave the file unchanged and exit successfully.
• overwrite: Delete the existing file and write a new one.
• update: If the output file is an existing workbook, update or create the RunMultipleOptions and RunMultipleRuns tables. For other output file types, this is the same as overwrite.
• prompt: Ask what to do, using the selected UI mode.

Limitation

Only .xlsx and .xlsm workbooks can be updated. New workbooks can only be created as .xlsx.