The FhSim input file

Table of Contents

• Overall structure
• Using XInclude to split input files
  • Example: shared simulation settings
• See also

A FhSim simulation scenario is defined in an XML input file. This file describes which SimObjects to use, how they are connected, their initial conditions, how the integrator should run, and what output to produce.

Overall structure

The input file must have a <Contents> root element containing the following sections:

<Contents>
    <VARIABLES>           <!-- optional -->
    ...
    </VARIABLES>
 
    <OBJECTS>              <!-- required -->
    ...
    </OBJECTS>
 
    <INTERCONNECTIONS>     <!-- required -->
    ...
    </INTERCONNECTIONS>
 
    <INITIALIZATION>       <!-- required -->
    ...
    </INITIALIZATION>
 
    <SIMULATION>           <!-- required -->
    ...
    </SIMULATION>
 
    <OBSERVERS>            <!-- optional -->
    ...
    </OBSERVERS>
</Contents>

Note

The order of sections within <Contents> does not matter.

Every number in an input file is unitless as far as FhSim is concerned — the engine defines no unit system and converts nothing. Units come from the SimObject library, and keeping them consistent is the scenario author's job. See Units and coordinate conventions, which also covers the comma-separated vector syntax and the Z-up visualisation convention.

Each section is documented on its own page:

Section	Purpose	Page
<VARIABLES>	Define reusable variables for $Variable substitution.	VARIABLES section
<OBJECTS>	Declare which SimObjects to load and their parameters.	OBJECTS section
<INTERCONNECTIONS>	Connect SimObject input ports to output ports or constants.	INTERCONNECTIONS section
<INITIALIZATION>	Set initial states for the SimObjects.	INITIALIZATION section
<SIMULATION>	Configure the integrator, timing, and simulation provider.	SIMULATION section
<OBSERVERS>	Configure output: file, console, network, visualisation, plugins.	OBSERVERS section

Using XInclude to split input files

FhSim input files support W3C XInclude via libxml2. This allows you to split a large input file into smaller, reusable fragments.

Declare the xi namespace on the root element and use <xi:include> to include other files:

<?xml version="1.0" encoding="utf-8"?>
<Contents xmlns:xi="http://www.w3.org/2001/XInclude">
 
    <OBJECTS>
        <!-- Include a shared set of environment objects -->
        <xi:include href="shared/environment_objects.xml"/>
 
        <!-- Define scenario-specific objects inline -->
        <Lib LibName="fhsim_base" SimObject="Body/Mass" Name="mass" Mass="1000"/>
    </OBJECTS>
 
    <!-- Include interconnections from a separate file -->
    <xi:include href="shared/connections.xml"/>
 
    <INITIALIZATION>
        <InitialCondition mass.Pos="0,0,0"/>
    </INITIALIZATION>
 
    <xi:include href="shared/simulation_settings.xml"/>
</Contents>

Included file paths are resolved relative to the parent file's directory. The included file must be a valid XML fragment whose root element matches the expected child type at the insertion point.

Example: shared simulation settings

**shared/simulation_settings.xml:**

<SIMULATION>
    <Timing TStart="0" TEnd="100.0"/>
    <Integrator Method="RK45_i">
        <StepControl AbsTol="1e-6" RelTol="1e-6" StepMax="0.05"/>
    </Integrator>
</SIMULATION>

This fragment can be included by any scenario that needs the same integrator configuration, making it easy to maintain consistent settings across multiple input files.

See also

• Input file examples
• Units and coordinate conventions — what the numbers mean.
• Running simulations