eulerian_scalar_field and eulerian_vector_field commands

Purpose

Define a Eulerian field read from file to be used in enable_one_way_coupling command. Separate commands for scalar and vector fields are available.

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

eulerian_scalar_field keyword value
eulerian_vector_field keyword value

With the following keyword argument pairs:

Keywords	Description
file	the file to read mandatory
field_name	the field name to define (Aspherix internal) must be one of the folling: rho, vorticity, eps, T, k, U, voidfraction mandatory
field_name_to_read	the field name to be used for reading from file optional, default is same as field_name
field_settings_id	the id of previously defined eulerian_field_settings command mandatory
is_transient	bool (yes or no) determining if the field changes in time default: no
is_periodic_in_time	bool (yes or no) determining if the field is periodic in time, only read if is_transient yes default: no
update_every_time	scalar value determining how often the field is interpolated in time, only read if is_transient yes default: same frequency as used for drag computation set in enable_one_way_coupling command
region	region id in which the field is valid default: entire simulation domain
use_elevation	bool (yes or no) determining if the elevation field must be used to set the field value default: no optional, but only available if is_transient yes is used
value_below_elevation	scalar setting the field value below the elevation mandatory if use_elevation is used
value_above_elevation	scalar setting the field value above the elevation optional if elevation is used default: 0
use_relative_field	bool (yes or no) determining if a relative value must be added to the elevation values default: no optional if use_elevation is used, it makes the field_name_to_read obligatory

Examples

eulerian_vector_field field_name "U" file data/velocity.csv
eulerian_scalar_field field_name "T" file data/sequence.txt is_transient yes update_every_time 1e-4

Description

Set up a Eulerian field for usage in enable_one_way_coupling command. Field data is read from the specified file, see Binsize and interpolation settings are retrieved from the specified eulerian_field_settings command. Depending on the data type (scalar or vector), the correct command must be used, i.e. eulerian_scalar_field or eulerian_vector_field.

Static field

The field data is assumed to be constant over time.

Static field definition

Three different file formats can be handled:

1. *.csv

2. *.vtk

3. *.vtu.

If a *.vtk or *.vtu is provided, a vector field named ‘U’ must be specified. You can use the resample_to_regular_grid command to convert legacy VTK files obtained from OpenFOAM’s foamToVTK tool to VTU files.

The binsize of the used eulerian_field_settings command is used to define the size of the structured bins/grid cells that fills the region. In case that binsize does not lead to an integer number of bins in x/y/z direction, the x/y/z bin sizes will be rounded up so to achieve this. The binsize will also be automatically adjusted in case it would lead to a too fine mesh. If the total number of cells exceeds max_bins (see eulerian_field_settings command), the command will halt with an error.

The option interpolate_field_to_grid of the used eulerian_field_settings command allows to switch between two different modi:

1. If yes, then the provided field must be an exact reprensentation of the internal field (same bounding box, same binsize). Each data point of the provided field will be used as a data point in the internal field. Therefore this approach is very fast, as no interpolation is done.

2. If no, then the provided field will be interpolated to the internal field, which is easier to use as no a-priori preparation of the field is needed. In case of enabled interpolation the file is loaded, where the average value of all contained points of the bin is assigned to the bin. For undefined bins the corresponding value is calculated by averaging over already defined neighbors.

For the import of csv files, the following file format must be provided:

Legacy csv immport

If a *.csv is provided for the velocity field, the file must contain a header line and data lines. The first three columns must contain any coordinate inside the bin/grid cell for which the field value should be set, followed by data for the field. The header line starts with x y z, followed by the name of each field. For vector fields the three components need to be provided separately, see example below. Note that the data columns in the file must be space delimited. Example of the file format for fluid velocity U and a density rho:

x y z                           U_x U_y U_z
-0.500000 -0.500000 0.500000    5.  0.  0.
-0.500000  0.500000 0.500000    5.  0.  0.
 0.500000 -0.500000 0.500000    0.  0.  0.
 0.500000  0.500000 0.500000    0.  0.  0.

x y z                           rho
-0.500000 -0.500000 0.500000    1000.
-0.500000  0.500000 0.500000    1000.
 0.500000 -0.500000 0.500000    1000.
 0.500000  0.500000 0.500000    1000.

Warning

The value for each bin/grid cell has to be set, and none of the cells must be assigned a value twice (by two lines in the file).

Transient field

The field is assumed to vary over time, defined by a series of files, each defining the field at a certain instance of time.

Transient field definition

If is_transient yes, then file is assumed to be a sequence file of the following form:

# anything staring with a hash is ignored
# timestamp path/to/fluid/file
0.01 u_fluid_1.data
0.02 u_fluid_2.data
0.05 u_fluid_3.data
0.06 u_fluid_4.data
....

The first column is a timestamp in time units, the second column specifies a path to a file containing fluid field information that follows the same format specifications as described above for static fields. The actual field values to be used for the are then found by linear interpolation between the previous and the next file: if, in the above example, the current simulation time is , the field is obtained by interpolation between the fields specified in u_fluid_1.data and u_fluid_2.data. The time stamps need to be in strictly ascending order, but do not need to start at 0. For times before the first time stamp, only the first flow field is used. For times after the last time stamp, only the last flow field is used.

If is_periodic_in_time yes, the fluid field is considered periodic in time. In this case, the first and the last line of the sequence file must refer to the same file in order to define the period length:

0.01 u_fluid_1.data
0.02 u_fluid_2.data
0.05 u_fluid_3.data
0.06 u_fluid_4.data
0.09 u_fluid_1.data

In the above example, the file u_fluid_1.data will be used for the first , then the sequence starts, and after , the sequence repeats. The period length in this example is .

Elevation field

With the use_elevation option an elevation field / surface can be used to set the value of the field as seen by the particle.

Elevation field definition

A typical example is to set the density field for a body of water, where the water level surface determines the value of the density. When use_elevation yes is used, the value_below_elevation is an obligatory keyword, while the value_above_elevation remains optional (default ). It is only available for transient fields (is_transient yes), and the field_name (sequence file) should contain time levels and (resampled) VTK structured grid data files (vts extension) that contain a field called ELEVATION (this can be adjusted via the field_name_to_read keyword). For each particle, the local elevation will be interpolated from this field and compared to the z-position of the particle. Next, depending on its position, the defined value_below_elevation and value_above_elevation will be used as a local field value for the particle. A linear interpolation in time will be used if that particle is between two time levels.

The data from the vts files might be too coarse to accurately determine if a particle is below / above the elevation (water level). Therefore, it is possible to use the actual 2D water surfaces directly. For this to work, there must be VTK poly data files (vtp extension) with the same names as the vts files (only the extension differs) in the same folder as the vts files. The vtp files (one for each time level) must contain the water level as a 2D surface. Internally, this surface will be used to determine the distance of a particle with respect to this surface. Based on this distance, the defined value_below_elevation and value_above_elevation will be used as a field value for the particle. Note that it is still required to provide the vts files (with the ELEVATION variable), although this data itself is no longer used. A linear interpolation (of the distances) in time will be used if that particle is between two time levels / two water level surfaces.

For stratified flow, where the field value might differ slightly from the defined value_below_elevation and value_above_elevation, the use_relative_field can be used. If enabled, the field_name_to_read is obligatory and must be set to the variable in the vts files containing the relative values to be added. Note that the use_relative_field can only be enabled if use_elevation is used with the 2D surface from vtp files as described above.

Additional information

Any field created using this command is added to the output by default and accessible as an Eulerian field in the result files.

Related commands

eulerian_field_settings command, enable_one_way_coupling command