Impose Regions

Note: The keyword-value pairs of imposeRegions will undergo significant modifications in nanoFluidX 2022. CUBOID and SPHERE shapes will be deprecated. PARALLELEPIPED and CYLINDER shapes will cover or extend the functionalities of the removed shapes.

There are two categories to define: geometric shape and effect type.

Available geometric shapes:

PARALLELEPIPED
CYLINDER (with or without hemispherical caps)

Available effect types:

Velocity (corresponding command suffix: *vel)
Acceleration (corresponding command suffix: *acc)
Porous media (corresponding command suffix: *porous)
Temperature (corresponding command suffix: *temp)

Any combination of shapes and effects is permitted, making for total of eight possible scenarios (or 12 if you count cylinders with hemispherical caps as a separate shape). The impose region type name is composed by specifying the geometric shape and adding the effect suffix in capital letters, for example: PARALLELEPIPEDVEL, PARALLELEPIPEDPOROUS, CYLINDERACC, or CYLINDERTEMP.

The fluid velocity region imposes a velocity on all fluid particles which are within the prescribed region. The easiest analogy is a pump mechanism (momentum source), except that there are no moving parts involved. The acceleration region imposes a defined acceleration on all the particles which are within the defined region. It also can be thought of as a momentum source region, except that by defining the acceleration instead of hard-setting the velocity of the particles, the region is likely to behave more stably. Porous media definition follows the well known Darcy-Forchheimer model and allows for definition of volume averaged isotropic or non-isotropic porous media. Finally, the temperature region assigns a temperature to all fluid or wall particles (optional) which are within the prescribed region, and is essentially a heat source/sink.

In addition to shape and effect types, there are specific commands which are applicable to a specific subset of desired shape-effect combinations. For example, as already mentioned, cylinder shape has a possibility to include hemispherical caps at the ends of the cylinder, such that if you specify the height of the cylinder as zero, you would end up with a spherical shape. More obviously, parameters which define the geometry are different between PARALLELEPIPED and CYLINDER impose regions.

There is also a possibility to SET a magnitude of a desired field value inside the impose region or use the ADD the command to add the specified value to any instantaneous field value the particle might have inside the impose region.

One other variable which allows flexibility is the LOOSE/STRICT option, which allows for either hard (strict) imposing of the specified value, or soft (loose) imposing of the specified value. If we take an example of specifying velocity in X direction - STRICT definition will impose exactly the vector which the user provides, with Y and Z components being equal to zero. If we use the LOOSE option, the code will impose the X direction velocity, but will allow the solver to naturally accommodate (calculate) Y and Z velocity components.

The final option available is to define inertial (INERT) or body (BODY) frame of reference for velocity effect regions. If INERT is selected, the velocity/acceleration definition in the region assumes that the general (default) simulation coordinate system is used, which is the common case. This means that whatever velocity/acceleration is specified, it will be used as such. In case the user specifies the velocity and enables BODY frame of reference, the resulting velocity/acceleration vector in the region will be specified vector plus the velocity/acceleration of the body. This can be useful in specific scenarios.

Note: Certain parameters are not applicable or are not supported for all effects as shown in Figure 1.

The regions are defined through a separate parameter section called imposeRegions.

When specifying the geometry of the shape type commands in the imposeRegions, a specific nomenclature is followed. Each command begins with the shape definition, followed by a suffix which defines the effect, followed by an underscore and key suffix (which is effectively unique to each command). For example:

parallelepiped<effect>_A_vec or cylinder<effect>_axis

more specifically resulting in parallelepipedvel_A_vec or cylinderporous_axis.

Additionally, when defining time series (varying parameters in time), additional suffixes are used for file, offset and latch commands. These suffixes are _tvs_ (time velocity series), _tas_ (time acceleration series) and _tts_ (time temperature series).

On the other hand, effect definitions are universal, such that once the impose region shape parameters are defined (using appropriate suffixes), you can add effect parameters.

We are emphasizing these definition principles in order to concisely (modularly) present the set of commands, instead of listing all eight (optionally 12) possible versions of the impose region definitions.

imposeRegions
{
	imposeRegion
	{
		;NOTE:
		;<shape>  = {parallelepiped, cylinder}
		;<effect> = {vel, acc, porous, temp}
		;<time_series> = {_tvs_, _tas_, _tts_}
		
		; UNIVERSAL PARAMETERS
		imposeRegion_type                       PARALLELEPIPEDTEMP 
		t_start                                 0.0
		t_damping                               0.1 
		t_end                                   20.0
		imposeregion_motphs                     1
		
		<shape><effect>_mode                    SET
		<shape><effect>_constraint              LOOSE
		<shape><effect>_frame                   BODY

		<shape><effect><time_series>file        time-dependent-series.txt
		<shape><effect><time_series>offset      0.1
		<shape><effect><time_series>latch       false

		; PARALLELEPIPED PARAMETERS
		parallelepiped<effect>_corner           "0.0 0.0 0.0"
		parallelepiped<effect>_A_vec            "1.0 0.0 0.0"
		parallelepiped<effect>_A_len            2           
		parallelepiped<effect>_B_vec            "0.0 1.0 1.0"
		parallelepiped<effect>_B_len            4            
		parallelepiped<effect>_C_vec            "1.0 0.0 1.0"
		parallelepiped<effect>_C_len            3            
		
		; CYLINDER PARAMETERS
		cylinder<effect>_axis                   "0.2 0.2 0.4"
		cylinder<effect>_cntr                   "0.2 0.2 0.4"
		cylinder<effect>_hght                   0.8
		cylinder<effect>_rad                    1.0
		cylinder<effect>_caps                   false
		
		; VELOCITY PARAMETERS
		<shape>vel_unv                          "1.0 2.0 0.0"
		<shape>vel_vel                          12.0
		use_prtl_reuni                          false

		; ACCELERATION PARAMETERS
		<shape>acc_acc                          100           
		<shape>acc_unv                          "0.0 0.0 1.0" 

		; TEMPERATURE PARAMETERS
		<shape>temp_temp                        150.0
		<shape>temp_fluidonly                   false

		; POROUS MEDIA PARAMETERS
		porous_principal_ax_x                   "1.0 0.0 0.0" 
		porous_principal_ax_y                   "0.0 1.0 0.0"
		porous_principal_ax_z                   "0.0 0.0 1.0"

		porous_inert                            "1000.0 10.0 1000.0"
		porous_inert_offdiag                    "1000.0 10.0 1000.0" 
		porous_visc                             "100.0  100.0 10.0"
		porous_visc_offdiag                     "100.0  100.0 10.0"
    }
}

General Commands

imposeRegion_type: Type of the impose region.; The key word is a composite of two keywords defining shape and effect associated with the impose region.; Shape keywords: PARALLELEPIPED , CYLINDER; Effect keywords: VEL,ACC,POROUS,TEMP; Any combination of the shape and effect keywords is permitted.; For example, a parallelepiped porous media would be type: PARALLELEPIPEDPOROUS, or a cylindrical velocity region would be: CYLINDERVEL
t_start / t_end: Common parameters for all imposed regions, indicating beginning and end of time at which the region is active.; Default: 0.0
Note: t_end must be greater than or equal to t_start.
t_damping: During this period, the prescribed velocity, body force or temperature will reach it prescribed value (analogous to the t_damping in the Motions section).; The command makes no physical sense for porous media, so in case the user specifies it in the porous impose region - the command will be ignored.; Default: 0.0
Note: t_damping will be renamed to t_ramping in the future, as it describes better the effect it has in the simulation.
imposeregion_motphs: Impose regions are capable of following a MOVINGWALL phase with a predefined motion.; This command specified the MOVINGWALL phase ID, which the region will follow.
<shape><effect>_mode: Defines the mode of the impose region, are the specified values added or set inside the impose region.; Options are: SET, ADD; This command is not applicable to porous regions (makes no physical sense).; Default: SET
<shape><effect>_constraint: Defines the constraint of the impose region, are the specified values strictly or loosely imposed in the region.; Options are: LOOSE, STRICT; This command is not applicable to porous regions and temperature regions (makes no physical sense).; Default: LOOSE
<shape><effect>_frame: Defines the relevant reference system when specifying a velocity impose region.; This command is only applicable to the velocity impose regions.; Options are: BODY, INERT; Default: INERT
<shape><effect>_tts_file: Name of the text file containing time-variable pairs (column format, no header, space delimiter), thus defining variable behavior of the desired field inside the impose region (Time Table Series – TTS).; For example, velocity TTS file format is: time u v w
<shape><effect>_tts_offset: Time offset value in case that the TTS file starts at a time different from zero, for example begin using TTS at t = 10 s.; Default: 0.0
<shape><effect>_tts_latch: Boolean command for keeping the last value of the TTS file throughout the simulation.; Example: TTS file defines only a ramp-up curve for the imposed region, from t = 0 to t = 5 s and velocity in X direction from u = 0 to u = 3 m/s, while the total simulation time is t_final = 10 s. If latch is set to true – for t > 5 s, velocity will be set constant at 3 m/s (last value in the TTS file). If latch is set to false, the velocity for t > 5 s will be set to 0 m/s.; Default: false

Parallelepiped Specific Commands

In Figure 2, note the three vectors which define the parallelepiped: parallelepiped<effect>_A_vec, parallelepiped<effect>_B_vec and parallelepiped<effect>_C_vec. The origin where the three vectors meet is the parallelepiped<effect>_corner.

parallelepiped<effect>_corner: Coordinates of the defining the origin corner of the parallelepiped; This is a vector variable of the format: "X Y Z"; Units: [m]
parallelepiped<effect>_A_vec: Three components of the vector A, which is defining one side of the parallelepiped.; This is a vector variable of the format: "X Y Z"
parallelepiped<effect>_A_len: Length of the side A (magnitude of the vector A).; This value is a scalar.; Units: [m]
parallelepiped<effect>_B_vec: Three components of the vector B, which is defining one side of the parallelepiped.; This is a vector variable of the format: "X Y Z"
parallelepiped<effect>_B_len: Length of the side B (magnitude of the vector B).; This value is a scalar.; Units: [m]
parallelepiped<effect>_C_vec: Three components of the vector C, which is defining one side of the parallelepiped.; This is a vector variable of the format: "X Y Z"
parallelepiped<effect>_C_len: Length of the side C (magnitude of the vector C).; This value is a scalar.; Units: [m]

Cylinder Specific Commands

cylinder<effect>_axis: This vector defines the main axis of the cylinder.; This is a vector variable of the format: X Y Z
cylinder<effect>_cntr: These are the coordinates of the center of the cylinder base where axis is located.; This is a vector variable of the format: X Y Z; Units: [m]
cylinder<effect>_hght: This command defines the height of the cylinder in the direction of axis.; This is a scalar value (length).; Units: [m]
cylinder<effect>_rad: Cylinder radius.; Units: [m]
cylinder<effect>_caps: Boolean switch which controls adding of hemispherical caps on the cylinder bases (resulting in a pill-shape geometry).; The caps are added to both sides of the cylinder.; Default: false

Velocity Region Specific Commands

<shape>vel_unv: This vector defines the direction of the velocity.; If time series file is specified, this command is ignored.; This is a vector variable of the format: X Y Z
<shape>vel_vel: This command defines the magnitude of the velocity.; If time series file is specified, this command is ignored.; This is a scalar value.; Units: [m/s]
use_prtl_reuni: This command toggles the use of transport velocity or artificial particle displacement (APD) inside the porous region. It is considered to be an advanced parameter.; Options: true / false; Default: false

Acceleration Region Specific Commands

<shape>acc_unv: This vector defines the direction of the acceleration.; If time series file is specified, this command is ignored.; This is a vector variable of the format: "X Y Z"
<shape>acc_acc: This command defines the magnitude of the acceleration.; If time series file is specified, this command is ignored.; This is a scalar value.; Units: [m/s^2]

Temperature Region Specific Commands

<shape>temp_fluidonly: Switch which allows to prescribe the temperature to only fluids, or alternatively to all FLUID, MOVINGWALL or WALL particles.; Default: false
<shape>temp_temp: Temperature which will be assigned to all the particles which enter the temperature region.; Units: [K]

Porous Region Specific Commands

It is generally assumed (default) that the principal axes of the porous region align with the base simulation X, Y, and Z coordinates (inertial reference frame). If that is not the case, a separate coordinate system can be defined and the values defining porosity will be considered in that new coordinate system. The commands which define the custom principal axes of the porous region are:

porous_principal_ax_x: This command defines the X principal axis of the custom coordinate system; The format of the command is a 3-component vector value of the form X Y Z.
porous_principal_ax_y: This command defines the Y principal axis of the custom coordinate system; The format of the command is a 3-component vector value of the form X Y Z.
porous_principal_ax_z: This command defines the Z principal axis of the custom coordinate system; The format of the command is a 3-component vector value of the form X Y Z.

There are four parameters which define the volume averaged porosity of the region:

porous_inert: This command defines the diagonal inertial coefficients in the Darcy-Forchheimer porosity model. If the values of this vector are all set to 0.0 and all the components of porous_visc are set to non-zero, then the used porosity model effectively becomes the Darcy model/equation.; Given that nanoFluidX supports non-isotropic porous media, this coefficient is a 3-component vector value of the form X Y Z.; If the value in any direction is defined as -1, that will set the specified direction as impermeable.; Unit: [1/m]
porous_inert_offdiag: This command defines the off-diagonal inertial coefficients in the Darcy-Forchheimer porosity model.; The off-diagonal terms only make sense if the porous media is non-isotropic.; Given that nanoFluidX supports non-isotropic porous media, this coefficient is a 3-component vector value of the form X Y Z.; Unit: [1/m]
porous_visc: This command defines the diagonal inertial component coefficient in the Darcy-Forchheimer porosity model.; Given that nanoFluidX supports non-isotropic porous media, this coefficient is a 3-component vector value of the form X Y Z.; If the value in any direction is defined as -1, that will set the specified direction as impermeable.; Unit: [1/m²]

porous_visc_offdiag: This command defines the off-diagonal inertial component coefficient in the Darcy-Forchheimer porosity model.; The off-diagonal terms only make sense if the porous media is non-isotropic.; Given that nanoFluidX supports non-isotropic porous media, this coefficient is a 3-component vector value of the form X Y Z.; Unit: [1/m²]