FhSim  3.1.0
Marine systems simulation
Loading...
Searching...
No Matches
Input file examples

Table of Contents

This page collects complete, self-contained input file examples that you can use as starting points for your own simulations.

Note
Examples 1 to 7 use a made-up library called MyLib. Each of them is about the <SIMULATION> configuration, so the SimObject names, parameters and port names in them are placeholders — substitute a real library and model from Available model libraries. Example 8 and the two tutorial files at the end of the page use real fhsim_base models and run as they stand.

Example 1 — Explicit adaptive (Engine RK45)

Standard explicit integration with tight tolerances.

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="Mass" Name="mass" Mass="1000" Radius="0.5"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition mass.Position="0,0,0" mass.Velocity="1,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="60.0"/>
<Integrator Method="RK45_i" NumCores="perCpuCore">
<StepControl AbsTol="1e-6" RelTol="1e-6" StepMax="0.05"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="result.csv"/>
</OBSERVERS>
</Contents>

Example 2 — Explicit adaptive (Engine DOPRI54)

Dormand-Prince is often more accurate than Cash-Karp for smooth ODEs.

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="Pendulum" Name="pend" Length="2.0"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition pend.Angle="0.5" pend.AngularVelocity="0.0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="30.0"/>
<Integrator Method="DOPRI54_i">
<StepControl AbsTol="1e-8" RelTol="1e-8" StepMax="0.1" StepMin="1e-10"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="pendulum.csv"/>
<ConsoleLog/>
</OBSERVERS>
</Contents>

Example 3 — Implicit fixed-step (Engine BackwardEuler)

Useful for stiff problems where an explicit method would require an extremely small step size.

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="StiffSpring" Name="spring" K="10000" C="500"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition spring.Position="0.1" spring.Velocity="0.0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="10.0"/>
<Integrator Method="BackwardEuler_i">
<StepControl Step="0.001"/>
<LinearSolver Type="dense"/>
<Jacobian Type="dense"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="spring_implicit.csv"/>
</OBSERVERS>
</Contents>

Example 4 — Implicit adaptive (Sundials BDF)

BDF is well-suited for stiff problems.

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="ChemicalReactor" Name="reactor"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition reactor.Concentration="1.0,0.0,0.0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="200.0"/>
<Integrator Method="BDF">
<StepControl AbsTol="1e-8" RelTol="1e-8" MaxSteps="5000"/>
<LinearSolver Type="DENSE" NonlinearSolver="newton"/>
<Jacobian Type="dense"/>
<SundialsExtra CVodeSetMaxOrd="5"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="reactor.csv"/>
</OBSERVERS>
</Contents>

Example 5 — Explicit Runge-Kutta (Sundials ERK)

SUNDIALS ERK with a specific Butcher table.

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="Oscillator" Name="osc" Omega="2.0"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition osc.x="1.0" osc.v="0.0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="10.0"/>
<Integrator Method="ERK">
<StepControl AbsTol="1e-6" RelTol="1e-6"/>
<SundialsExtra ERKStepSetTableNum="HEUN_EULER_2_1_2"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="osc_erk.csv"/>
<ConsoleLog/>
</OBSERVERS>
</Contents>

Example 6 — Simulation chaining (save/resume state)

Run segment 1, save the final state, then resume from it in segment 2.

Segment 1 — run and save:

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="Vessel" Name="vessel"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition vessel.Position="0,0,0" vessel.Velocity="1,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="100.0"/>
<Integrator Method="RK45_i" FinalStatesFile="segment1_end.bin">
<StepControl AbsTol="1e-6" RelTol="1e-6" StepMax="0.05"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="segment1.csv"/>
</OBSERVERS>
</Contents>

Segment 2 — resume from saved state:

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="Vessel" Name="vessel"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition vessel.Position="0,0,0" vessel.Velocity="1,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="200.0"/>
<Integrator Method="RK45_i" InitialStatesFile="segment1_end.bin">
<StepControl AbsTol="1e-6" RelTol="1e-6" StepMax="0.05"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="segment2.csv"/>
</OBSERVERS>
</Contents>
Note
InitialStatesFile loads the time and states from the binary file, overriding both TStart and the <InitialCondition> block.

Example 7 — Network streaming (publisher + subscriber)

Publisher process:

<Contents>
<OBJECTS>
<Lib LibName="MyLib" SimObject="Mass" Name="mass" Mass="100"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition mass.Position="0,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="60"/>
<Integrator Method="RK45_i">
<StepControl AbsTol="1e-4" RelTol="1e-4"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="results.csv"/>
<Network endpoint="tcp://*:5555"/>
</OBSERVERS>
</Contents>

Subscriber process:

<Contents>
<SIMULATION>
<Network endpoint="tcp://localhost:5555" timeout="10000"/>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="received.csv"/>
</OBSERVERS>
</Contents>

Example 8 — Using variables and arithmetic

<Contents>
<VARIABLES>
<Var Name="TotalMass" Value="2000"/>
<Var Name="SpringK" Value="500"/>
<Var Name="Depth" Value="20"/>
</VARIABLES>
<OBJECTS>
<Lib LibName="fhsim_base" SimObject="Body/Mass" Name="mass"
Mass="$TotalMass" Scale="0.7"/>
<Lib LibName="fhsim_base" SimObject="Cable/LinearSpring" Name="spring"
Stiffness="$SpringK*2" RelaxedLength="2.0"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
spring.PosA="mass.Pos"
spring.PosB="0,0,0"
mass.Force="spring.ForceA"
/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition mass.Pos="0,0,-$Depth/2" mass.Vel="0,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="120"/>
<Integrator Method="RK45_i">
<StepControl AbsTol="1e-6" RelTol="1e-6" StepMax="0.05"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="result.csv"/>
</OBSERVERS>
</Contents>

Stiffness="$SpringK*2" evaluates to 1000 and mass.Pos="0,0,-$Depth/2" to 0,0,-10.

Warning
TEnd is written out in full on purpose. $Variable substitution does not reach <Timing>: TEnd="$Duration" is not an error, it is silently read as TEnd="0" and the simulation ends immediately. See Where substitution applies.

Tutorial examples

The following input file examples are included with FhSim and used in the tutorials:

OneMass.xml

A mass on a linear spring anchored at the origin.

<Contents>
<OBJECTS>
<Lib LibName="fhsim_base" SimObject="Body/Mass" Name="mass"
Mass="1" Material="Simple/Black" Scale="1"/>
<Lib LibName="fhsim_base" SimObject="Cable/LinearSpring" Name="spring"
Stiffness="0.10" RelaxedLength="2.5"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
mass.Force="spring.ForceA"
spring.PosA="mass.Pos"
spring.PosB="0,0,0"/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition
mass.Pos="0,2,0"
mass.Vel="0,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0.0" TEnd="10.0"/>
<Integrator Method="RK45_i" NumCores="1">
<StepControl AbsTol="1e-7" RelTol="1e-7" StepMax="0.03" StepMin="1e-6"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="OneMass.csv" Select="objects:ports"/>
</OBSERVERS>
</Contents>

TwoMass.xml

Two masses joined by a single linear spring: each mass takes one end of the spring's reaction force, so the pair oscillates about its common centre of mass.

<Contents>
<OBJECTS>
<Lib LibName="fhsim_base" SimObject="Body/Mass" Name="mass1"
Mass="2.2" Material="Simple/Black" Scale="0.5"/>
<Lib LibName="fhsim_base" SimObject="Body/Mass" Name="mass2"
Mass="1.0" Material="Simple/Black" Scale="0.5"/>
<Lib LibName="fhsim_base" SimObject="Cable/LinearSpring" Name="spring"
Stiffness="10.0" RelaxedLength="2.5"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
spring.PosA="mass1.Pos"
spring.PosB="mass2.Pos"
mass1.Force="spring.ForceA"
mass2.Force="spring.ForceB"/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition
mass1.Pos="-2,0,0"
mass1.Vel="0,0,0"
mass2.Pos="2,0,0"
mass2.Vel="0,1,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0.0" TEnd="60.0"/>
<Integrator Method="RK45_i" NumCores="1">
<StepControl AbsTol="1e-7" RelTol="1e-7" StepMax="0.03" StepMin="1e-6"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="TwoMass.csv" Select="objects:all"/>
</OBSERVERS>
</Contents>

OneMass_sundials.xml

The same model as OneMass.xml, integrated with the SUNDIALS BDF method instead of the Engine's RK45_i. It is the worked counterpart to the Sundials reference material: <Integrator Method="BDF"> with a <LinearSolver> and a <Jacobian> child, and MaxSteps on <StepControl> rather than on <Integrator>. Only the <SIMULATION> and <OBSERVERS> sections differ from OneMass.xml, so the two files run the same physics and can be compared directly.

<Contents>
<OBJECTS>
<Lib LibName="fhsim_base" SimObject="Body/Mass" Name="mass"
Mass="1" Material="Simple/Black" Scale="1"/>
<Lib LibName="fhsim_base" SimObject="Cable/LinearSpring" Name="spring"
Stiffness="0.10" RelaxedLength="2.5"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
mass.Force="spring.ForceA"
spring.PosA="mass.Pos"
spring.PosB="0,0,0"/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition
mass.Pos="0,2,0"
mass.Vel="0,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0.0" TEnd="10.0"/>
<Integrator Method="BDF">
<StepControl AbsTol="1e-7" RelTol="1e-7" MaxSteps="5000"/>
<LinearSolver Type="SPGMR" NonlinearSolver="newton"/>
<Jacobian Type="dense"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<FileOutput outputFile="OneMass_sundials.csv" Select="objects:all"/>
</OBSERVERS>
</Contents>

<Jacobian Type="dense"/> with <LinearSolver Type="SPGMR"/> is a deliberate, valid pairing: an iterative Krylov solve that still has a full Jacobian available. See SUNDIALS and linear-solver configuration for the complete table of valid <Jacobian Type> / <LinearSolver Type> combinations.

See also