Explicit Single Phase MPM - geomechanics/mpm GitHub Wiki

Overall Structure

Geomechanics MPM uses a JSON input file. The following file structure is used.

{
    "title": "Example Title",
    "mesh": {
        
    },
    "particles":[

    ],
    "materials":[

    ],
    "material_sets":[

    ],
    "external_loading_conditions":{

    },
    "math_functions": [

    ],
    "analysis": {

    },
    "post_processing": {

    }

}

Mesh

The mesh object defines the mesh (node and cells) and boundary conditions. The following inputs are considered.

{

    "mesh":{
        "mesh": "mesh.txt",
        "entity_sets": "entity_sets.json",
        "particles_volumes": "particles-volume.txt",
        "particles_stresses": {
          "type": "file",
          "location": "particles-stresses.txt"
        },
        "particle_cells": "particles-cells.txt",
        "boundary_conditions":{
            "acceleration_constraints": [
                {
                    "nset_id": 0,
                    "dir": 0,
                    "math_function_id": 0,
                    "acceleration": 1.0
                }, 
                {
                    "file": "acceleration_constraints_inputs.txt"
                }
            ],
            "velocity_constraints": [
                {
                    "nset_id": 1,
                    "dir": 1,
                    "velocity": 0.0
                }, 
                {
                    "file": "velocity_constraints_inputs.txt"
                }
            ],
            "friction_constraints": [
                {
                    "nset_id": 2,
                    "dir": 1,
                    "sign_n": -1,
                    "friction": 0.5
                },
                {
                    "file": "friction_constraints_inputs.txt"
                }
            ],
            "cohesion_constraints": [
                {
                    "nset_id": 2,
                    "dir": 1,
                    "sign_n": -1,
                    "cohesion": 2000,
                    "h_min" : 3,
                    "position" : 1
                },
                {
                    "file": "cohesion_constraints_inputs.txt"
                }
            ],
            "absorbing_constraints": [
                {
                    "nset_id" : 3,
                    "dir" : 2,
                    "delta" : 1.5,
                    "h_min" : 3,
                    "a" : 1.0,
                    "b" : 1.0,
                    "position" : "corner"
                }
            ],
            "nodal_euler_angles": "nodal-euler-angles.txt",
            "particles_velocity_constraints": [
                {
                    "pset_id": 0,
                    "dir": 0,
                    "velocity": 0.0
                }
            ]
        },
        "cell_type": "ED2Q4",
        "isoparametric": false,
        "check_duplicates": false,
        "io_type": "Ascii3D",
        "node_type": "N2D"
    },

}

• "isoparametric" flag is set true for unstructured (non-prismatic) elementes.
• "check_duplicates" flag is set true to check for repeating material points within the model.
• "io_type" is either "Ascii2D" or "Ascii3D".
• "node_type" is either "N2D" or "N3D".

Input Mesh Files

File	Description	Optional?
mesh	nodal coordinates and cell connectivity	no
entity sets	defines particle, node, and cell sets	yes
particles volumes	defines particle volumes	yes
particles stresses	defines initial particle stresses (Voigt convention)	yes
particle cells	defines initial guess of particle location	yes

Particles Stresses

Optional particles stresses can be input via text file (as shown above). First row of the text file provides the total number of material points. Each subsequent row provides the stress state, using Voigt convention, for each material point in order.

Alternatively, if the stress in the entire simulation domain is isotropic, the "isotropic" option can be specified following this format:

{
    
        "particles_stresses": {
            "type": "isotropic",
            "values": [
                -10000000,
                -10000000,
                -10000000,
                0.0000000,
                0.0000000,
                0.0000000
            ]
        }

}

where the "values" are the stresses written in Voigt notation with the following order: sigma_xx, sigma_yy, sigma_zz, sigma_xy, sigma_xz, and sigma_yz.

Boundary Conditions

Optional boundary conditions include nodal friction constraints, cohesion constraints, velocity constraints, acceleration constraints, absorbing boundary constraints, and Euler angles, as well as particle velocity constraints.

For acceleration constraints:

• "nset_id" corresponds to defined nodal sets within the entity sets JSON file.
• "math_function_id" corresponds to IDs for defined "math_functions".
• "dir" is the direction of the constraint (0|1|2).
• "acceleration" is the magnitude of acceleration scaling (i.e., "acceleration": 1 is no scaling).
• Nodal acceleration constraints can be input as a .txt file with each row corresponding to an individual constraint.

For nodal and particle velocity constraints:

• "nset_id" and "pset_id" correspond to defined sets within the entity sets JSON file.
• "dir" is the direction of the constraint (0|1|2).
• "velocity" is the specified velocity in declared direction.
• Nodal velocity constraints can be input as a .txt file with each row corresponding to an individual constraint.

For friction constraints:

• "nest_id" corresponds to defined nodal sets within the entity sets JSON file.
• "dir" is the direction normal to resistance (0|1|2).
• "sign_n" is the sign of the normal vector to the friction plane (-1|+1).
• "friction" is the frictional coefficient.
• Nodal friction constraints can be input as a .txt file with each row corresponding to an individual constraint.

For cohesion constraints:

• "nset_id" corresponds to defined nodal sets within the entity sets JSON file.
• "dir" is the direction normal to resistance (0|1|2).
• "sign_n" is the sign of the normal vector to the cohesion plane (-1|+1).
• "cohesion" is the value of cohesion.
• "h_min" is the mean cell length.
• "nposition" indicates where nodes are located relative to the model bounding box. Locations for nodes are input as an integer, and include: 1 (corner), 2 (edge), and 3 (face).
• Nodal cohesion constraints can be input as a .txt file with each row corresponding to an individual constraint.
• Current cohesion boundary implementation is developed for square mesh.

For absorbing boundary constraints:

• "nset_id" corresponds to defined nodal sets within the entity sets JSON file.
• "dir" is the direction (0|1|2) that corresponds to compression wave (p-wave) travel.
• "delta" is the virtual thickness that controls spring stiffness and thus boundary dispalcements.
• "h_min" is the mean cell length.
• "a" is an optional dimensionless dashpot factor corresponding to compression waves (p-waves); default is 1.
• "b" is an optional dimensionless dashpot factor corresponding to shear waves (s-waves); default is 1.
• "position" indicates where nodes are located within the model. Possible locations for nodes include "corner", "edge", and "face".
• Current absorbing boundary implementation is developed for square mesh using linear basis functions.
• Current absorbing boundary implementation is developed for only homogenous material.
• Current absorbing boundary implementation is developed for non-MPI simulations.

For Euler angles:

• "nid" corresponds to the nodal index.
• "angles" is a set of angles (α|β|γ) of length Tdim which forms a rotation matrix. Each Euler angle describes an orientation change between the original axes (x-y-z) and some tilted axes (X-Y-Z). Angles are in radians and the sign convention is positive for counterclockwise.
  • α describes the angle between x and N.
  • β describes the angle between N and X.
  • γ describes the angle between z and Z.
• Nodal Euler angles can be input as a .txt file with each row corresponding to an individual constraint.
• Nodal Euler angles allow modification of other applied boundary conditions: the axis x-y-z which defines directions of applied boundary conditions may be modified to some tilted axes X-Y-Z.

Cell Type

The following cell types are currently supported.

Cell type	Description
ED2T2	2D Triangle 3-noded element
ED2T6	2D Triangle 3-noded element
ED2Q4	2D Quadrilateral 4-noded element
ED2Q8	2D Quadrilateral 8-noded element
ED2Q9	2D Quadrilateral 9-noded element
ED2Q16G	2D GIMP Quadrilateral 4-noded element
ED2Q4P2B	2D Quadratic BSpline Quadrilateral element
ED3T4	3D Tetrahedron 4-noded element
ED3H8	3D Hexahedron 8-noded element
ED3H20	3D Hexahedron 20-noded element
ED3H64	3D GIMP Hexahedron 64-noded element
ED3H8P2B	3D Quadratic BSpline Hexahedron element

• To run elements with higher-order basis function, please see this page.
• Current 3D tetrahedron element implementation is developed for non-MPI simulations.

Particles

The particles object defines material points from either an ASCII file or the built-in Gauss point generator.

{

    "particles": [
        {
            "generator": {
                "check_duplicates": true,
                "pset_id": 99,
                "material_id": 0,
                "particle_type": "P2D",
                "type": "file",
                "location": "particles.txt",
                "io_type": "Ascii2D"
            }
        },
        {
            "generator": {
                "check_duplicates": true,
                "pset_id": 98,
                "material_id": 1,
                "particle_type": "P2D",
                "type": "gauss",
                "nparticles_per_dir": 2, 
                "cset_id": -1
            }
        }
    ]

}

For both generators:

• "check_duplicates" flag is set true to check for repeating material points within the model.
• "pset_id" is the ID of the generated particle set.
• "material_id" corresponds to a specific material model defined below.
• "particles_type" is either "P2D" or "P3D".

For particles from file:

• "type" is set to "file".
• "location" defines the particle file name in the working directory.
• "io_type" is either "Ascii2D" or "Ascii3D".

For particles from Gauss generator:

• "type" is set to "gauss".
• "nparticles_per_dir" is the number of material points per direction in either
• "cset_id" defines which cells have material points generated; using -1 generates material points in all cells.

Materials

The materials object defines that material types are used in the analysis. Available materials include:

• Linear Elastic
• Mohr-Coulomb
• Modified Cam Clay
• Bonded NorSand

Check out the links in the right-hand sidebar for further details.

Material Sets

The material_sets object defines the relationship between material_id and pset_id. This object is optional. If provided, this relationship is used to redefine the material_id for each particle associated with the provided pset_id. This optional object allows for the particles from a single input file to be assigned multiple materials.

{

    "material_sets": [
        {
            "material_id": 0,
            "pset_id": 2
        }
    ]

}

External Loading Conditions

The external_loading_conditions object specifies gravity, nodal forces, and particle forces.

{

    "external_loading_conditions": {
        "gravity": [0.0, -9.81, 0.0],
        "concentrated_nodal_forces": [
            {
                "nset_id": 0,
                "math_function_id": 0,
                "dir": 1,
                "force": 100
            }
        ],
        "particle_surface_traction": [
            {
                "pset_id": 1,
                "math_function_id": 1,
                "dir": 0,
                "traction": 10
            }
        ]
    }

}

For concentrated nodal forces:

• "nset_id" correspond to defined sets within the entity sets JSON file.
• "math_function_id" corresponds to a specific math function defined below.
• "dir" is the direction of the constraint (0|1|2).
• "force" is the concentrated nodal force applied (consistent units).
• Nodal forces can be input as a .txt file where each line is nid, dir, and force.

For particle surface tractions:

• "pset_id" correspond to defined sets within the entity sets JSON file.
• "math_function_id" corresponds to a specific math function defined below.
• "dir" is the direction of the constraint (0|1|2).
• "traction" is the surface traction applied (consistent units).

Math Functions

The math_function object defines how loads change over time.

{

    "math_functions": [
        {
            "id": 0,
            "type": "Linear",
            "xvalues": [0.0, 1.0, 10.0],
            "fxvalues": [0.0, 1.0, 1.0]
        },
        {
            "id": 1,
            "type": "Linear",
            "file": "math_function_input.csv"
        }
    ]

}

• "id" corresponds the applied boundary loading above.
• "type" is currently limited to linear functions.
• "xvalues" is the model time.
• "fxvalues" is the relative weight of the force or traction magnitude defined in the loading conditions.
• Math functions can be input as a .csv file with each row corresponding to the pair [x, f(x)].

Analysis

The analysis object defines the type of analysis, time step, and total number of steps.

{

    "analysis": {
        "type": "MPMExplicit2D",
        "mpm_scheme": "usf",
        "stress_rate": "jaumann",
        "velocity_update": "flip",
        "velocity_update_settings": {
	        "blending_ratio": 0.95
        },
        "dt": 1.0e-5,
        "nsteps": 1001,
        "locate_particles": true,
        "nload_balance_steps": 100,
        "uuid": "output-name-000",
        "resume": {
            "resume": false,
            "uuid": "output-name-000",
            "step": 100
        },
        "damping": {
            "type": "Cundall",
            "damping_factor": 0.01
        }
    }

}

Type

"type" determines if a simulation is 2D or 3D:

Analysis	Description
"MPMExplicit2D"	explicit 2D MPM
"MPMExplicit3D"	explicit 3D MPM

Scheme

"mpm_scheme" defines what stress update scheme is utilized. 3 options are supported:

Schemes	Description
"usf"	update stress first
"usl"	update stress last
"musl"	modified update stress last

Stress Rate

"stress_rate" defines what stress rate is assumed for the incremental stress update. 2 options are supported:

Rate	Description
"jaumann"	Jaumann rate of Cauchy stress tensor (objective)
-	Cauchy stress tensor rate (non-objective)

Velocity Update

"velocity_update" defines what scheme is assumed to update the particle velocity from nodal velocity/acceleration. 5 options are supported:

1. "flip" fluid-implicit-particle (acceleration update)
2. "pic" particle-in-cell (velocity update)
3. "tpic" Taylor pic
4. "apic" Affine pic
5. "asflip" Affine separable flip

For the "flip" and "asflip" schemes, there is an option to include a blending ratio with "pic". One can specify that in the input .json in "blending_ratio" under the "velocity_update_settings".

Resume

Resume is optional.

Damping

Damping is optional.

Only Cundall damping can be specified.

Other Settings

• "dt" is the time step.
• "nsteps" is the total number of steps.
• "locate_particles" flag is set false to allow simulation to continue if material points leave the mesh domain.
• "nload_balance_steps" is optional to redefine the dynamic load balancing; default is every 1000 steps.
• "uuid" is the analysis name.

Post Processing

The post_processing object defines what output files are generated.

{

    "post_processing":{
        "output_steps": 100,
        "path": "results/",
        "vtk": [ ],
        "vtk_statevars": [
            {
                "statevars": [ ]
            }
        ]
    }

}

• "output_steps" is the number of steps between generated files.
• "path" is where output files will be saved; the path will be generated if it does not already exist.

VTK

Available VTK files include mass, volume, mass_density, displacements, velocities, normals, strains, and stresses.

VTK State Variables

Available state variables are material-dependent.