|
FhSim
3.1.0
Marine systems simulation
|
|
|
FhSim
3.1.0
Marine systems simulation
|
This is the quick start for FhSim: five minutes from an installed FhSim to a results file you can plot. The page is self-contained — everything you need to type is here, and each step says what you should see before you move on.
You need three things. FhSim itself and the model library come from the installer described in Installation and setup; the licence file is issued separately.
1. FhSim installed. This page uses the FhSim executable (no visualisation). FhVis is the same simulator with 3D visualisation; step 5 shows how to swap it in.
2. A licence. FhSim validates a licence before it instantiates any SimObject, so a licence is needed even for the two-object model below. Provide it in one of two ways:
SFH_LICENSE_FILE to the full path of your licence file, orlicense.lic in the directory FhSim runs in (step 1 below).If neither is found, the run stops with
To obtain a licence file, contact your SINTEF liaison or the FhSim team — see Installation and setup and License and terms of use.
3. The fhsim_base model library. The model below uses two SimObjects from it. FhSim looks for model libraries in a SimObjectLibraries sub-directory of its working directory, so running from a directory that has no SimObjectLibraries next to it fails with Simobject library file not found in one of: ....
The FhSim binary directory is not added to PATH by the installer, and FhSim looks for its model libraries and for license.lic relative to its working directory. Running from the binary directory satisfies both at once:
Everything on this page happens in that directory: the model file is saved there, and results.csv is written there.
FHSIM_DIR_IDENTIFIER in the current directory, then in the executable's directory, then in $FHSIM_DIR, and changes to the first match. Starting from the binary directory makes that a no-op, which is why "run from
the `bin` directory" is the advice everywhere in this manual. The input file name and the -o option are resolved before that switch, against the directory you launched from. See the OBSERVERSsection" for the full path-resolution rule.
@section autotoc_md233 2. Save the model file
Save the following as <tt>quickstart.xml</tt> in the directory from step 1. It is a
point mass on a linear spring — a harmonic oscillator along the <em>z</em> axis.
@icode{xml}
<?xml version="1.0" encoding="utf-8"?>
<Contents>
<OBJECTS>
<!-- Point mass, 1 kg. Ports: Force in; Pos, Vel out. -->
<Lib LibName="fhsim_base" SimObject="Body/Mass" Name="M"
Mass="1"/>
<!-- Spring between end A and end B. Ports: PosA, PosB in; ForceA, ForceB out. -->
<Lib LibName="fhsim_base" SimObject="Cable/LinearSpring" Name="S"
Stiffness="10" RelaxedLength="1"/>
</OBJECTS>
<INTERCONNECTIONS>
<Connection
S.PosA="0,0,0"
S.PosB="M.Pos"
M.Force="S.ForceB"/>
</INTERCONNECTIONS>
<INITIALIZATION>
<InitialCondition
M.Pos="0,0,1.5"
M.Vel="0,0,0"/>
</INITIALIZATION>
<SIMULATION>
<Timing TStart="0" TEnd="10"/>
<!-- non-stiff choice -->
<Integrator Method="RK45_i" NumCores="1">
<!-- tightened deliberately; StepMax resolves oscillation -->
<StepControl AbsTol="1e-6" RelTol="1e-6" StepMax="0.01"/>
</Integrator>
</SIMULATION>
<OBSERVERS>
<!-- even sampling; states only -->
<FileOutput outputFile="results.csv" TOutput="0:0.01:10"
Select="objects:states"/>
</OBSERVERS>
</Contents>
@endicode
Three choices in that file are worth a word of explanation:
- <tt>Method="RK45_i"</tt> is the adaptive Runge-Kutta Cash-Karp method — the
general-purpose first choice for a non-stiff system such as this one. Stiff
systems need an implicit method instead. <tt>Method</tt> is required; there is no
implicit default (@ref fs-page-input-simulation).
- <tt>AbsTol</tt> and <tt>RelTol</tt> are set to <tt>1e-6</tt>, which is <strong>tighter than FhSim's
default of <tt>1e-4</tt></strong>. A smooth oscillator is cheap to integrate, so the
tighter tolerance costs almost nothing and makes the result reproducible;
do not assume <tt>1e-6</tt> elsewhere.
- <tt>StepMax="0.01"</tt> caps the step at about one two-hundredth of the oscillation
period, so the solver cannot stride over a peak. Without it the engine
default is a <tt>StepMax</tt> of 10 s.
@section autotoc_md237 3. Run the simulation
On Linux and macOS, executables in the current directory need a <tt>./</tt> prefix:
@icode{shell}
./FhSim quickstart.xml
@endicode
On Windows:
@icode
FhSim quickstart.xml
@endicode
<strong>What you should see.</strong> The FhSim banner with the version number, then — this
is the line that tells you the run worked:
@icode
*------------------------------------------*
* FhSim ended successfully. *
...
@endicode
If instead you see a licence or library message, jump to
@ref fs-page-quickstart-trouble "If it did not work".
@section autotoc_md239 4. Inspect the results
<tt>results.csv</tt> is now in the same directory. It has two header rows — SimObject
names, then signal names — and one data row per output time, semicolon
separated:
@icode
Time;M;M;M;M;M;M;
;Pos_0;Pos_1;Pos_2;Vel_0;Vel_1;Vel_2;
0.000000e+00;0.000000e+00;0.000000e+00;1.500000e+00;0.000000e+00;0.000000e+00;0.000000e+00;
@endicode
With <tt>TOutput="0:0.01:10"</tt> there are 1001 data rows, from <tt>t = 0</tt> to <tt>t = 10</tt>.
The mass starts at <tt>Pos_2 = 1.5</tt> and swings about the spring's relaxed length
of 1.0, so <tt>Pos_2</tt> oscillates between roughly 0.5 and 1.5 with a period of
about 2 s — \_form#64 for <tt>Mass="1"</tt> and <tt>Stiffness="10"</tt>. The <tt>_0</tt>
and <tt>_1</tt> columns stay at zero: the motion is purely along <em>z</em>.
Open the file in any spreadsheet or plotting tool, or use the browser viewer
that ships with FhSim — see @ref fs-observer-results-viewer "the results HTML viewer".
@section autotoc_md354 5. Run it with visualisation
The same file runs unchanged under the visualisation executable:
@icode{shell}
./FhVis quickstart.xml
@endicode
Press <tt>\<Esc\></tt> to stop the simulation and close the window. <tt>FhVis</tt> needs a
graphical environment; see @ref fs-page-user-setup-install for the
platform prerequisites.
@section fs-page-quickstart-trouble If it did not work
<table class="markdownTable">
<tr class="markdownTableHead"> <th class="markdownTableHeadNone"> Message Cause
Cannot find a valid licence file...
No licence found — see Before you start above, and Troubleshooting.
Simobject library file not found in one of: ...
FhSim is not running from a directory with SimObjectLibraries next to it, or fhsim_base is not installed — see Troubleshooting.
The simulation object of class "..." was not found.
The SimObject attribute names a type the library does not provide — check the spelling against Available model libraries.
For other runtime messages, see Runtime errors and diagnostics.
1.9.8