Material Point Reservoir

Introduction

Simulations in NairnMPM are currently limited to a fixed number of particles. To allow for simulation options that delete particles or inject particles, the code implements a reservoir of material points. This reservoir is currently only implemented in OSParticulas but will be moved to NairnMPM soon.

The reservoir is created automatically for all simulations (unless you are using an unstructured grid, which is uncommon because many features are lost for such grids). For most simulations, the reservoir handles all options that might delete particles and happens automatically without your input commands needing extra commands to set reservoir properties. Some features (which currently are only in custom tasks) can inject particles into the simulation. To use any such custom tasks, your input commands should pre-fill the reservoir with particles type needed for that task.

Deleting Particles

Any feature that deletes particles, moves those particle into the reservoir. These reservoir tasks happen automatically. You input commands only need to invoke options that delete particles. The current options are:

LeaveLimit Command - if this command's (maxNum) parameter is negative, particles that leave the grid are deleted from the simulation.
DeleteLimit Command - if this command's (maxNum) parameter is greater than 1, particles that develop nan are deleted from the simulation.
DeleteDamaged Custom Task - this task can delete damaged particles after decohesion.
JWLPlusPlus Material - this material has an option to delete gas particles a sufficient distance from the ignition site.

Injecting Particles

Some simulations might work better by injecting particles as needed rather then starting will all particles already in place. In the future, built-in feature that inject particle might be added, but currently particle injection is only done in custom tasks. The only custom task that injects particles is:

FluidSource Custom Task - to inject liquid particles at a specified rate, location, and direction.

User-written custom tasks can also inject particles. Information on adding reservoir features to custom tasks is given below.

Filling the Reservoir

To allow custom tasks to inject particles, the reservoir normally needs to be seeded with enough material points for the injection process. The command to fill the reservoir in scripted files is:

Fill (num),(matid),<(lx)>,<(ly)>,<(lz)>

In XML files, the reservoir is filled using a Fill element that must be within the single <MaterialPoints> element in the input file:

 <MaterialPoints>
   <Fill num='(num)' mat='(matid)' lx='(lx)' ly='(ly)' lz='(lz)'/>
 </MaterialPoints>

where

(num) is the number of material points to put into the reservoir.
(matid) is the material ID for a previously defined material (which must be a material number in XML files).
(lx), (ly), and (lz) optionally specify the size of the material point in length units. If these optional parameters are not provided, the material points will use the default size for the simulation (as set using the PtsPerElement command). When a custom task injects particles of a certain size, that size must made available in the reservoir by use a matching size in this command.

Adding Reservoir Methods to a Custom Task

The reservoir class is automatically added to all simulations (unless you are using an unstructured grid). To write code that uses the reservoir, your custom task should include the NairnMPM_Class/Reservoir.hpp. This header defines global variable that provides a pointer to the created Reservoir class:

 extern Reservoir *mpmReservoir

Your custom tasks can use the following features of the reservoir.

Custom Tasks Initialization

The custom task Initialize() method is called for each custom task before the simulation begins. It is good practice for this method to verify the reserviour is available. Typical code to start the Initialize() method is:

// requires reservoir
if(mpmReservoir==NULL)
{   throw CommonException("This custom task requires an available reservoir (i.e., a structured grid)",
                          "MyCustomTasks::Initialize");
}

Inject a Particle

Whenever your task determines that a particle should be injected, call:

mpmReservoir->InjectParticle(Vector *location,Vector *lpart,int matid)

where

location is pointer to vector for injection location
lpart is pointer to vector with desired absolute size for the injected particle (for 2D simulations, the z coordinated is never accessed).
matid is the desired material ID for the injected particle

The method returns a pointer to the material point that was injected. The particle will be reset to properties that would exist at the start of a simulation. If needed, your custom tasks can set any material point properties, provided they are consistent with simulation needs. If the reservoir is empty (or just empty for the requested type), this method returns NULL.

The reservoir maintains separate lists of particles sorted by size and material ID. Normally, you want to fill the reservoir with needed sizes and material IDs and then retrieve from those lists when needed by your task. Some options with these parameters are:

lpart = NULL - passing NULL in this parameter means you do not care about particle size. The method will return the first particle found that matches matid. This option might be common for a simulations in which all particles are the same size and your custom tasks has no need to ever change particle size.
*lpart has unknown size - if you request a particle size that is not in the reservoir, this method will find a particle that matches matid and change its size to your requested size. The mass of the particle will scale to the new size and information will be written to the PtDims.txt results file that visualization tools use to plot particles correctly even when they change size during a simulation. Note that for visualization efficiency, it is better to avoid changing particle sizes. Thus, if possible, you should fill the reservoir will all sizes needed by your custom task. Some tasks, however, might not know the needed size until a simulation is running. This method will handle size changes needed by such tasks.
matid<=0 - using this setting means you will accept any material type in the reservoir. The first one found will be returned. This option is acceptable for simulations in which all particles are the same material type.

Delete a Particle

To delete a particle, call:

mpmReservoir->DeleteParticle(MPMBase *mpmptr)

where mpmptr is pointer to material point to be deleted. All properties of the particle will be reset to initial conditions. If needed, the particle size will be changed to match size for a list in the reservoir. If size is changed, the mass will be rescaled and information will be written to the PtDims.txt results file.

Changing a Particle Size

To change the size of any particle without moving it to the reservoir, call

mpmReservoir->ChangeParticleSize(MPMBase *mptr,Vector *lpart)

where mptr is pointer to the material point and lpart is the new absolute size. The reason to use this methods is to change size without changing other material point properties. The method handles rescaling the mass, changing the size, and writing information to the PtDims.txt results file. Your custom task is responsible for determining that the size change does not cause numerical artifacts. For example, the size change might need to go along with changes to other particle properties.