.. _nemoh-interface: NEMOH ***** The time domain simulator requires that you supply frequency domain hydrodynamic coefficients derived from potential flow analysis. One program capable of generating the required data is `NEMOH`_. NEMOH is a Boundary Element Methods (BEM) code dedicated to the computation of first order wave loads on offshore structures (added mass, radiation damping, diffraction forces). It was been developed by researchers at Ecole Centrale de Nantes for 30 years before being released under a free software licence (`Apache v2`_). .. _NEMOH: https://lheea.ec-nantes.fr/logiciels-et-brevets/nemoh-presentation-192863.kjsp?RH=1489593406974 .. _Apache v2: http://www.apache.org/licenses/LICENSE-2.0 Detailed information can be found at the project homepage linked above and in academic papers, links for which can also be found at the project homepage. This document focusses on the use of a Matlab preprocessor which has been developed as part of the |TNShort| to ease the creation of this data for WECs, rather than the details of what NEMOH produces. Getting Nemoh ============= For information and instructions on obtaining and installing Nemoh, see :ref:`install-nemoh`. Note also the section :ref:`nemoh-interface-exec-loc` below. NEMOH Preprocessor ================== The Matlab preprocessor for NEMOH is based on an object oriented approach. Two classes are used to describe the system to be simulated a ``body`` class and a ``system`` class. The system class acts as a container for one or more body objects and generates the Nemoh input files. Like the |TNShort|, and MBDyn tools, the NEMOH classes are intended to be a standalone package and as such are in their own `namespace`_ ``nemoh``. This means the classes must be referenced using syntax like ``nemoh.body`` and ``nemoh.system``. The use of the preprocessor is best demonstrated with a simple example, as shown in the listing below, which shows how to simulate a simple cylinder using the NEMOH preprocessor. .. literalinclude:: /examples/example_nemoh_cylinder.m :linenos: This script can be broken down as follows. The fist section simply does some Matlab magic to locate the directory containing the example file, and create a subdirectory in that directory in which we will generate the NEMOH input files from the Matlab description of the problem .. literalinclude:: /examples/example_nemoh_cylinder.m :end-before: %% create the Nemoh body The next part creates the body for for which the hydrodynamics will be solved. A simulation can be made up of multiple bodies, but here we will just have the cylinder. In this case, the cylinder is specified using a 2D profile from which a 3D mesh is generated by rotating it around the Z axis. The method ``makeAxiSymmetricMesh`` is provided to accomplish this. See the help for ``makeAxiSymmetricMesh`` for more details on how to specify a mesh in this way. Note also the use ``nemoh`` package namespace in the body creation command. .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% create the Nemoh body :end-before: %% draw the course body mesh (will be refined later) ``makeAxiSymmetricMesh`` creates only a course representation of the mesh, which must be refined by the Nemoh meshing program. However, at this point we can draw the course mesh by calling the ``drawMesh`` method. .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% draw the course body mesh (will be refined later) :end-before: %% Create the nemoh simulation The mesh is shown in :numref:`ex_cylinder_course_mesh`: .. _ex_cylinder_course_mesh: .. figure:: example_nemoh_cylinder_fig_1_course_mesh.png As can be seen, by default the symmetry of the body is taken advantage of to reduce the computation time by calculating for only half the axisymmetric mesh. The next section creates a NEMOH simulation preprocessor object and puts the body into it at the same time. .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% Create the nemoh simulation :end-before: %% write mesh files Bodies don't have to added at this point, they can be also be added by calling the ``nemoh.simulation.addBody`` method later, the 'Bodies' argument is optional. The simulation has one non-optional argument, which is the input directory where all NEMOH files will be generated. The nest step writes mesh files for each of the bodies in the simulation (just the cylinder in this case). This method calls the ``writeMesh`` method for each body in the simulation. .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% write mesh files :end-before: %% process mesh files What is actually done by writeMesh depends on the type of mesh the body has. For the axisymmetric mesh type it writes the course mesh description in a file format understood by the NEMOH meshing program. The mesh program must be run on the course mesh input file to generate the mesh file suitable for input to the other NEMOH programs. To do this step, the ``processMeshes`` method is called. .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% process mesh files :end-before: %% Draw all meshes in one figure ``processMeshes`` calls the ``processMesh`` method for every body in the simulation. ``processMesh`` does any processing required for the body mesh to create the appropriate input files for the other NEMOH programs. What this processing actually is (if any) depends on the mesh type. With the mesh files generated, we can draw the meshes again: .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% Draw all meshes in one figure :end-before: %% Generate the Nemoh input file The simulation ``drawMesh`` object draws the meshes for all bodies in the simulation in one figure. The now refined cylinder mesh is shown in :numref:`ex_cylinder_refined_mesh`. The blue arrows in the figure denote the direction of the mesh face normals. NEMOH requires that these point outward into the fluid. .. _ex_cylinder_refined_mesh: .. figure:: example_nemoh_cylinder_fig_2_refined_mesh.png We can now proceed to generate the Nemoh input files. It is at this point that the simulation parameters are provided. .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% Generate the Nemoh input file :end-before: %% Run Nemoh on the input files As stated in the comments in the code section above, there are several optional arguments which can be provided to control the calculation, and details about their use can be found in the help text for the ``nemoh.simulation/writeNemoh`` method. This help is shown below: Output of ``help nemoh.simulation/writeNemoh`` .. literalinclude:: /generated/help.nemoh.simulation.writeNemoh :language: none The final step is to run the NEMOH on the input files .. literalinclude:: /examples/example_nemoh_cylinder.m :start-at: %% Run Nemoh on the input files The ``run`` method first writes the small `input.txt` and `ID.dat` files required by NEMOH, then runs the preProcessor, solver and postProcessor on the generated input files. The hydrodynamic data will have been output to the usual files produced by NEMOH. Note that the ``run`` method is capable of accepting additional optional arguments not used here in order to control the solver type (achieved by setting variables in the `input.txt` file). Again, details of the available options may be found in the help for the ``nemoh.simulation/run`` method which is shown below. Output of ``help nemoh.simulation/run`` .. literalinclude:: /generated/help.nemoh.simulation.writeNemoh :language: none .. _nemoh-interface-exec-loc: The NEMOH Executables Location ============================== It is worth noting that by default, the NEMOH interface described here assumes that the NEMOH program files (called Mesh.exe, preProcessor.exe, Solver.exe and postProcessor.exe on windows, and mesh, preProcessor, solver and postProcessor on Linux/Mac) are installed somewhere on you computer such that you can run them just by typing their name on the command line without giving their full path (i.e. they are on the `program path`_). If this is not the case, e.g. you haven't installed them, or you are testing more than one version of NEMOH installed in different directories, you can specify the NEMOH install location when creating the ``nemoh.simulation`` object by using the optional ``'InstallDir'`` option. See the help for the simulation constructor (``help nemoh.simulation/simulation`` for more details). .. _namespace: https://uk.mathworks.com/help/matlab/matlab_oop/scoping-classes-with-packages.html .. _program path: https://en.wikipedia.org/wiki/PATH_(variable)