# 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, 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… | –