PropertyRamp Custom Task

A custom task to apply temperature difference to all particles.

Introduction

In brief, this task allows you to apply certain particle properties slowly to reduce or eliminate dynamic effects that would be caused by more sudden changes. This tasks used to called ThermalRamp, because it was originally written only for ramping particle temperature, but now has been generalized to ramp or just set more properties (the old name is still accepted in input command files). The ramp can change all particles the same amount, change them according to a function of position, change them according to pixels in an image, or change them according to text values in a tab-delimited data file. Multiple ramps can be combined to ramp different properties or to ramp the same property at different times.

For example, consider the problem of finding residual thermal stresses in a composite material. One way solve this problem is set particle temperature at the start of the calculations to a temperature that differs from the stress free temperature. Different materials in the composite would develop different residual stress according to their therrmomechanical properties. But application of the entire temperature change on the first time step is analogous to impact loading and would like cause stress and strain oscillations making analysis of residual stresses difficult. To avoid these dynamic effects, it is better to use this custom task ramp up particle temperatures slowly enough to avoid all dynamic artifacts.

Task Scheduling and Ramp Settings

In scripted files, a PropertyRamp custom task is scheduled by starting with

CustomTask PropertyRamp
Parameter property,(rampProp)
Parameter time,(time)
Parameter start,(start)
Parameter sigmoidal,(style)
Parameter exponential,(lifetimes)
Parameter stretch,(stretch)

In XML files, this task is started using a <Schedule> element, which must be within the single <CustomTasks> block:

<Schedule name='PropertyRamp'>
   <Parameter name='property'>(rampProp)</Parameter>
   <Parameter name='time'>(time)</Parameter>
   <Parameter name='start'>(start)</Parameter>
   <Parameter name='sigmoidal'>(style)</Parameter>
</Schedule>

where the parameters are:

• (rampProp) - This parameter determines which particle property is ramped. The options are:
  0. Ramp temperature (default setting). A temperature ramp can be used without doing conduction calculations, such as to calculate residual thermal stress in composite materials.
  1. Ramp out-of-plane stress(zz) for plane stress analysis or strain(zz) for plane strain analysis. A task with this option is not allowed for unless running 2D plane stress or plane strain analyses. This option is used to implement Generalized Plane Stress and Strain.
  2. Ramp particle fluid concentration. For diffusion calculations, this option will ramp particle concentration potential. For poroelasticity calculations, this option will ramp particle pore pressure. A task with this option is not allowed unless the simulation is running either diffusion or poroelasticity calculations.
  3. Set relative initiation stress for damage mechanics materials. Note that strength is set at the end of the first time step (rather than ramped) and any entered ramp settings are ignored.
  4. Set relative toughness for damage mechanics materials. Note that toughness is set at the end of the first time step (rather than ramped) and any entered ramp settings are ignored.
  Options 3 and 4 are most commonly used with a BMP image of a Gaussian random field that models variations in strength or toughness.
• (time) - Enter the time interval for applying ramp the particle property (in alt time units). This parameter is optional; if omitted, enter ramp value is applied in one time step.
• (start) - Enter the start time for the ramp (in alt time units). This parameter is optional; if omitted, the ramp starts at time zero. The ramp ends at time (start)+(time).
• (style), (lifetimes), and (stretch) - Determines the type of ramp as explained in the following.

The plot on the right shows four types of ramps. If (lifetimes) is not set (or is set less than or equal to zero), the ramp is determined by (style) — (style)=0 gives a linear ramp, (style)>0 gives a sigmoidal ramp, and (style)<0 means a user-defined function provides the change rate (if no (style) is provided, the default is 0 or linear). The resulting ramps for (style)≥0 as fraction of the maximum value are:

      [math]\displaystyle{ f = \frac{t}{t_{ramp}} \quad({\rm linear}) \qquad f = \frac{1+\exp(-k/2)}{1-\exp(-k)}\frac{1-\exp(-kt/t_{ramp})}{1+\exp\left(-k\left(\frac{t}{t_{ramp}}-\frac{1}{2}\right)\right)} \quad({\rm sigmoidal}) }[/math]

where k defaults to 12 (but can be changed by providing (stretch)). A sigmoidal ramp may reduce dynamic effects at the start and end of the ramp.

If (lifetimes) is provided, the ramp changes to an exponential function (and the (style)=0 setting is ignored):

      [math]\displaystyle{ f = \frac{1 - \exp\left[\left(-\frac{t}{\tau}\right)^\beta\right]}{1-\exp\left(-({\rm lifetimes})^\beta\right)} \quad\mathrm{where} \quad \tau = \frac{t_{ramp}}{\rm \texttt{(lifetimes)}} }[/math]

and β is value entered for the (stretch) parameter (it is set to 1 if not entered). Note that (lifetimes) is number of exponential lifetimes within [math]\displaystyle{ t_{ramp} }[/math].

Note that in above equations, t is time since (start) (or actual t-(start)) and [math]\displaystyle{ t_{ramp} }[/math] is (time). All ramps go from zero for time (start) to one for time (start)+(time).

Calculate Property Change During the Ramp

The previous section defines the type of ramp. This next section explains different ways to calculate the change in particle property applied during the ramp.

Specified Property Change

To ramp all particles to the same property change or a position-dependent change, add the following two commands in scripted files:

Parameter Delta,(delta)
Parameter scale,(function)

or in XML files, add:

   <Parameter name='Delta'>(delta)</Parameter>
   <Parameter name='scale'>(function)</Parameter>

where

• (delta) - the final property change to apply to all particles (or the magnitude of the change after the ramp is done). The ramp will apply this change incrementally by the chosen ramp style during the duration of the ramp. Once the ramp is done, no more changes will be made.
• (function) - user-defined function of time (in alt time units) and particle position (in length units). When (scale)≥0, the increment in value on any particle will be the calculated increment times the value of (function). When (scale)<0, the function is required and gives property change rate per alt time units (see below for more details). Because this function is evaluated for every particle on every time step, complicated functions will slow down simulations during the ramp period.

The units for (delta) depend on property being ramped:

• Temperature - in degrees
• Stress(zz) - in pressure units
• Strain(zz) - in percent strain
• Concentration - in dimensionless concentration potential
• Pore Pressure - in pressure units
• Relative Initiation Stress - dimensionless
• Relative Toughness - dimensionless

Incremental Changes on Particles

When (style)≥0, the first step is to calculate the current ramp value [math]\displaystyle{ f(t) }[/math], that increases from 0 to 1 over the property ramp (time). Then, for the current time step, the increment in property, [math]\displaystyle{ \Delta P }[/math], is given by:

      [math]\displaystyle{ \Delta P = u(\vec x_p,t)(f(t+\Delta t)-f(t)){\tt (delta)} }[/math]

where [math]\displaystyle{ u(\vec x_p,t) }[/math] is the optional user-defined function of particle position and time (the function is not used when setting properties from image or text data). The Relative Initiation Stress and Toughness are not applied incrementally (which does not make sense). Instead, they are set to value:

      [math]\displaystyle{ R = u(\vec x_p,t)f(t){\tt (delta)} }[/math]

These relative values are typically applied in a single time step where [math]\displaystyle{ f(t)=1 }[/math] and [math]\displaystyle{ u(\vec x_p,t) }[/math] can define position-dependent relative values (the function is not used when setting properties from image or text data). By this approach, they are all set on the first time step.

When (style)<0, the required user-defined function directly sets the property change rate resulting in

      [math]\displaystyle{ \Delta P = u(\vec x_p,t)\Delta t }[/math]

Note that input (delta) is ignored. Because Relative Initiation Stress and Toughness are not applied incrementally, that are just set using the function or:

      [math]\displaystyle{ R = u(\vec x_p,t) }[/math]

Typically this is done on one time step and the function only depends on position to allow some position-dependent failure properties. More commonly, Relative Initiation Stress and Toughness are set with image or text data.

Property Change from Image 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. In scripted files, a PropertyRamp custom task for file input adds the following parameters

Parameter file,(bmpFileName)
Parameter width,(width)
Parameter height,(height)
Parameter xorigin,(xO)
Parameter yorigin,(yO)
Parameter zlevel,(zO)
Parameter flipped,(flipped)
Parameter DeltaMin,(deltaMin)
Parameter DeltaMax,(deltaMax)

In XML files, this task is scheduled using a <Schedule> element, which must be within the single <CustomTasks> block:

   <Parameter name='file'>(bmpFileName)</Parameter>
   <Parameter name='width'>(width)</Parameter>
   <Parameter name='height'>(height)</Parameter>
   <Parameter name='xorigin'>(xO)</Parameter>
   <Parameter name='yorigin'>(yO)</Parameter>
   <Parameter name='zlevel'>(zO)</Parameter>
   <Parameter name='flipped'>(flipped)</Parameter>
   <Parameter name='DeltaMin'>(deltaMin)</Parameter>
   <Parameter name='DeltaMax'>(deltaMax)</Parameter>

where

• (bmpFileName) is the full or relative path name to a BMP file. Most BMP formats are accepted and data are converted to 256 levels of gray (or intensity for RGB files).
• (width) and (height) specify the width and height for the image, but there are several ways to specify them.
• (xO), (yO), and (zO) give the (x,y,z) coordinate for the origin of the image when mapped to the grid or mesh in length units. The (zO) coordinate is only needed for 3D calculations and gives z value for each 2D slice of the x-y plane of the data.
• (flipped) is 0 (default) or 1; if it is 1, the origin will move to the upper-left corner of the image with y increasing in the downward direction and x increasing to the right. This change will flip the image in the y direction in the analysis compared to the image graphics.
• (deltaMin) and (deltaMax) map gray values 0 and 255 to a property change. All other gray values are linearly interpolated between these values.

In other words, the property change applied to particles replaces the (delta) parameter above with

      (delta) [math]\displaystyle{ = (deltaMin) + {\bigl((deltaMax)-(deltaMin)\bigr) g\over 255} }[/math]

where g is the average gray value over the domain of the particle. This change is applied incrementally by the chosen ramp style over the duration of the ramp.

Property Change from Text Data File

An alternative method for ramping up property change is to ramp to any distribution of particle values as represented in a tab-delimited or command-separated-values spread sheet of text data. In scripted files, a PropertyRamp custom task for text-file input adds the following parameters

Parameter file,(txtFileName)
Parameter width,(width)
Parameter height,(height)
Parameter xorigin,(xO)
Parameter yorigin,(yO)
Parameter zlevel,(zO)
Parameter DeltaMin,(deltaMin)
Parameter DeltaMax,(deltaMax)

In XML files, this task is scheduled using a <Schedule> element, which must be within the single <CustomTasks> block:

   <Parameter name='file'>(txtFileName)</Parameter>
   <Parameter name='width'>(width)</Parameter>
   <Parameter name='height'>(height)</Parameter>
   <Parameter name='xorigin'>(xO)</Parameter>
   <Parameter name='yorigin'>(yO)</Parameter>
   <Parameter name='zlevel'>(zO)</Parameter>
   <Parameter name='DeltaMin'>(deltaMin)</Parameter>
   <Parameter name='DeltaMax'>(deltaMax)</Parameter>

where

• (txtFileName) is the full or relative path name to a tab-delimited or comma-separated-values plain-text file.
• (deltaMin) and (deltaMax) map numerical values in the table to (delta)=(deltaMin)+(deltaMax)*x where x if data value in the table. This change is applied incrementally by the chosen ramp style over the duration of the ramp.

All other properties are the same as described for input using image data except that reference to pixels in BMP files means data cells in text files.

Property Change from Level Sets

Alternatively, the particle property can be determined from ranges of gray scale intensity (from BMP or a text file) 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. In scripted files, the new commands are:

Parameter "map #1 #2",(delta)
Parameter "map #1 #2",(delta)

or in XML files, they are:

   <Parameter name='map #1 #2'>(delta)</Parameter>
   <Parameter name='map #1 #2'>(delta)</Parameter>

where

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

Unlike the previous section, this method selects (delta) by the most prominent matched range under the particle domain and not by the average gray value. This method is actually identical to method used to assign material types in a BMPRegion Command. Because the methods are the same, one could use the same image to assign material types and then use this type of property ramp to pick different property values for each material type.

Multiple Property Ramps

A single calculation may use multiple property ramps and the resulting property setting will be sum of all ramp values. This feature can be used to increase and then decrease a property or even to have overlapping ramps. Because relative initiation stress and relative toughness are set, instead of ramped, multiple ramps for those properties do not make sense (if used, the values will be set to the last defined task values).