TrackError Custom Task
A custom task to archive simulations results compared to theoretical predictions
Introduction
This tasks can compare particle values to a theoretical model and archive some metric for accuracy of the simulation. It is useful for tracking convergence of MPM simulations.
Simulation Error Metrics
Imagine a generic distance from particle value to a theoretical expectation for that value equal to [math]\displaystyle{ |x_p| }[/math]. For example, the distance could be scalar difference between particle stress in the x direction and expected stress:
[math]\displaystyle{ |x_p| = |\sigma_{p,xx} - \sigma_{xx}({\rm theory})| }[/math]
If the particle value is a vector, the distance would be a vector distance between value and expection. For example, a velocity distance would be:
[math]\displaystyle{ |x_p| = \sqrt{\bigl(\vec V_p-\vec V({\rm theory})\bigr)\cdot\bigl(\vec V_p-\vec V({\rm theory})\bigr)} }[/math]
The P-norm for a given distance definition and for [math]\displaystyle{ N_p }[/math] particles is defined as:
[math]\displaystyle{ ||x||_P = \left( \sum_{p=1}^{N_p} |x_p|^P\right)^{1/P} }[/math]
The same distance can also define a root-mean-squared distance defined as:
[math]\displaystyle{ {\rm RMS} = \sqrt{{1\over N_p} \sum_{p=1}^{N_p} |x_p|^2} }[/math]
This task can archive mean P-norm values and RMS distances for any entered function for [math]\displaystyle{ |x_p| }[/math]. The archived values can be for each time step or cumulatively averaged over all time step calculations.
Task Scheduling
In scripted files, a TrackError custom task is scheduled using
CustomTask TrackError Parameter archiveTime,(timeInterval) Parameter firstArchiveTime,(firstTime) Parameter cumulative,(cumulative) Parameter P,(Pvalue) Parameter function,(xpexpr) . . .
In XML files, this task is scheduled using a Schedule element, which must be within the single <CustomTasks> block:
<Schedule name='TrackError'>
<Parameter name='archiveTime'>(timeInterval)</Parameter>
<Parameter name='firstArchiveTime'>(firstTime)</Parameter>
<Parameter name='cumulative'>(cumulative)</Parameter>
<Parameter name='P'>(Pvalue)</Parameter>
<Parameter name='function'>(xpexpr)</Parameter>
. . .
</Schedule>
where the first two parameters, both of which are optional, are
- (timeInterval) - Enter the time interval (in alt time units) between calculations of error metrics. If this parameter is omitted, the calculations are done on the same steps as the particle archives.
- (firstTime) - Enter the time to start error metric calculations (in alt time units). After this time is reached, subsequent calculations will be spaced by the entered (timeInterval). This parameter is ignored unless the (timeInterval) parameter is set as well.
Next, you enter up to 10 (xpexpr)[math]\displaystyle{ =|x_p| }[/math] expressions for evaluating a "distance." The expressions are written in the style of user-defined functions, but can contain different variables:
- t for simulation time (in alt time units)
- x, y, and z for particle position (in length units)
- xo, yo, and zo for original particle position (in length units)
- vx, vy, and vz for particle velocity (in velocity units)
- sxx, syy, szz, sxy, sxz, and syz for particle stress (in pressure units)
To determine the type of error metric that is calculated, enter (cumulative) and (Pvalue) options before entering the (xpexpr) expressions. Once these parameters are set, they apply to all subsequent (xpexpr) expressions unless changed to new values with new Parameter commands. Their functions are
- (cumulative) - set to 0 or 1. If 0, the error metric is found for each time step. If 1, the error metric is averaged over all time steps with calculations. The default is 0 (if never entered).
- (Pvalue) - determines the error metric that is calculated. The default is 2 (if never entered).
Equations for the calculated error metrics for each combination of (cumulative) and (Pvalue) are in the following table (and [math]\displaystyle{ N_s }[/math] is the number of calculation time steps).
| (Pvalue) | (cumulative)=0 | (cumulative)=1 |
|---|---|---|
| 0 (RMS error) | [math]\displaystyle{ \sqrt{{1\over N_p} \sum_{p=1}^{N_p} ({\rm xpexpr})^2} }[/math] | [math]\displaystyle{ {1\over N_s}\sum_{i=1}^{N_s} \sqrt{{1\over N_p} \sum_{p=1}^{N_p} ({\rm xpexpr})^2} }[/math] |
| P>0 (mean P-norm) | [math]\displaystyle{ {1\over N_p}\left( \sum_{p=1}^{N_p} ({\rm xpexpr})^P\right)^{1/P} }[/math] | [math]\displaystyle{ {1\over N_s}\sum_{s=1}^{N_s}\left({1\over N_p} \sum_{p=1}^{N_p} ({\rm xpexpr})^P\right)^{1/P} }[/math] |
TrackError Output
The TrackError calculations will be written to a tab-delimited text file with name
(path)_Error(num).txt
where (path) is the path name used to archive results and (num) is the TrackError task number. A single TrackError task can track up to 10 error functions. An MPM simulation can use any number of TrackError tasks if it needs more than 10 error function or if you prefer the error metrics to be in separate files.
Note that calculations in files written by a TrackError task can be plotted in NairnFEAMPM or NairnFEAMPMViz by using the "Import..." options for any 2D plots.
Notes
- Note the (Pvalue)=1 is ordinary mean value of the (xpexpr) expression. This setting can be used to extend global archiving options to include arbitrary functions of particle properties or the average of that property over all time steps (by using (cumulative)=1.