|
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.
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