|
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: $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:535-542), so TEnd="$Duration" is handed to the numeric parser as the literal text $Duration, which is not a number. The same error, with another element and attribute, appears for any number that is not wholly a number:
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: A parameter that the SimObject reads as a number, a whole number, a bool or a list is not wholly a valid value. Text that only starts like a value (1.5m, ten, 2.7 for a whole number, ture for a bool) is an error, not a prefix read as a smaller number. The message names the SimObject, the parameter and the text (src/simobject/SimObjectOrganizer.cpp:42,433). The same rule holds for <InitialCondition> values and for the numbers in <Timing>, <StepControl>, <LinearSolver> and <Jacobian>; there the message names the element and the attribute.
Resolution: Write the value as a plain number, a bool word (true/false/1/0/yes/no/on/off) or a comma-separated list without a trailing comma. Arithmetic such as 2*1000 is still valid. See "Value rules" in OBJECTS section.
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.
This failure produces 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: 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: with two or more FhSim FMUs (or instances of one) in the same process, the second one that should open a render window fails at ExitInitializationMode with Another FhSim instance in this process is already rendering.
Cause: several FhSim FMUs, and several instances of one, run in one process (canBeInstantiatedOnlyOncePerProcess="false"), but only one of them can render: the visualization's Ogre and SDL objects exist once per process.
Resolution: set visualization[0] to false, or instantiate with visible=false, for every instance but the one that renders. To see more than one window, give each rendering FhSim FMU its own process — with Open Simulation Platform, proxyfmu://localhost?file=... in the source attribute of its Simulator.
Two further rules apply to FhSim FMUs that share a process: they must come from the same FhSim version (they share libraries that are found by name), and a SimObject library must keep its state per instance, not in global variables (instances of one FMU share the library). ADR 0012 records what was checked.
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 system temporary directory (/tmp, TEMP%) gains directories named fhsim-fmu-<uuid>, one per FMU instance, while a run is in progress.
Cause: an FhSim FMU writes nothing into its own folder, which a host may unpack read-only or share between instances. What the engine needs as files goes to a directory of the instance's own instead: the engine log (model.log) and, when the experiment's start time differs from the time saved in the initial-states file, a .mangle copy of that file with the start time patched in.
Resolution: nothing, in the normal case. The directory is removed on Terminate, on Reset and when the instance is destroyed. A directory that survives a run means a process that died without terminating its instance; it can be deleted. Up to 3.3.x the slave wrote file_to_fhsim_<uuid>.xml and modellog_<uuid>.log into the FMU root instead, and named a modeloutput_<uuid>.csv there that the engine never wrote.
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