mesh command

Purpose

Command to import a geometry from a surface mesh file.

Note

This command is supported by Aspherix GPU.

Syntax

mesh keyword value

General keywords:

Keywords	Description
id	non-obligatory keyword, required for referencing the mesh
file	name of STL, VTK or OBJ file containing the triangle mesh data, obligatory if `from_command` is not used
from_command	id of command that provides a mesh, can be used instead of specifying `file`

Keywords	Description
solid	`yes` or `no`, states whether mesh is used as solid wall default: `yes`
is_planar	`yes` or `no`, denotes planar mesh for insertion or massflow measurement default: `no`
material	material name of the wall imported from file, mandatory if solid = yes
region	ID of region to filter elements which are imported
scale	factor to scale the mesh in all axis directions default: 1; range: (0,∞); units: [-]
scale_axes	factors to scale the mesh in x-, y-, and z-direction, vector default: (1, 1, 1); range: (0,∞); units: [-]
translate	vector; move the mesh by this extent in x-, y-, and z-direction default: (0, 0, 0); range: (-∞,∞); units: [length]
rotate	`axis` vector `angle` value: axis vector for rotation and rotation angle default: (0, 0, 0) and 0; units: [length] and [degrees]
temperature	temperature of the wall units: [temperature]
mass_for_heat_capacity	mass assumed for temperature update in the frame of enable_surface_heating range: (0,∞); units: [mass]
planar_extrusion_length	length that a planar mesh is extruded in anti-normal direction range: (0,∞); units: [length]
mesh_modules	list of mesh_module names that are applied to this mesh
voltage	voltage of the wall to be used in enable_electrical_conductivity units: [Volts]
current	electric current through the wall to be used in enable_electrical_conductivity units: [Ampere]

Keywords	Description
surface_velocity	vector, conveyor belt surface velocity units: [length/time]
surface_angular_velocity	`origin` vector `axis` vector `omega` value: origin, axis and rotational velocity units: [length], [-], [rad/time]

Keywords	Description
reference_point_torque	vector with coordinates of reference point units: [length]
reference_axis_torque	vector with coordinates of reference axis or `none` units: [none]
stress_calculation	`on` or `off`; switching calculation of normal and shear stresses on / off default: `on`

Keywords	Description
verbose	`yes` or `no`; enables / disables output of warning details default: `no`
precision	mesh nodes at / below this distance are considered identical units: [length]
heal	`auto_remove_duplicates` or `no`; enables / disables automated removal of duplicate elements default: `no`
min_feature_length	exclude element if belongs to an entity where no element is larger than this range: (0,∞) ; units: [length]
element_exclusion_list	`mode` style `file` filename; styles `read` or `write` are available. reads / writes file with list of elements to be excluded
remove_protruding_mesh_elements	`yes` or `no`; ignores mesh elements that are outside of simulation domain default: `no`
curvature	maximum angle between mesh faces belonging to the same surface range: (0,∞) ; units: [degree]
curvature_tolerant	`yes` or `no`; allows curvature to be larger than any angle in any mesh element default: `no`
all_edges_corners_active	`yes` or `no`; setting all edges and corners of mesh elements active default: `no`
weighted_wall_formulation	`yes` or `no`; experimental feature, computes particle-wall contribution using a different algorithm default: `no`

Keywords	Description
boundary_condition_name	mandatory if `from_command` refers to a enable_fem_coupling command, determines which boundary condition from Elmer is imported
boundary_name	mandatory if `from_command` refers to a enable_cfd_coupling command, determines which boundary from CFD is imported

Keywords	Description
enable_reflection	`yes` or `no`
virtual_radius_factor	scaling factor for the radius of particles impacting the mesh units: nondimensional
min_particle_position_z	impose a minimum value for the particle position on the z direction units: [length]

Examples

mesh id solidWall file meshes/solid_wall.stl material steel solid yes
mesh id box file meshes/box.stl material steel translate (0.2, 0.2, 0.1) scale 1.5 temperature 100 solid yes
mesh id insertionFace file meshes/insertion_face.stl translate (0.62, 0.3, 0.55) solid no is_planar yes
mesh id chute file meshes/simple_chute.stl material steel solid yes mesh_modules {move, wear_model}
mesh id screw file meshes/extruder_screw.stl material steel solid yes mesh_modules {rotate} reference_axis_torque (1, 1, 0) reference_point_torque (-0.2, 0.3, 1)
mesh id screw file meshes/extruder_screw.stl material steel solid yes mesh_modules {rotate} reference_axis_torque (1, 1, 0) reference_point_torque (-0.2, 0.3, 1)
mesh id moving_part from_command fem boundary_condition_name "force at cap" material plastic solid yes
mesh id kiln from_command cfd boundary_name mantle mesh_modules {mm_heattransfer}
mesh id plate material m1 solid yes file mesh.stl enable_reflection yes virtual_radius_factor 5.0
mesh id plate material m1 solid yes file mesh.stl enable_reflection yes virtual_radius_factor 8000.0 min_particle_position_z 49.0

Description

This command allows the import of a triangular surface mesh geometry from ASCII STL files, legacy ASCII VTK files or ASCII OBJ files. The meshes can either be used as walls within the simulation or as faces for particle insertion or massflow measurement. The keyword id is used to assign a user-defined name to the object for later reference, the filename of the mesh is specified by the keyword file.

If no file is specified then the from_command keyword can be used to generate a mesh from specialized commands. More detail can be found below.

If a mesh is used as wall, the keyword material must be used to define the meshes material. In this case, also the module keyword solid has to be set to true.

When using a mesh for particle insertion or for massflow measurements, the used geometry must be planar. This is denoted by setting the keyword is_planar to yes.

The region keyword can be used to filter elements which are imported. A mesh element is only imported if all of its vertices is inside the specified region. Please note that the geometric extent of this region refers to the unscaled, unmoved, and unrotated original state of the geometry.

In general, you can apply scaling, offset and rotation to the imported mesh via keywords scale, scale_axes, translate and rotate. Operations are applied in the order as they are specified. The rotation via rotate is performed around the rotation axis defined by the origin (0,0,0) and the axis vector specified.

With the temperature keyword, you can define a temperature for a wall in conjunction with heat conduction via the enable_heat_transfer command. The value can be either a positive scalar, or a variable reference (eg. temperature v_temp). Note that the actual calculation of the heat transfer happens only if you use the mesh as wall (i.e., with solid yes). If enable_surface_heating is enabled, the keyword mass_for_heat_capacity is used to assign a mass to the mesh in order to compute the actual heat capacity from the specific heat capacity.

The voltage keyword specifies the voltage of the mesh. Alternatively an electrical current can be specified via the current keyword. These keywords are used by the enable_electrical_conductivity command. The values should be numerical scalars. The mesh must be included in the meshes list of the enable_electrical_conductivity command for the corresponding boundary condition to be applied. If a mesh is specified in the meshes list but does not provide any voltage or current, a zero-valued current is set.

The planar_extrusion_length keyword allows to extrude a planar mesh in direction of the anti-normal by a specified length values.

The mesh_modules keyword allows to append multiple mesh modules defined by mesh_module commands. Note that some of these modules are dependent on each other and some are mutually exclusive. The order of the mesh modules is important and the arguments for each mesh module need to be appended in the same order as the modules.

Warning

When using the deform, heattransfer or liquidtransfer module and periodic boundary conditions the mesh needs to fulfill the following properties: (i) a triangle is not allowed to be in contact with itself through periodic boundaries, (ii) if two triangles are in contact inside the domain, they are not allowed to be in contact through periodic boundaries. Note that these restrictions are not validated by Aspherix® and must be ensured by the user.

With the surface_velocity keyword a surface velocity can be imposed to a mesh that is used as wall. This way, a simple conveyor belt can be modelled: The velocity direction for each mesh face is given by the projection of the conveyor belt velocity parallel to the mesh face, the velocity magnitude for each mesh face is equal to the conveyor belt velocity. This ensures the model is also applicable for curved meshes.

Likewise, the optional rotation model, activated via keyword surface_angular_velocity, mimics rotational motion of the mesh (e.g. for modeling a shear cell).

By default the mesh command evaluates the normal and shear stresses that the particles exert on the mesh elements (triangles). Furthermore, also the total force is calculated.

For an accurate calculation of the body torque the reference point has to be set through the keyword reference_point_torque. Note that the reference point is set after the scale, scale_axes, translate and rotate keywords are applied in the initialization. Thus, the reference point should be set with respect to the repositioned mesh and not with respect to the STL file. Similarly, the reference_axis_torque keyword can be used to calculate the torque with respect to an axis instead of a point. This is important when calculating the torque acting on a screw for example. The axis is set automatically in case a rotating mesh motion is associated with the mesh. In case you wish to override this, use none as argument instead of an axis.

The output of the normal and shear stresses (per-element values) and the forces and torques (global per-mesh values) is taken care of by the output_settings command.

Details about the stress calculation:

To compute these normal and shear stresses, first the normal and tangential forces (as exerted on the mesh element by nearby particles) are determined. Next, these normal and tangential forces are divided by the area of the specific mesh element to obtain the normal and shear stresses, respectively. This computation is performed for all mesh elements, and each mesh element will therefore obtain (mesh element averaged) normal and shear stresses. As this stress calculation will cost a bit of performance, it can be disabled by using the stress_calculation keyword with the value off.

Aspherix® checks a couple of quality criteria upon loading a mesh. Aspherix® tries to give you as much information about the issue as possible.

Warning messages:

There should be no angle < 0.5 degrees in any element (soft limit for angles)
All nodes should be within the simulation box

If any of the above rules is not fulfilled, a warning is generated. The keyword verbose controls if details about the warning are written to the screen.

Error messages:

The curvature must not be larger than any angle in any mesh element
There must be no element with an angle < 0.0181185 degrees in any element (hard limit for angles)
The number of neighbor elements must be <= 5 for any element
Mesh elements must not be duplicate
Coplanar mesh elements that share an edge must not overlap
Mesh elements must not leave the simulation domain (based on the center of the element)

If any of the above rules is not fulfilled, an error is generated and Aspherix® halts. Error messages are always verbose. If Aspherix® halts due to the last error, you might think about (a) changing the mesh import parameters (scale, scale_axes, translate, rotate), (b) changing the mesh dynamics if a mesh_module_wrapper command is applied.

There are a couple of features that help read/repair a mesh which can not be read correctly in the first place:

precision
curvature
heal
element_exclusion_list
min_feature_length
curvature_tolerant

The precision keyword specifies how far away mesh nodes can be at maximum to be recognized as identical. This is important for building the topology of the mesh and identify elements as neighbors. Normally, this should only be changed if the mesh file you are working with is suffering from precision/round-off issues.

The curvature keyword lets you specify up to which angle between two triangles the triangles should be treated as belonging to the same surface (e.g. useful for bends). This angle is used to decide if (a) contact history is copied from one triangle to the other as the contact point proceeds and (b) if edge and corner interaction is calculated.

The curvature_tolerant keyword can simply turn off the check that the curvature must not be larger than any angle in any mesh element. This is typically not recommended, but can be used as a last resort measure.

If Aspherix® stalls because of duplicate elements, you can try setting heal to auto_remove_duplicates. Aspherix® will then try to heal the geometry by removing duplicate elements.

With the optional element_exclusion_list keyword is used in mode write, Aspherix® will write a list of elements which

have more than the allowed 5 face neighbors per surface
have an angle below 0.05729578 degrees
are duplicate element

to a file. The read mode can then use this file and will skip the elements in the list.

However, you can also manually write such a file to exclude elements you do not want to have included

Warning

The element_exclusion_list mode write model requires the execution of a simulate command. If left out, the exclusion list will be incomplete. For writing exclusion lists for several meshes, write each list with a separate run. In Aspherix® GUI a tool (Tools / Mesh Healer) for generating these element exclusion lists is provided.

Note

The element_exclusion_list mode write model works in serial only. However, this is not a real restriction, since you can generate the exclusion lists in serial, but then read them to import the mesh into a parallel simulation.

Warning

If you use the heal or element_exclusion_list keywords, you should check the changes to the geometry, e.g. by checking the mesh written by the output_settings command or by using a dump mesh/stl command.

With the min_feature_length option, you can exclude elements which do not belong to an entity which has any element larger than min_feature_length. In this context, “entity” is defined by the neighborhood of the element. min_feature_length also writes to the exclusion list, and can thus only be used along with the element_exclusion_list feature.

The remove_protruding_mesh_elements keyword can be used for meshes that are too large for the simulation domain. This would normally cause Aspherix® to abort. To remove all elements completely that protrude from the domain set the value associated with this keyword to yes. Note, it will not cut the elements at the boundary but rather remove them completely. It is left to the users discretion to verify that no holes are created that interfere with the simulation. In case no mesh elements are left after the removal an error is thrown.

Under some rare circumstances, contacts between a particle and a triangle corner or triangle edge can be missed. Setting all_edges_corners_active to yes circumvents this by setting all edges/corners to active. This is needed for energy evaluation via the calculate command.

Warning

The following keyword weighted_wall_formulation is missing several error checks and might cause undefined behaviour if used incorrectly. Make sure you manually check all the restrictions listed below.

The keyword weighted_wall_formulation is an experimental feature that computes the particle-wall contribution using a different algorithm. This keyword should only be used in conjunction with meshes that are watertight (locally where particle interactions happen). Depending on the mesh resolution this keyword might cause performance penalties. The key task of the algorithm is to ensure that the normal contact between mesh and particle conserves energy. This can be used to improve the result of the calculate command. Note that this is not true for any other contact models (e.g. tangential). Additionally, this keyword does not work with any models that require non-surface contacts (e.g. bond models).

The default usage of the mesh command is with the file keyword which allows reading in a meshed surface. Alternatively, it is possible to extract meshes from certain commands and use them in a similar manner as a mesh from a file. Currently, only the enable_fem_coupling and enable_cfd_coupling commands provide this functionality. Using this keyword it is possible to import the boundaries defined in the Elmer / CFD mesh directly to Aspherix as boundaries for the particles. Note, for Elmer each boundary must be imported separately using the boundary_condition_name keyword to identify which boundary is to be imported using the Name in the Boundary Condition section of an Elmer .sif file. For CFD, from_command cfd boundary_name <WALLNAME> should be used, where WALLNAME should be a valid CFD patch name. If a boundary contains quadrilateral elements, for both commands each quadrilateral element will be converted (split) into two triangles.

The keyword/value pair enable_reflection yes enables the reflection algorithm for mesh walls. This algorithm modifies the contact detection between the wall and solid particles in two ways: (i) the contact detection calculation is executed considering particles with a enlarged radius, by a factor of virtual_radius_factor, and (ii) when the virtualy enlarged particles are in contact with the wall, with a corresponding overlap distance $\delta$ [m], they are displaced by a distance $1.01 \delta$ [m] on the opposite direction of the wall contact vector, instead of experiencing a contact force, and the sign of the corresponding velocity component on that direction is flipped. The magnitude of the particle velocity vector after the collision is scaled according to the specified coefficient of restitution.

The reflection algorithm can be useful for example in cases where the particles pass through solid walls without experiencing any wall contact because the time step of the simulation is excessively large. This issue can also be solved by reducing the time step of the simulation. However, in some applications it is not possible to reduce the time step due to the very high computational cost. The use of the reflection algorithm reduces the accuracy of a simulation.

The wall neighbor lists are not modified by the reflection algorithm and therefore in some cases it is necessary to change the neighbor list build with the contact_distance_factor keyword of the neigh_modify command, as in the example below.

variable virtual_radius_factor equal 200
neigh_modify contact_distance_factor ${virtual_radius_factor}
mesh id walls file walls.stl material steel enable_reflection yes virtual_radius_factor ${virtual_radius_factor}

In some extreme cases it is difficult to identify the appropriate value for the virtual_radius_factor that will ensure that the particles do not cross a solid wall. If the wall is approximately parallel to the xy plane, the keyword min_particle_position_z can be useful in those extreme cases. This will ensure that the position of the particles on the z direction is never lower than the value specified by min_particle_position_z, regardless of the value of virtual_radius_factor. If a particle falls to a location that is lower than min_particle_position_z, it will be reflected upwards, to a z location given by min_particle_position_z plus the particle radius scaled by the contact_distance_factor and multiplied by 1.01.

Additional information

This command stores a global vector with 9 components for access by various output commands. The first 3 components are equal to the total force on the mesh, the next 3 components store the total torque on the body exerted by the particles (set reference_point_torque when accessing torque, see above). Finally, the last 3 components are the coordinates (translated, scaled, rotated) of the reference point. The output_settings command automatically saves the forces, and if a reference point is set also the torques. If a mesh module is applied that modified the posiiton of the reference point (e.g., 6dof or servo) the also the reference point denoted as id_meshID.center_of_mass_x/y/z is saved.

The property values can be accessed via the property name: for example, id_myMesh.fx will return the force in x-direction. See the table below for a complete overview of the available properties and how to access them.

Mesh module property	property name (dot access)	array position
total forces on the mesh	fx, fy, fz	1-3
total torques on the mesh	tx, ty, tz	4-6
reference point coordinates	ref_px, ref_py, ref_pz	7-9
torque on axis	torque_on_axis	10

Note that all force, torque and reference point components can also be accessed via their longer variants: fx becomes force_x, tx becomes torque_x, and ref_px becomes reference_point_x. The torque on axis (torque_on_axis) property is non-zero only if a reference_axis_torque is set or automatically detected.

The voltage and electric current on the mesh can be obtained by id_myMesh.voltage and id_myMesh.current, respectively.

The output of the normal and shear stresses (per-element values) and the forces and torques (global per-mesh values) is taken care of by the output_settings command.

This command also supports the modify_command with option shift = dx dy dz and keyword/pair old_style yes. This command shifts mesh instantaneously by the provided vector.

The mesh command writes the stl data to binary restart files to be able to correctly resume the simulation in case the mesh is moved. Even if the mesh in the restart file does not contain any temperature information, the temperature can be set/added after loading the restart file.

Restrictions

To date, only ASCII STL, VTK and OBJ files can be read (binary is not supported). In the current implementation, each processor allocates memory for the whole geometry, which may lead to memory issues for very large geometries. It is not supported to use both the moving mesh and the conveyor belt feature.

Warning

The keyword remove_protruding_mesh_elements does not have GPU support. For GPU runs the output values of the mesh forces are zero even when the actual values resulting from computations are non-zero.

mesh command

Syntax

Examples

Description

Additional information

Restrictions

Related commands