PropertyRamp Custom Task

Jump to navigation Jump to search

A custom task to apply temperature difference to all particles.


Various particle properties can induce residual stresses. For example, one way to model residual thermal is set particle temperature at the start of the calculations to a temperature that differs from the stress free temperature. Such an instantaneous temperature change is analogous to impact loading and may cause stress and strain oscillations. To avoid these dynamic effects, it is better to ramp up some particle temperature gradually by using this custom task.

This task allows you to apply certain particle properties slower to to reduce or eliminate dynamic effects that would be caused by more sudden changes. The tasks used to called ThermalRamp, because it was originally written only for ramping particle temperature, but now has been generalize to ramp 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, or change them according to pixels in an image. Multiple ramps can be combined to ramp different properties or to ramp the same property at different times.

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>

where the parameters are:

  • (rampProp) - This parameter determines which particle property is ramped. The options are:
    1. Ramp temperature (default setting). A temperature ramp can be used without doing conduction calculations, such as to calculate residual thermal stress in composite materials.
    2. 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.
    3. Ramp particle fluid concentration. For diffusion calculations, this option will ramp particle concentration potential (between 0 and 1). 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.
    4. 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.
    5. 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.

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 will be linear or sigmoidal for (style) equal to 0 or 1, respectively (if no (style) is provided, the default is 0 or linear). The resulting ramps 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 will use an exponential function

      [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]. Also note that t is time minus (start) and [math]\displaystyle{ t_{ramp} }[/math] is (time). All ramps go from zero at 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>


  • (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 in either a linear or a sigmoidal rate (depending on the style parameter setting) during the duration of the ramp. Once the ramp is done, no more changes will be made.
  • (function) - when this optional parameter is used, the applied (delta) ramp is scaled by any user-defined function of time and particle position. The final change on any particle will be (delta) times the value of (function) evaluated at the particle location.

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 (and all changes will be constrain particle value to the range 0 to 1)
  • Pore Pressure - in pressure units
  • Relative Initiation Stress - dimensionless
  • Relative Toughness - dimensionless

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>


  • (bmpFile) 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 (linearly or sigmoidally) over the duration of the ramp.

Property Change from Image Blocks

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


  • #1 and #2 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").
  • (delta) is temperature 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 property ramps and this method would let you 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).