NairnFEAMPM Icon

CustomTask Command

NairnMPM supports custom tasks 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 be scheduled when needed. This topic explains how to schedule user-defined custom tasks and documents the currently-available custom tasks.

The method for scheduling custom tasks is as follows

CustomTask #1
Parameter #2,#3
Parameter #2,#3
   .
   .
   .
CustomTask #1
Parameter #2,#3
   .
   .
   .

where the CustomTask commands schedule a custom task and each CustomTask can be followed by any number of Parameter commands that set the options for the most recent custom task. The meanings of the arguments are:

PeriodicXPIC Custom Task

The XPIC(k) and FMPM(k) methods are advanced methods that filter out unwanted noise (in the null space) without damping out useful information. Many simulations can benefit by running them using XPIC(k) or FMPM(k). This custom tasks lets you add XPIC(k) or FMPM(k) to any simulation and select the frequency of those calculations (some more details are on OSUPDocs). The parameters for mechanics modeling are:

FMPMOrder (order)
Select the order k and use FMPM(k) in the simulations. The preferred method.
XPICOrder (order)
Select the order k and use XPIC(k) in the simulations. FMPM(k) is usually better; this option is mostly for comparisons.
periodicSteps (steps)
Select the number of steps between time steps using XPIC(k) or FMPM(k).
periodicTime (time)
Select the time interval between time steps using XPIC(k) or FMPM(k) (in alt time units).
periodicCFL (CFL)
Select the time interval based on a CFL factor between time steps using XPIC(k) or FMPM(k).
verbose (option)
If a non-zero integer, a comment line is printed in the output file every time FMPM(k) or XPIC(k) time steps are done. The default is 0.
GridBCOption (option)
Use "lumped" to use lumped mass matrix methods for boundary conditions, "velocity" to only impose grid velocity conditions in the velocity field, or "combined" to do both. The default is "combined" for FMPM(k) and "lumped" for XPIC(k). Note that XPIC(k) cannot use "velocity" option. This option only affects calculations when order k is greater than 1.

If periodicSteps is set, it is used and the other two are ignored. If periodicSteps is not used, the time step is found from the periodicCFL value (if provided) or from periodicCFL value. One of these three parameters is required to enable periodic FMPM(k) or XPIC(k) calculations.

Additional PeriodicXPIC parameters can set add FMPM(k) options for conduction, diffusion, or poroelasticity calculations. The calculations will use the order specified in above FMPMOrder command. The other setting area;

periodicStepsConduction (steps)
Select the number of steps between time steps using FMPM(k) for conduction.
periodicTimeConduction (time)
Select the time interval between time steps using FMPM(k) for conduction (in alt time units).
periodicCFLConduction (CFL)
Select the time interval based on a transport CFL factor between time steps using FMPM(k) for conduction.
periodicStepsDiffusion (steps)
Select the number of steps between time steps using FMPM(k) for diffusion or poroelasticity.
periodicTimeDiffusion (time)
Select the time interval between time steps using FMPM(k) for diffusion or poroelasticity (in alt time units).
periodicCFLDiffusion (CFL)
Select the time interval based on a transport CFL factor between time steps using FMPM(k) for diffusion or poroelasticity.

The three parameters for each choose periodicity by same methods explained above for mechanics except the (steps) parameter changes. If (steps)≥1, its meaning is the same as for mechanics. But if 0<(steps)<1, it invokes a new feature not available for mechanics modeling. In this range the simulation will blend FMPM(k) and FLIP methods using a fraction (steps) of FMPM(k) and fraction 1-(steps) of FLIP. From transport properties, the best choice is often the CFL option and set it to 0.5 or higher. Doing FMPM(k) more often might result in numerical diffusion. The blending option is another method to avoid numerical diffusion.

VTKArchive Custom Task

A VTKArchive custom task allows exporting of data extrapolated to the grid during the calculation. The normal archiving is always particle data. This option is most useful for visualization of grid results from 3D calculations. The files can be read by third-party visualization applications. A good option is the free, multi-platform ParaView application. The exported files have been written to work well with ParaView. If you export multiple archives in a single run, ParaView can load them as a block and animate the results. There are books and web sites on the use of ParaView.

The allowed parameters for the VTKArchive custom task are given below. Most parameters simply define a result to archive and thus take no value. They can omit argument #3 above for the Parameter command. Same quantity and all time parameters, however, require the #3 argument. The VTK archiving options are:

mass
Archive nodal mass (in mass units). This option is needed for creating contours that visualize the boundaries of the object. The surface can then be colored in any other archived result. Note that mass is always archived; you do not need to specify it.
material
Archives the material number for help in visualizing composite materials. Since the material number is extrapolated to the grid, the material edges will be blurred compared to particle plots.
displacement
Archive displacement vector (in length units).
velocity
Archive velocity vector (in velocity units). For problems with cracks, it is the center of mass velocity.
stress
Archive stress tensor (in pressure units).
pressure
Archive pressure (in pressure units).
equivstress
Archive equivalent stress (also know as von Mises stress) (in pressure units).
defgrad
The deformation gradient (absolute)
totalstrain
Archive total Biot strain tensor (absolute).
elasticstrain
Archive elastic Biot strain tensor (absolute, can be "strain" as well).
plasticstrain
Archive plastic Biot strain tensor, which is total strain minus elastic strain for plasticity materials (absolute).
deltav
Archive relative volume change (V-V0)/V0 (absolute).
equivstrain
Archive equivalent strain from the above total Biot strain (absolute).
temperature
Archive temperature (in K).
concentration
Archive concentration (in wt %). Only useful when diffusion calculations are activated.
porepressure
Archive pore pressure (in pressure units). Only useful when poroelasticity calculations are activated.
strainenergy
Archive strain energy (in energy units, can be "workenergy" as well).
heatenergy
Archive heat energy (in energy units).
plasticenergy
Archive plastic energy (in energy units).
history (num)
Archive material-dependent history variable using the provided (num) in the next parameter.
contactforce
Nodal force on the grid for multimaterial mode simulations when they include rigid materials that have direction=8. It is force of the rigid material on the object (in force units).
volumegradient (mat)
The volume gradient (a vector) for the material specified in (mat) (which is required and given by material ID). This gradient is used in contact calculations and can visualized by plotting glyphs of this archived property.
numpoints
The number of points interacting with each node.
archiveTime (time)
Enter the time interval (in alt time units) between saving of VTK archives. If this parameter is omitted, the VTK archive files are written on the same steps as the particle archives (see ArchiveTime command). The one difference is that the first particle archive file is written before the calculations start while the first VTK archive file is written after the first time step is completed.
firstArchiveTime (time)
Enter the time to archive the first results (in alt time units). After this time is reached, subsequent archives will be spaced by the entered archiveTime. This parameter is ignored unless the archiveTime parameter is set as well.
selectMaterial (matnum)
selects a material (by material number only) to archive grid results only from that material. You can use multiple VTKArchive custom tasks to output different materials. The default is to omit this parameter and export from all materials.

Any quantity can be followed by a colon and a name such as:

Parameter "history:Equivalent Plastic Strain",1

When the VTK files are written, the name will used in the VTK file and other software can display by that name rather then the quantity name. This option is most useful for history variables. Note that VTK files cannot accept spaces in names and any used in the name will be replaced by underscores.

Note: when archiving strains, they are calculated as a Biot strain in the current configuration. The Biot strain is defined is V-I where V is the left-stretch tension. This strain is also the Seth-Hill strain with m=1/2 in current configuration. For small strain problems it is equivalent to the small strain tensor.

Archived vectors will include all components of the vector and applications like ParaView can use the magnitude or any single component for constructing graphics. Archived tensors will include all components of the tensor. In ParaView, the magnitude and components 0 through 8 or tensors will be listed. The numbers correspond to the following tensor components:

   ( xx   xy   xz )   ( 0  1  2 )
   | yx   yy   yz | = | 3  4  5 |
   ( zx   zy   zz ) = ( 6  7  8 )

HistoryArchive

The ToArchive command options can only archive history variables 1 through 4 for each particle. This custom task provides a method to archive more history variables and also provides an alternate format for archiving history variables 1 through 4.

When this task is activated, the history data on each particle will be written to tab-delimited text files in the output results folder. The name of the file will include the archive path and will be followed by "_History_#.txt", where "#" is the step number. The file will begin with short header giving step number, step time, and column labels. Each row that follows will have data for one particle. It will include particle number, current particle position (in length units), and each requested history variable.

(number)
Enter a series Parameter commands with a single number (1 or higher) in argument #2 to select each history variable to be archived. Argument #3 is ignored and can be omitted.
archiveTime (time)
Enter the time interval (in alt time units) between saving of history archives. If this parameter is omitted, the history archive files are written on the same steps as the particle archives (see Archive command). The one exception is that no history archive is written before the first step.
firstArchiveTime (time)
Enter the time to save the first history results (in alt time units). After this time is reached, subsequent archives will be spaced by the entered archiveTime. This parameter is ignored unless the archiveTime parameter is set as well. To get a history archive after the first step, enter firstArchiveTime of zero.

ReverseLoad Custom Task

Documentation for this custom task is now on-line only

AdjustTimeStep Custom Task

For convergence of explicit, dynamic calculations, like NairnMPM, the time step must be less then the time it takes a stress wave or a particle (at its current velocity) to pass across the smallest element size. For safety, the time step is usually calculated to be some fraction of this time as specified by the input Courant-Friedrichs-Lewy (CFL) factor. If the wave speed might changes during the calculations or particle move too fast, it might be necessary to adjust the time step to retain convergence. This tasks allows you to periodically adjust the time step. The parameters are:

adjustTime (time)
The time to check if time step needs to be adjusted (in alt time units). The default is to check each time data are archived. Enter 0 to check on every time step.
verbose (option)
Set to 1 to display a message in the output file every time the time step is changed or set to 0 to adjust time step but print no message. The default is 0.
velocityCFL (CFL)
Pick an optional, different CFL factor to use for particle velocities. The default is to use the same as the input CFL factor.
maxIncrease (maxInc)
This option limits any increases in time step to be (1+(maxInc))*Δt where Δt is the current time step.

PropertyRamp

This task ramps a particle property gradually to a desired value. Firat, you create the task, decide which property to ramp, and define the ramp settings (more details on the OSUPDocs wiki). The initial parameters are

property (prop)
The options, entered by number, are:
  1. Temperature
  2. Out-of-plane stress or strain for generalized plane stress or strain
  3. Concentration or pore pressure. For diffusion calculations, this option will ramp particle concentration potential. For poroelasticity calculations, this option will ramp particle pore pressure.
  4. Relative initiation stress
  5. Relative toughness
Options 3 and 4 apply only to damage mechanics materials and the properties are set (not ramped) in the first time step (other ramp settings are ignored).
time (time)
Enter the time of the ramp (in alt time units). This parameter is optional; if omitted, the ramp occurs in a single time step.
start (start)
Enter the time to start the ramp (in alt time units). This parameter is optional; if omitted, the ramp starts at time zero. It ends at time (start)+(time)
sigmoidal (style)
Enter 0 or 1 for a linear or sigmoidal ramp. This parameter is optional; if omitted, the ramp is linear.
exponential (lifetimes)
This paramater uses an asymptotic exponential ramp 1-exp(-t/tau) where tau = ramp time/(lifetimes). If this parameter is used, the (style) setting is ignored.
stretch (stretch)
When using an exponential ramp, this parameter changes to a stretched exponential or 1-exp((-t/tau)^(stretch)). For sigmoidal, it changes shape of the step function. If omitted, the stretch is 1 for exponential or 12 for sigmoidal.

The above parameters create a ramp. The next sections explain different ways to calculate the change in particle property applied during the ramp.

Specified Property Change

Delta (delta)
Enter final property change (in units for that property).
scale (function)
If this optional command is used, the applied (delta) is scaled by any user-defined function of time and particle position.

Property Change from Image Data or Text Data

An alternative method for ramping up property change is to ramp to any distribution of particle values as represented within a bit mapped file or stored in a comma-separated or tab-delimited plain-text file. The parameters for using an image or text data are:

file (fileName)
Full or relative path name to a BMP file or a TXT file. Most BMP formats are accepted and data are converted to 256 levels of gray (or intensity for RGB files). TXT files should be comma-separated values or tab-delimited columns.
width (width)
height (height)
Specify the width and height for the image or data in text files (see BMPRegion command for width and height setting options).
xorigin (xO)
yorigin (yO)
zlevel (zO)
(x,y,z) coordinate for the origin of the image or text data when mapped to the grid in length units.
flipped (flipped)
Default is 0. If 1, the image or text data are flipped in the vertical direction.
DeltaMin (deltaMin)
DeltaMax (deltaMax)
For image data, gray values 0 to 255 are linearly interpreted between these limits. For text files, the entered value is given by (deltaMin)+(deltaMax)*x where x is a value in the text file.

Property Change from Image Blocks

Alternatively, the particle property can be determined from ranges of intensity by the same method that bit mapped files can be used to assign particle material type. This method is done by replacing (deltaMin) and (deltaMax) with one or more map commands:

"map #1 #2" (delta)
#1 and #2 are a range of gray scale values (from 0 to 255 with #2 ≥ #1). These values must be embedded in the text of the parameter name, which must begin in "map" (e.g., "map 20 75"). The (delta) is property change to apply to all particles under regions within the gray scale range specified by #1 and #2.

DeleteDamage

The task deletes particles from a simulation after they undergo decohesion. This function is only useful for softening materials. A second use of this task is to delete particles after a certain time. This function works for any material type. Its parameters are:

material (num)
matname (name)
Use one or the other to specify a material type by number in the file (ordered from 1) or by name assigned to the material in the material command.
store_x (xloc)
store_y (yloc)
store_z (zloc)
Deleted particles are moved to (xloc, yloc, zloc) on the background grid. This location must be in the grid and empty such that particles will not interact with active particles. Enter in length units.
minCOD (cod)
Normally particles are deleted right after they fail. Alternatively, you can require the implied crack in the particle to open further before deletion by entering a minimum crack opening displacement (COD) (in length units)
direction (dir)
By default, the (cod) refers to magnitude of the COD. Alternatively, the minimum can apply to one component of the COD selected by entered integer
  1. = use magnitude of the COD (the default and option used if you enter an invalid (dir))
  2. = use component of COD normal to the crack plane
  3. = use component of COD tangential to the crack plane
  4. = use xy shear slippage (same as 3 in 2D simulations)
  5. = use xz shear slippage (only nonzero in 3D simulations)
deleteTime (time)
If this parameter is set, particles of the specified material type will all be deleted when time reaches the entered (time) in alt time units.

Undocumented Custom Tasks

Other custom tasks may be written for NairnMPM (or OSParticulas) but not known to this help information. You can find the lastest available tasks in the OSUPDocs wiki on Custom Tasks. You can still use such tasks. Enter the name of the task (exactly as specified and case sensitive) in the CustomTask command and then follow that with any number of Parameter commands. The parameter names and their values are passed exactly as provided (case sensitive) to the input file (including text values) and should match the requirements of the undocumented task.

Notes

  1. The CustomTask command is only allowed for MPM analyses.