Main Help → All Commands → Custom Tasks → CustomTask
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:
NairnMPM
but not known here to NairnFEAMPM, such as user-written custom tasks.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:
k
and use FMPM(k) in the simulations. The preferred method.k
and use XPIC(k) in the simulations. FMPM(k) is usually better; this option is mostly for comparisons.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, poroelasticity or additional diffusion calculations. The calculations will use the order specified in above FMPMOrder command. The other setting area;
Here "#" in the diffusion commands should be "0" (or omitted) to set values for diffusion or poroelasticity calculations or can refer to other transport calculations by number in the order they were created in the input command file by extra Diffusion commands (starting with 1 and not counting commands for solvent diffusion or poroelasticity where ever they occurred).
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.
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:
(num)
in the next parameter.
direction=8
. It is force of the rigid material on the object (in force units).(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.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.
archiveTime
. This parameter is ignored unless the archiveTime
parameter is set as well.
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 )
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.
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
. 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.
Documentation for this custom task is now on-line only
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:
(1+(maxInc))*
Δt where Δt is the current time step.
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
The above parameters create a ramp. The next sections explain different ways to calculate the change in particle property applied during the ramp.
(delta)
is scaled by any user-defined function of time and particle position.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:
(deltaMin)+(deltaMax)*x
where x
is a value in the text file.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:
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
#1
and (delta)
is property change to apply to all particles under regions within the gray scale range specified by #1
and #2
.
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:
(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.(cod)
refers to magnitude of the COD. Alternatively, the minimum can apply to one component of the COD selected by entered integer
(dir)
)(time)
in alt time units.
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.
CustomTask
command is only allowed for MPM analyses.