Skip to content

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 Autory Excel ribbon 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"'
Profile boolean ❌ TRUE "TRUE"
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 old Save & Run button in a model workbook, not when using 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.

Common values are:

  • pyxl or python-excel for the Python-Excel engine.
  • pyjl or python-julia for the Julia engine, if the separate Julia engine distribution is installed.
  • vba for the deprecated VBA engine.

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 used when starting a run from Excel with the Autory Excel ribbon or the old Save & Run button in a model workbook. When running a model from the command line, you can set the log level using the --log-level command line option.

Detailed logs are written to .AutoryLog files. See how to view run logs for how to open them in the Autory log viewer.

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, Autory 3 always writes the per-iteration results to .feather output files. 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. If a later run must reuse those projection node results from the disk, make sure they are not excluded here.

Changes from Autory 2 to Autory 3

OutputProjectionNodeFilter replaces OutputCapValuationDates, OutputFromHLevel, OutputFromValnDate, OutputToHLevel, OutputToValnDate, and ValnTypesToOutput. Put the old limits into one formula, for example AND(hLevel>=2,hLevel<=3,OR(valnType="Summary",valnType="Detail")).

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. If a later run must reuse these projection node results from the disk, consider writing all time steps.

Changes from Autory 2 to Autory 3

OutputTimeStepFilter replaces OutputFromProjectionDate, OutputProjectionPeriods, and OutputProjectionMonthsIntervalMonths. Put the old date, period, and interval limits into one formula, for example AND(Date>=DATE(2024,5,31),t<=12,MOD(t-1,3)=0).

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.

Profile

Whether to profile the performance of the run.

When this is TRUE, Autory writes profiling statistics to the log directory. This is intended for troubleshooting slow models or comparing performance changes. For normal production runs, leave this as FALSE.

RunChildNodes

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

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. See reusing results from previous runs for how Autory decides whether to recalculate, reuse, or ignore a projection node.

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.

Changes from Autory 2 to Autory 3

RunProjectionNodesFilter replaces CapValuationDates, RunFromHLevel, RunFromValnDate, RunOnlyOneValnType, RunOnlySomeValnTypes, RunToHLevel, RunToValnDate, runValnTypeToRun, and runValnTypesToRun. Put the old limits into one formula, for example AND(hLevel>=2,hLevel<=3,valnDate>=DATE(2024,12,31),valnType="Summary").

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.