Simulation components

Table of Contents

• What are simulation components?
• Adding simulation components to the case
• List of simulation components
• Controling execution and file output
  • vorticity
  • lambda2
  • probes
    • Supported types:
    • Example usage:
  • field_writer
  • derivative
  • weak_grad

What are simulation components?

Simulation components, or simcomps fo short, incapsulate additional functionality that may be useful for certain cases but not necessary to run the solver. This can include computation and output of additional fields, in-situ post-processing operations, data sampling, etc.

By design, simulation components can tap into every aspect of the simulation, so they can be quite powerful. As the code grows, we expect to add more and more simcomps to the code.

Adding simulation components to the case

Each simcomp is defined as a single JSON object at are added to an array of objects called simulation_components, which resides directly under the case object.

List of simulation components

The following is a list of simulation components that are currently available in Neko. The list will be updated as new simcomps are added.

• Computation of vorticity field vorticity
• Computation of \( \lambda_2 \) lambda2
• Probing of fields at selected points probes
• Output of registered fields to an .fld file field_writer
• Computation of the derivative of a field derivative
• Computation of the weak gradient of a field weak_grad
• User defined components User defined simulation components

Controling execution and file output

Each simulation component is, by default, executed once per time step to perform associated computations and output. However, this can be modified by using the compute_control and compute_value parameters for the computation and the output_control and and output_value for the output to disk. The parameters for the _control values are the same as for the fluid and checkpointing. Additionally, one can set output_control to global and never. The former will sync the output_ parameter to that of the fluid. Choosing never will suppress output all together. If no parameters for the output_ parameters are provided, they are set to be the same as for compute_.

For simcomps that compute 3D fields, the output can be either added to the main .fld file, containing velocity and pressure, or saved to a separate file. For the latter, the output_filename keyword should be provided. One can additionally provide the precision keyword, which can be set to either single or double to control the precision of the written data.

For example, in the tgv example case the vorticity component is executed once per 50 time steps. The output_ parameters are synced to that, and the vorticity fields will be added to the main .fld file.

{
    "type": "vorticity",
    "compute_control": "tsteps",
    "compute_value": 50
}

vorticity

Computes the vorticity field an stores in the field registry as omega_x, omega_y and omega_z. Currently produces no output.

lambda2

Computes \( \lambda_2 \) for the velocity field and stores it in the normal output files as the first unused field. This means that \( \lambda_2 \) can be found in the temperature field in then fld files if running without a scalar and s1 if neko is run with one scalar.

probes

Probes selected solution fields at a list of points. This list of points can be generated in a variety of ways, but the most common is to use the csv type.

Supported types:

• file: Reads a list of points from a CSV file. The name of the file is provided with the file_name keyword. The CSV file should have the following format:

  x_0, y_0, z_0
  x_1, y_1, z_1
  ...
  x_N, y_N, z_N

  The points are assumed to be in the same units as the simulation.

points: Reads a list of points from a JSON file. The points are specified based in the coordinates keyword and should be a list of x,y,z values. The file should have the following format:

{
  "type": "points",
  "coordinates": [
    0.0, 0.0, 0.0,
    1.0, 0.0, 0.0,
    0.0, 1.0, 0.0,
    0.0, 0.0, 1.0,
    ...
  ]
}

The points are assumed to be in the same units as the simulation.

• line: Generates a list of points along a line. The line is defined by two points, start and end, and the number of points to generate, amount. The points are generated by linearly interpolating between start and end. The line is defined as:

  {
    "type": "line",
    "start": [0.0, 0.0, 0.0],
    "end": [1.0, 1.0, 1.0],
    "amount": 10
  }

• circle: Generates a list of points along a circle. The circle is defined by a center, center, a radius, radius and the normal, normal, the number of points to generate is controlled by amount. The points are generated by rotating a point around the center starting from the specified axis projected onto the circle. The circle is defined:

  {
    "type": "circle",
    "center": [0.0, 0.0, 0.0],
    "radius": 1.0,
    "normal": [0.0, 0.0, 1.0],
    "axis": "x",
    "amount": 4
  }

  Leads to the following points:

  1.0, 0.0, 0.0
  0.0, 1.0, 0.0
  -1.0, 0.0, 0.0
  0.0, -1.0, 0.0

Example usage:

{
  "type": "probes",
  "compute_control": "simulationtime",
  "compute_value"    : 1,
  "fields": ["w","s"],
  "output_file":  "output.csv",
  "points": [
     {
       "type": "file",
       "file_name": "points.csv"
     }
   ],
}

This probes the fields 'w', and 's' in the points described by points.csv and outputs into output.csv every 1 time units.

The probed information will be saved in the output file in the following format:

N_p, N_f, fields[0], fields[1], ..., fields[N_f-1]
p_0_x, p_0_y, p_0_z
p_1_x, p_1_y, p_1_z
...
p_N_p_x, p_N_p_y, p_N_p_z
time_0, p_0_field_0, p_0_field_1, ..., p_0_field_N_f-1
time_0, p_1_field_0, p_1_field_1, ..., p_1_field_N_f-1
...
time_0, p_N_p_field_0, p_N_p_field_1, ..., p_N_p_field_N_f-1
time_1, p_0_field_0, p_0_field_1, ..., p_0_field_N_f-1
time_1, p_1_field_0, p_1_field_1, ..., p_1_field_N_f-1
...
time_N_p, p_N_p_field_0, p_N_p_field_1, ..., p_N_p_field_N_f-1

field_writer

Outputs registered 3D fields to an .fld file. Requires a list of field names in the fields keyword. Primarily to be used for outputting new fields defined in the user file. The fields are added to then neko_field_registry object and are expected to be updated in the user file, or, perhaps, by other simcomps. Since this simcomp does not compute anything compute_ configuration is irrelevant.

{
  "type": "field_writer",
  "fields": ["my_field1", "my_field2"],
  "output_filename": "myfields",
  "precision": "double",
  "output_control" : "simulation_time",
  "output_value" : 1.0
}

derivative

Computes the derivative of field along a chosen direction (x, y, or z). The field to derivate is controlled by the field keyword and the direction by the direction keyword. The simcomp will register the computed derivatives in the registry as d[field]_d[direction], where the values in the brackets correspond to the choice of the user keywords. Supports writing the computed fields to disk via the usual common keywords.

{
  "type": "derivative",
  "field": "u",
  "direction", "y",
  "output_control" : "simulation_time",
  "output_value" : 1.0
}

weak_grad

Computes the weak gradient of a field. The weak gradient is value of the gradeint multiplied by the local value of the mass matrix. This is how a gradient term appears in the weak formulation of the governing equations The field to derivate is controlled by the field keyword. The simcomp will register the computed components of the gradients in the registry as weak_grad_[field]_x, weak_grad_[field]_y, weak_grad_[field]_z where the value in the brackets corresponds to the choice of the user keyword. Supports writing the computed fields to disk via the usual common keywords.

{
  "type": "weak_gradient"
  "field": "u",
  "output_control" : "never"
}