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 small 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 Specifying Lattice Domain Boundary Conditions 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:

  1. Full

  2. Custom

  3. 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.

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:

  1. Domain Center

  2. 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 these points.

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 inside the vessel walls

  • For all simulations, the interior volume 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.

../_images/moreFlood.JPG

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.

../_images/floodFill2.JPG

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

../_images/floodFill3.JPG

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:

  1. No-slip

  2. Free-slip

  3. 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 X.X 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

Refinement Lattice Dt

Lattice timestep within the refinement box