Syntax

Initial conditions are specified as attributes of an <InitialCondition> tag:

<INITIALIZATION>
    <InitialCondition
        someObject.SomeState="some value"
        anotherObject.AnotherState="another value"
    />
</INITIALIZATION>

Each attribute has the form:

<objectName>.<stateName> = "<value>"

Rules

States not listed default to zero. If a state is not mentioned in the <InitialCondition> tag, it is initialised to zero.
SimObjects may override initial conditions. Individual SimObjects can implement InitialConditionSetup() to compute initial states from their parameters or input ports (e.g. a cable computing node positions from its endpoints). These run after the XML initial conditions are applied.
Vector states are specified as comma-separated values:

<InitialCondition
    mass.Pos="-13, 2, -5"
    mass.Vel="0, 0, 0"
/>

Variable substitution and arithmetic

Initial condition values can use $Variable references defined in the VARIABLES section, and are then passed through the arithmetic evaluator:

<VARIABLES>
    <Var Name="StartPos" Value="10,0,0"/>
    <Var Name="Depth" Value="50"/>
</VARIABLES>
 
<INITIALIZATION>
    <InitialCondition mass.Pos="$StartPos" anchor.Pos="0,0,-$Depth/2"/>
</INITIALIZATION>

Both apply to <InitialCondition> attributes only — not to <FromFile> or its <State> children. See Arithmetic in attribute values for exactly when a value is treated as an expression, and for the six-significant-digit rounding that comes with it.

Example

<INITIALIZATION>
    <InitialCondition
        mass1.Pos="0, 0, -5"
        mass1.Vel="1, 0, 0"
        mass2.Pos="10, 0, -5"
        mass2.Vel="0, 0, 0"
        cable.Tension="100"
    />
</INITIALIZATION>

Binary initial conditions (<FromFile>)

For large models with many repeated elements (e.g. discretised cables or chains), initial conditions can be loaded from a binary file using <FromFile>.

<INITIALIZATION>
    <InitialCondition mass.Pos="0,0,0"/>
 
    <FromFile SimObjectName="cable" FileName="cable_ic.bin">
        <State Name="Position" Dimension="3" Range="0,100"/>
        <State Name="Velocity" Dimension="3" Range="0,100"/>
    </FromFile>
</INITIALIZATION>

<FromFile> attributes

Attribute	Required	Description
`SimObjectName`	Yes	Name of the target SimObject.
`FileName`	Yes	Path to the binary file. Relative paths resolve against the working directory — see Path resolution. A missing file stops the run.

<State> child elements

Each <State> element describes one block of state data in the binary file:

Attribute	Required	Description
`Name`	Yes	Base name of the state (e.g. `"Position"`).
`Dimension`	Yes	Number of doubles per element (e.g. `3` for a 3D vector).
`Range`	Yes	Integer range `"start,end"` — reads elements `start` to `end-1`. Both indices are required.

Binary file format

The binary file contains raw double values in sequence. For each <State> element, FhSim reads (end - start) × Dimension doubles and assigns them to the states named Name_start, Name_(start+1), ..., Name_(end-1), each holding Dimension values.

Note: The index in the state name is the index within Range, not a position counted from zero. Range="0,100" fills Position_0 … Position_99, but Range="50,100" fills Position_50 … Position_99 from the first bytes of its block — it does not skip 50 elements of the file.

The file is read sequentially: <State> elements must appear in the same order as the data was written to the file. If the file ends before the declared Dimension and Range have been satisfied, the run stops with an error naming the state it was reading.

Table of Contents