Overview

The SKIRT radiation transfer simulation code is exposed to the user as a command line program to be executed in a terminal window. SKIRT features a wealth of built-in models, mechanisms, and options that require configuring by the user. All options defining a single, complete SKIRT simulation are stored in a SKIRT parameter file with the filename extension ".ski". Such a parameter file is customary called a ski file (pronounced to rhyme with "me"). The data format of ski files allows efficient manipulation by computers, while being sufficiently transparent for viewing and editing by humans. The ski file format is further discussed in The SKIRT parameter file format (ski file).

The SKIRT command line program can be invoked in one of two modes (depending on the command line arguments):

In interactive mode, SKIRT asks the user a series of questions (via console input/output in the terminal window), and it constructs a ski file based on the user's responses. The resulting ski file is saved for later use, without actually performing a simulation at this point.
In non-interactive mode, SKIRT performs one or more simulations as specified in preconfigured ski files and produces the corresponding output. In this mode, SKIRT expects no user input other than the command line arguments, so it is ideal for batch processing.

Interactive mode

When invoked without any command line arguments, SKIRT enters interactive mode. For example:

$ skirt
   Welcome to SKIRT v___
   Running on ___ for ___
   Interactively constructing a simulation...
 ? Enter the name of the ski file to be created: example

   ___more questions and answers___

   Successfully created ski file 'example.ski'.
   To run the simulation use the command: skirt example
$

The time stamp preceding each line, the version information on the welcome line, and the list of questions to configure the simulation parameters are omitted here for brevity. After all questions have been answered, SKIRT saves a new ski file (here called example.ski) and exits.

So that they would stand out, questions are marked with a question mark at the front and error messages are marked with an asterisk. For example:

 ? Enter the name for this instrument:
 * *** Error: Enter a nonempty string
 ? Enter the name for this instrument: xy

Where appropriate, the question lists the range of acceptable values between square brackets, as in [minValue,maxValue]. Often there is a default value, listed between round brackets at the end of the question. To select the default value, enter the empty string. For example, here the user is asked to select an item from a list, with extragalactic units as the default:

   Possible choices for the units system:
      1. SI units
      2. Stellar units (length in AU, distance in pc)
      3. Extragalactic units (length in pc, distance in Mpc)
 ? Enter one of these numbers [1,3] (3):

For physical quantities, the default units are listed in the question as part of the minimum, maximum and/or default values. To use the default units, simply enter a number. To explicitly specify units, enter a number followed by a space and a unit abbreviation (see Supported units). For example, the following two inputs are equivalent:

 ? Enter the outer radius [0 pc, .. pc]: 8000
 ? Enter the outer radius [0 pc, .. pc]: 8 kpc

Boolean questions can be answered with the strings "yes" or "no", or just the first letter "y" or "n", in lower- or uppercase. For example:

 ? Do you want to include support for polarization? [yes/no] (no): yes

Non-interactive mode

When invoked with the name of a ski file as the sole command line argument, SKIRT performs the simulation configured in the ski file, reading any required input files (specified in the ski file) from the current directory, and placing any output files in the current directory as well. For example:

$ skirt example
   Welcome to SKIRT v___
   Running on ___ for ___
   Constructing a simulation from ski file 'example.ski'...
   Starting simulation example...

   ___more progress messages___

 - Finished simulation example in __ s.
$

SKIRT can perform multiple simulations in one go, and also supports a number of command line options according to the following syntax:

 skirt [-t <threads>] [-s <simulations>]
       [-b] [-v] [-m] [-e]
       [-k] [-i <dirpath>] [-o <dirpath>]
       [-r] {<filepath>}*

The -t option specifies the number of parallel execution threads used for each simulation. The default value is the number of logical cores on the computer running SKIRT, with a maximum of 24. On desktop computers this default number is usually appropriate. On larger computing systems it is often wise to explicitly specify the number of threads. Although the system might have many processing cores, it is almost never meaningful to run SKIRT with more than 24 threads per process. For more information, see Parallel execution threads.
The -s option specifies the number of simulations to be executed in parallel. The default value is one. For more information, see Multiple parallel simulations.
The -b option forces brief console logging, i.e. only success and error messages are shown rather than all progress messages. If there are multiple parallel simulations (see the -s option), the -b option is turned on automatically to avoid a plethora of randomly intermixing messages. If there is only one simulation at a time, the console shows all messages unless the -b option is present. In any case, the complete log output for each simulation is always written to a file in the output directory.
The -v option enables verbose logging for simulations running with multiple processes, causing each process to create its own log file (rather than relying on the root process to log all relevant information). For more information, see Multiple processes (MPI).
The -m option causes information on current memory usage to be included in each log message.
The -e option activates emulation mode, which can be used to estimate the amount of memory used by a given simulation without actually performing the simulation. For more information, see Emulation mode below.
The -k option causes the simulation input/output paths to be relative to the ski file being processed, rather than to the current directory. This is useful, for example, when processing multiple ski files organized in a nested directory hierarchy (see the -r option).
The -i option specifies the absolute or relative path for simulation input files.
The -o option specifies the absolute or relative path for simulation output files.
The -r option causes recursive directory descent for all specified <filepath> arguments, in other words all directories inside the specified base paths are searched for the specified filename (or filename pattern).

In the simplest case, a <filepath> argument specifies the relative or absolute file path for a single ski file, with or without the ".ski" filename extension. However, the filename (not the base path) may also contain ? and * wildcards forming a pattern to match multiple files. If the -r option is present, all directories recursively nested within the base path are searched as well, using the same filename pattern. If the filename contains wildcards or the -r option is present (in other words, if the filepath may match multiple files) the ".ski" filename extension is not automatically added.

Note: Filepaths containing wildcards should be enclosed in quotes on the command line to avoid expansion of the wildcard pattern by the shell.

For example, to process all "test" ski files inside the "geometry" directory hierarchy, one could specify:

skirt -t 4 -r "/root-test-file-path/geometry/test*.ski"

When invoked with invalid command line arguments, SKIRT prints a brief help message.

Output files

A typical simulation run produces quite a few output files. The precise set depends on the contents of the ski file. However all output filenames for a particular simulation start with the name of the ski file (plus an underscore).

Two "standard" files are always generated for every simulation (assuming a ski file named example.ski):

example_log.txt contains the complete progress log for the simulation, including all messages even if the -b option is turned on. It is a plain text file using UTF-8 encoding (i.e. essentially a plain ASCII text file).
example_parameters.xml contains a version of the SKIRT parameter file corresponding to the simulation, in the format described in The SKIRT parameter file format (ski file). This output parameter file is regenerated after the incoming ski file has been interpreted by SKIRT, eliminating any ambiguities. For example, optional parameters that were omitted from the incoming ski file will be added to the output parameter file with the default value used for the simulation. To avoid confusion, the generated parameter file does not have the ".ski" filename extension. However the file can be renamed (possibly after manual editing) to serve as a regular ski file.

Many of the other output files are described in the tutorials offered in the Tutorials section on this web site.

Emulation mode

To get an estimate of the amount of memory required for a particular SKIRT simulation, SKIRT can be executed in emulation mode. In this mode, SKIRT will limit the amount of computation while still traversing most relevant simulation steps. At the end, an estimate of the amount of required memory will be stated. Emulation mode can be invoked by passing the '-e' command line option to the SKIRT executable.

skirt -e example.ski

The behaviour of the other command-line arguments is unchanged when using the emulation option. Multiprocessing is also supported (see Multiple processes (MPI)). To invoke emulation mode with multiple processes, use, for example:

mpirun -np 2 /path/to/executable/skirt -e -v example.ski

The amount of memory stated at the end of the console output applies to just the root process. The memory requirements for the other processes can be found a the end of the log file for each process.