User Defined Functions

Some commands let you set properties using a function that is evaluated at run time.

Function Variables

When a function option is allowed in any command, you can enter any valid function of the following variables. Note that commands that allow functions may only allow a subset of these variables (due to command context). You can refer to each command for the allowed variables. When a function is used, it will be calculated using these variables and should return a results in the units expected by the command.These variables specify position and may refer for particle (in MPM), element centroid (in FEA), or node (in FEA) positions:

• x - x position in length units
• y - y position in length units
• z - z position in length units
• R - radial position in length units for axisymmetric calculation; R is a synonym for x, which also works
• Z - axial position in length units for axisymmetric calculation; Z is a synonym for y, which also works
• D - distance from origin (i.e., r in polar coordinates).
• T - counter-clockwise angle (in radians) from the positive x axis (i.e., θ in polar coordinates)

If a polar function is more appropriate for 2D analyses, the function can depend on D and T, where D is distance from the origin to the (x,y) (or (R,Z) if axisymmetric) point (in length units) and T is counter-clockwise angle (in radians) from the positive x (or R if axisymmetric) axis to the point.

The following variables are only allowed in MPM calculations:

• t - current time in alt time units
• dt - the time step in alt time units
• q - particle rotation in radians about the z (or θ if axisymmetric) axis

For example, some MPM options (as detailed in their documentation) require the function to depend only on time. Particle based MPM boundary conditions let the function depend on clockwise particle rotational angle q about the z axis (in radians), which allows rotation of the bondary conditions with the particle. Note that q is particle rotation since the start of the simulation and will differ from material angle if the particle started with a non-zero orientation angle (i.e., the current material angle is the sum of q and its initial angle).

Function Format

Some details on entering functions are:

• In scripted files, the function must be enclosed in quotes (e.g., "x^2+y^2") to prevent it from being evaluated as a command expression prior to being used in the analysis.
• Enter variables simply as x, y, etc., and not with the preceding "#" used for command expression variables.
• Operators: The function uses standard operators + - * / and ^ with standard operator precedence for addition, subtraction, multiplication, division, and raising to a power.
• The function can contain the following defined functions:
  • sin(x), cos(x), and tan(x) - trigonometric function of angle in radians.
  • asin(x), acos(x), and atan(x) - inverse trigonometric function with result in radians.
  • sqrt(x) - square root.
  • log(x) and ln(x) - log base 10 and natural log, respectively (note these are different than log functions used in command expressions in scripted files due to different math expression parser in the code engines).
  • exp(x) - exponential of x.
  • abs(x) - absolute value of x.
  • int(x) - integer part of x as next lower integer. For negative numbers, it is next lower integer or int(-3.4)=-4.
  • Sinh(x), Cosh(x), and Tanh(x) - hyperbolic trigonometric functions. (note the initial uppercase is needed here, and differs from scripted command expressions due to different math expression parser in the code engines).
• The following functions are helpful if creating boundary conditions:
  • [math]\displaystyle{ {\rm ramp}(A,x) = \left\{\begin{array}{ll} 0 & x\le 0 \\ Ax & 0\lt x\lt 1 \\ A & x \ge 1 \end{array}\right. }[/math]
  • [math]\displaystyle{ {\rm cosramp}(A,x) = \left\{\begin{array}{ll} 0 & x\le 0 \\ {A\over 2}\left(1-\cos(\pi x)\right) & 0\lt x\lt 1 \\ A & x \ge 1 \end{array}\right. }[/math]
  • [math]\displaystyle{ {\rm box}(A,x) = \left\{\begin{array}{ll} 0 & x\le 0 \\ A & 0\lt x\lt 1 \\ 0 & x \ge 1 \end{array}\right. }[/math]
  • [math]\displaystyle{ {\rm sinbox}(A,x) = \left\{\begin{array}{ll} 0 & x\le 0 \\ A\sin(\pi x) & 0\lt x\lt 1 \\ 0 & x \ge 1 \end{array}\right. }[/math]
  • [math]\displaystyle{ {\rm sgn}(x) = \left\{\begin{array}{ll} -1 & x \lt 0 \\ 0 & x = 0 \\ +1 & x \gt 0 \end{array}\right. }[/math]
  • [math]\displaystyle{ {\rm sign}(x) = \left\{\begin{array}{ll} 0 & x \lt 0 \\ 1 & x \ge0 \end{array}\right. }[/math]

  For example, to apply a ramp from 0 to t_f, use x = t/t_f; to apply a ramp from t_s to t_f,use x = (t-t_s)/(t_f-t_s). The new functions are only available in versions after about September 1, 2018.

• Functions can include pi (or Pi or PI) for the number π.
• Exponential Notation: numbers can have "e" or "E" for powers of ten such as 1.4e3 for 1400.
• Extra spaces in the function are ignored.