# 7.3. Initial Variable Assignment

    BEGIN INITIAL CONDITION
      #
      # mesh-entity set commands
      NODE SET|NODESET = <string list>nodelist_names
      SURFACE = <string list>surface_names
      BLOCK = <string list>block_names
      ASSEMBLY = <string list>assembly_names
      INCLUDE ALL BLOCKS
      REMOVE NODE SET = <string list>nodelist_names
      REMOVE SURFACE = <string list>surface_names
      REMOVE BLOCK = <string list>block_names
      #
      # variable identification commands
      INITIALIZE VARIABLE NAME = <string>var_name
      VARIABLE TYPE = NODE|EDGE|FACE|ELEMENT|GLOBAL
      #
      # specification command
      MAGNITUDE = <real list>initial_values
      #
      # Weibull probability distribution commands
      WEIBULL SHAPE = <real>shapeVal
      WEIBULL SCALE = <real>scaleVal
      WEIBULL MEDIAN = <real>medianVal
      WEIBULL SEED = <int>seedVal(123456)
      WEIBULL SCALING FIELD TYPE = NODE|EDGE|FACE|ELEMENT|
        GLOBAL(ELEMENT)
      WEIBULL SCALING FIELD NAME = <string>fieldVal(VOLUME)
      WEIBULL SCALING REFERENCE VALUE = <real>value
      WEIBULL SCALING EXPONENT SCALE = <real>scaleVal(1.0)
      #
      # external database commands
      READ VARIABLE = <string>var_name
      COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
        MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
      COPY NEAREST ELEMENT|FACE|NODE <string>varName
        FROM MODEL <string>model_name
      TIME = <real>time|FIRST|LAST
      #
      # user subroutine commands
      NODE SET SUBROUTINE = <string>subroutine_name |
        SURFACE SUBROUTINE = <string>subroutine_name |
        ELEMENT BLOCK SUBROUTINE = <string>subroutine_name
      SUBROUTINE DEBUGGING OFF|ON
      SUBROUTINE REAL PARAMETER: <string>param_name
        = <real>param_value
      SUBROUTINE INTEGER PARAMETER: <string>param_name
        = <integer>param_value
      SUBROUTINE STRING PARAMETER: <string>param_name
        = <string>param_value
      #
      # distance function commands
      DISTANCE TYPE = XTYPE|YTYPE|ZTYPE|RTYPE|
        RXTYPE|RYTYPE|RZTYPE
      FUNCTION = <string>function_name
      #
      # additional command
      SCALE FACTOR = <real>scale_factor(1.0)
      #
      # Specialized initialization method
      CALCULATE AS CLOSEST PROJECTION TO SURFACE =
        <string list>closeSurfs

    END [INITIAL CONDITION]

Sierra/SM supports a general initialization procedure for setting the value of any variable. This procedure can be used to set material state variables, shell thickness, initial stress, etc. The initialization is performed both before and after the element and material model initialization. This allows the elements and material models to compute other initial variables based on variables specified by the user and also ensures that the variables specified by the user are not overwritten by the elements and material models. However, there is minimal checking in Sierra/SM to ensure that the changes made yield a consistent system. There is also no guarantee that the changes will not be overwritten or misinterpreted by some other internal routine depending on what variable is being changed. Thus, caution is advised when using this capability.

The `INITIAL CONDITION` command block, which appears in the region scope, is used to select a method and set values for initializing a variable. The command block specifies the initial value of a global variable or a variable associated with a set of mesh entities (nodes, edges, faces, or elements). The user has three options for setting initial values: with a constant magnitude, with an input mesh variable, or by a user subroutine. Only one of these three options can be specified in the command block.

The command block contains five groups of commands—mesh-entity set, variable identification, magnitude, input mesh variable, and user subroutine. In addition to the command lines in the five groups, there is one additional command line: `SCALE FACTOR`. Following are descriptions of the different command groups and the `SCALE FACTOR` command line.

## 7.3.1. Mesh-Entity Set Commands

The `mesh-entity set commands` portion of the `INITIAL CONDITION` command block specifies the nodes, element faces, elements, or assemblies associated with the variable to be initialized. This portion of the command block can include some combination of the following command lines:

    NODE SET|NODESET = <string list>nodelist_names
    SURFACE = <string list>surface_names
    BLOCK = <string list>block_names
    ASSEMBLY = <string list>assembly_names
    INCLUDE ALL BLOCKS
    REMOVE NODE SET = <string list>nodelist_names
    REMOVE SURFACE = <string list>surface_names
    REMOVE BLOCK = <string list>block_names

These command lines, taken collectively, constitute a set of Boolean operators for constructing a set of nodes, element faces, or elements. See Section 7.1.1 for more information about the use of these command lines for mesh entities. There must be at least one `NODE SET|NODESET`, `SURFACE`, `BLOCK`, `INCLUDE ALL BLOCKS`, or `ASSEMBLY` command line in the command block. Assemblies may contain blocks, surfaces, nodesets, or assemblies of these.

## 7.3.2. Variable Identification Commands

Any variable used in the `INITIAL CONDITION` command block must exist in Sierra/SM. The variable can be any currently defined variable in Sierra/SM or any user-defined variable created with the `USER VARIABLE` command block (see Section 10.2.4).

There are two command lines that identify the variable:

    INITIALIZE VARIABLE NAME = <string>var_name
    VARIABLE TYPE = [NODE|EDGE|FACE|ELEMENT|GLOBAL]

The `INITIALIZE VARIABLE NAME` command line gives the name of the variable for which initial values are being assigned. The variable name must be a name known by Sierra/SM. The variable name may use component syntax to initialize only specific integration points or components of the variable, see Section 9.1 for more information on component syntax.

The `VARIABLE TYPE` command line provides additional information about the variable being initialized. The options `NODE`, `EDGE`, `FACE`, `ELEMENT`, and `GLOBAL` on the command line indicate whether the variable is, respectively, a nodal, edge, face, element, or global quantity. One of these options must appear in the `VARIABLE TYPE` command line. The `GLOBAL` variable type cannot be read from an external mesh database (see Section 7.3.5).

Both of these command lines are required regardless of the option selected to set values for the variable.

## 7.3.3. Specification Command

If the constant magnitude command is used, one or more initial values are specified directly in the command block. This is done using the following command line:

    MAGNITUDE = <real list>initial_values

The `initial_values` specified on the `MAGNITUDE` command line will set the values for the variable given by `var_name` in the `INITIALIZE VARIABLE NAME` command line. The length of the `MAGNITUDE` list (\(l_{\textrm{Mag}}\)) must be either one, \(n_{\textrm{comp}}\), or \(n_{\textrm{comp}}\times n_{\textrm{int}}\) where \(n_{\textrm{comp}}\) is the number of components for the variable (e.g., \(n_{\textrm{comp}} = 3\) for a vector) and \(n_{\textrm{int}}\) is the number of integration points. If \(l_{\textrm{Mag}} = 1\), then each component of each integration point will be set to this value. If \(l_{\textrm{Mag}} = n_{\textrm{comp}}\), then the respective components will be set according to the values of `MAGNITUDE` and replicated for all integration points. Finally, if \(l_{\textrm{Mag}} = n_{\textrm{comp}} \times n_{\textrm{int}}\), then the \(i^{\textrm{th}}\) component of the \(j^{\textrm{th}}\) integration point will be set to the value of \(\textrm{Mag}(n_{\textrm{comp}}(j - 1) + i)\); that is, the first \(n_{\textrm{comp}}\) values of `MAGNITUDE` set the components of the first integration point, the second \(n_{\textrm{comp}}\) values set the components of the second integration point, and so on.

As an example, if the following `INITIAL CONDITION` block is specified for a vector variable with an element with four integration points,

    BEGIN INITIAL CONDITION
      BLOCK = block_2
      INITIALIZE VARIABLE NAME = var
      VARIABLE TYPE = element
    END INITIAL CONDITION

then the various ways of initializing `var` depending on the size of `MAGNITUDE` are shown as follows:

    MAGNITUDE = 1

    var(1,1)=1 var(1,2)=1 var(1,3)=1 var(1,4)=1
    var(2,1)=1 var(2,2)=1 var(2,3)=1 var(2,4)=1
    var(3,1)=1 var(3,2)=1 var(3,3)=1 var(3,4)=1

    MAGNITUDE = 1 2 3

    var(1,1)=1 var(1,2)=1 var(1,3)=1 var(1,4)=1
    var(2,1)=2 var(2,2)=2 var(2,3)=2 var(2,4)=2
    var(3,1)=3 var(3,2)=3 var(3,3)=3 var(3,4)=3

    MAGNITUDE = 1  2  3  \#
                4  5  6  \#
                7  8  9  \#
                10 11 12

    var(1,1)=1 var(1,2)=4 var(1,3)=7 var(1,4)=10
    var(2,1)=2 var(2,2)=5 var(2,3)=8 var(2,4)=11
    var(3,1)=3 var(3,2)=6 var(3,3)=9 var(3,4)=12

## 7.3.4. Weibull Probability Distribution Commands

The field to be initialized can optionally be initialized or scaled with random numbers generated to conform to a specified Weibull probability distribution function. This is accomplished by including some of the following commands:

    WEIBULL SHAPE = <real>shapeVal
    WEIBULL SCALE = <real>scaleVal
    WEIBULL MEDIAN = <real>medianVal
    WEIBULL SEED = <int>seedVal (123456)

The Weibull commands may be used in conjunction with the `MAGNITUDE` command or the `READ VARIABLE` command to set the initial value, \(m_{i}\), that will be scaled by the distribution. Otherwise \(m_{i}\) starts off equal to \(1.0\).

Two and only two of the parameters `WEIBULL SHAPE`, `WEIBULL SCALE`, and `WEIBULL MEDIAN` may be specified. The relationship among `WEIBULL SHAPE`, \(k\), (also known as the Weibull modulus) `WEIBULL SCALE`, \(\lambda\), and `WEIBULL MEDIAN`, \(\mu\), is shown in the following equation:

\[\mu = \lambda(\ln(2)^{\frac{1}{k}})\]

The `WEIBULL SEED` parameter sets the starting point for the random number generation. Be careful when initializing two independent fields with Weibull distributions: if the default seed (or the same user specified seed) is used for both field, the random numbers generated will be the same for both fields and the fields will therefore be completely correlated element by element.

The values at each point can be further scaled by another factor, \(\alpha_{i}\). If no scaling commands are used then \(\alpha_{i} = 1.0\). Scaling is accomplished by using the Weibull scaling commands:

    WEIBULL SCALING FIELD TYPE = NODE|EDGE|FACE|ELEMENT|
      GLOBAL(ELEMENT)
    WEIBULL SCALING FIELD NAME = <string>fieldVal (VOLUME)
    WEIBULL SCALING REFERENCE VALUE = <real>value
    WEIBULL SCALING EXPONENT SCALE = <real>scaleVal (1.0)

The scaling commands are implemented to allow the use of any field variable for scaling; however, the field type must match the type of field being set. The `WEIBULL SCALING FIELD NAME` gives the name of a variable and the `WEIBULL SCALING FIELD TYPE` gives the variable field type which can be one of nodal, edge, face, element, or global type. The `WEIBULL SCALING FIELD TYPE` and `WEIBULL SCALING FIELD NAME` default to `ELEMENT` and `VOLUME` respectively. The `WEIBULL SCALING REFERENCE VALUE` gives the reference value \(v_{ref}\). A `WEIBULL SCALING EXPONENT SCALE`, \(\beta\), may also be defined and will default to \(1.0\) if not defined. The scaling factor \(\alpha_{i}\) is formed with the following formula:

\[\alpha_{i} = \biggl(\frac{v_{ref}}{v_{i}}\biggr)^{\frac{\beta}{k}}\]

where \(v_{i}\) is the value of a field variable specified with `WEIBULL SCALING FIELD TYPE` and `WEIBULL SCALING FIELD NAME` at the current point \(i\), and the rest of the variables are those defined previously.

The scaled initial value is determined by the equation:

\[\mathrm{InitialValue} = m_{i} \alpha_{i} \mu \biggl(\frac{\ln(R)}{\ln(\frac{1}{2})}\biggr)^\frac{1}{k}\]

where \(R\) is a random number in an uniform distribution between \(0\) and \(1\).

## 7.3.5. External Mesh Database Commands

    READ VARIABLE = <string>var_name
    COPY VARIABLE = <string>var_name [FROM MODEL <string>model_name]
      MAP_BY_PROXIMITY|MAP_BY_ID(MAP_BY_PROXIMITY)
    TIME = <real>time|FIRST|LAST

Warning

At this time the `COPY VARIABLE` command can only be used with nodal variables. Neither the `COPY VARIABLE` command nor the `READ VARIABLE` command is compatible with global variables.

A number of boundary conditions work by applying some field defined on either the input mesh database or an external mesh database. For example a prescribed temperature may be applied by reading the spatial time history oftemperature from a mesh file. The mesh files are defined via the `FINITE ELEMENT MODEL` command block described in Section 6.1.

The `READ VARIABLE = <string>var_name` command reads data from the input mesh for the region. The `read_var_name` string specifies the name of the variable as it appears on the mesh database. Generally the size and types of variables that are read need to be compatible with the types of target fields they are defining. For example, if `read_var_name` refers to a vector variable stored in the region’s finite element mesh database and `init_var_name` refers to a vector variable being initialized, then the following command only works if both vectors have the same number of components:

    INITIALIZE VARIABLE NAME = <string>init_var_name
    READ VARIABLE = <string>read_var_name

Alternatively, individual components of a variable can be assigned using `<string>var_name(<int>component)`. For example, the following command line works for reading the first component of a vector and assigning it to the first component of an initialized vector:

    INITIALIZE VARIABLE NAME = <string>init_var_name(1)
    READ VARIABLE = <string>read_var_name(1)

The variable name used on the mesh file can be arbitrary. The name can be identical to or different from the variable name specified on the `INITIALIZE VARIABLE NAME` command line. For more information on component variable syntax see Section Section 9.1.

The field to be read may be defined at a number of different time slices on the mesh file. The default behavior is interpolate these values to the current simulation time to extract the value of the field to transfer. The `TIME` command line can optionally be used to select a specific time from which to read the variable from. If necessary, values are interpolated to the specified time. In addition to specifying a time, the keyword `FIRST` or `LAST` may be used to read values corresponding to the first or last time step in the input mesh.

The `READ VARIABLE` command may be used in conjunction with `SCALE FACTOR` or `FUNCTION` commands, in such cases these source terms are multiplied together.

The copy variable function is a more flexible version of the read variable command. However, the copy variable command only works for nodal variables. The `COPY VARIABLE` command may be used for the following purposes:

- if the source field is defined on the input mesh file, but the analysis will be doing some extensive topology modifications, the copy variable command can be used to map the field that exists on the original geometry to the new geometry. This is necessary when performing such operations as dynamic mesh re-balancing, particle creation, or XFEM geometry modification.

- if the field is defined on some mesh database other than the input mesh file this command may be used to automatically map data between the two meshes databases. For example the temperature could have been calculated via an Aria run on one mesh, and then applied to the same geometry, but different mesh topology in Sierra/SM. For this mapping to function properly either the two meshes must occupy the same volume (`MAP_BY_PROXIMITY`) or the meshes must have identical topology and node and element ID numbers (`MAP_BY_ID`).

This `COPY VARIABLE` command specifies that the variable named `copy_var_name` will be used as the source variable. This `copy_var_name` is the name of a nodal field on an input mesh database. The `FROM MODEL <string>model_name` portion of the command is optional. If it is specified, the results are read from the mesh database named `model_name`, see Section 6.1. If the `model_name` is not provided, the region’s finite element mesh database will be used to read the source variable.

Two types of mapping are available. The default `MAP_BY_PROXIMITY` option can be used to map data from a model with that occupies the same volume, but has a different topology than the analysis model. When using `MAP_BY_PROXIMITY` a node in the target mesh will define data by interpolating from nearby nodes in the source mesh. This mapping is done in the original coordinates and is not affected by displacement. The option `MAP_BY_ID` can be used to directly send data between nodes in the source and target mesh with the exact same ID numbers. The `MAP_BY_ID` option can provide a faster and potentially more accurate mapping if the two models being mapped between are known to have completely identical topology.

The `COPY NEAREST` command extends the functionality of the `COPY VARIABLE` command by allowing transfers between different source and target variable types. Element variables may be transferred to nodal, face, or element variables. Meanwhile, face variables may be transferred to nodal or face variables. Lastly, nodal variables are only permitted to be transferred to nodal variables. These are all done using a nearest copy. In the boundary conditions scope, the `OBJECT TYPE` command sets the target type. If none is selected, the object type is set to its default, which is boundary condition dependent.

### 7.3.5.1. Read Variable Examples

The following command would initialize the unrotated_stress in the model based on reading the “stress” values that existed in the input mesh file at time 1.5.

    BEGIN INITIAL CONDITION
      INCLUDE ALL BLOCKS
      INITIALIZE VARIABLE NAME = unrotated_stress(:)
      VARIABLE TYPE = ELEMENT
      READ VARIABLE = stress
      TIME = 1.5
    END

The following command would define the temperature in a block as a function of time based on reading in the state variable at index five of a state array defined in the input mesh.

    BEGIN PRESCRIBED TEMPERATURE
      block = block_32
      READ VARIABLE = aria_state_output(5)
    END

### 7.3.5.2. Copy Variable Examples

The following command would define the temperature in a block by copying the variable `temp` of a block from model `tempRead` based on mapping the element ID to the analysis mesh.

    BEGIN PRESCRIBED TEMPERATURE
      block = block_32
      copy variable = temp from model tempRead  MAP_BY_ID
    END

The following command would map the displacement defined in some other mesh to the boundary of the analysis mesh. Note the `dispOut` variable must be a three component vector field on the mesh on which it is defined.

    BEGIN PRESCRIBED DISPLACEMENT
      node set = nodelist_1 nodelist_50
      COPY VARIABLE = dispOut FROM MODEL dispSourceModel \textbackslash\#
        MAP_BY_PROXIMITY
      COMPONENT = <string>X|Y|Z
    END

### 7.3.5.3. Copy Nearest Examples

The following command would define the pressure on a surface by copying the element variable `pressure` from the model `OML_pressure` that is a shell mesh. With the object type set to `node`, it would do a nearest element copy to the nodes, and output that as a nodal variable field `thispressure`.

    BEGIN PRESSURE
      surface = surface_1
      COPY NEAREST element pressure FROM MODEL OML_pressure
      OBJECT TYPE = node
      EXTERNAL FORCE CONTRIUBTION OUTPUT NAME = thispressure
    END

## 7.3.6. User Subroutine Commands

If the user subroutine option is used, the initial values will be calculated by a subroutine that is written by the user explicitly for this purpose. The subroutine will be called by Sierra/SM at the appropriate time to perform the calculations.

Following are the command lines related to the user subroutine option:

    NODE SET SUBROUTINE = <string>subroutine_name |
      SURFACE SUBROUTINE = <string>subroutine_name |
      ELEMENT BLOCK SUBROUTINE = <string>subroutine_name
    SUBROUTINE DEBUGGING OFF | SUBROUTINE DEBUGGING ON
    SUBROUTINE REAL PARAMETER: <string>param_name
      = <real>param_value
    SUBROUTINE INTEGER PARAMETER: <string>param_name
      = <integer>param_value
    SUBROUTINE STRING PARAMETER: <string>param_name
      = <string>param_value

Only one of the first three command lines listed above can be specified in the command block. The particular command line selected depends on the mesh-entity type of the variable being initialized. For example, variables associated with nodes would be initialized if using the `NODE SET SUBROUTINE` command line, variables associated with faces if using the `SURFACE SUBROUTINE` command line, and variables associated with elements if using the `ELEMENT BLOCK SUBROUTINE` command line. The string `subroutine_name` is the name of a FORTRAN subroutine that is written by the user.

Following the selected subroutine command line are other command lines that may be used to implement the user subroutine option. These command lines are described in Section 10.2.2 and consist of `SUBROUTINE DEBUGGING OFF`, `SUBROUTINE DEBUGGING ON`, `SUBROUTINE REAL PARAMETER`, `SUBROUTINE INTEGER PARAMETER`, and `SUBROUTINE STRING PARAMETER`. Examples of using these command lines are provided throughout Section 10.

The application of user subroutines for variable initialization is essentially the same as the application of user subroutines in general. See Section 7.4.10 and Section 10 for more details on implementing the user subroutine option.

When the user subroutine option is used for variable initialization, the user subroutine is called only once. Also, when a user subroutine is being used, the returned value is the new (initial) variable value at each mesh entity, and the flags array is ignored.

## 7.3.7. Distance Function Commands

    DISTANCE TYPE = XTYPE|YTYPE|ZTYPE|RTYPE|
                    RXTYPE|RYTYPE|RZTYPE
    FUNCTION = <string>function_name

Usage of the `DISTANCE TYPE` command line in the `INITIAL CONDITION` command block indicates that initial values will be assigned based on the positions of the mesh entities in relation to the origin or the axes of the global coordinate system. A `FUNCTION` command line must also be given in the same `INITIAL CONDITION` block as the `DISTANCE TYPE` command line. The given function must be an xy-function, where the independent x-value is a distance quantity and the dependent \(y\)-value is returned as the initial condition value. The xy-function is evaluated at each mesh entity. The `XTYPE`, `YTYPE`, and `ZTYPE` options quantify distance as the signed \(x\)-, \(y\)-, or \(z\)-coordinate, respectively, of each mesh entity. The `RTYPE` option quantifies distance as the unsigned radial distance from the origin to the mesh entity. The `RXTYPE`, `RYTYPE`, and `RZTYPE` options quantify distance as the unsigned radial distance from the global \(x\)-axis, \(y\)-axis, and \(z\)-axis, respectively, to the mesh entity.

Warning

The distance function option is only implemented for `VARIABLE TYPE = ELEMENT` and the distance quantity for each element is evaluated at the averaged nodal coordinates (approximately the centroid) of the element.

## 7.3.8. Additional Command

This command line provides an additional option for the `INITIAL CONDITION` command block:

    SCALE FACTOR = <real>scale_factor(1.0)

Any initial value can be scaled by use of the `SCALE FACTOR` command line. An initial value generated by any one of the three initial-value-setting options in this command block (i.e., constant magnitude, input mesh, or user subroutine) will be scaled by the real value `scale_factor`.

## 7.3.9. Specialized Initialization Methods

A handful of highly specialized initial condition routine options are documented below.

The `CALCULATE AS CLOSEST PROJECTION TO SURFACE` initializes a three component vector at an element centroid to the direction pointing to the closest point on the given provided sidesets `closeSurfs`. Such a direction is often used for defining body fitted coordinate systems. For example, a sideset could be placed on the top of a bolt head. Then this point direction direction would define the bolt aligned length direction for use in artificial strain or orthotropic material definition.

## 7.3.10. Examples

Initialize the stress tensors in an element block

    # Initialize the material stress tensor on block 1 such that
    #   s_xx = s_yy = s_zz = 2.3
    #   s_xy = s_xz = s_yz = 0.0
    BEGIN INITIAL CONDITION
      BLOCK = block_1
      INITIALIZE VARIABLE NAME = unrotated_stress
      VARIABLE TYPE = element
      MAGNITUDE = 2.3, 2.3, 2.3, 0.0, 0.0, 0.0
    END
    #
    # Initialize the ZZ component of the material stress tensor on
    # block_2 to 1.5
    #
    BEGIN INITIAL CONDITION
      BLOCK = block_2
      INITIALIZE VARIABLE NAME = unrotated_stress(zz)
      VARIABLE TYPE = element
      MAGNITUDE = 1.5
    END
    #
    # Initialize the bolt aligned coordinate system for later
    # use in defining artificial preload strain
    #
    BEGIN USER VARIABLE pdir
      TYPE = element vector
    END
    BEGIN INITIAL CONDITION
      BLOCK = block_3
      INITIALIZE VARIABLE NAME = pdir
      VARIABLE TYPE = element
      CALCULATE AS CLOSEST PROJECTION TO SURFACE = sideset_3
    END
    BEGIN ARTIFICIAL STRAIN
      BLOCK = block_3
      DIRECTION FIELD pdir FUNCTION = shrinkFunc
    END