Answers to the questions people actually arrive with. Each entry is the shortest thing that works, with a link to the page that explains it.

Run a model

FhSim model.xml          # no visualisation
FhVis model.xml          # Ogre3D visualisation
FhSimUI model.xml        # SDL2 UI; launch bare to pick a file interactively

Run these from the FhSim bin directory; on Linux and macOS prefix the executable with ./. See Path resolution for why the working directory matters.

The .xml extension may be omitted. Full option reference: Running simulations. Full list of installed programs: FhSim executables.

Write the results to a CSV

FhSim model.xml -o results.csv # explicit name

FhSim model.xml -d # model.xml -> model.csv

Or let the scenario carry its own name, which -o/-d then override:

<OBSERVERS>
  <FileOutput outputFile="results.csv"/>
</OBSERVERS>

With no <OBSERVERS> section and no -o/-d, nothing is written. See OBSERVERS section.

Change how often output is written

Output is written every step unless the observer is given a schedule. TOutput belongs on the observer, not on <Integrator>:

Plot a run, or compare two runs

fhsim_plot results.csv                          # bakes the data into a viewer and opens it
fhsim_plot runA/results.csv runB/results.csv    # both runs in the same axes
fhsim_plot diagnostics.json                     # diagnostics viewer instead
fhsim_plot results.csv -o /tmp/run.html --no-open
fhsim_plot results.csv --template my-viewer.html   # use your own viewer page

See OBSERVERS section for the viewer itself.

Run in real time

FhVis uses -s, FhSimUI uses --rt / --rtf, and a headless run is paced only from the XML:

FhVis model.xml -s 1.0

FhSimUI model.xml --rtf 0.5

See Real-time pacing.

What units is this number in?

None that FhSim enforces. The engine defines no unit system and converts nothing; units come from the SimObject library, and every object in a scenario must agree. The visualisation assumes Z up, X–Y horizontal. Details and the vector-attribute syntax: Units and coordinate conventions.

Make it faster

Match the method to the problem — explicit (RK45_i) for non-stiff, implicit (BDF, DIRK) for stiff.
Loosen AbsTol/RelTol to no tighter than the accuracy you need.
For large implicit systems, pick the right linear solver, and provide an analytical Jacobian.
Raise the output interval (TOutput).

See Performance tuning.

Diagnose NaN/Inf, a collapsing step size, or a wrong Jacobian

Enable the diagnostics subsystem via <Diagnostics> in the input file, then open the JSON it writes with fhsim_plot. Worked recipes: Diagnostics cookbook.

See more of what the run is doing

FhSim model.xml -c 3 -l run.log # -c console level, -l log file

FhSim model.xml -f 4 # -f file level (0=no logging .. 4=debug)

Warning: -v is --version, not verbosity.

When something fails at startup

License discoverable (SFH_LICENSE_FILE, or license.lic in the working directory)?
Run from the playpen bin directory — LibName is resolved against the SimObjectLibraries sub-directory of the working directory.
Every required input port connected, exactly once?
Error messages and their fixes: Runtime errors and diagnostics.

Debugging in Visual Studio

Set the startup executable to FhSim, FhVis or FhSimUI in your playpen bin folder.
Set command arguments to your input XML path.
Set the working directory to playpen bin.
Run with the debugger (F5).