|
FhSim
3.1.0
Marine systems simulation
|
|
|
FhSim
3.1.0
Marine systems simulation
|
This page explains common runtime error messages, their causes, and how to resolve them. For build/setup issues, see Troubleshooting.
Symptom: The simulation stops with exactly that message.
Cause: The adaptive integrator repeatedly shrinks the time step to meet tolerances but reaches the configured StepMin. This usually means the ODE system is stiff or has a discontinuity at the current time.
Resolution: the message names the two knobs, and both go the opposite way from what one first expects:
AbsTol and RelTol in <StepControl> — a tolerance tighter than the accuracy you need is the most common cause of a step-size collapse.StepMin if you are confident the system is well-posed and simply needs a smaller step through a transient.Method="BDF" or Method="DIRK") which handles stiff systems better. (There is no method named ARKODE; DIRK and ERK are the ARKODE-backed methods.)Symptom: Log mentions Newton iteration failure or nonlinear solver divergence.
Cause: The Jacobian is inaccurate, the initial guess is poor, or the system has become singular.
Resolution:
OdeJacobian) against a finite-difference approximation. A small test with known states will reveal sign or indexing errors.StepMax so the predictor starts closer to the solution.GetJacobianSparsity() returns the correct sparsity pattern — missing entries silently produce wrong results.Symptom: Output contains nan or inf, or the simulation aborts with a floating-point error.
Cause: Division by zero, sqrt of negative number, or exponential blowup in OdeFcn.
Resolution:
OdeFcn for degenerate cases (e.g., zero mass, zero length).Cause: The shared library file is missing or has a name the loader does not derive from LibName. A LibName without a path separator is looked up in the SimObjectLibraries sub-directory of the working directory; the loader tries the plain name first and then a fhsim_-prefixed fallback, and the message quotes both paths it tried.
Resolution:
playpen/bin).LibName in your XML matches the actual library filename (without prefix/suffix — e.g., fhsim_base not libfhsim_base.so)._d to the file name it looks for, and a visualization build appends Vis.Cause: The file was found but the operating system refused to load it — typically a missing runtime dependency or an incompatible build. The visualization loader reports the same text prefixed In FhVisDll:.
Resolution:
LD_LIBRARY_PATH; on Windows, check PATH.Cause: The SimObject attribute is missing from an <Lib> element.
Resolution: Every <Lib> element must have SimObject="Category/ClassName".
Cause: The Name attribute contains spaces or tabs.
Resolution: Remove the whitespace. Any whitespace character anywhere in the name is rejected; other characters are not restricted.
Cause: The Name attribute is missing from a <Lib> element.
Resolution: Add a unique Name to every <Lib> element.
Cause: The required <INITIALIZATION> element is missing from the XML.
Resolution: Add an <INITIALIZATION> section, even if empty:
Cause: The <OBJECTS> section is missing or empty.
Resolution: Ensure your XML contains at least one <Lib> entry inside <OBJECTS>.
Cause: The integrator configuration is missing or uses the deprecated format.
Resolution: Use the v3 format:
See Migrating to FhSim 3.0 if migrating from v2.
These two failures produce no error message at all. FhSim reports success and writes a file; the file is simply not what you asked for.
Cause: the <FileOutput Select> expression uses the objects.<Type>: form, which selects by SimObject type. The observer evaluates the expression against the output metadata, and that metadata carries no SimObject type, so every candidate signal is offered with an empty type string and nothing matches (src/engine/io/OutputView.cpp:22-28). The expression is syntactically valid, so there is no parse error and no warning — the selection is just empty, and only the Time column survives.
Resolution: select by instance name with the singular object.<name>: form, or across all objects with the plural, name-less objects: form:
An unknown instance name or signal name behaves the same way — it selects nothing rather than reporting an error. See the selector grammar and the matching warning in the OBSERVERS section.
Cause: $Variable substitution never reaches <Timing>. Inside <SIMULATION>, substitution is applied to the attributes of the <Integrator> element and to nothing else (src/engine/core/Parse.cpp:493-504), so TEnd="$Duration" is handed to the numeric parser as the literal text $Duration. That conversion is atof-style and yields 0, so the simulation starts at TStart and is already finished.
Resolution: write the number into <Timing> directly, or have whatever generates $Duration rewrite TEnd as well. The full list of places substitution does and does not apply is Where substitution applies.
Cause: An <INTERCONNECTIONS> entry connects ports of different sizes (e.g., a size-3 output to a size-6 input).
Resolution: Verify that connected ports have matching dimensions. Check the SimObject documentation for expected port sizes.
Cause: Typo in the port name, or the referenced object does not expose that port. The same message exists for output ports.
Resolution: The error lists every port the object does register, with its size, immediately below the first line — compare spelling and case against that list. If the object itself is unknown, the message is instead Can not connect to input port <...> on SimObject <...> since the SimObject does not exist.
Cause: Two <INTERCONNECTIONS> entries drive the same input port.
Resolution: Keep exactly one connection per input port. Every registered input port must also be connected: an unconnected one fails with The input port <...> on the SimObject <...> was not specified.
These are the failures specific to exporting an FhSim model as an FMU and running it in someone else's co-simulation master. The exporter and the exported FMU are described in FMU tools.
Symptom: the host reports a failure at fmi2ExitInitializationMode / fmi3ExitInitializationMode, or a batch job that was supposed to be headless opens an Ogre window and then hangs or fails on a machine with no display.
Cause: an exported FMU starts with visualization on whenever the renderer was bundled with it, so at ExitInitializationMode it loads the visualization engine and asks for a render window. On a headless machine that request fails, and the failure surfaces as a failed initialization.
Resolution: pick one of the three measures in Running an FhSim FMU in an automated host. In short: set the Boolean parameter visualization[0] (value reference 0) to false while the instance is still in Instantiated or Initialization Mode; or export the FMU with --no-bundled-vis, so the renderer is absent and the parameter's start value is already false; or instantiate with visible=false, which the FMU honours even when the parameter is true.
Symptom: one FhSim FMU works; adding a second one to the same system structure produces a crash, a hang, or a model that reads files from the wrong directory. The FMU also logs not running in proxyfmu, could cause segfaults/crashes due to library conflicts!.
Cause: the FMU declares canBeInstantiatedOnlyOncePerProcess="true" and means it. The engine resolves several of its inputs relative to the process working directory, so the slave changes the whole process's working directory while it builds the model; a second instance initializing concurrently sees the first one's directory. This is a property of the engine, not of how the FMU is packaged — the FMU module exports only the fmi2* / fmi3* C entry points, so leaking library symbols is not the cause.
Resolution: give each FhSim FMU its own process. With Open Simulation Platform that means proxyfmu://localhost?file=... in the source attribute of every FhSim Simulator, as shown in FMU tools. With a single FhSim FMU in the process the proxyfmu warning is expected and harmless.
Symptom: a set call that worked before the first DoStep now fails with a message naming the value reference and saying that parameters are declared fixed.
Cause: every parameter an FhSim FMU carries — the three built-in ones and one per <VARIABLES>/<Var> entry — is declared fixed, not tunable. FhSim applies those values by patching the model file it is about to load, which happens once, at ExitInitializationMode. Accepting a later write would silently do nothing, so the FMU refuses it instead.
Resolution: write every parameter while the instance is in Instantiated or Initialization Mode. Inputs remain writable for the whole run; if a quantity genuinely has to change mid-run, expose it as an ExternalLinkStandard port rather than as a parameter. See Parameters the exported FMU carries.
Symptom: FhFmuExport stops with that message, preceded by a line naming two file names it looked for, and exits with status 11.
Cause: the model names a SimObject library through a LibName attribute that is not present in the exporter playpen's SimObjectLibraries directory, under either the plain name or the fhsim_-prefixed fallback. The exporter refuses rather than shipping an FMU that would fail on the host's first Instantiate.
Resolution: build or copy that library into the playpen, remembering that the search starts from the directory the FhFmuExport executable itself lives in, and that the file name carries the build-type and visualization suffixes (_d, Vis). The other positive exit codes are listed in Exit codes.
Symptom: Refusing to export into "<name>": the directory already exists and does not look like a previous FMU export ..., exit status 1.
Cause: a deliberate safety check. The export begins by deleting the output directory, so before deleting it, it confirms that the directory is one an earlier export created — it must contain modelDescription.xml or resources/iomapping.xml. A directory holding neither is something else, most likely a typo in --model-name or the wrong working directory, and deleting it unasked was silent data loss.
Resolution: check --model-name and where you are running from. If the name really is the one you want, remove the directory yourself, or choose a different name.
Symptom: a trajectory read at the master's communication points is a little ahead of the closed form or of a reference run, by an amount that matches the integrator step size rather than growing over time.
Cause: the engine stops at the first accepted integrator step at or past the time it was asked for, and it does not shorten that last step to land exactly on a communication point that is not a whole multiple of the integrator step size. The output you read then belongs to a time up to one integrator step past the point you requested.
Resolution: make the master's communication step size a whole multiple of the FMU's integrator_timestep[0] — either by choosing the communication step size to suit the model, or by setting that parameter during initialization. See What the exported FMU can and cannot do.
Symptom: an FMI 3.0 host that probes the whole type interface gets fmi3Error from the Float32, 8/16/64-bit integer, unsigned-integer, Binary or Clock calls, with a log message naming the function.
Cause: FhSim exchanges four type families, so the FMU serves Float64, Int32, Boolean and String and refuses the rest. No exported variable has any of those other types, so a well-behaved host never makes the call.
Resolution: none needed — the refusal is by design, it is a clean error, and the instance stays usable. Read the variables by the types the model description declares.
Symptom: a host such as OMEdit instantiates the FMU and it fails to find model.xml, iomapping.xml or the bundled binaries, although the archive unpacked correctly.
Cause: the FMU has to turn the location the host hands it into the root of the unpacked archive, and hosts differ in what they hand over. The runtime therefore normalises it: it strips the file:// scheme, percent-decodes escapes such as %20 in a path with a space, drops trailing path separators so that .../Model/ and .../Model mean the same directory, and — because OMEdit unpacks into a resources directory and passes that — treats a location whose last component is resources as pointing one level below the FMU root. A location that is none of these, for instance one pointing at binaries, is not recognised.
Resolution: point the host at the FMU archive or at the root of the unpacked FMU directory. If a host insists on some other directory, unpack the FMU yourself and hand over the directory that contains modelDescription.xml.
Symptom: the unpacked FMU directory gains files with those names, one set per instantiation, while a run is in progress.
Cause: the slave writes the patched model file, the engine log and the engine's own output CSV into the FMU root, each named with a fresh UUID so that concurrent instances cannot collide.
Resolution: nothing, in the normal case. The patched XML and the log are the FMU's own and are removed on Terminate, on Reset and when the instance is destroyed. The output CSV is deliberately left behind, because a host may still want to read it — it is yours to keep or delete. Files that survive a run therefore mean either a process that died without terminating its instance, or a CSV nobody collected.
Symptom: Ogre.log shows resource loading failures or the window does not appear.
Resolution:
ogre.cfg to regenerate renderer settings.resources directory.Resolution:
logoutput.txt for earlier errors (often a model loading failure).FhSim) first to confirm the model loads.Verbosity is set separately for the console (-c, --console-verbosity) and for the log file (-f, --file-verbosity), both on the scale 0–4 with default 2.
-v is --version: it prints the version string and exits. It does not set a verbosity level.| Level | Content |
|---|---|
| 0 | No logging at all |
| 1 | Errors |
| 2 | Errors and warnings (default) |
| 3 | Information — port registration, parameter values, library loading |
| 4 | Debug — maximum logging; much of it only in debug builds |
Example:
Review the log file to identify where the failure occurs. The last successfully logged operation before the error typically points to the problematic object or connection.
-c 3 or -c 4 (console), or -f 4 (log file), to capture detailed diagnostics.
1.9.8