MPM Input Files

MPM simulations are run using NairnMPM. Some of the key features of these code engines (with links) are listed here. The documentation on this page explains how to run MPM calculations by described all the sections of input command files.

Input Command File Overview

When using NairnFEAMPM or NairnFEAMPMViz to set up calculations, the input command files are usually script files written using the custom scripting language. When you interpret these scripts, the applications will create an XML input command file that is needed to drive the code engines. Click this link to see a sample scripted MPM input command file for simulation of two colliding disks.

Alternatively, you can directly create XML input command files. Because this approach cannot use the language control options of a scripting language, it is much less powerful then scripting methods and much harder to customize for a range of simulations. If you do use the manual XML method, the files must conform to the structure defined here. Click this link to see a sample XML MPM input command file for simulation of two colliding disks.

Some input commands for calculations support the use of user defined functions to increase options for setting up simulations. These functions can be used in both scripting commands and in XML commands. Scripting commands can build functions using string expressions. In XML files, you enter the entire function.

Main Header

This section defines the type of analysis to run, number of processors (for parallel code), the units for input parameters, and provides an optional description of the calculations. When using a scripting language, the header is created automatically and its content is controlled by commands defined below. When manually writing XML files, the header, which is required, is defined in a single header block:

<Header>
  (commands)
</Header>

The possible header commands are

• Analysis Command - pick the type of MPM analysis to run.
• ConsistentUnits Command - pick units for the calculations
• Processors Command - pick number of processors for parallel code.
• Annotation Commands - these commands let you annotate the calculations.
• RandSeed Command - to pick a seed for random number generation
• Setting Developer Flags

MPM Header

This section defines many settings and features for the MPM calculations. When using a scripting language, the MPM header is created automatically by various commands defined in this section. When writing XML input files, all these commands must be within a single MPM header block:

<MPMHeader>
  (commands)
</MPMHeader>

The possible MPM header commands are given below by categories.

• MPM Methods and Simulation Timing - these commands determine the MPM method to use, the time step, and the maximum simulations time.
• Damping Options - these commands set up grid-based damping options.
• XPIC(k) and FMPM(k) Features - improved MPM with enhanced stability and noise reduction
• LeaveLimit Command - this command determines what happens when particles leave the grid.
• DeleteLimit Command - this command determines what happens when particles get nan values.
• ExtrapolateRigid Command - activates a mode where rigid materials extrapolate to the grid before setting boundary conditions.

Archiving Results

MPM results can be saved as particle results or global results, where global results are averages over all particles, or specific material types during the calculations:

• MPM Archiving Options - these commands determine which particle results are archived and where they are saved.
• MPM Global Archiving Options - these commands determine which averaged, global results are archived in a global results file.

Besides the above built-in archiving options, some custom tasks provide additional options:

• VTKArchive Custom Task - to archive results extrapolated to the grid in "VTK Legacy" files.
• HistoryArchive Custom Task - to archive material history data to a tab-delimited file.

If more archiving options are needed, you can always write a new custom task.

Creating the MPM Background Grid

Although MPM is a particle method, it uses a background grid for calculations. In general, this grid is a regular grid of orthogonal elements with linear shape functions. The background grid is easily generated with a few commands. NairnMPM does allow explicitly generated grids, but you should never use them because many important features of MPM rely on a regular grid and are only efficient for a regular grid (e.g., uGIMP and CPDI shape functions).

Creating the Material Points

In MPM the object is discretized by a collection of material points. Once the background grid is created, the material points are added to that grid using a series of Region and Hole commands or additionally by directly translating pixels in an image to an MPM model. Each of these command fills part of the grid with a collection of material points and those material points are assigned initial conditions and material type.

When using custom tasks that inject particles, a simulation must fill the Material Point Reservoir with any material point types needed by that task.

Defining Material Models

Each material point is assigned a material type. NairnMPM supports numerous material models. For plasticity materials, each material type can choose from among a set of hardening laws. For softening materials, each material type can choose amoung a set of damage initiation laws and softening laws. When using explicit cracks, the material points along the cracks can be assigned to various traction laws. Finally when using multimaterial mode or using explicit cracks, the contact mechanics at that interfaces can be controlled by contact laws. The information on these options are in the following sections:

• Material Models - all material models available for MPM simulations, which have the following types
  • Linear Elastic Small Strain
  • Hyperelastic
  • Elastic-Plastic Small Strain
  • Hyperelastic-Plastic
  • Softening
  • Viscoelastic
  • Phase Transition
  • Membrane
  • Rigid
• Traction Laws - all traction laws available for modeling cohesive zones on cracks
• Contact Laws - all contact laws used for implementing friction or imperfect interface on cracks or between materials
• Hardening Laws - all hardening laws available for plasticity materials
• Damage Initiation Laws - all damage initiation laws available for modeling softening materials
• Softening Laws - all softening laws available for modeling softening materials

Using Explicit Cracks

An advanced feature of NairnMPM is that it can model explicit cracks including multiple cracks, interacting cracks, and crack propagation. To create a simultion with cracks, you first define the cracks and then optionally customize crack settings to customize crack modeling methods. To include crack propagation, you also need to set all needed material fracture properties. By choosing a default contact law (or by choosing custom contact laws for each crack), crack surfaces can model either frictional contact or model the crack plane as an imperfect interface. By adding traction laws to cracks, they can model cohesive zones.

Multimaterial MPM

Running in multimaterial mode allows a simulation to model contact between materials. By choosing a default contact law (or by choosing custom contact laws for each material pair), multimaterial mode simulations can model material interfaces as frictional contact or as an imperfect interface.

Boundary Conditions

In MPM, boundary conditions can be applied to nodes on the grid or applied directly on the particles:

• Grid-Based Boundary Conditions - These boundary conditions are applied to nodes on the grid and are used to set velocity, temperature, and concentration. Grid-based velocity conditions can also set up object symmetry planes.
• Particle-Based Boundary Conditions - Most of the commands set boundary conditions that are applied to the particles for such things as forces, tractions, and fluxes. Some commands in these blocks instead set initial conditions for particle such as damage state.

Thermal Calculations

MPM simulations can do thermal calculations that account for thermal strains in the stress analysis and can model thermal conduction.

Diffusion, Poroelasticity, or Other Transport Calculations

MPM simulations can model diffusion and track concentration of an absorbed solvent in the materials. The concentration is coupled to strains by solvent expansion coefficients of the materials.

Alternatively, MPM simulations can model poroelastic materials and track pore pressure within a material saturated with fluid. The fluid transport between particles is modeled using Darcey's law. The pore pressure is coupled to changes in volume by poroelasticity properties of the materials.

In additional to diffusion or poroelasticity (only one of which can be in any simulation), MPM simulations can couple to other transport properties into the analysis.

Gravitation Field

MPM calculations can apply a gravitation field (or actually any constant body forces).

Custom Tasks

Custom tasks are special calculations that are performed at the end of each time step in MPM calculations. Custom tasks can be written by users working with NairnMPM source code. These user-defined custom tasks can then be scheduled when needed in some calculations. The current custom tasks are:

• PeriodicXPIC Custom Task - implement XPIC(m) simulations with an option to run them periodically instead of every time step
• AdjustTimeStep Custom Task - to adjust time step during the calculations according to current stress state of the particles.
• VTKArchive Custom Task - to archive results extrapolated to the grid in "VTK Legacy" files.
• HistoryArchive Custom Task - to archive material history data to a tab-delimited file.
• ReverseLoad Custom Task - to monitor crack length and perform actions when a specified crack length is reached.
• PropertyRamp Custom Task - to gradually change a particle property
• DeleteDamaged Custom Task - to delete failure particles or remove unneeded particles
• FluidSource Custom Task - to inject liquid particles into a simulation
• TrackError Custom Task - archive simulations errors in a tab-delimited file
• LoadControl Custom Task - to run load control simulation based on calculations of contact or reaction forces.

The following custom tasks are currently available only in OSParticulas

• CarnotCycle Custom Task - demonstration task to run simulation through a Carnot cycle.
• PressureDependentMelting Custom Task - method to change melting temperature with pressure
• ReactionEnergy Custom Task - research task for chemical reaction modeling
• Crack3DArchive Custom Task - research task for 3D cracks
• JiggleGrid Custom Tasks - research task for grid changes
• JPIC Custom Task - research task for noise reduction

Custom tasks are a good way to add features or to test out new feature. See help on writing a custom task for steps on writing source code for a new custom task. If you do add a new custom taks, the following link explains how to include it in you input command files:

• Undocumented Custom Task - you can include custom tasks that are in NairnMPM but not yet supported by scripted files.

XML Insertion

When writing scripted input files, it is sometimes useful to insert raw XML commands into the automatically-format XML input file. The two commands that help in this task are:

• Entity Command - to define entities that will appear in the automatically-format XML input file.
• XMLData Command - to insert raw XML data into various sections of the automatically-format XML input file.