Run control

Run control options are global settings that determine what happens when you run the model (e.g., by clicking Save & Run in the model workbook or running a command such as autory run direct).

See this guide for how to set run control options in your model.

Here is an alphabetical list of run control options with their data types:

Name	Data type	Variable? ¹	Example in Excel ²	Example in YAML ² ³
AutoryAppDir	string	❌	C:\autory	—
AutoryEngine	string	❌	pyxl	'"pyxl"'
BcSqliteDoubleQuotedStringLiterals	boolean	❌	FALSE	"FALSE"
ExcelVisible	boolean	❌	TRUE	"TRUE"
LogLevel	string	❌	Info	—
LoopIterationFilter	formula	❌	VarOne>2	VarOne>2
LoopTimeStepFilter	formula	❌	t=1	t=1
LoopWriteIterationsToWorkbook	boolean	❌	TRUE	"TRUE"
OutputFolder	string	✅	%temp%\folder	'"%temp%\folder"'
OutputProjectionNodeFilter	formula	❌	hLevel>=2	hLevel>=2
OutputSingleWorkbook	boolean	❌	TRUE	"TRUE"
OutputTimeStepFilter	formula	❌	t=1	t=1
PostRunScripts	string	❌	post.cmd	'"post.cmd"'
PreRunScripts	string	❌	pre.py	'"pre.py"'
RunChildNodes	boolean	❌	TRUE	"TRUE"
RunDate	date	✅	31 December 2024	DATE(2024,12,31)
RunHierarchyLevel	integer	✅	2	"2"
RunHierarchyPath	string	✅	One|Two|Three	'"One|Two|Three"'
RunProjectionNodesFilter	formula	❌	hLevel>=2	hLevel>=2
RunStartValnType	string	✅	Summary	'"Summary"'
SqlDialect	string	❌	duckdb	'"duckdb"'

Notes:

1. ↑ Some options are available as global variables to use in your variable library.
2. ↑ Some options are only available in Excel model workbooks, and not in YAML or JSON model files.
3. ↑ In YAML or JSON model files, all options are defined as formulas, which should evaluate to the expected data type for the option. Therefore:
   • For booleans, use "TRUE", not TRUE.
   • For numbers, use "2", not 2.
   • For dates, use DATE(2024,12,31), not "2024-12-31".
   • For strings, use '"Summary"' or "'Summary'", but not "Summary" or 'Summary' or Summary.
   • Other formulas may be written verbatim, as long as they don't look like special YAML syntax.

AutoryAppDir

Look for Autory in this directory instead of the default installation directory.

This is an advanced option used when testing multiple versions of Autory on the same computer. If in doubt, leave this cell blank.

This is only applicable when clicking the Save & Run button in the model workbook (not in the Autory Excel ribbon), as it determines which autory command line to use when there are multiple installations.

See this guide for more information.

AutoryEngine

The name of the Autory calculation engine to use.

BcSqliteDoubleQuotedStringLiterals

Backward compatibility option for SQLite string literal syntax.

When TRUE, double-quoted string literals are allowed, but will cause a warning to be logged. When FALSE, double-quoted strings are expected to be identifiers like in most SQL dialects.

See this explanation for more information.

This option:

• does not exist before Autory 3.
• defaults to TRUE in Autory 3.
• will default to FALSE in a future Autory version.
• will be removed in a more distant future Autory version.

ExcelVisible

Whether to show or hide the Excel application window during the run. This is only applicable when using an Excel-based calculation engine.

LogLevel

This determines the level of logging shown in the terminal window during the run.

This is only applicable when clicking the Save & Run button in the model workbook. When running a model from the command line, you can set the log level using the --log-level command line option.

LoopIterationFilter

A formula to determine which iterations to output when performing iterative calculations. This formula is evaluated for each iteration, in every projection node that contains iterative calculations. When it returns true, the iteration is included in the output.

LoopTimeStepFilter

A formula to determine which time steps to output when performing iterative calculations. This formula is evaluated for each time step of each iteration, in every projection node that contains iterative calculations. When it returns true, the time vectors for that time step are included in the output.

Not to be confused with OutputTimeStepFilter. This applies to the per-iteration results, not the aggregated results.

LoopWriteIterationsToWorkbook

When performing iterative calculations, the per-iteration results are always written to the .feather output files (from Autory 3). When this option is TRUE, the per-iteration results are also written to the .xlsx output files. Otherwise, the .xlsx output files contain only the final, aggregated results.

OutputFolder

Where to write the results of the model when it runs.

This is the path to a folder, not a file. It may be an absolute path, like C:\my\work, or a relative path, like output. Relative paths are relative to the folder in which the model workbook resides. Leaving the cell empty is the same as specifying ., which is the model workbook's folder.

OutputProjectionNodeFilter

A formula to determine which projection nodes from the projection node tree to output.

Not to be confused with RunProjectionNodesFilter. This prevents the output of certain projection nodes from being written, but it does not prevent them from running.

OutputSingleWorkbook

When this is TRUE, all projection nodes are written to a single output workbook. When this is FALSE, each projection node is written to a separate output workbook.

OutputTimeStepFilter

A formula to determine which time steps to output. This formula is evaluated for each time step of the aggregated results of every projection node. When it returns true, the time vectors for that time step are included in the output.

Not to be confused with LoopTimeStepFilter. When doing iterative calculations, this applies to the aggregated results, not the per-iteration results.

PreRunScripts and PostRunScripts

Run commands before or after the rest of the model.

• Separate multiple commands by newlines.
• Each command must use POSIX command line syntax.
• The working directory is the folder in which the model workbook resides.
• The first argument is the program, and receives special consideration:
  • If it's "autory", we use the current Autory installation's command line interface.
  • If it's "python", we use the current Autory installation's Python interpreter.
  • If it's a path (absolute or relative to the working directory) that exists on the disk:
    • If it's a .py file, we use the current Autory installation's Python interpreter to run it.
    • If it's a .ps1 file, we use powershell.exe to run it.
  • Otherwise, we let the operating system decide what to do with it.
    • .exe and .cmd files on Windows will be run directly as expected.

PostRunScripts

Run these commands after the rest of the model. If one fails, the subsequent scripts are not executed.

PreRunScripts

Run these commands before the rest of the model. If one fails, the subsequent scripts are not executed, and the model is not executed.

RunChildNodes

Whether to start projection nodes on every child node of RunHierarchyPath or just on the node at RunHierarchyPath.

• FALSE: A single starting projection node will be created on the starting hierarchy node (i.e., the one specified by RunHierarchyPath and RunHierarchyLevel.
• TRUE: A projection node will be created on the starting hierarchy node AND on each of its children in the hierarchy tree. In this case, there is more than one starting projection node.

In both cases, all precedents of the starting projection nodes will also be executed.

RunDate

The valuation date for the first projection node in the projection node tree.

Not to be confused with ProjectionStartDate or ValnDate.

RunHierarchyLevel

The hierarchy level to start on. This, together with RunHierarchyPath, determines the starting hierarchy node.

RunHierarchyPath

A pipe-separated list of hierarchy node names describing the path (from root to branch) of the hierarchy node to start on. This, together with RunHierarchyLevel, determines the starting hierarchy node.

RunProjectionNodesFilter

A formula to determine which projection nodes from the projection node tree to run.

When results are needed from a projection node that is excluded by this filter, the result files of a previous run will be used if available. Otherwise, the run will be stopped early with an error message.

Not to be confused with OutputProjectionNodeFilter. This prevents certain projection nodes from being run. If you want them to run, but not be included in the output, use OutputProjectionNodeFilter instead.

RunStartValnType

The valuation type of the starting projection node.

SqlDialect

The SQL dialect to use for SQL queries.

The default value is "duckdb". Specifying any other value will cause Autory to attempt to translate your SQL queries from the given dialect to the DuckDB dialect before executing the query.

The primary use case for this is to assist upgrading from Autory 2 (which defaulted to the "sqlite" dialect) to Autory 3 (which uses DuckDB as the default database engine and SQL dialect).

This does not affect SQL queries performed using sqlToTable, which always use the dialect of the target database engine.

Autory uses the sqlglot Python library to inspect and translate queries. See their list of supported dialects.

Do not change this option unless you have a specific reason to do so.