FhSim executables

Three executables run a scenario: FhSim (no visualisation), FhVis (Ogre3D visualisation) and FhSimUI (SDL2/ImGui visualisation, see FhSimUI — the interactive front end). The other installed programs — fhsim_plot and FhFmuExport — post-process or convert a model rather than run one. The authoritative list, including which programs exist only in visualisation builds, is FhSim executables.

Real-time simulation is not a separate executable in FhSim 3. Instead, a run can be paced to wall-clock time — see Real-time pacing below.

Note: Which executables you have access to depends on your license.

Basic invocation

Quick start is the five-minute, step-by-step path from an installed FhSim to a results file; this page is the option reference behind it.

Open a terminal and change into the FhSim bin directory, then run a simulation without visualisation. On Linux and macOS an executable in the current directory needs a ./ prefix:

cd <fhsim-install-dir>/bin

./FhSim path/to/MySystem.xml

On Windows the prefix is not used:

FhSim path\to\MySystem.xml

Replace FhSim with FhVis to run with 3D visualisation. To exit the visualisation, press <Esc>.

Note: The .xml extension can be omitted.; Running from bin is the advice throughout this manual because FhSim picks its own working directory at start-up and resolves model libraries, licence file and every path written inside the XML against it. The input file named on the command line and an output file given with -o are resolved before that switch, against the directory you launched from. The full search order and the exact list of affected paths are in Path resolution.

Command-line options

FhSim [options] <input-file>

FhSim [options] -i <input-file>

Flag	Default	Description
`-i`, `--input-file`	(required)	XML model description file.
`-o`, `--output-file`	(from XML)	CSV result file. Overrides XML `<FileOutput outputFile="…"/>`. With neither `-o` nor `-d`, the XML value is used (`modeloutput.csv` if `<FileOutput>` names none); with no `<OBSERVERS>` section either, no CSV is written at all.
`-d`, `--output-file-from-input`	—	Derive output filename from the input filename (`.xml` → `.csv`). Takes precedence over `-o`.
`-l`, `--log-file`	`logoutput.txt`	FhSim log file.
`-c`, `--console-verbosity`	`2`	Console log level: `0`=no logging, `1`=errors, `2`=warnings, `3`=info, `4`=debug.
`-f`, `--file-verbosity`	`2`	File log level (same scale as `-c`).
`-h`, `--help`	—	Print usage.
`-v`, `--version`	—	Print version string and exit.

Warning: -v is **--version**, not a verbosity flag. Use -c (console) and -f (file) to raise the log level.

**FhVis only** — these three flags are compiled into the visualisation executable and are a parse error for FhSim:

Flag	Default	Description
`-r`, `--resource-path`	`../resources/`	Directory holding the visualisation `resources.cfg`.
`--fps`, `--frame-rate`	`0` (from XML)	Visualisation frame rate. Overrides XML `<Visualization frameRate="…"/>`.
`-s`, `--simulation-speed`	`0` (from XML)	Real-time speed multiplier. `1.0` = real time, `2.0` = twice real time, `0` = use XML value.

FhSimUI takes the common options above but has its own visualisation and pacing flags — see FhSimUI — the interactive front end.

Examples

These show the option patterns only. Invoke the executable as under Basic invocation above — from the bin directory, with a ./ prefix on Linux and macOS.

Run a simulation and write results to a custom file:

FhSim model.xml -o results.csv

Run with increased console logging:

FhSim model.xml -c 3

Run with visualisation at 2× real-time speed:

FhVis model.xml -s 2.0

Real-time pacing

By default a simulation runs as fast as possible. To pace it against wall-clock time, set a simulation speed multiplier — the ratio of simulated time to real time:

Speed	Effect
`0`	Run as fast as possible (default).
`1.0`	Real time (1 s simulated ≈ 1 s wall-clock).
`2.0`	Twice real time.
`0.5`	Half real time (slow motion).

Set it on the command line. The -s flag exists on FhVis only; FhSimUI spells the same thing --rtf (or --rt for --rtf 1.0), and FhSim has no pacing flag at all — a headless run is paced only through the XML attribute below:

FhVis model.xml -s 1.0

FhSimUI model.xml --rt

or in the input file, so the scenario carries its own default:

<SIMULATION simulationSpeed="1.0">
  ...
</SIMULATION>

The -s / --simulation-speed flag overrides the XML simulationSpeed attribute. If the machine cannot keep up (the simulation is slower than the requested pace), FhSim runs as fast as it can and does not sleep. See SIMULATION section for the full <SIMULATION> schema.

FhSimUI — the interactive front end

FhSimUI runs the same scenarios as FhVis, but draws through SDL2 and adds an ImGui user interface: a menu bar, a file browser, a console, an inspector, signal plots and a Jacobian debugger (see 3D scene navigation).

Unlike FhSim and FhVis, its input file is optional. Launched bare, it opens the interactive file browser and waits for you to load a scenario:

FhSimUI # opens the file browser

FhSimUI model.xml # loads and runs immediately

It accepts the common options from the table above (-i, -o, -d, -l, -c, -f, -h, -v) plus:

Flag	Default	Description
`-r`, `--resource-path`	`../resources/`	Directory holding the visualisation `resources.cfg`.
`--fps`, `--frame-rate`	from saved preferences	Visualisation frame rate.
`--rtf`, `--real-time-factor`	from saved preferences	Real-time factor: simulated time / wall-clock time. `1.0` = real time, `<1` = slow motion, `>1` = faster. Must be positive.
`--rt`	—	Shorthand for `--rtf 1.0`.
`--freeze`, `--no-exit`	—	Keep the window open after the simulation completes, so the scene can still be navigated.
`--no-freeze`	—	Disable the freeze that is otherwise the default when launching without an input file.
`--headless`	—	Run without displaying the visualisation window.
`--no-gui-console`	—	Disable the ImGui console overlay; log output goes to stdout only.
`--gui-console-only`	—	Enable the ImGui console overlay and suppress stdout log output.

Four pairs are mutually exclusive and are rejected with an error message before the run starts: --headless with --freeze, --freeze with --no-freeze, --rt with --rtf, and --no-gui-console with --gui-console-only.

Note: FhSimUI keeps display, rendering and verbosity preferences in fhsim.cfg in the resource directory. Settings are applied in the order built-in defaults → fhsim.cfg → command-line flags, so a flag overrides the stored value for that run; -c and -f take effect only when given explicitly.

Table of Contents