xdyn

xdyn is a lightweight ship simulator modelling the dynamic behaviour of a ship at sea, with its actuators, including some non-linear aspects of that behaviour and featuring a customizable maneuvring model. It simulates the mechanical behaviour of a solid body in a fluid environment by solving Newton's second law of motion, taking hydrodynamic forces into account.

It was developed by SIREHNA through both self-funded projects and various collaborative projects, including the IRT Jules Verne's "Bassin Numérique" project.

Disclaimer: Documentation was written for a French project, with French participants, therefore it is in French. It will be translated eventually. Also, please note that it is still a work-in-progress and, as such, can be incomplete. Despite our best efforts, inaccuracies may remain. However, the documentation will continue to evolve as new developments on xdyn are on-going.

Getting Started

The easiest way to run xdyn is to use Docker:

docker run sirehna/xdyn

This does not require installing or downloading anything except Docker itself.

Pre-built binaries of xdyn are also available:

There are many other ways of using xdyn, all of which are described in the documentation.

The models implemented inside xdyn are described in detail from section 11 to section 13 of the documentation. You can also learn how to use xdyn using the tutorials.

Building xdyn from source

This section describes what you need to do if you wish to compile xdyn yourself. These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

To build xdyn, the easiest is to use Docker.

Depending on your platform, please refer to:

You also need make.

Installing

Once Docker is installed, use:

make

to build both the Windows & the Debian versions.

If you only want one of the two versions, you can use:

make debian

make windows

which performs a cross-compilation for Windows using GCC.

The binaries can then be found in build_windows or build_debian, respectively.

If you wish to build only part of the project, use:

./ninja_windows.sh package

for example, to build the Windows package (ZIP file containing the xdyn executable)

./ninja_debian.sh run_all_tests

to rebuild the Debian tests.

Once the build has finished, you can run the tests.

Running the tests

To run the tests for Debian use:

./run_all_tests_debian.sh

To run the Windows tests (using Wine in a Docker container) enter:

./run_all_tests_windows.sh

The tests are written using Google test. These are both end-to-end tests and unit tests. The end-to-end tests can be a bit long so you can disable them using Google tests filters:

./run_all_tests_debian.sh --gtest_filter=-'*LONG*'

All arguments after the script name are passed to the GTest executable. Please refer to the Google Test documentation for details and other available options.

Running xdyn

Running xdyn on Windows

Compile xdyn (make windows), install the xdyn executable, then run:

./xdyn <yaml file> [xdyn options]

All options can be found in the documentation.

For example, to run the first tutorial, from the executables/demos folder, you can run:

./xdyn tutorial_01_falling_ball.yml --dt 0.1 --tend 1

Running xdyn on Debian

Compile xdyn (make debian) and install the xdyn executable (sudo dpkg -i xdyn.deb). You'll also need to install libgfortran3 (for debian9) or libgfortran5 (for debian10).

You can then run:

xdyn <yaml file> [xdyn options]

All options can be found in the documentation.

For example, to run the first tutorial, from the executables/demos folder, you can run:

xdyn tutorial_01_falling_ball.yml --dt 0.1 --tend 1

Running xdyn on Debian with Docker

To create a Docker image containing xdyn, run:

make debian
make docker

To run the xdyn Docker container, use:

docker run -it --rm -u $(id -u):$(id -g) -v $(pwd):/build -w /build/path_to_yaml_file xdyn <yaml file> [xdyn options]

Flag --rm deletes the container (not the image) after exit
Flag -u $(id -u):$(id -g) launches the container with the permissions of the current user, which ensures the files generated by xdyn (if any) are owned by the current user
Flag -v $(pwd):/build mounts the current directory to the container's /build directory
Flag -w /build/path_to_yaml_file sets the container's working directory and path_to_yaml_file should be replaced by a sub-path of the current directory

More details can be found in Docker's official documentation.

For example, to run the first tutorial and display the results in the terminal, assuming we are in the project's root directory:

docker run -it --rm -u $(id -u):$(id -g) -v $(pwd):/build -w /build/build_debian/executables/demos xdyn tutorial_01_falling_ball.yml --dt 0.1 --tend 1 -o tsv

Results can be plotted using Matplotlib and pandas (which can be installed using pip3 install matplotlib pandas):

docker run -it --rm -u $(id -u):$(id -g) -v $(pwd):/build -w /build/build_debian/executables/demos xdyn tutorial_01_falling_ball.yml --dt 0.1 --tend 1 -o csv | python3 postprocessing/Python/plot.py tutorial_01_plot 0 3

Debugging

Valgrind

The memory analyzer Valgrind can be used during development to check for memory leaks and use of uninitialized values. To use it, first build a debug version (if you haven't already):

./ninja_debug.sh run_all_tests
~~~~~

then run:

~~~~~~{.bash}
./run_all_tests_valgrind.sh
~~~~~

This script accepts any [flag `run_all_tests` does](https://gitlab.inria.fr/Phylophile/Treerecs/blob/f6551e06797b52819ba3e630b92315254a944da5/tests/gtest/googletest/docs/AdvancedGuide.md#running-test-programs-advanced-options), in particular filtering:

~~~~~~{.bash}
./run_all_tests_valgrind.sh --gtest_filter='Gravity*'
~~~~~

### GDB

A script called `gdb.sh` can be used during development to launch `xdyn` or the
unit tests under [GDB](https://www.gnu.org/software/gdb/).

To debug xdyn, first build a debug version (if you haven't already):

~~~~~~{.bash}
./ninja_debug.sh xdyn
~~~~~

Then run:

~~~~~~{.bash}
./gdb.sh /build/executables/xdyn

This will open a GDB prompt. To close it, press Ctrl+D. For more details on how to use GDB, refer to the official GDB documentation.

To launch the debugger on the unit tests, first build a debug version (if you haven't already):

./ninja_debug.sh run_all_tests

Then run:

./gdb.sh run_all_tests

Deployment

Add additional notes about how to deploy this on a live system.

Built With

CMake - Used to compile C++ code for various platforms.
Make - Used for the one-step build described above.
GCC - Compiler used for both the Windows & Linux: Visual Studio is currently not supported.
Boost - For command-line options, regular expressions, filesystem library.
yaml-cpp - To parse the input files.
HDF5 - To store the outputs.
Eigen - For matrix manipulations.
Pandoc - To generate the documentation.
Pweave - To generate the tutorials.
SSC - For websockets, units decoding, interpolations, kinematics, CSV file reading and exception handling.

Contributing

Please read CONTRIBUTING.md for details on how to submit issues & pull requests to xdyn. Our code of conduct is the Contributor Covenant (original version available here ).

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the Eclipse Public License (version 2) - see the LICENSE.md file for details.