preCICE-MBDyn-adapter.md

+## Overview
+
+This _adapter_ allows to make __FSI__ (fluid-structure interaction) simulations using:
+
+ - [MBDyn](https://www.mbdyn.org/) as structural solver 
+ - [preCICE](https://www.precice.org/) for coupling with any available _CFD_ solver
+
+some examples of usage are given [below](#examples)
+
+## Prerequisites and Dependencies
+
+Apart from [MBDyn](https://www.mbdyn.org/) and [preCICE](https://www.precice.org/), which should already have been installed, the code depends on:
+
+ - [RapidJSON](https://rapidjson.org/): used for the input file
+ - [VTK](https://vtk.org/): for the output files
+
+On Ubuntu they can be installed by:
+
+```shell
+sudo apt install rapidjson-dev libvkt7-dev
+```
+
+which should be available in the repositories. 
+
+## Compile the adapter
+
+### Makefile variables
+
+The code is independent from [MBDyn](https://www.mbdyn.org/) and [preCICE](https://www.precice.org/), but uses the libraries `libmbc.so` and `libprecice.so`.
+
+The [Makefile](https://gitlab.com/stilita/mbdyn-esm-adapter/-/blob/master/adapter/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](https://www.precice.org/quickstart.html#start-here)) 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:
+
+```shell
+make all
+```
+
+The exacutable 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
+
+```shell
+make clean
+```
+
+## Prepare a simulation
+
+This _adapter_ make 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](https://www.mbdyn.org/userfiles/documents/mbdyn-input-1.7.3.pdf) 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](https://gitlab.com/stilita/mbdyn-esm-adapter/-/blob/master/utils/salome/exp_dat.py) subdirectory. It can be used in the [Salome](https://www.salome-platform.org/) environment in the **Mesh module**. Simply load the script *exp_dat.py* 
+ and then type in the python shell:
+
+```
+ExportDATFile('Mesh','fliename')
+```
+
+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](https://www.gnu.org/software/octave/index):
+
+1. start `octave`
+1. add the _MBDyn_ project subdirectory `contrib/MLS/` to Octave path (e.g. type `addpath('path/to/contrib/MLS')`)
+1. 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
+
+<!--
+json file 
+
+;;;json
+{
+  "title": "About Front Matter"
+  "example": {
+    "language": "json"
+  }
+}
+;;;
+
+-->
+
+## <a name="examples"></a>Tutorials and use cases
+
+### Dummy Fluid solver
+
+### Coupling with OpenFOAM
+
+### Coupling with SU2
\ No newline at end of file