Skip to content

Explicit Single Phase MPM

Jump to bottom
Bodhinanda Chandra edited this page Oct 6, 2024 · 47 revisions

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 the material types 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.

Stress Rate

Our materials assume hypo-elastic formulation, and hence, the stress update is generally not objective. One is recommended to include "stress_rate" settings in their material parameters to specify which approach they would like to use. "stress_rate" defines what stress rate is assumed for the incremental stress update. We are using the objective algorithm proposed by Simo and Hughes (1998). 2 options are supported:

Rate Description
"jaumann" Jaumann rate of Cauchy stress tensor (objective)
"green_naghdi" Green-Naghdi rate of Cauchy stress tensor (objective)
"none" Cauchy stress tensor rate (non-objective)

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",
        "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

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.

Project Information

Getting Started

Input File

Pre and Post Processing

Material Models

Clone this wiki locally