Structure of a ski file

A SKIRT parameter file (ski file) is an XML document stored using UTF-8 encoding. The structure of the XML elements and attributes closely mimics the run-time object hierarchy representing a simulation in the SKIRT code. For example, here is the contents of a minimal "no-operation" ski file:

<?xml version="1.0" encoding="UTF-8"?>
<!-- A SKIRT parameter file © Astronomical Observatory, Ghent University -->
<skirt-simulation-hierarchy type="MonteCarloSimulation" format="9">
    <MonteCarloSimulation userLevel="Basic" simulationMode="OligoNoMedium" numPackets="0">
        <units type="Units">
            <ExtragalacticUnits wavelengthOutputStyle="Wavelength" fluxOutputStyle="Frequency"/>
        </units>
        <sourceSystem type="SourceSystem" wavelengths="0.55 micron">
            <SourceSystem/>
        </sourceSystem>
        <instrumentSystem type="InstrumentSystem">
            <InstrumentSystem/>
        </instrumentSystem>
        <probeSystem type="ProbeSystem">
            <ProbeSystem/>
        </probeSystem>
    </MonteCarloSimulation>
</skirt-simulation-hierarchy>

An XML element called sample starts with a <sample> tag and ends with a </sample> tag. An empty element <sample></sample> can also be expressed with a single <sample/> tag. XML elements can be nested inside other elements. An XML element can carry zero or more attributes. Attributes are specified inside the start tag in the format key="value". In ski files there is no text outside of the element tags, except for spaces and line breaks. This white space is not meaningful except for presentation to a human. By convention the lines are indented so as to reflect the nesting level of the XML elements.

After the standard XML declaration (and an optional comment line), a ski file always defines the XML element skirt-simulation-hierarchy as the top-level or root element. The format attribute specifies the file format version number, which allows future version of SKIRT to detect and adjust for ski files in older formats. To represent a complete simulation hierarchy, further XML elements are nested recursively within the root element, and some of these elements carry attributes.

An element with a capitalized name (i.e. the first letter is uppercase) represents an object, i.e. an instance of a C++ class with the same name as the element. Such an element can carry attributes reflecting the scalar properties of the object, and can contain nested elements reflecting compound properties of the object. The value of a scalar property can be represented as a string (Boolean, integer number, floating point number with unit abbreviation, comma-separated list of such numbers, ...), while the value of a compound property is another object or a list of objects.

An element with a non-capitalized name (i.e. the first letter is lowercase) represents a compound property of the object represented by its parent element. Such an element always has a single attribute called type, which indirectly specifies the names of the XML element or elements that can be immediately contained inside the element. The type corresponds to the name of an abstract C++ class, and the names of the immediately contained element(s) must correspond to a C++ class that inherits the specified class.

Supported units

When SKIRT outputs a parameter file, it always uses the defaults of the units system selected by the ski file. However, when reading parameters in ski files and in interactive mode, SKIRT recognizes various unit abbreviations for physical quantities as listed in The SKIRT units system & supported units.

Editing a ski file

It is not a good idea to manually create a ski file from scratch, because the SKIRT simulation object hierarchy has many complexities that are easy to miss. Instead, to create a ski file use SKIRT's interactive mode (see Interactive mode) or the optional MakeUp utility (see MakeUp, the graphical interface for SKIRT parameter files) if it is available.

Once you have created a ski file, you can use any text editor to make small changes to it, such as updating the number of photon packets or adding an instrument. Many text editors offer syntax coloring for XML files (although you may need to setup the editor so that it recognizes the ".ski" filename extension in addition to .xml). Syntax coloring is nice but not really needed for working with ski files.

Based on the naming conventions explained in Structure of a ski file, it is fairly easy to locate the information about a particular option in the SKIRT reference documentation, even if you are not a developer:

A capitalized XML element name (i.e. the first letter is uppercase) corresponds to a C++ class name. For example, SourceSystem is a class name.
A non-capitalized XML element name (i.e. the first letter is lowercase) corresponds to a function name in the C++ class corresponding to the name of the XML element in which the non-capitalized element resides. For example, sourceSystem() is a function in the MonteCarloSimulation class.
An XML attribute name (except type) corresponds to a function name in the C++ class corresponding to the name of the element carrying the attribute. For example, wavelengths() is a function in the SourceSystem class.

Quick reference help for manual ski file editing can be found here: