View source for MPM Archiving Options

These commands determine the way results of the calculations are archived for later analysis.

== Archiving Particle Data ==

In MPM calculations, the calculation results are stored in a series of archive files. These files give periodic snapshots for the state of each material point. These files are read after the analysis to plot the results; in fact the results cannot be visualized without them. For more details, you can refer to the [[Archive File Formats|output file format definition]].

=== Scripted Input Files ===

In scripted input files, the archiving options have two forms:

 Archive (path)
 ArchiveTime (time),<(first time)>
 ToArchive (list on quantities)

or

 ArchiveUnique (path)
 ArchiveTime (time),<(first time)>
 ToArchive (list on quantities)

where

<ul>
<li><span id="path_name"></span><tt>(path)</tt> gives a relative path name from the saved output file to the archived files. The path name should be entered in Unix style or

<pre>folder/folder/folder/root</pre>

where there can be any number of folders followed by the root archive file name. The saved files will be in that location and have names

<pre>root.num</pre>

where <tt>num</tt> is the step number being archived. The folder names and root name cannot contain any colons (":"), to avoid conflict with MacOS path names) or spaces (to be consistent with most Unix systems).<br>
&nbsp;&nbsp;&nbsp;If a series MPM calculations are saved to the same folder without changing the archive path name, the later calculations will most likely overwrite the earlier calculations causing you to lose results. The solution is to use the second form above that replaces the <tt>Archive</tt> command with an <tt>ArchiveUnique</tt> command. The <tt>ArchiveUnique</tt> command forces creation of a new folder within the last folder of the path. In the above path example, the <tt>ArchiveUnique</tt> option will write to the files:

<pre>folder/folder/folder/#/root.num</pre>

where # is chosen from 1, 2, 3, ...  to create a unique folder. You can then safely write multiple MPM output files to the save folder without conflicts

<li><span id="atime"></span><tt>(time)</tt> gives the time interval between archiving results in milliseconds (it can be an [[Entity Command|entity]]). The analysis will always archive the initial state (to define the problem). You only need to archive enough results to get good plots or movies after the analysis is done.</li>

<li><span id="ftime"></span><tt>(first time)</tt> is an optional time to start archiving in milliseconds (it can be an [[Entity Command|entity]]). If this time is greater than zero, the analysis will archive the initial state (to define the problem) and not archive anymore more results until this time is reached. After this time, archiving will proceed at the time interval specified in <tt>(time)</tt>.

<li><tt>(list on quantities)</tt> is a comma-separted list of quantities to be archived (see [[#ToArchive Command|<tt>ToArchive</tt> command]] for the details.

</ul>

==== ToArchive Command ====

The <tt>ToArchive</tt> command determines which calculation results to include in archived results by providing a comma-separated list of the following options (which can be in one or more ToArchive commands and are case sensitive):

<ul>
<li><tt>velocity</tt> - particle velocities</li>
<li><tt>stress</tt> - particle stress</li>
<li><tt>strain</tt> - particle strain, which is elastic strain for some plasticity [[Material Models|materials]], but total strain for some others</li>
<li><tt>plasticstrain</tt> - particle plastic strain for some plasticity [[Material Models|materials]]</li>
<li><tt>strainenergy</tt> - particle strain energy, which is cumulative &sigma;.d(&epsilon;-&epsilon;<sub>res</sub>)</li>
<li><tt>workenergy</tt> - particle work energy, which is cumulative &sigma;.d&epsilon;</li>
<li><tt>heatenergy</tt> - particle heat energy; the value will only be physically correct if all [[Material Models|materials]] specify their heat capacity</li>
<li><tt>plasticenergy</tt> - cumulative dissipated energy</li>
<li><tt>temperature</tt> - particle temperature</li>
<li><tt>concentration</tt> - particle concentration and concentration gradients</li>
<li><tt>shearcomponents</tt> - separate components of total shear strain (namely u/y and v/x; these sum to total shear strain)</li>
<li><tt>jintegral</tt> - crack tip J1 and J2 integrals</li>
<li><tt>stressintensity</tt> - crack tip KI and KII</li>
<li><tt>energybalance</tt> - energy balance results during crack growth by energy balance.</li>
<li><tt>history#</tt> - where '#' is 1 to 4 to archive that history variable for a  [[Material Models|material]]. This history variable is only relevant for certain types of materials. To archive history data beyond #4 or to archive to a different format, you can use the [[HistoryData CustomTask]].</li>
<li><tt>elementcrossings</tt> - number of times the particle has crossed an element boundary since the last archive time.</li>
<li><tt>rotstrain</tt> - rotational strain. Archiving this strain is needed to plot transformed material points.</li>
</ul>

Certain particle results are always archived and thus there is no need to specify them in a <code>ToArchive</code> command. The standard archived data are:

<ul>
<li><tt>mass</tt> - particle mass</li>
<li><tt>material ID</tt> - material ID number for particle</li>
<li><tt>material angle</tt> - material axis angle for anisotropic materials</li>
<li><tt>thickness</tt> - thickness for 2D calculations</li>
<li><tt>position</tt> - current particle position</li>
<li><tt>original position</tt> - initial position for displacement calculations</li>
<li><tt>crack position</tt> - crack particle positions</li>
<li><tt>crack original position</tt> - initial crack particle positions</li>
<li><tt>crack surface positions</tt> - location of crack surfaces</li>
</ul>

Finally, note that if no <tt>ToArchive</tt> command is used in an input file, the default archived quantities will be equivalent to the commands:

 ToArchive velocity,stress,strain,plasticstrain
 ToArchive plasticenergy,workenergy,temperature

But if one or more <tt>ToArchive</tt> commands are used, you have to specify all quantities you want (''i.e.'', the default ones are not automatically included).

=== XML Input Files ===

In XML input files, the archiving commands, which must be within the [[MPM Input Files#MPM Header|<tt><MPMHeader></tt> element]], are:

 <ArchiveRoot unique='0'>(path)</ArchiveRoot>
 <ArchiveTime>(time)</ArchiveTime>
 <FirstArchiveTime>(first time)</FirstArchiveTime>
 <MPMArchiveOrder>iYYYYNYYYNYYNNNNNY</MPMArchiveOrder>
 <CrackArchiveOrder>iYYYN</CrackArchiveOrder>

where

* <tt>(path)</tt> is the archive path as explain [[#path_name|above]].
* <tt>(time)</tt> is the [[#atime|time interval between archiving]]. A [[Units Attribute|units attribute]] determines the time units.
* <tt>(time)</tt> is the [[#ftime|first time results are archived]]. A [[Units Attribute|units attribute]] determines the time units.

The calculations results included in the archive files are determined by a series of 'Y' and 'N' (or other) flags in the strings in the <tt>MPMArchiveOrder</tt> and <tt>CrackArchiveOrder</tt> commands.

==== <MPMArchiveOrder> ====
  <ul>
  <li>Byte 1: byte order of archived files ('m' for old Macintosh order or 'i' for Intel chip order). This parameter is ignored on input but must be supplied for alignment.</li>
  <li>Byte 2: default particle properties (particle mass, position, material information, and thickness). This byte must always by 'Y'.</li>
  <li>Byte 3: particle velocity</li>
  <li>Byte 4: particle stress</li>
  <li>Byte 5: particle strain (which is elastic strain for plasticity materials)</li>
  <li>Byte 6: particle plastic strain</li>
  <li>Byte 7: should always be 'N'. Present to support reading old versions of archive files.</li>
  <li>Byte 8: particle work energy, which is cumulative &sigma;.d&epsilon;</li>
  <li>Byte 9: particle temperature</li>
  <li>Byte 10: particle plastic energy</li>
  <li>Byte 11: should always be 'N'. Present to support reading old versions of archive files.</li>
  <li>Byte 12: particle total shear strain components (du/dy and dv/dx)</li>
  <li>Byte 13: particle strain energy, which is cumulative &sigma;.d(&epsilon;-&epsilon;<sub>res</sub>)</li>
  <li>Byte 14: setting 'Y' or 'N' refers to particle history variable 1, but up to four history variables can be archived by using the following characters in this byte:
<pre class="near">
'1' or 'Y' - history 1
'2' - history 2
'3' - history 1 and 2
'4' - history 3
'5' - history 1 and 3
'6' - history 2 and 3
'7' - history 1, 2, and 3
'8' - history 4
'9' - history 1 and 4
':' - history 2 and 4
';' - history 1, 2, and 4
'&lt;' - history 3 and 4
'=' - history 1, 3, and 4
'&gt;' - history 2, 3, and 4
'?' - history 1, 2, 3, and 4
</pre>
History variables are only meaningful for some [[Material Models|material types]]. To archive history data beyond #4 or to archive to a different format, you can use the [[HistoryData CustomTask]].</li>
  <li>Byte 15: particle concentration and concentration gradients - only meaningful when doing diffusion calculations.</li>
  <li>Byte 16: particle heat energy; the value will only be physically correct if all [[Material Models|materials]] specify their heat capacity</li>
  <li>Byte 17: number of times this particle crossed an element boundary since the last archive time.</li>
  <li>Byte 18: rotational strain; this strain must be archived for visualization tools to be able to plot &quot;transformed&quot; points (<i>i.e.</i>, the stretch and shear plotted points to match the material point deformation state).</li>
  </ul>
  
'''Default value''': <tt>iYNN...</tt>  - <i>i.e.</i> one Y and the rest N

==== <CrackArchiveOrder> ====
  <ul>
  <li>Byte 1: Byte order of archived files ('m' for Macintosh order or 'i' for Intel chip order). This parameter is ignored on input but must be supplied for alignment.</li>
  <li>Byte 2: Default crack particle properties (location, surface positions). This byte must always by 'Y'.</li>
  <li>Byte 3: J Integral at designated crack tips.</li>
  <li>Byte 4: Stress intensity factors at designated crack tips.</li>
  <li>Byte 5: Dynamic energy balancing results (in research, not meant for general use).</li>
  </ul>
  
'''Default value''': <tt>iYNNNN</tt>.

== Archiving Mesh Data in VTK Files ==

As an alternative to particle data, you can archive grid results using the [[VTKArchive Custom Task]], which write "VTK Legacy" files that can be viewed in other applications. This option is most useful for new visualization options for 3D simulations.

== Notes ==

# There are no options for archiving kinetic energy because it is easily calculated in visualization software from mass and velocity. Thus, to do kinetic energy calculations, you must archive particle velocity.
# Total energy is sum of strain energy and kinetic energy. To visualize total energy results, you must archive strain energy and velocity (for kinetic energy)