Modeling User Defined VOF Waves

The User Defined Wave model within Simcenter STAR-CCM+ allows you to perform a free surface simulation using any type of wave that has been created externally. Typically, these external waves are generated using third-party potential wave kinematic solvers.

You import data from the third party wave solver into Simcenter STAR-CCM+ by using a file in CGNS format (this process corresponds to a one-way file-based coupling.) Therefore, before you begin, you generate a CGNS file that contains the velocity and the surface elevation data of the wave that you want to import. You can provide the velocity as 2D or 3D data. 2D velocity data (on a cross-section) is sufficient when the wave does not change in the transversal direction. You define the free surface elevation data on a horizontal plane, for example, the undisturbed free water surface.
To set up a free surface simulation with a user-defined wave, the following steps are executed in each time-step:
  • Import the external CGNS data for the free surface elevation and velocity into Simcenter STAR-CCM+.
  • Map this data to the full computational domain through the use of surface to volume data mappers (transversal invariant waves) or volume to volume data mappers (transversal varying waves).
  • Calculate the VOF wave field for each time-step when you run the simulation.
To model User Defined VOF waves:
  1. Import the CGNS data:
    1. Create an external physics continuum for CGNS file import
      If you are importing 2D data use the Surface Three Dimensional model. If you are importing 3D data use the Three Dimensional model. For more information see Preparing the Simulation for CGNS File Exchange.
    2. Expand the External Link > [Link 1] node and set the following properties:
      Node Property Setting
      Conditions
      Transfer Direction Option Import
      External Continua Continua Set to the external physics continuum.
      Values
      File Directory Specify the folder where the CGNS file is located.
      Base Filename Set to the external CGNS file that contains the velocity and the free surface elevation data.
    3. Right-click the External Link > [Link 1] node and select Import Meshes.
    4. Repeat step 3, but select Import Fields.
Once you have imported the CGNS data into Simcenter STAR-CCM+, you map it onto the full computational domain. Since velocity and elevation can be provided as either 2D or 3D data, you need to use the appropriate data mapper. For the 2D data, you use a surface to volume data mapper and for 3D data, you use a volume to volume data mapper. You create two data mappers: one for the velocity and one for the surface elevation data.
  1. To define the data mappers for velocity and free surface elevation:
    1. Create either surface or volume data mappers for the velocity and the free surface elevation data. See Mapping Data from Surface, Volume, or Beam Sources.
    2. For each surface to volume data mapper, right-click the Tools > Data Mappers > [surface data mapper] > Target Specifications node and select New Group > Volume.
    3. Expand the Tools > Data Mappers > [elevation data mapper] and [velocity data mapper] nodes and set the following properties:
      Node Property Setting
      [elevation data mapper] Source Surfaces or Source Volumes Set to the CGNS region that contains the elevation data.
      Source Stencil For CGNS data coming from an external wave solver, typically set to Vertex. If the CGNS data is cell-centered, set to Face.
      Scalar Field Function [Co-Simulation:Free Surface Elevation]
      Target Specification > Surface 1 (Surface to Volume Data Mapper only) Target Entities To improve accuracy, you are advised to map elevation data to all boundaries where you need to specify wave boundary conditions, typically inflow and outflow boundaries.
      Target Stencil Face
      Target Specification > Volume 1 Target Entities Set to the region that represents the computational domain.
      Target Stencil Cell
      [velocity data mapper] Source Surfaces or Source Volumes Set to the CGNS region that contains the velocity data.
      Source Stencil For CGNS data coming from an external wave solver, typically set to Vertex. If the CGNS data is cell-centered, set to Face.
      Scalar Field Function [Co-Simulation:Velocity X], [Co-Simulation:Velocity Z], and Co-Simulation: Velocity Y (Volume to Volume Data Mapper only)
      Target Specification > Surface 1 (Surface to Volume Data Mapper only) Target Entities To improve accuracy, you are advised to map velocity data to all boundaries where you need to specify the wave boundary conditions, typically inflow and outflow boundaries.
      Target Stencil Face
      Target Specification > Volume 1 Target Entities Set to the region that represents the computational domain.
      Target Stencil Cell
    4. Right-click the Data Mappers > [elevation data mapper] node and select Map Data.
    5. Repeat the previous step, but right-click the [velocity data mapper] node.
      The data mapper takes the imported CGNS mesh and CGNS field data and interpolates it from the source surfaces (CGNS regions) to the target volume (computational domain region). For more information see Data Mapper Reference by Type.
  2. Associate the mapped data with the user-defined wave profiles:
    1. Right-click the Continua > Physics 1 > VOF Waves > Waves node and select New > User Defined.
    2. Select the Waves > User Defined VOF Wave 1 node and set the following properties:
    Node Property Setting
    Free Surface Elevation Scalar Function [Mapped Free Surface Elevation]
    Wave Velocity Method Composite
    Composite > X Component Method Field Function
    Scalar Function [Mapped X Velocity]
    Composite > Y Component Method Field Function
    Scalar Function [Mapped Y Velocity] (3D only)
    Composite > Z Component Method Field Function
    Scalar Function [Mapped Z Velocity]
Simcenter STAR-CCM+ allows you to run user defined wave simulations using two different methods. You can either run the simulation through a .java macro or you can run the simulation manually using the toolbar options. However, it is recommended that you run the simulation through a .java macro.
  1. To run the simulation using a .java macro:
    1. Create a .java macro either in Simcenter STAR-CCM+ or using an external java text editor which includes the following elements:
      • An execution step to import the CGNS mesh and the CGNS field data:
        coSimulation.executeAction("ImportMesh");
coSimulation.executeAction("ImportFields");
      • A map data command for the elevation and velocity data mappers:
        ((SurfaceDataMapper) simulation.get(DataMapperManager.class).getObject("ElevationMapper")).mapData();
((SurfaceDataMapper) simulation.get(DataMapperManager.class).getObject("VelocityMapper")).mapData();

        The first line maps the free surface elevation data using a surface to volume mapper. The second line maps the velocity data using a surface to volume mapper.

      • An initialize solution step before you step the solution:
        simulation.getSolution().initializeSolution()
      • A while loop to import the CGNS data and run the simulation for one time-step for each of CGNS import link states:
        
while(cgnsImportPartner.getStateIndex() < cgnsImportPartner.getMaxStateIndex()) {
    cgnsImportPartner.setStateIndex(cgnsImportPartner.getStateIndex() + 1);
    coSimulation.executeAction("ImportFields");
    ((SurfaceDataMapper) simulation.get(DataMapperManager.class).getObject("ElevationMapper")).mapData();
    ((SurfaceDataMapper) simulation.get(DataMapperManager.class).getObject("VelocityMapper")).mapData();

    simulation.getSimulationIterator().step(1);
    loop++;
}
    2. Save the macro file.
    3. Click the (Play Macro...) button in the Macro toolbar.
    4. Within the Open window, select the .java file you have create and click Open.
      Simcenter STAR-CCM+ will run the .java macro and run the simulation until the while loop criteria is no longer satisfied and the macro has been run to completion.
  2. To run the simulation manually:
    1. Right-click the External Links > [Link 1] node and select Import Meshes.
    2. Select the External Links > [Link 1] > Values > Import Link State node and set the State Name to the first available state.
    3. Right-click the External Links > [Link 1] node and select Import Fields.
    4. Right-click the Data Mappers > [elevation data mapper] node and select Map Data.
    5. Repeat the previous step, but right-click the [velocity data mapper] node.
    6. Click the (Initialize Solution) button in the Solution toolbar.
    7. When the initialization is complete, select the External Links > [Link 1] > Values > Import Link State node and increase the State Name by one state.
    8. Right-click the External Links > [Link 1] node and select Import Fields.
    9. Right-click the Data Mappers > [elevation data mapper] node and select Map Data.
    10. Repeat the previous step, but right-click the [velocity data mapper] node.
    11. Click the (Step) button in the Solution toolbar.
    12. Repeat the previous five steps for as many time-steps as required.