Skip to content

GitLab

Last edited by Claudio Giovanni Caccia;Claudio Giovanni Caccia
Page history

preCICE MBDyn adapter

Overview

This adapter allows to perform fluid-structure interaction (FSI) simulations using:

  • MBDyn as structural solver
  • preCICE for coupling with any available CFD solver

some examples of usage are given in the tutorials and in the test-cases.

The code is currently hosted here.

Prerequisites and Dependencies

Apart from MBDyn and preCICE, which should already have been installed, the code depends on:

  • RapidJSON: used for the input file
  • VTK: for the output files

On Ubuntu they can be installed by:

sudo apt install rapidjson-dev libvtk7-dev

which should be available in the repositories.

Compile the adapter

Makefile variables

The code is independent from MBDyn and preCICE, but uses the libraries libmbc.so and libprecice.so.

The Makefile refers to the previously installed VTK libraries (version 7.1) so, if another version has to be used, the include directory (variable VTK_ROOT) and the linked libraries must be changed accordingly. It also looks for MBDyn in usr/local/mbdyn (variable MBDYN_ROOT).

If preCICE (see the quickstart) is installed using the deb package or compiled and installed in the default directory, it should be automatically found.

Otherwise the output of pkg-config --cflags libprecice and pkg-config --libs libprecice should be added to the Makefile.

Compile

To compile the adapter simply give:

make all

The executable is named mbdyn-esm-adapter (the name can be changed with the Makefile variable PROGRAM_NAME). There is no install script.
All the intermediate and output files can be removed by typing

make clean

Prepare a simulation

This adapter makes use of the MBDyn function external structural mapping: for this reason a FSI simulation needs to be set up on the MBDyn side. You should refer to the input manual (e.g. here for MBDyn version 1.7.3, section 8.8.11) for further details.

Mesh preparation

The first step consists in preparing a mesh of points. The same mesh is needed by:

  • MBDyn: in order to map the model structural nodes to the interface mesh (so that forces and displacements can be computed)
  • the adapter: in order to exchange information with the CFD solver through preCICE

The file has the form:

XX # n. of points
x1 y1 z1
x2 y2 z2
...
XX # n. of cells
p1 p2 p3 (p4)
...

Specifications:

  • lines beginning with # are considered comments
  • the first line contains the number of points in the mesh
  • the following lines contain the x,y,z coordinates of each point
  • the next line contains the number of cells in the mesh. These data are used by the adapter
    • for drawing the output data
    • for mapping purposes (e.g. nearest projection, but yet to be implemented)
  • the following lines contain the list of points belonging to a cell:
    • the order refers to the list above
    • the number is 1-based (i.e. first point is labeled 1)
    • triangular and quadrangular cells can be used

Please note that the parser in the adapter is quite raw and not very tolerant.

Automate the mesh file preparation

In order to simplify the file generation, a small script has been prepared. It ca be found in the utils directory of the project, in the salome subdirectory. It can be used in the Salome environment in the Mesh module. Simply load the script exp_dat.py and then type in the python shell:

ExportDATFile('Mesh','filename')

to generate a file containing the information concerning the selected mesh.

Generate the Mapping Matrix for MBDyn

This operation is described in the MBDyn input manual (section 8.8.11) and briefly reported here for clarity:

Generation of points file

Your MBdyn configuration file should contain, in the external structural mapping definition, 3 lines in the form:

#echo, "mesh_points.dat", surface, "mesh.dat", output, "mesh_H.dat", order, 2, basenode, 12, weight, 2, stop;
mapped points number, 86,
sparse mapping file, "mesh_H.dat";

Note:

  • the first line is normally commented out:
  • the file mesh.dat is the one generated above
  • the number of points in the second line must coincide with the points of the mesh

In order to generate the file mesh_points.dat you should uncomment the first line and run something like:

mbdyn -f filename.mbd

where filename.mbd is the MBDyn input simulation file. Then the first line should be commented back.

Generation of H matrix file

This step generates the mapping matrix H, using the files mesh.dat and mesh_points.dat.

The matrix is stored in the file mesh_H.dat (see the code snippet above).

This step requires Octave:

  1. start octave
  2. add the MBDyn project subdirectory contrib/MLS/ to Octave path (e.g. type addpath('path/to/contrib/MLS'))
  3. execute the create_mls_interface function to generate the matrix file (e.g. type create_mls_interface(mesh_points.dat) )

At this point MBDyn is ready to perform a simulation.

Run a simulation

In general, the root directory of a simulation contains:

  • a directory Fluid containing the CFD case
  • a directory MBDyn containing the MBDyn case
  • the preCICE configuration file (precice-config.xml)
  • a MDByn adapter configuration file (config.json)
  • some scripts to run, monitor and clean the simulation

JSON configuration file

The adapter requires a json file for configuration purposes. The structural part of the simulation starts by typing:

mbdyn-esm-adapter -f config.json

The configuration files must contain the following information:

  1. information regarding the coupling : those name must be equal to the ones contained in the preCICE configuration file (i.e. name of the participant, name of the mesh, name of data to be read and written, location of the preCICE configuration file):
{
    "participantName" : "Solid"
    "meshName": "Solid-Mesh"
    "readDataName": "Displacements0"
    "writeDataName" : "Forces0"
    "precice-config": "./precice-config.xml"
  1. information regarding the mbdyn simulation:
  • location and name of the mesh file, the coordinates of the origin to compute the resultant moment on the structure, name and location of the file containing the resultant
    "mesh": "/MBDyn/mesh/root0.dat"
    "root-coords": [0.0, 0.0, 0.0]
    "resultant-file": "./MBDyn/output/resultant.txt"
  • name and location of the MBDyn configuration file, name of the socket for the external structural force (must coincide with the name in the MBDyn configuration file), location and prefix for MBDyn output files, log and VTU files and its output frequency (in # of iterations)
    "mbdyn-input": "./MBDyn/map_4n_3x_9j.mbd"
    "node-socket": "/tmp/mbdyn2.node.sock"
    "mbdyn-output": "./MBDyn/out_mbd"
    "mbdyn-log-location": "./MBDyn/mbd/"
    "vtk-output": "./MBDyn/output/MBDyn-OF_"
    "write-interval": 1
  1. flag to set if \Delta displacements must be passed to preCICE
    "displacement-delta": false
  1. parameters to define the progressive loading of the structure: an initial coefficient (coeff0) is applied to the forces coming from the interface for the first cycles (iterstart), then the structure is progressively loaded up to 100% for the next iterations (period) with a linear ("linear") or \frac{1}{2}\left(1 - \cos \right) law ("cos"). The keyword "none" avoids progressive loading
    "coeff0": 0.01
    "iterstart": 202
    "period": 198
    "ramp-type": "linear"
}

Tutorials

Some simple examples of usage are located here.

Dummy Fluid solver

Here it is possible to couple an MBDyn instance with a dummy fluid solver, written in python, which can can load a set of configurable nodes with a configurable time law.

Vertical flap

The case of a flexible vertical flap invested by a flow

  1. MBDyn OpenFOAM

Shows the coupling with OpenFOAM with a laminar incompressible flow

  1. MBDyn SU2

Shows the coupling with a possibly outdated version of the SU2-adapter

Test Cases

The current set-up has been validated with the Turek-Hron FSI benchmarks. It is possible to run simulations validating the fluid part, the structural part, or the complete FSI system according to the specifications given in the article.

CFD

The fluid part has been simulated in OpenFOAM and the 3 test cases are located here. For each test case:

  • the OpenFOAM dictionaries are configured for the ESI version
  • the user can define the fineness of the mesh, by selecting one of the BlockMeshDict files available (i.e. giving the name BlockMeshDict to one of the BlockMeshDict* files in the system directory)
  • the simulations use groovyBC (i.e. swak4foam) to generate a parabolic inlet profile. Otherwise the user must comment the groovyBC boundary condition and uncomment uniform in the U dictionary
  • The simulation starts by giving ./runFluid (or ./runFluid -parallel for a parallel computation) in the home directory of the case
  • The script ./Allclean cleans the case
  • The results can be analyzed using this ipython notebook, in the directory containing the 3 test cases.

CSM

The structural part has been simulated with MBDyn and preCICE connection with preCICE is used to get the displacements a the interface points (tip displacement). The 3 test cases are located here. For each test case:

  • the name of the directory indicates the case and the number of beam elements (i.e. CSM1-4 is case 1 with 4 beam elements).

  • the subdirectory MBDyn contains the model of the cantilever. The model uses the gravity force to define how the structure is loaded

  • the subdirectory dummy contains the dummy solver which sends 0 forces and reads the displacements.

  • CSM-1 and 2 are considered static and CSM-3 dynamic, in the paper. CSM-1 and 2 are simulated with a high structural damping and the final tip displacement is read as static deformation. CSM-3 used a very low damping so that if is possible to estimate the frequency

  • how to run:

    • open 2 shells
    • in one go to current-case/MBDyn and type mbdyn-esm-adapter -f ../config.json
    • in the other go to current-case/dummy and give ./runFluid, which calls python3 and the dummy solver, which simply reads the displacements at the interface

  • the script ./Allclean cleans the case

  • some analyses of the results are contained in the directory results. A jupyter-notebook reads some data from previous simulations

FSI

The FSI test-cases put together some of the elements seen in CFD and CSM cases.

  • the subdirectory MBDyn contains the cantilever model

  • the subdirectory Fluid contains the OpenFOAM model

  • how to run:

    • open 2 shells pointing to the root of the current case
    • the structural symulation starts with mbdyn-esm-adapter -f config.json
    • the CFD simulation starts by giving ./runFluid (or ./runFluid -parallel for a parallel computation)
    • the script plotDisplacement.sh is a gnuplot script to plot the y tip displacement
    • the sctipy plotConv.sh is a python script that plots the convergence error and the number of iterations of the coupled simulation

  • the script ./Allclean cleans the case

  • some analyses of the results are contained in the directory FSI. Some jupyter-notebooks read some data from the directories where the simualtions are run