7.10. User Functions

This section is referenced in the following other sections

Simulation Setup: User Functions

7.10.1. Definition For Function

Scope: Sierra
Summary: Defines a function in terms of its type and values.

begin Definition For Function FunctionName

   Abscissa {=} Name...

   Abscissa Offset {=} Abscissa_offset

   Abscissa Scale {=} Abscissa_scale

   At Discontinuity Evaluate To {left | right}

   Column Titles Titles1 Titles2...

   Data File = filename [ X From Column xcol Y From Column ycol  ]

   Debug {=} {off | on}

   Differentiate Expression {=} Expr

   Evaluate Expression {=} Expr

   Evaluate From x0 To x1 By Dx

   Expression Variable: Expr = {element | element_sym_tensor | element_tensor | element_vector | face | global | nodal | nodal_sym_tensor | nodal_tensor | nodal_vector} source_var_name... [ State {new | none | old}  ]

   Expression Variable: Expr

   Field Types Titles1 Titles2...

   Ordinate {=} Name...

   Ordinate Offset {=} Ordinate_offset

   Ordinate Scale {=} Ordinate_scale

   Scale By x

   Type {=} {analytic | constant | multicolumn piecewise linear | piecewise analytic | piecewise constant | piecewise linear | piecewise multivariate | xtable}

   X Offset {=} X_offset

   X Scale {=} X_scale

   Y Offset {=} Y_offset

   Y Scale {=} Y_scale

   begin Expressions empty
   end

   begin Values empty
   end

end Definition For Function FunctionName

7.10.1.1. Line Commands

Abscissa

Syntax: Abscissa {=} Name…
Summary: Specifies a string identifier for the independent variable. Optionally specify a scale and/or offset value which transforms the abscissa values into scaled_abscissa = scale * ( abscissa + abscissa_offset).

Parameter	Value	Default
{=}	{= \| are \| is}	–
Name	string…	–

Abscissa Offset

Syntax: Abscissa Offset {=} Abscissa_offset
Summary: Alias for X OFFSET

Parameter	Value	Default
{=}	{= \| are \| is}	–
Abscissa_offset	real	–

Abscissa Scale

Syntax: Abscissa Scale {=} Abscissa_scale
Summary: Alias for X SCALE

Parameter	Value	Default
{=}	{= \| are \| is}	–
Abscissa_scale	real	–

At Discontinuity Evaluate To

Syntax: At Discontinuity Evaluate To {left | right}
Summary: Control the behavior of a piecewise constant function when evaluated at a discontinuity (plus or minus a small tolerance). The default behavior is to take the value to the right of the discontinuity. If “Left” is specified, the value to the left of the discontinuity is taken instead.

Parameter	Value	Default
Option	{left \| right}	–

Column Titles

Syntax: Column Titles Titles1 Titles2…
Summary: Name the columns (and also defined the expected number of columns) for Multicolumn Piecewise Linear tabular data.

Parameter	Value	Default
Titles	string1 string2…	–

Data File

Syntax

Data File = filename [ X From Column xcol Y From Column ycol ]

Summary

Function will read tabular data from an input file. Compatible with the piecewise linear function type. File must be of form like:

---------------------------------------------
\# EXAMPLE FILE
1.099   1191
1.101   221
5.9011  133.1
---------------------------------------------

Lines headed by a # are considered comments and will be ignored. Data itself must by in tabular columns separated by whitespace or commas.

Parameter	Value	Default
filename	string	–

Debug

Syntax: Debug {=} {off | on}
Summary: Prints functions to the log file.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Option	{off \| on}	–

Differentiate Expression

Syntax: Differentiate Expression {=} Expr
Summary: Specifies the expression of derivative of evaluation expression.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Expr	(expression)	–

Evaluate Expression

Syntax

Evaluate Expression {=} Expr

Summary

Specifies the expression to evaluate.

Description

This will greatly help with manufactured solutions, and be useful for other purposes as well. This uses the STK expression evaluator to evaluate the provided string. See the STK user manual for details about valid syntax.

begin definition for function pressure
  type is analytic
  evaluate expression is "x <= 0.0 ? 0.0 : (x < 0.5 ? x*200.0
     : (x < 1.0 ? (x - 0.5) *50.0 + 100.00 : 150.0))"
end definition for function pressure

Parameter	Value	Default
{=}	{= \| are \| is}	–
Expr	(expression)	–

Evaluate From

Syntax: Evaluate From x0 To x1 By Dx
Summary: Specifies the range and evaluation interval.

Parameter	Value	Default
x0	real	–
x1	real	–
Dx	real	–

Expression Variable:

Syntax

Expression Variable: Expr = {element | element_sym_tensor | element_tensor | element_vector | face | global | nodal | nodal_sym_tensor | nodal_tensor | nodal_vector} source_var_name… [ State {new | none | old} ]

Summary

Specifies what the arguments of an expression correspond to. For example:

BEGIN DEFINITION FOR FUNCTION dx_shear
  TYPE = ANALYTIC
  EXPRESSION variable: mx   = NODAL model_coordinates(x)
  EXPRESSION variable: my   = NODAL model_coordinates(y)
  EXPRESSION variable: time = GLOBAL time
  EVALUATE EXPRESSION = "(time/{termTime})*({stretchx}*(mx - 0.0) + ((my-0.25)/0.5)*{stretchxy})"
END

Assuming the above expression is being evaluated on nodes the current values for x and y model coordinates would be placed into mx and my and current analysis time placed into time

Parameter	Value	Default
Expr	string	–
VarType	{element \| element_sym_tensor \| element_tensor \| element_vector \| face \| global \| nodal \| nodal_sym_tensor \| nodal_tensor \| nodal_vector}	–
source_var_name	string…	–

Expression Variable:

Syntax

Expression Variable: Expr

Summary

Specifies what the arguments of an expression exists, but does not define it correspond to. For example:

BEGIN DEFINITION FOR FUNCTION dx_shear
  TYPE = ANALYTIC
  EXPRESSION variable: mx
  EXPRESSION variable: my
  EXPRESSION variable: time
  EVALUATE EXPRESSION = "(time/{termTime})*({stretchx}*(mx - 0.0) + ((my-0.25)/0.5)*{stretchxy})"
END

Call function must determine what each variable actually is is based off of the string name

Parameter	Value	Default
Expr	string	–

Field Types

Syntax: Field Types Titles1 Titles2…
Summary: The field types (GLOBAL/NODE/ELEMENT) that correspond to the column titles listed for the multicolumn data.

Parameter	Value	Default
Titles	string1 string2…	–

Ordinate

Syntax: Ordinate {=} Name…
Summary: Specifies a string identifier for the dependent variable. Optionally specify a scale and/or offset value which transforms the ordinate values into scaled_ordinate = scale * ( ordinate + ordinate_offset).

Parameter	Value	Default
{=}	{= \| are \| is}	–
Name	string…	–

Ordinate Offset

Syntax: Ordinate Offset {=} Ordinate_offset
Summary: Alias for Y OFFSET

Parameter	Value	Default
{=}	{= \| are \| is}	–
Ordinate_offset	real	–

Ordinate Scale

Syntax: Ordinate Scale {=} Ordinate_scale
Summary: Alias for Y SCALE

Parameter	Value	Default
{=}	{= \| are \| is}	–
Ordinate_scale	real	–

Scale By

Syntax: Scale By x
Summary: Specifies a scale factor to be applied.

Parameter	Value	Default
x	real	–

Type

Syntax: Type {=} {analytic | constant | multicolumn piecewise linear | piecewise analytic | piecewise constant | piecewise linear | piecewise multivariate | xtable}
Summary: Specifies the type of function.

Parameter	Value	Default
{=}	{= \| are \| is}	–
Type	{analytic \| constant \| multicolumn piecewise linear \| piecewise analytic \| piecewise constant \| piecewise linear \| piecewise multivariate \| xtable}	–

X Offset

Syntax: X Offset {=} X_offset
Summary: Sets an offset for the x-axis

Parameter	Value	Default
{=}	{= \| are \| is}	–
X_offset	real	–

X Scale

Syntax: X Scale {=} X_scale
Summary: Sets a scale factor for the x-axis

Parameter	Value	Default
{=}	{= \| are \| is}	–
X_scale	real	–

Y Offset

Syntax: Y Offset {=} Y_offset
Summary: Sets an offset for the y-axis

Parameter	Value	Default
{=}	{= \| are \| is}	–
Y_offset	real	–

Y Scale

Syntax: Y Scale {=} Y_scale
Summary: Sets a scale factor for the y-axis

Parameter	Value	Default
{=}	{= \| are \| is}	–
Y_scale	real	–

7.10.2. Values

Scope: Definition For Function
Summary: Lists the values of the function. The values should be listed one pair per line, independent variable first, with whitespace or comma as a separator.

begin Values empty

    Xyvalues...

end Values empty

7.10.2.1. Line Commands

Xyvalues

Syntax: Xyvalues Xyvalues…
Summary: For a piecewise linear function, lists an x-y pair for the nth interpolation point.

Parameter	Value	Default
Xyvalues	real…	–