typSurf2Vol ----------- Description ~~~~~~~~~~~ ``Surf2Vol`` is wrapper class to access HOS Ocean and NWT class. Functionality and data of both HOS classes are similar but the mathematical formulation and meshes are a little bit different. Therefore the flow information from each HOS grid is only taken by using HOS mesh base class and transfer it to ``Vol2Vol`` Class. It is reminded that the direct access on the HOS wave fields is only possible by HOS mesh pointer to prevent misuse of HOS wave data. ``Surf2Vol`` class structure is depicted in :numref:`fig:surf2VolStructure`. ``Surf2Vol`` class contains ``HOSOceanSurf2Vol`` and ``HOSNWTSurf2Vol`` classes. When the functionality is called, it calls the functionality of sub-class distiguished by HOS type. When the subroutine ``correct`` is called, the sub-class reads HOS modes from HOS result file and conducts :math:`H_2` operation to re-construct wave fields. Reconstructed wave field is saved on derived HOS grid class. And the HOS grid pointer at ``Surf2Vol`` points to derived HOS grid class to access wave fields. .. figure:: figures/c1.structure/Surf2VolClassStructure.png :alt: ``Surf2Vol`` class structure :name: fig:surf2VolStructure ``Surf2Vol`` class structure ``hosNWTSurf2Vol`` and ``hosOceanSurf2Vol`` classes reconstruct HOS wave fields from HOS result file by using the :math:`H_2` operator. Wave reconstruction and HOS wave theory is well explained in :cite:t:`ducrozet2007` and :cite:t:`ducrozet2012`. Each class constructs wave fields on derived HOS mesh class which can be pointed by HOS mesh base class. HOS wave theory is based on the superposition of base modes which satisfy Laplace equation, sea bottom and free surface boundary condition basically, the behavior of the mode function has an exponential profile. This exponential profile could magnify local modes which has high wave number above :math:`z=0`. For high steepness waves, this property gives unnatural values closed to free surface, criterion to cut local mode is introduced as :eq:`eq:fnzCriterion`. .. math:: :label: eq:fnzCriterion f_{mn}(z) = \begin{cases} \dfrac{\cosh k_{mn}(z+H)}{\cosh k_{mn}H} & \text{if} \quad f_{mn}(z) < C_{f(z)} \\ C_{f(z)} & \text{if} \quad f_{mn}(z) \geq C_{f(z)} \end{cases} where :math:`k_{mn}` is the HOS mode wave number, :math:`z` is the HOS z-coordinates, :math:`H` is the water depth and :math:`C_{f(z)}` is the :math:`f_{mn}(z)` function criterion value (default = 10). The parameter :math:`C_{f(z)}` is set to the default value of 10 in ``Grid2Grid``. If the local wave velocities generated by ``Grid2Grid`` are not sufficient, the parameter can be changed. The parameter is defined in ``modGrid2GridType.f90`` as a ``FNZ_VALUE``. HOS result file only contains mode amplitudes computed at each HOS simulation time, the volumic grid should then be reconstructed from those modes. HOS does not need vertical grid information, so z-directional grid information should be given when HOS ``surf2vol`` is initialised. Constructed HOS grid is used for interpolation grid. To constuct the HOS grid, following information should be given. - ``zMin``, ``zMax`` - ``nZMin``, ``nZMax`` - ``nZMinRatio``, ``nZMaxRatio`` [Optional] where ``zMin`` and ``zMax`` is used to set :math:`z`-directional domain and it should have negative and positive value. ``nZMin`` and ``nZMax`` are the number of :math:`z`-directional grid. It is recommended to have at least 50-100 points for the interpolation. If a sufficient number of grid points is not given, the interpolation scheme could give strange values due to exponetial profile of :math:`f_{mn}(z)`. ``nZMinRatio`` and ``nZMaxRatio`` are the ratio of maximum and minumum height of grid (:math:`{\Delta z_{max}}/{\Delta z_{min}}`). Minimum grid is located at :math:`z=0`. Those are optional values set to be 3 as default. The grid can be visualized by using ParaView. The VTK file is located at VTK/Grid2Grid/surf2volMesh.vtk. Class (Type) ~~~~~~~~~~~~ **Class**: ``Surf2Vol`` - Data: - ``hosNWTSurf2Vol_``: HOS-NWT Surf2Vol Class - ``hosOceanSurf2Vol_``: HOS-Ocean Surf2Vol Class - ``ptrHOSMesh_``: HOS Mesh Pointer - Functionality: - ``initialize``: Initialise HOS Surf2Vol class - ``correct``: Update HOS wave fields - ``destroy``: Class desroyer **Class**: ``HOSOcean`` and ``HOSNWT`` - Data: - ``HOSfile``: HOS result file (``modes_HOS_SWENSE.dat``) or ``modes_HOS_SWENSE.hdf5`` - ``HOSmode``: HOS Ocean or NWT modes - ``HOSmesh``: HOS Ocean or NWT mesh - ``HOSfftw``: HOS FFT class for :math:`H_2` operator - Public Functionality: - ``initialize``: Initialise HOS Ocean or NWT Surf2Vol - ``correct``: Update HOS Ocean or NWT wave fields - ``destroy``: Class desroyer - Private Functionality: - ``init_read_mod``: Read HOS number of modes and allocate dynamic array - ``read_mod``: Read HOS modes at given HOS time index - ``buildGlobalMesh``: Build HOS mesh with the given HOS construction parameter - ``reconstuctionFFTs``: Reconstruct the wave fields by :math:`H_2` operator How to use ~~~~~~~~~~ - Initialise ``Surf2Vol`` .. code:: fortran Call hosS2V%initialize(hosType, filePath, zMin, zMax, nZmin, nZmax, zMinRatio, zMaxRatio) ! hosS2V : Surf2vol Class (Type) ! hosType : HOS Type (Ocean or NWT) ! filePath : HOS result file path (modes_HOS_SWENS.dat) ! zMin, zMax : HOS grid z-minimum and z-maximul (vertical domain) ! nZmin, nZmax : Number of z-directional Grid ! ! zMinRatio, zMaxRatio (Optional) ! : Ratio of maximum and minimum height of grid (default=3) ! or Call hosS2V%initialize(dict) ! hosS2V : Surf2vol Class (Type) ! dict : HOS dictionary to initialize HOS surf2vol (Type) - Correct ``Surf2Vol`` .. code:: fortran Call hosS2V%correct(hosIndex) ! hosS2V : Surf2vol Class (Type) ! hosIndex : HOS time index - Data access on wave field of ``Surf2Vol`` - Wave elevation .. code:: fortran eta = hosS2V%ptrHOSMesh_%eta(ix, iy) ! hosS2V : Surf2vol class (Type) ! ix, iy : HOS grid index (x, y) ! eta : Wave elevation - Wave velocity .. code:: bash u = hosS2V%ptrHOSMesh_%eta(ix, iy, iz) v = hosS2V%ptrHOSMesh_%eta(ix, iy, iz) w = hosS2V%ptrHOSMesh_%eta(ix, iy, iz) ! hosS2V : Surf2vol class (Type) ! ix, iy, iz : HOS grid index (x, y, z) ! u, v, w : Wave velocity (x, y, z) - Dynamic pressure (:math:`p_d = p - \rho g z`) .. code:: fortran pd = hosS2V%ptrHOSMesh_%pd(ix, iy, iz) ! hosS2V : Surf2Vol class (Type) ! ix, iy, iz : HOS grid index (x, y, z) ! pd : Dynamic pressure - Destruct of ``Surf2Vol`` .. code:: fortran Call hosS2V%destroy() ! hosS2V : Surf2Vol class (Type)