# Defining the System¶

## Main Lattice¶

### Conceptual Overview¶

The main lattice domain represents the mathematical extent of the model. This domain is always cuboid and is initially presented as a green 1 m^3 box centered about the global origin. The position and extents of the main lattice will automatically adjust during model set-up to define a cuboid bounding box containing all user-imported solid geometry. Once import is complete, the position and extents of the lattice can be tailored by the user to isolate specific sections of the imported geometry. Only those portions of the imported geometry that are inside the main lattice will be included in the simulation. See Main Lattice Domain for more detail on domain sizing and cropping.

For a lattice domain that contains vessels, pipes, vials, tanks, etc., the solver needs to differentiate the interior zone of the lattice domain from the exterior zone. The interior zone is a continuous region within the lattice domain that, at some point during the simulation, may contain fluids, particles, species or moving solid surfaces. The exterior zone, which typically occupies the region between the outside tank walls and the lattice domain, contains no fluid or particles. To discriminate interior from exterior zones, the solver performs a 3D flood fill beginning at a user-defined seed point and then expanding to the vessel walls and/or the simulation bounding box. By default, the seed point is set to the center of the main lattice domain. Users can move the flood fill seed point to other locations inside the domain, if needed. See Flood Fill for more detail on flood fill specification.

The six sidewalls of the main lattice domain are, by default, assigned a no-slip wall boundary conditions. In this state, the lattice domain represents six rigid walls through which fluid, species, and/or particles cannot cross. The individual faces of the bounding box can alternatively be assigned velocity, pressure, and/or free-slip boundary conditions. Periodic boundary conditions can also be imposed across face pairs (e.g., +/-x, +/- y and/or +/- z) For systems with openings, such as a pipes entering a tank, users can impose local boundary conditions along specific regions of the lattice domain. Multiple boundary conditions can be imposed on a single side of the lattice domain. See Basic Concepts for more detail on local boundary conditions specification.

Linear and centripetal accelerations can be imposed on the lattice. These accelerations can be constant or time-varying. By default, a constant acceleration of 9.81 m/s^2 is imposed negative y-direction of the main lattice. Additional accelerations can be superimposed onto the system. See Applying External Accelerations for more detail on lattice domain accelerations.

For convenience with multi-fluid model building and set-up, users can define a model “UP-direction”. The UP-direction typically points in the opposite direction of gravity, and provides ease-of-use functionality when defining partially filled tanks or initially stratified fluids. By default, gravity points in the -y direction, and the UP-Direction points in the +y-direction. This default can be changed in the Edit->Preferences menu.

### Main Lattice Domain¶

Users have three options for defining the extent of the main lattice domain:

Full

Custom

Partial

- Full Domain
The position and extents of the main lattice domain automatically adjust during model set-up to define a cubic, axis-aligned minimum bounding box containing all user-imported solid geometry. User can see the current locations of the lower and upper points defining the box, but cannot adjust these points.

- Custom Domain
User specifies the locations of the lower and upper points defining the lattice domain. User can see the current locations of the lower and upper points defining the box, and adjust these points as desired.

- Partial Domain
The position and extents of the main lattice domain automatically adjust during model set-up to define a cubic, axis-aligned minimum bounding box containing all user-imported solid geometry. User can see the current locations of the lower and upper points defining the box, but only adjust the height of the box aligned with the UP-direction.

To illustrate these three options, consider the image below. In the left hand pane, the main lattice domain is set to Full. As such, then lattice represents a cubic bounding box containing all imported geometry. In the center pane, the main lattice domain is set to Partial. Under this setting, the height of the box in the UP-direction can be adjusted, while the dimensions of the box perpendicular to the UP-direction are set to contain all imported geometry. In the right hand pane, the main lattice domain is set to Custom. In this configuration, the bounding box can be given an arbitrary location and extent.

### Flood Fill¶

Within the lattice domain, the simulation needs user information to differentiate the interior of the vessel from the exterior of the vessel. The interior is any region of the lattice domain that, at some point during the simulation, may contain fluids, particles, species or moving solid surfaces. These interior regions are the typically the space inside a vessel, pipe, or bounding geometry. The exterior is any region of the lattice domain that, at no point during the simulation, contains fluid, particles, species or moving solid surfaces. Exterior zones are typically the space between a vessel wall and the simulation bounding box.

To differentiate interior from exterior zones, the user must provide the location of an interior flood fill seed point. The solver then performs a 3D flood fill, expanding from this seed point to the walls of the body and/or the simulation bounding box. The region of the simulation domain that is touched by the flood fill is identified as a interior zone. The region that is not touched by the flood fill is identified as exterior zone, and is excluded from the calculation.

Users have two options for defining the location of the flood fill point:

Domain Center

Custom

- Domain Center
The position of the flood fill location is the center of the lattice domain. User can see the current coordinates, but cannot adjust the coordinates.

- Custom
User enters a custom point as the flood fill seed location User can see the current coordinates and adjust the coordinates as needed.

Note

The flood fill point is shown in the 3D view. In most cases, the default (Domain Center) flood fill location is acceptable

In some cases however, such as U-tube manometers, toroidal geometries, or tanks with interior support structures, the point must be relocated to a location interior to the vessel.

For all simulations, the interior volume calculated during the flood fill routine is reported to the simulation output log. If this calculated volume is in significant disagreement with the expected tank volume, check the flood fill seed point.

To illustrate the effect of flood fill seed location, consider the two flood fill results below. In image (a), the flood fill seed point was located inside the vessel in a region that is known to be wet during the simulation. Appropriately, the active region of the lattice domain is inside the tank, while the inactive region is outside the tank. In image (b), the flood fill was inappropriately located outside the vessel. The active region of the lattice domain is inappropriately located outside the tank, while the inactive region is inside the tank.

Further illustration is presented below, for system involving flow around a bend. In image (a), the flood fill seed point is located inside the pipe. The flood fill algorithm expands to the sidewalls of the pipe and the lattice bounding box. The interior zone is (correctly) inside the pipe elbow. The exterior zone is (correctly) located outside the elbow. Regions in the active zone will be modeled. Those in the inactive zone will not be modeled. In image (b), the flood fill point is located outside the pipe. The flood fill algorithm again expands to the sidewalls of the pipe and the lattice bounding box. The interior zone is incorrectly located outside the pipe. The flood fill seed point needs to be located inside the pipe on order to make the inside of the pipe the active zone.

A final illustration is presented below. In this model, we model species transport between two tanks connected by a small pipe. Improper selection of the seed point leads to improper active versus inactive zones.

Important

The results of the flood fill algorithm are recorded in the BoundaryConditions.txt file, which can be rendered in M-Star Post. Regions where the reported fluid value is equal to 0 are inactive simulation zones that were untouched by the flood fill.

Simulations predicting non-physical forces on moving objects (e.g. gigaewtons) and/or zero fluid velocity despite the presence of a momentum source often result from an improper flood fill seed point location.

If most of the simulation zone is inactive, consider using a sparse mesh to improve runtime speed and decrease memory requirements

### Specifying Lattice Domain Boundary Conditions¶

Users have three options for defining boundary conditions across each face of the main lattice domain:

No-slip

Free-slip

Periodic

By default, the top surface (defined relative to the simulation UP-direction) is free slip, while the remaining five sides are no-slip. Periodic boundary conditions, which treat the lattice domain as a unit cell, can be imposed across face pairs (e.g., +/-x, +/- y and/or +/- z) but not to single faces. For example, if the +x lattice domain boundary is set to periodic, the -x will automatically follow. Particles in systems with periodic boundary conditions follow the minimum image convention.

Local boundary conditions can be imposed at user-defined regions of the lattice domain. These local boundary conditions can be different from the lattice domain boundary condition. See Section Basic Concepts for more detail on local boundary conditions specification.

Note

For simulations involving closed tanks, where the interior never touches the lattice domain side walls, the lattice domain boundary condition is of no consequence.

### Applying External Accelerations¶

- Acceleration X
x-acceleration analytic expression [m/s^2]. Function of variable time ‘t’ with units [s]

This acceleration is applied to all lattice points inside the fluid domain. Linear accelerations are typically combined with free surface simulations to observe sloshing.

For example, to describe a time-varying acceleration in the x-direction with a magnitude 0.1 m/s^2 and a periodic frequency of 0.1 Hz, the user would specify:

0.1*sin(2*3.141*0.1*t)

Additional examples of entering formulas are presented in - User Defined Expression Syntax

- Acceleration Y
y-acceleration analytic expression [m/s^2]. Function of variable time ‘t’ with units [s]

This acceleration is applied to all lattice points inside the fluid domain. By default, all simulations have a body acceleration of -9.81 m/s^2 in the y direction.

- Acceleration Z
z-acceleration analytic expression [m/s^2]. Function of variable time ‘t’ with units [s]

This acceleration is applied to all lattice points inside the fluid domain. Linear accelerations are typically combined with free surface simulations to observe sloshing.

For example, to describe a constant acceleration in the z-direction with a magnitude 0.06 m/s^2, the user would specify:

`0.06`

Additional examples of entering formulas are presented in - User Defined Expression Syntax

- Rotation RPM
Rotation RPM external forcing function of time ‘t’, in units rotations/minute [RPM]

This value represents the rotational speed of the domain about a user-defined rotation axis. For example, to define a ramp-up velocity from zero to constant value omega1 over period t1 using a quarter sine wave, define:

t<t1?omega1*sin(t/t1*3.1416/2.):omega1

For example, increase the velocity from zero to 3 RPM over 0.6 s interval:

t<0.6?3.*sin(t/0.6*3.1416/2.):3.

Additional examples of entering formulas are presented in - User Defined Expression Syntax

- Rotation Axis Mount
Rigid body rotation mount point. [Model Units]

For lattice domains with centripetal accelerations, this point represents the root of the rotation axis. Displacing this mount point from the centroid of the main lattice domain will produce eccentric rotation. Rotational motion is typically combined with free surface simulations to observe sloshing and vortex formation.

- Rotation Axis
Rigid body rotation axis point. [Unit vector]

For lattice domains with centripetal accelerations, this vector represents the direction of the rotation axis.

### Adding Refinement Boxes¶

*Overview*

Refinement boxes are cuboid regions within the domain where the lattice realizes a step change in resolution and timestep. Such zones are particularly useful in modeling systems with high aspect ratio features, such as small openings in large vessels or small impellers inside large tanks. When applied judiciously, refinement boxes can offer multiple order-of-magnitude decreases in simulation runtimes, as compared to uniform mesh simulations.

Refinement boxes are added to the domain via Build->Add Refinement Box.

Once created, refinement boxes can be moved, scaled, copied, or deleted by right-clicking the icon in the model tree.

- Level Number
This value defines the degree of refinement. The lattice spacing and time-step inside each refinement box is equal to the far-field values (listed under the Simulation menu) divided by 2^(Level Number). For example, if the Level Number is set to 1, the resolution and time-step within the refinement box will be 1/2 that of the far-field. If the Level Number is set to 2, the the resolution and time-step within the refinement box will be 1/4 that of the far-field.

Important

Regions with multiple refinement boxes must follow a Russian nesting doll configuration. That is, a refinement box of Level 2 must be surrounded by a refinement box of Level 1 and cannot interact directly with the far-field (Level 0). Likewise, a refinement box of Level 3 must exist between boxes of Levels 2 and 4.

Above three or four boxes, the additional communication costs associated with each refinement box can exceed the computational savings associated with the reduction in total lattice count.

Refinement should be used as a mechanism for enhancing near field resolution, not starving the far-field resolution. If the far-field is under-resolved, spurious motions will appear at the boundaries of refinement zones.

At short times, turbulence inside the refinement box will be better resolved than flow outside the box. At longer times, as the bulk flow becomes increasingly turbulent, the boundary will become less apparent. See: https://mstarcfd.wistia.com/medias/qcgtuc5p0m

- Fluid Box Point 1
Refinement box lower corner. Coordinates shown in selected Template units.

- Fluid Box Point 2
Refinement bounding box upper corner. Coordinates shown in selected Template units.

- Refinement Lattice Dx
Lattice spacing within the refinement box

This value cannot be edited directly, as it is defined by the resolution of the main lattice.

- Refinement Lattice Dt
Lattice timestep within the refinement box

This value cannot be edited directly, as it is defined by the timestep of the main lattice.

## Adding Solid Bodies¶

### General Concepts¶

Static Bodies are fixed, non-deformable geometries that act as walls for fluids, particles, bubbles, and/or species. Static Bodies are characterized by a parent-child relationship. Within this relationship, the parent defines the global properties/boundary conditions uniformly assigned to a set of children. The children define the shape/geometry/topology of the solid surface with the boundary conditions defined by the parent. Parents define the properties, children define where these properties will be applied.

### Importing Static Bodies¶

A Static Geometry parent is defined under the Geometry->Add Static Body menu command. Upon import, users will be asked to define the first child geometry. Users have two options for defining child geometry:

Import from File, or

Create Parametric.

#### Import from File¶

The Import from File option prompts the user to open either a STL, STEP, or IGES file (Manifold Solid [type 186]) containing a solid model of the child geometry. The CAD geometry need not contain continuous components, as objects like dip tubes, heating coils, or baffles may be disconnected from the general geometry body. Upon import, the local origin of any imported geometry will be placed coincident with the global simulation origin.

#### Create Parametric¶

This option allows users to build simple tank, pipe, cylinder, and box children geometries directly within the GUI. Users can also interactively modify the dimensions and parameters of these objects.

Any number of children geometry can be added to the static boundary parent. These children can be a heterogeneous mixture of imported CAD and parametric geometry.

### Positioning Static Bodies¶

#### Parents¶

Parents can be named, rotated, translated and scaled by right-clicking on the object in the model tree. A transformation to the parent affects all children equally. The position and orientation of the parent (relative to the simulation basis) is reported in the property grid.

#### Children¶

Children can be rotated, translated, scaled and colored independently of any parents and siblings. The position and orientation of the child (relative to the simulation frame) is reported in the property grid. The position of all children is defined relative to the global origin.

### Parent Properties and Operators¶

#### Properties¶

##### Contact angle, [degrees]¶

Used to quantify the wettability of the children geometry via the Young equation

##### Boundary type, [Bounce Back, Off-lattice]¶

Static bodies can be modeled using either (i) an on-lattice voxelized approach, or (ii) an off-lattice, interpolated approach.

In the on-lattice voxelized approach, any fluid lattice element that intersects the static geometry is assigned a no-slip, bounce-back wall boundary condition. This approach is ideal for flat, lattice-aligned walls. Any curved surfaces, however, will follow a stair-step contour with a step height equal to the local lattice spacing.

For the off-lattice interpolated approach, fluid lattice elements are not explicitly redefined. Rather, the effects of the wall on the fluid are extrapolated onto the fluid as a function of distance from the wall. For curved or non-grid-aligned surfaces, the off-lattice interpolated approach can provide a superior representation of the boundary. With increasing resolution, however, the difference between these two approaches diminishes.

For the on-lattice approach, the wall is assumed to have zero velocity. With off-lattice interpolated boundary conditions, users have the option to impose a non-zero wall velocity. Options are presented to define a constant translational velocity or a constant angular velocity (about a user-defined axis of rotation).

#### Operators¶

##### Add Geometry¶

Add new child geometry to the parent

##### Translate¶

Translate entire static body family about a user-defined displacement vector

##### Rotate¶

Rotate entire static body family about a user-defined rotation vector

##### Scale¶

Volume scale the entire static body family about a user-defined anchor point

##### Rename¶

Rename the parent. This name will persist to the output files.

##### Delete¶

Delete the parent and all children.

### Child Properties and Operators¶

#### Location, [model units]¶

Used to define the position of the child geometry in the global Domain

#### Orientation, [-]¶

Unit vector describing the orientation of the local basis vectors, with respect to the global x, y and z basis.

#### Visible, [on, off]¶

Chose to render the child in the 3D view window

#### Transparency, [-]¶

Set the rendering transparency of the child geometry

#### Color, [-]¶

Set the color of the child geometry

#### Mode, [Shaded, Wireframe]¶

Set the representation of the child geometry

#### Material, [-]¶

Set the material representation of the child geometry in rendered viewed

## Specifying a Fluid Configuration¶

### Conceptual Overview¶

Fluids are gases and liquids that flow when subject to an applied shear stress. For single-phase fluids, momentum transport is governed by the fluid density and viscosity. For multi-phase systems, the surface tension must also be defined to describe dynamics at the interface between two phases.

M-Star CFD can handle both Newtonian and non-Newtonian fluid rheology. The available fluid models, along with the relevant simulation parameters, are described in the sections that follow.

Laminar and transitional flows are typically modeled via direct numerical simulation. Turbulent fluid flows in M-Star CFD are modeled using implicit large eddy simulations (ILES) or large eddy simulation (LES). Additional theoretical details related to the LES model are provided in the Theory and Implementation section of this manual.

Users must select a fluid configuration. Five configurations are available:

Single phase

Free surface

Two-fluid miscible

Two-fluid immiscible

None

In the sections that follow, each of these configurations are discussed in detail.

### Single Phase¶

Single phase models, as the name suggests, are simulations involving a single base fluid with Newtonian or non-Newtonian rheology. Common applications include pipe flow simulations, well-baffled agitated tanks, jet mixing systems, and pumps. Within this configuration, users must specify the fluid density and define the constitutive relationship between fluid stress and fluid strain. As discussed in Particles and Bubbles, additional phases (such as discrete bubbles and discrete solid particle) can be added to the system and one- or two-way coupled to the fluid. Thermal fields and scalar fields can also be superimposed on the single phase fluid, as discussed in Thermal Field and Scalar Fields.

Within the single phase model, users can chose from one of five constitutive relationships:

Newtonian

Power law (with or without a yield stress)

Carreau

Custom expression

C++ Plug-in

Briefly speaking, relationships (1)-(3) are familiar Newtonian and non-Newtonian rheology models. Relationships (4) and (5) represent custom expressions that may be more complex functions of strain, age, species concentration, and temperature. Currently, users can define the relationship in terms of the following reserved variables:

s: the norm of strain rate tensor (no sqrt(2) factor), seconds^-1

ss: shear stress (defined as strain rate x kinematic viscosity x density, again not multiplied by sqrt(2)), Pascal

t: the current simulation time, seconds

T: the instantaneous local temperature, Kelvin

age: the instantaneous local mean-age, seconds [Only available if mean-age calculation is active]

scalarName: the instantaneous local concentration of any named scalar field the system, molarity. [Only available if scalar fields are active].

Additional details for each of these relationships are provided in _fluidModels

In single phase models, the entire interior zone of the lattice domain is assumed to be filled with the fluid.

### Free Surface¶

Free surface models are simulations involving a moving free surface with a single Newtonian or non-Newtonian rheology. Common applications include filling/draining simulations, jet sprays, sloshing, vortex formation, and coating processes. Within this configuration, users must specify the fluid density, surface tension and define the constitutive relationship between fluid stress and fluid strain. As discussed in Particles and Bubbles, additional phases (such as discrete bubbles and discrete solid particle) can be added to the system and one- or two-way coupled to the fluid. Thermal fields and scalar fields can also be superimposed on the single phase fluid, as discussed in Thermal Field and Scalar Fields.

Within free surface model, users can chose from one of five constitutive relationships:

Newtonian

Power law (with or without a yield stress)

Carreau

Custom expression

C++ Plug-in

Briefly speaking, relationships (i)-(iii) are familiar Newtonian and non-Newtonian rheology models. Relationships (iv) and (v) represent custom expressions that may be more complex functions of strain, age, species concentration, and temperature. Currently, users can define the relationship in terms of the following reserved variables:

s: the norm of strain rate tensor (no sqrt(2) factor), seconds^-1

ss: shear stress (defined as strain rate x kinematic viscosity x density, again not multiplied by sqrt(2)), Pascal

t: the current simulation time, seconds

T: the instantaneous local temperature, Kelvin

age: the instantaneous local mean-age, seconds [Only available if mean-age calculation is active]

scalarName: the instantaneous local concentration of any named scalar field the system, molarity. [Only available if scalar fields are active].

Additional details for each of these relationships are provided in _fluidModels

Unlike the single phase fluid, which is assumed to fill the entire interior zone of the lattice, users must specify which portions of the interior zone (if any) are initially filled with the fluid. Any initial fluid configuration can be specified using any combination of parametric geometry and/or user-imported geometry. By default, the initial condition is a parametric “Fluid Height Box”. This cuboid geometry is anchored to the main lattice domain, but the height of the box aligned with the “UP-direction” can be adjusted.

### Two Fluid: Miscible¶

Two fluid miscible simulations involve two miscible fluids with user defined rheology. Common applications include fluid dilution, miscible fluid blending, and simulations of cleaning/washing. As discussed in Particles and Bubbles, additional phases (such as discrete bubbles and discrete solid particle) can be added to the system and one- or two-way coupled to the fluid. Thermal fields and scalar fields can also be superimposed on the single phase fluid, as discussed in Thermal Field and Scalar Fields.

Within this configuration, users must specify the density of each fluid and a constitutive relationship between fluid stress and fluid strain. This constitutive relationship will typically be a function of the relative concentrations of each fluid. This relationship may also be a function of other fluid variables, including strain, energy dissipation rate, species concentration, time, temperature, age, etc. At each simulation time step, the solver uses this user-provided constitutive relationship to calculate the local viscosity at each point within the lattice domain. Users can enter this expression directly into the graphical interface, or write a C++ plug-in to be executed at runtime.

We now present multiple examples for defining constitutive relationship expression directly into the graphical interface. Consider two miscible Newtonian fluids, f1 and f2, with a kinematic viscosity of 1e-6 m^2/s and 1e-4 m^2/s, respectively. Assume the mixture viscosity is calculated using a weighted average concentration. The appropriate constitutive relationship to specify would be:

```
f1/(f1+f2)*1e-6+f2/(f1+f2)*1e-4
```

In regions of the lattice where f1 (the instantaneous, relative concentration of fluid 1) is 1 and f2 (the instantaneous, relative concentration of fluid 2) is zero, the local fluid viscosity will be 1e-6 m^2/s. In regions of the lattice where f1 is zero, f2 is 1, the local fluid viscosity will be 1e-4 m^2/s. In regions of the lattice where f1 is 0.5, f2 is 0.5, the local fluid viscosity will be 5e-5 m^2/s.

Next, consider two miscible power law fluids, f1 and f2, with a kinematic viscosity of 1e-3*s^0.9 m^2/s and 1e-4*s^0.8 m^2/s, respectively. Note that the rheology of each fluid is a function of strain, s, and assume the mixture viscosity is calculated using a weighted average concentration.

The appropriate constitutive relationship to specify would be:

```
f1/(f1+f2)*(1e-3*s^0.9)+f2/(f1+f2)*(1e-4*s^0.8)
```

In regions of the lattice where f1 (the instantaneous, relative concentration of fluid 1) is 1, f2 (the instantaneous, relative concentration of fluid 2) is zero, and s (the instantaneous, local strain) is 0.5 1/s, the local fluid viscosity will be 5.35e-4 m^2/s. In regions of the lattice where f1 is zero, f2 is 1, and s is 0.5 1/s, the local fluid viscosity will be 3.74e-5 m^2/s. In regions of the lattice where f1 is 0.5, f2 is 0.5, and s is 0.5 1/s, the local fluid viscosity will be 2.97e-4 m^2/s.

To reemphasize, the local viscosity at each point in the lattice domain is calculated at each time step according to the user-defined constitutive relationship. The functional form of these constitutive relationships can be arbitrarily complex or arbitrary simple. In fact, for two miscible fluids with an identical viscosities (4e-5 m^2/s, for example), the appropriate constitutive relationship to specify would simply be:

```
4e-5
```

In regions of the lattice where f1 (the instantaneous, relative concentration of fluid 1) is 1 and f2 (the instantaneous, relative concentration of fluid 2) is zero, the local fluid viscosity will be 4e-5 m^2/s. In regions of the lattice where f1 is zero, f2 is 1, the local fluid viscosity will be 4e-5 m^2/s. In regions of the lattice where f1 is 0.5, f2 is 0.5, the local fluid viscosity will be 4e-5 m^2/s.

This single valued approach is useful for stratified fluids with very similar viscosities, but different densities.

As demonstrated above, the user-defined constitutive relationship expressions can be a function of various fluid variables. Currently, users can define the relationship in terms of the following reserved variables:

f1: the instantaneous relative concentration of fluid 1

f2: the instantaneous relative concentration of fluid 2

s: the norm of strain rate tensor (no sqrt(2) factor), seconds^-1

ss: shear stress (defined as strain rate x kinematic viscosity x density, again not multiplied by sqrt(2)), Pascal

t: the current simulation time, seconds

T: the instantaneous local temperature, Kelvin

age: the instantaneous local mean-age, seconds [Only available if mean-age calculation is active]

scalarName: the instantaneous local concentration of any named scalar field the system, molarity. [Only available if scalar fields are active].

Note that, if other fluid properties are required to describe viscosity or the constitutive relationship is too complex to recast as an equation, users can write a C++ plug-in to support complex functions with intermediate variables. More information about writing C++ plug-ins is presented in User Plugins.

Important

The quality of the simulation prediction will be directly correlated to the quality of the user-specified constitutive relationship

The examples above are illustrative; most miscible fluid mixtures do not follow a weighted average concentration

Within the context of the solver, constitutive relationship expressions and constitutive relationship plug-ins are mutually exclusive. If the user specifies “Plug-in” as the Rheology Specification, the equation field will disappear.

The local fluid density, which is also calculated at each point within the lattice domain at each time step, is found from arithmetic average density:

```
rho=f1/(f1+f2)*rho1+f2/(f1+f2)*rho2
```

If more complex relationship are needed, users and write a C++ plug-in to support arbitrary density mixing rules.

Unlike the single phase fluid, which is assumed to fill the entire interior zone of the lattice, users must specify which portions of the interior zone are initially filled with each fluid. The “Background Fluid” describes the primary fluid in the tank. This background is typically defined as fluid1, but can be redefined by the user. The initial distribution of the secondary fluid (which is typically fluid2) can be specified using any combination of parametric geometry and/or user-imported geometry. By default, the secondary fluid condition is a parametric “Fluid Height Box”. This cuboid geometry is anchored to the main lattice domain, but the height of the box aligned with the “UP-direction” can be adjusted.

### Two Fluid: Immiscible¶

Immiscible fluid models, as the name suggests, are simulations involving a two immiscible fluids with Newtonian or non-Newtonian rheology. Common applications include two-phase gas flow simulations, colloid suspensions, and oil-water systems, Users must specify, for each fluid, the density and the constitutive relationship between fluid stress and fluid strain. Users must also specify a surface tension between the two fluids. As discussed in Particles and Bubbles, additional phases (such as discrete bubbles and discrete solid particle) can be added to the system and one- or two-way coupled to the fluid. Thermal fields and scalar fields can also be superimposed on the single phase fluid, as discussed in Thermal Field and Scalar Fields.

Newtonian

Power law (with or without a yield stress)

Carreau

Custom expression

C++ Plug-in

Briefly speaking, relationships (1)-(3) are familiar Newtonian and non-Newtonian rheology models. Relationships (4) and (5) represent custom expressions that may be more complex functions of strain, age, species concentration, and temperature. Currently, users can define the relationship in terms of the following reserved variables:

s: the norm of strain rate tensor (no sqrt(2) factor), seconds^-1

t: the current simulation time, seconds

T: the instantaneous local temperature, Kelvin

age: the instantaneous local mean-age, seconds [Only available if mean-age calculation is active]

The two immiscible fluids do not need to have the same constitutive relationships.

Unlike the single phase fluid, which is assumed to fill the entire interior zone of the lattice, users must specify which portions of the interior zone are initially filled with each fluid. The “Background Fluid” describes the primary fluid in the tank. This background is typically defined as fluid1, but can be redefined by the user. The initial distribution of the secondary fluid (which is typically fluid2) can be specified using any combination of parametric geometry and/or user-imported geometry. By default, the secondary fluid condition is a parametric “Fluid Height Box”. This cuboid geometry is anchored to the main lattice domain, but the height of the box aligned with the “UP-direction” can be adjusted.

### No Fluid¶

In this set-up, which is typically paired with particle discrete element modeling (DEM), no fluid is modeled explicitly. Instead, the effects of any fluid on particle dynamics are modeled via a implicit damping functions.