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 is defined as:

      [math]\displaystyle{ ||x||_P = \left( \sum_{p=1}^{N_p} |x_p|^P\right)^{1/P} }[/math]

where [math]\displaystyle{ N_p }[/math] is the number of particles. The root-mean-squared distance is 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 archive 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 tasks 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 error metrics. 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, 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 averaged over all time steps with calculations.
• (Pvalue) - determines the error metric that is calculated. If (Pvalue)=P>0 and (cumulative)=0, the error metric calculated is:
        [math]\displaystyle{ ({\rm metric}) = {1\over N_p}\left( \sum_{p=1}^{N_p} ({\rm xpexpr})^P\right)^{1/P} }[/math]
  If (cumulative)=1, the error metric is averaged over calculation time steps using:
        [math]\displaystyle{ ({\rm metric}) = {1\over N_sN_p}\left( \sum_{s=1}^{N_s}\sum_{p=1}^{N_p} ({\rm xpexpr})^P\right)^{1/P} }[/math]
  where [math]\displaystyle{ N_s }[/math] is the number of time steps with error calculations. If (Pvalue)=0 and (cumulative)=0, the error metric is an RMS calculation:
        [math]\displaystyle{ {\rm RMS} = \sqrt{{1\over N_p} \sum_{p=1}^{N_p} ({\rm xpexpr})^2} }[/math]
  If (cumulative)=1, the RMS error is averaged over calculation time steps using:
        [math]\displaystyle{ \left\langle{\rm RMS}\right\rangle = {1\over N_s}\sum_{i=1}^{N_s} \sqrt{{1\over N_p} \sum_{p=1}^{N_p} ({\rm xpexpr})^2} }[/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.

Notes

1. 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.