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 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.1).
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:
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:
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:
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.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.2.
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.2 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