Setup Files

Overview

Simulations are initialized via text-based setup files. A simulation can include models from multiple model libraries, each with a specified integrator. Parameters and states can be initialized to specific values in the setup file.

The DSimManager application supports the creation and modification of setup files, which are xml. The application includes a test facility to ensure the simulation you have created will run.

This page describes the directives used in the xml files.

Directives

The required fields are:

• startJD The simulation epoch in Julian date.
• timeStep The simulation time step in seconds.
• startSeconds The simulation start time step in seconds.

Additional possible directives are:

• name The name of the simulation.
• maxTimeStep The maximum time step allowed. This cannot be less than the nominal timeStep.
• endSeconds The simulation end time in seconds. This must be greater than startSeconds.
• timeScale The simulation time scale ratio, sim time/real time. A time scale of -1 will tell the simulation to run as fast as possible.
• outputLogFile The path to the message log file.
• dataLogFile The path to the data log file.

Objects

The object tree is the heart of the DSim setup file. A simulation requires at least one object in the tree. Each object can have children. The directives required for each object are:

• name The human-readable name of the object.
• type The model class of the object.
• library The path to the model library containing the class.
• integrator The name of the integrator to use.

The additional possible fields are:

• telemetry Mark the named variable as a telemetry point.
• command Mark the named variable as a command.
• logVariable Log the named variable to the data log file.
• child Children objects
• setValue Set a variable value, with the subfields variable and value
• dependency An object on which this object is dependent
• connectOutlet Connect one model's variable to another model's outlet, with the subfields variable and source.
• connectTarget Connect a target, with the subfields name and target.

Setup directives

A model may accept custom setup commands. For instance, files may need to be loaded for a particular model. This is handled with subfields key and value. The model is responsible for appropriately handing the setup keys in the dsim_model::parse_setup() function. An example loading a JPL ephemeris file is shown below.

    <setup>
        <key>AddSPKFile</key>
        <value>/Library/Application Support/VisualCommander/Model Libraries/de414.bsp</value>
    </setup>
    

See the Model Initialization module.

Attributes

Attributes can be set up programmatically in a model, or ad hoc in a setup file. See the Model Attributes module. In the setup file, the attribute directive can be used with name and value fields.

Integrators

The integrators used in the simulation are introduced in the header of the simulation and then referenced as needed by each object. For instance, you might have RK4 and RK78 both listed and then used for different objects. Integrators must be specified by library and type (class) and may also have custom setup directives.

• name The human-readable name of the object.
• type The model class of the object.
• library The path to the model library containing the class.
• setup key/value pairs for custom setup directives. For instance, setting a tolerance or minimum timestep for a variable step integrator.

Setup File

The example file shown below contains a single integrator and a single second-order object. The setup file must specify at least one integrator and at least one object in the object tree to have a functional simulation.

     <Simulation>
        <version>1</version>
        <timeStep>0.01</timeStep>
        <startSeconds>0</startSeconds>
        <startJD>2455623.953075618</startJD>
        <timeScale>1</timeScale>
        <name>Second Order Dynamic Simulation</name>
        <integrator>
            <name>RK4</name>
            <type>DSimRK4</type>
            <library>builtin</library>
        </integrator>
        <objectTree>
            <object>
                <name>second_order</name>
                <type>DSimSecondOrder</type>
                <library>builtin</library>
                <integrator>RK4</integrator>
                <logVariable>yDotDot</logVariable>
                <logVariable>yDot</logVariable>
                <logVariable>y</logVariable>
            </object>
        </objectTree>
    </Simulation>
    

A variable is set using the following lines:

    <setValue>
        <variable>my_state</variable>
        <value>0.1</value>
    </setValue>
    

An outlet is connected using the follow lines:

    <connectOutlet>
        <variable>myVar</variable>
        <source>Parent1|Child1:param1</source>
    </connectOutlet>
    

An additional example using some of the builtin models with logging is shown below. This example also includes a child object and setting of some variable initial values. Observe that the dependency setting uses the following path to the child spring object: PointMass|Spring.

<Simulation>
    <version>1</version>
    <comments>This is a test simulation, only really good for verifying that DSim is properly doing integration and that DSim Manager can properly read and write files.</comments>
    <timeStep>0.1</timeStep>
    <maxTimeStep>0.1</maxTimeStep>
    <startSeconds>0</startSeconds>
    <endSeconds>10</endSeconds>
    <startJD>2451816.51111</startJD>
    <timeScale>1</timeScale>
    <dataLogfile>SpringData.log</dataLogfile>
    <name>Example Simulation</name>
    <integrator>
        <name>primary</name>
        <type>DSimRK4</type>
        <library>builtin</library>
    </integrator>
    <objectTree>
        <object>
            <name>PointMass</name>
            <type>DSimRigidBody</type>
            <library>builtin</library>
            <integrator>primary</integrator>
            <setValue>
                <variable>position</variable>
                <value>[0; 1; 0]</value>
            </setValue>
            <setValue>
                <variable>velocity</variable>
                <value>[0; 2; 0]</value>
            </setValue>
            <dependency>PointMass|Spring</dependency>
            <logVariable>position</logVariable>
            <logVariable>velocity</logVariable>
            <telemetry>mass</telemetry>
            <telemetry>position</telemetry>
            <telemetry>velocity</telemetry>
            <command>mass</command>
            <child>
                <name>Spring</name>
                <type>DSimIdealSpring</type>
                <library>builtin</library>
                <integrator>primary</integrator>
                <connectTarget>
                    <name>mass</name>
                    <target>PointMass</target>
                </connectTarget>
                <telemetry>x0</telemetry>
                <telemetry>k</telemetry>
                <command>k</command>
            </child>
        </object>
    </objectTree>
</Simulation>

Since the setup files are actually text files, they are easy to configuration manage. They can also be compared against each other in a file merge utility.