|
Marine systems simulation
|
|
|
Marine systems simulation
|
It is essential to have a simulation scenario when running a simulation in FhSim. Such a simulation scenario both defines the composition of – and the relations between – models. A simulation scenario is in FhSim implemented through an XML file.
In summary, the scenario input file specifies:
The XML input file contains both mandatory and optional sections as indicated in the following code snippet:
<Contents>tag.For the remainder of this page we will assume that the XML file is called MySystem.xml. See Input file example 1 and Input file example 2 for complete input files.
Open a command terminal. Suppose FhSim is installed to /home/john/fhsim-playpen or C:\Users\john\fhsim-playpen. Navigate to this directory and go to the directory where the FhSim executables are installed – the bin folder. In the following we use Windows as example. Linux is similar, only that local executables are run with a ./ prefix.
Suppose you want to run the simulation described by the input file C:\Users\john\fhsim-playpen\examples\input\MySystem.xml without visualization. You simply write:
Replace FhSim with FhVis if you want to run with visualization. Use FhRtSim or FhRtVis if you want to run with real time requirements. To exit the visualization, press <Esc>. See 3D scene navigation to learn how to control the camera.
The first time a program is run with visualization, an Ogre3D dialog may pop up where you can set your preferred view settings. You can change the settings later, but you will need to delete the file ogre.cfg, which is located in the resources subdirectory.
You can get the available command line program options by typing FhVis --help:
The input file is divided into different sections, and each has their own specific purpose.
The section OBJECTS specifies the simulation objects that are part of the simulation. The SimObjects are usually compiled into separate shared libraries (dll's on windows), and they are defined by the location and name of the library file, as well as the type name of the individual object. The parameters are also given for each SimObject.
Each SimObject is specified by a <Lib /> tag with the following attributes
The parameters which are specific to a type of SimObject should normally be described in the documentation for that SimObject. The names and types must match the implementation. If a SimObject has a numeric parameter called Mass, for instance, then Mass="20.0" is valid whereas Mass123="abc" is not. The type is actually not checked though, so Mass="abc" wouldn't raise any errors, but would look quite funny in the simulation. Parameters which have a default value can be omitted.
<OBJECTS> section: The name of a library may then be assembled as: LibName<Visualization suffix><Debug suffix> One library name on Windows may therefore be:
fhsim_baseVis_d.dll.fhsim_baseVis.dll.The subsection Connection in INTERCONNECTIONS specify how the SimObjects are connected. This is done according to simObject names, port tags and constants. Simobjects have a number of input and output ports. All input ports must be connected to an output port, but output ports may be left unconnected. Connections are described through attributes of a <Connection> tag, with the following syntax:
<INTERCONNECTIONS> section can contain multiple <Connection> tag. This can be useful for grouping connections, making reading the input file easier.The names and possible values of a simobject's states should be specified in the simobject's documentation.
The first case connects the input port PositionA of the SimObject cable to the output port Position of the SimObject mass1. The second sets the input port PositionB of the SimObject cable equal to the vector [0 0 0]. The names of the simObjects are defined in the OBJECTS section of the input file, while the tag names are set in the definition of the SimObjects (in the C++ source code).
The InitialCondition subsection specifies the initial states of the simObjects. It contains a single <InitialCondition> tag in which the initial conditions of all objects in the system are specified with the following syntax
The initialization is done using the simObject names and the state tag names:
MassOne.Pos="10.0, 0.0, 0.0"
The states which are not initialized, are initially set to zero. There may, however be provided methods in the individual SimObject which sets the initial conditions, either based on the input parameters or input ports. A typical example would be a cable object, which could use positions of the ends to set the initial positions of the nodes in between.
The INTEGRATION section contains options that influence how the simulation is run, i.e. which simulation method is used, the time steps etc. Simulations can be integrated with two different integration frameworks: the classic FhSim integration framework referred to as Engine and the external Sundials integration framework. The integration framework and its options are specified in the <Engine> or <Sundials> subsections.
Engine options
Engine options decide how the integrator executes and how outputs are written to file. The options are described in the table below.
| Property | Example | Comment |
|---|---|---|
| IntegratorMethod | 2 | 0 = Forward Euler. 2 = Runge Kutta 45. |
| TOutput | T0, OutputSpec, T | Defines the start time, the times for outputs and the stop time. If the stop time is given as Inf, it is interpreted as infinite. Note that logging is only done if LogStates is 1 and/or FileOutput is set. Examples are shown below. |
| T | Simulation starting at time 0 (default), no output(default) and T is the stop time. | |
| T0,T | Simulation starting at time T0, no output(default) and T is the stop time. | |
| T0,To1,T | Simulation starting at time T0, output at t = T01 if activated, the stop time is T. | |
| T0, To1,,,ToN, T | Simulation starting at time T0, output at t = To1,,,ToN if activated, the stop time is T. | |
| T0, To1:T02, T | Simulation starting at time T0, output at every integration step between t = T01 and To2 if activated, the stop time is T. | |
| T0, To1:dT:T02, T | Simulation starting at time T0, output at between t = T01 and To2 with dT interval if logging is activated, the stop time is T. | |
| LogStates | 1 | Bool (0 or 1). Should the output be logged internally by CFhIntegrator? This is not applicable if the simulation is run by the standard FhSim or FhVis executables. Set to 1 if logging is wanted. |
| StepSize | 0 0.01 | Variable step size if 0. Fixed step size if larger than 0. |
| HMax | 0.1 | The maximum allowed step size (for variable step size only). |
| HMin | 0.1 | The minimum allowed step size (for variable step size only). An error will be given if the system can not be solved within error tolerances without using a smaller step size. |
| AbsTol | 1e-6 | The maximum allowed absolute derivative error (for variable step size only). |
| RelTol | 1e-6 | The maximum allowed derivative error relative to the states (for variable step size only). |
| UseRSSNormInsteadOfInfNorm | 0 | \(\text{epsilon} = f_0() \), see below |
| 1 | \(\text{epsilon} = f_1() \), see below | |
| FileOutput | "OBJECT_SET:DATASTREAM_SET" | The OBJECT_SET string defines a set of simombjects from which some kind of outputstream should be logged to file. The DATASTREAM_SET string defines which streams should be logged from the aforementioned simobjects. Logging will take place at timesteps defined in the TOutput property |
| "objects:all" | Write all ports and states of all simObjects to result file. | |
| "objects:ports" | Write the output ports of all simObjects to result file. | |
| "objects.Mass:states" | Write the states of all Mass simObjects to result file. | |
| "object.spring1:port.ForceA" | Write the ForceA output port of spring1 to result file. | |
| "union(object.spring1:ports, objects.Mass:states)" | Write the ports of spring1 AND the states of all Mass objects to result file. | |
| "minus(objects:all, union(objects.Mass:ports, objects.Cable:states, object.spring1:ForceB))" | Write everything EXCEPT ports from Mass objects, states from Cable objects and ForceB from spring1. | |
| "" | Empty string. No output to file. | |
| InitialStatesFile | "initialstates.bin" | A binary file containing the initial states. |
| FinalStatesFile | "initialstates.bin" | A binary file to write all final states to. This can be used for continuing the simulation from an earlier state. |
\( f_0 = \max \frac{\epsilon_i}{|tol_{rel}\cdot x_i|+tol_{abs}}\) and \( f_1 = \sqrt{\sum_{i=0}^{i=N} (\frac{\epsilon_i}{|tol_{rel}\cdot x_i|+tol_{abs}})^2}\), where \(\epsilon\) = error to compare to allowed tolerance; \(tol_{abs}\) = the absolute tolerance; \(tol_{rel}\) = the relative tolerance; \(\epsilon_i\) = the estimated error in the derivative for state \(i\).
Sundials options
Please see the Sundials documentation for more information about the Sundials integration framework.
| Property | Example | Comment |
|---|---|---|
| sundials_method | cvodes | The integration infrastructure Sundials will use. Currently, only cvodes and arkode are supported. CVODES is a suite of nonlinear and DAE solvers. ARKODE is a suite of adaptive-step time integrations solvers for ODEs. |
| cvodes_method | BDF | The method used by CVODES. Currently, only BDF and ADAMS are supported. |
| arkode_method | ERK | The method used by ARKODE. Currently, only ERK and DIRK are supported. |
| t_start | 0 | The start time of the simulation. |
| t_end | 10 | The end time of the simulation. |
| dt | 0.1 | The step size for when output is written to file. Notice that this is not the step size used by the integrator, which may be adaptive based on the options. |
| reltol | 1e-6 | The relative tolerance used by the integrator. |
| abstol | 1e-6 | The absolute tolerance used by the integrator. |
| jtype | DENSE | Sundials can estimate a Jacobian matrix, but must know how large the matrix should be. The parameter "jtype" in the integrator controls the patterns of the Jacobian matrix. Currently, only dense, sparse and none are supported. Can only be set with cvodes or arkode in combination with DIRK. |
| linear_solver | SPGMR | Linear solver. The available options are SPGMR or DENSE. Can only be set with cvodes or arkode in combination with DIRK. |
| nonlinear_solver | NEWTON | Nonlinear solver. The available options are newton or fixed_point. Can only be set with cvodes or arkode in combination with DIRK. |
| print_step_info | 1 | In combination with verbose level 4, this will print to console or write to log file information about the integration steps. |
| file_output | objects:ports | Similar to FileOutput in the Engine options. |
| initial_states_file | "initialstates.bin" | A binary file containing the initial states. |
| final_states_file | "initialstates.bin" | A binary file to write all final states to. This can be used for continuing the simulation from an earlier state. |
Several additional options are available, please see the documentation for the CVODES, ARKODE/DIRK and ARKODE/ERK integrators. The options can be set with parameters with the same name as in the official Sundials documentation. If a parameter is not yet available in FhSim, an error will be thrown during start-up. A few examples are shown below.
| Property | Example | Comment |
|---|---|---|
| ERKStepSetFixedStep | 0.1 | Fixes the step size used by the integrator. Can only be set with arkode in combination with ERK. Generally not recommended. |
| ERKStepSetTableNum | HEUN_EULER_2_1_2 | Sets the explicit Butcher table when using arkode in combination with ERK. See the available options in the official documentation. |
| ARKStepSetTableNum | SDIRK_2_1_2 | Sets the implicit Butcher table when using arkode in combination with DIRK. See the available options in the official documentation. |
When navigating in the visualization you are essentially moving a camera. This section holds an overview of the keys to use while the simulation is running.
Movement of camera along local axes
| Shortcut | Function |
|---|---|
| W | Moves the camera forward |
| S | Moves the camera backward |
| A | Moves the camera left |
| D | Moves the camera right |
| Q | Moves the camera up |
| E | Moves the camera down |
Movement of camera along global axes
| Shortcut | Function |
|---|---|
| Numpad 7 | Moves the camera along positive x-axis |
| Numpad 4 | Moves the camera along negative x-axis |
| Numpad 8 | Moves the camera along positive y-axis |
| Numpad 5 | Moves the camera along negative y-axis |
| Numpad 9 | Moves the camera along positive z-axis |
| Numpad 6 | Moves the camera along negative z-axis |
Choice of target viewpoint
| Shortcut | Function |
|---|---|
| 1 - 9 | Selects a target to use as a target viewpoint |
| 0 | De-selects target to use as a target viewpoint |
Speed of camera movement
| Shortcut | Function |
|---|---|
| <Left shift> | Increase camera speed |
| <Left ctrl> | Decrease camera speed |
| <Tab> | Resets camera speed |
Camera view direction (only if no target viewpoint is set)
| Shortcut | Function |
|---|---|
| <Arrow up> | Increase elevation |
| <Arrow down> | Decrease elevation |
| <Arrow left> | Look to the left |
| <Arrow right> | Look to the right |
Special keys
| Shortcut | Function |
|---|---|
| X | Toggles mesh or surface view |
| C | Toggles view of origin axes |
| V | Decreases the size of the origin axes |
| B | Increases the size of the origin axes |
| <esc> | Quits the simulation |
This input file models a mass hanging from a linear spring, which again is hanging from a fixed point.
This input file models a mass hanging from a cable, which again is hanging from another mass, which is connected to a spring. It uses the TutorialLib library.
Same as example 2, but with Sundials integration.
1.9.4