PARAMETERS

PARAMETERS

The figure on the left is the * PARAMETER main menu in PRIMER.

From release 970 onwards Ansys LS-DYNA supports parameters. These are Integer or Real (floating point) values defined by name at the top of the input deck which can be used in any data field of the relevant type. From LS971 R6 LS-DYNA also offers character parameters.

In addition the *PARAMETER_EXPRESSION card allows a parameter to be defined by an arbitrary mathematical expression which may contain references to other previously defined parameters.

The *PARAMETER keyword in Ansys LS-DYNA has grown in capability over time, and the following is a summary of these changes and how they are supported in successive releases of PRIMER .

From release 9.3RC2 onwards PRIMER provides full support for parameters:

• Both *PARAMETER and *PARAMETER_EXPRESSION are evaluated on input.
• The association between a parameter and the data field in which it is used is "remembered" across all operations, and rewritten on keyword output.
• Parameters, including the _EXPRESSION variant, may be created, edited and deleted interactively.
• When a parameter's value is changed all affected parts of the model will be rebuilt to reflect the change.
• Either parameters or their underlying values can be displayed in all editing panels, and parameters may be typed into any valid field on these.

From release 10.0 PRIMER adds support for the LS971R5 keywords:

• *PARAMETER_LOCAL , which permits multiple parameters with the same name but different values in different include files
• *PARAMETER_DUPLICATION , which tells Ansys LS-DYNA how to process _LOCAL name conflicts is supported in a limited way.

From release 11.0 PRIMER adds support for LS971R6 options

• Parameter type character ("C")
• Parameter names may now be up to 9 characters long (formally the case in 971R6, informally in R5 and later releases of R4)
• The *PARAMETER_DUPLICATION card is now fully supported, and its effect on parameter usage mimics that of Ansys LS-DYNA

From release 12.0 PRIMER adds support for LS971 R7.1 options.

• The _MUTABLE suffix is now supported
• The _TYPE suffix is now supported
• Handling of multiple *PARAMETER_DUPLICATION keywords has been clarified in the Ansys LS-DYNA user manual, and PRIMER supports this.
• You can now Pre-read Parameters when reading keyword files, to avoid the "used before value is known" problem in complex cases.
• The potential to handle parameter names up to 19 characters long has been added, see Rules governing the length of *PARAMETER names.

From release 13.0 PRIMER adds support for "implicit" parameters

• Implicit parameters defined within <...> in a keyword data field are supported.

From release 14.0 PRIMER adds support for LS_OPT expressions in data fields.

• LS_OPT expressions defined within <<..>.> in a keyword data field are supported to a limited extent. See Support for LS_OPT expressions below.

From release 16.0 PRIMER has improved the handling of accepting duplicate parameters.

• When a *PARAMETER_DUPLICATION card accepting duplicate parameters (option 2 or 4) is present, until version 15 PRIMER only used the youngest definition of parameters of the same name and marked all others as ignored. From version 16.0 onwards duplicate parameters are treated internally as _MUTABLE with these duplication settings, which seems to match better how Ansys LS-DYNA reads them.
  
  NOTE : Following clarification in the Ansys LS-DYNA user manual it turned out that treating duplicate parameters as implicitly _MUTABLE as a consequence of a *PARAMETER_DUPLICATION card was wrong, this was fixed in release 18.0.

From release 18.0 PRIMER corrected the handling of the *PARAMETER_DUPLICATION card.

• The behaviour in releases 16.x and 17.x was wrong. *PARAMETER_DUPLICATION is now programmed to work as specified in the Ansys LS-DYNA user manual.

Creating a Parameter Parameters may be created in the following ways:
(1) By typing a new parameter name into any text entry box in an editing panel
This will map a creation panel populated with: the parameter name the type (Integer or Real) as deduced from the context a sensible default value for this context. To create a character parameter type first create it in this way, and then change the given type (I or R) to C, and supply its name. When you start typing "&..." a popup box showing all existing parameters in the model matching the characters typed so far will be mapped, allowing you to select one directly. For example if you type " &B " all parameters starting with " B " will be shown, and as you type more characters the list will be refined.

Using wildcard syntax to limit the list of parameter names displayed.

In models with many parameters this popup of matching parameter names can be very large so you can also use wildcard syntax to limit what is shown: '?' matches a single character and '*' any number of characters or none. This is best illustrated by example:

Consider a model that contains parameters ALPHA, BAY, BAG, BACK, BODY ,B1, B10 and CHASSIS .

If you use wildcard syntax remember that parameters must start with a letter A-Z, and may only contain the characters A-Z, 0-9 and _ (underscore). So if you have used wildcard syntax but have not found anything that matches in the popup list then the name you have, containing * and/or ?, is not a valid parameter name and will be rejected unless you correct it.

Creating an "Implicit" parameter in <...> As an alternative to the &name syntax above it is also possible to create an implicit parameter expression by writing the expression directly in <...> Implicit parameters are described in more detail below, but briefly they behave like ordinary parameter expressions but don't have an explicit name.

(2) From the Create button in the main Parameter panel

(3) From the "Create new..." button on the Modify Parameter panel

The Create/Edit parameter panel

The panel allows you to edit all attributes of the parameter:

• Its name: up to 9 characters without the initial "&"
• Its type: I(nteger), R(eal) or C(haracter)
• Its value
  
  
• Whether or not it is an EXPRESSION parameter
• Whether or not it is a LOCAL parameter
• Whether or not it is a MUTABLE parameter
  
  alternatively
  
  
• Whether or not it is a _TYPE parameter, and the PRTYP argument if it is

The value is simply typed into the "Value" box.

As with other editing panels this is a scratch definition, and the saved attributes of the parameter will only be updated when you use Update.

Using the _EXPRESSION option

In the _EXPRESSION case the panel extends to provide editing rows to contain the expression.

As many rows as necessary to define the expression may be used. PRIMER will reformat the expression over as many lines as necessary to make it fit the 80 column width of the Ansys LS-DYNA input deck.

Its value is calculated when you hit <return>, but if a parameter referred to in the expression (for example Beta or Gamma here) is changed externally you can use RECALCULATE at any time to force a recalculation.

Arithmetic rules used to evaluate PARAMETER_EXPRESSION

PARAMETER_EXPRESSION uses syntax and standard operators common to most programming languages. The standard rules of arithmetic evaluation and operator precedence are obeyed, and built-in functions common to most programming languages are supported.

In particular note that integer expressions evaluate as integers, see Integer vs Floating evaluation of expressions below.

Precedence of operators

Brackets (..)	are senior to
Unary +/- (e.g. -10, +3.141592)	are senior to
Raising to the power of (**)	is senior to
Multiply, divide, modulo (*, /, %)	are senior to
Add and subtract (+, -)

Built-in functions

All functions return a floating point result except for:

Integer vs Floating evaluation of expressions

Programming languages make a distinction between an integer (e.g. 2) and a floating point value (e.g. 2.0). The same is true of expressions which give a result of the same type of their component parts, however when an expression is mixed the result is "promoted" to floating point. Generally this has little influence on the outcome, but there is one significant exception:

WARNING: integer division truncates!!

Consider the following examples

These rules apply to subsets of expressions as well as the expression as a whole, for example:

Because it is easy to write an "all integer" expression by mistake when a floating point result is desired PRIMER performs a check for this on all PARAMETER_EXPRESSION definitions. It evaluates the parameter twice: once using the rules described above and a second time using "all floating point" arithmetic. If the results are different by more than 1 part in 1e6 of the magnitude of the result then a warning is issued stating that the result depends upon integer truncation. Almost always this is due to integer division as given in the examples above, but it is theoretically also possible as a result of the mod(x,y) function (or the expression x % y , which means the same thing) returning an integer result.

It is recommended that "real" expressions are always written using floating point numbers, i.e. write 2.0 rather than 2, as this reduces the chances of accidental integer truncation and the meaning is clear to anyone reading the expression.

Integer expressions may deliberately utilise integer truncation, but it is recommended that this is made explicit by using the int(x) function. It will make no difference to the outcome, but it will make it clear to the reader that truncation is intended.

When expressions refer to other parameters the type of each parameter's value is retained: integer parameters evaluate as integers, and real parameters as floats.

Conversion of results by Parameter type

You will see from the above that the results of parameter expressions may be floating point or integer, however parameters themselves may also be declared as being "real" (floating point) or integer.

PRIMER converts results as follows:

Conversion between R eal or I nteger parameters and C haracter parameters is not permitted.

Precision of Parameters

Integer parameters are stored using 64 bit signed integers, giving a range of +/-2^63-1, approximately +/-9e18. This is to permit them to represent "large" labels.

Real parameters are stored using 64 bit floating point doubles. This gives a mantissa precision of 2^53-1, approximately 1 part in 9e15, and a decimal exponent range of +/-e308.

PARAMETER_EXPRESSION s are evaluated as follows:

• All calculations are performed using double precision floating point variables, so all arithmetic is performed with a mantissa precision of approx 16 significant figures and an exponent range of 1.0e+/-308.
  
  
• Where integer truncation is applied as described above within an expression the result is a "whole number" stored as a double precision float, retaining this precision.
  
  
• The result of a PARAMETER_EXPRESSION evaluation is converted to the intrinsic type of the parameter, thus:
  
  Real parameters give a direct double precision result.
  
  Integer parameters are limited to the mantissa precision of a double float, therefore they give a value in the range +/-9e15 approx.
  
  When a PARAMETER_EXPRESSION is used to calculate an integer result, typically for a label, it is advisable to use "all integer syntax" in the expression to avoid any possibility of ambiguity or rounding errors.

Parameters and Include files.

Early versions of Ansys LS-DYNA required all *PARAMETER statements to occur after *KEYWORD and before any other input card. This was quite restrictive, and the limitation was soon removed - in fact Ansys LS-DYNA 971R3 doesn't care what order parameters arrive in, of where they are written - see "the order in which parameters are defined" below.

PRIMER adopts the following strategy:

• It doesn't care where in the deck a *PARAMETER statement occurs.
• From release 9.3 onwards it no longer needs to be defined before it is used, although not doing so is deprecated.
• It doesn't care if a *PARAMETER statement occurs in an include file, and it will keep it in that include file.
• It permits parameters to be moved between include files and master file, just like any other keyword.

The use of parameters inside include files manipulated by *INCLUDE_TRANSFORM is a special case, please see below for more details.

The use of the _LOCAL suffix to the *PARAMETER card, introduced in LS971R5, permits parameters to be multiply defined with different values in different include files, and this affects the scope of their applicability. This is explained under "Using the LOCAL option" below.

From LS971 R7.1 parameters may also have a _MUTABLE suffix, permitting their value to change as each duplicate definition in the input deck is read.

The policy used for the destination Include file of new parameters.

There are three options:

1. Create the parameter in the current layer (include file)
   This is the default, and is consistent with the creation policy for other items in PRIMER.
   
   
2. Use referrer's layer
   
   This is only relevant in the case of a parameter being created via a new name (&xxx) being typed into a text entry box (option 1 above).
   
   In this mode the new parameter will "inherit" the include file of the item being edited. Parameters created by other means will use the default "current layer" to determine their include file.
   
   
3. Use master file
   
   All new parameters are forced to reside in the master file. If the strict Ansys ls-dyna rules are applied this is the safest option, however where parameters are used in an include file it may result in "decoupling" of the parameter definition and its subsequent usage in a different context.

The include file of any parameter may be changed at will using the standard "include" editing buttons just as for any other in PRIMER.

Using the _LOCAL option

*PARAMETER_LOCAL rules used in PRIMER

The LS971R5 manual leaves certain details of this usage ambiguous, however reverse-engineering the behaviour of Ansys LS-DYNA suggests that the following rules are correct:

• A non _LOCAL (i.e. global) parameter can be defined anywhere in the input deck, in any include file, and it will be used to satisfy a parameter reference anywhere in the input deck except where superseded by a _LOCAL definition of the same name as described below.
  
  
• A _LOCAL parameter is valid only in the include file in which it is defined, and in any "children" of that include file, to any number of generations.
  
  
• A _LOCAL parameter "masks" (supersedes) a global parameter definition in the include file in which it is defined, and any children of that file to any number of generations. This is true even if a global parameter of the same name is defined in this file or its children.
  
  
• A _LOCAL parameter in an include file also masks a _LOCAL parameter of the same name in the parent (or grand-parent, to any number of generations) include file that "owns" this one. It also masks it in any children of this file.

These rules could be summarised as

• A global parameter is valid everywhere unless it is masked by a _LOCAL parameter in that context.
• _LOCAL parameters apply in the include file in which they are defined, and any child include files referenced in that file, to any include depth.
• _LOCAL parameters in an include file also mask other _LOCAL parameters defined in a "parent" include file.

How duplicate parameter names are handled

Ansys LS-DYNA is configured to permit duplicate (multiply-defined with the same name) parameters to exist using a combination of three strategies:

1. _LOCAL parameters can legally mask global parameters of the same name, and they can also legally mask other _LOCAL parameters of the same name in different include files.
   
   
2. _MUTABLE parameters can be redefined any number of times, with the "scope" of the current definition persisting until a new definition is encountered.
   
   
3. Otherwise duplicate parameters are illegal but tolerated, and Ansys LS-DYNA uses the following strategies:
   
   If there is no *PARAMETER_DUPLICATION card (see below) the first definition of a parameter is used, subsequent definitions are ignored with a warning.
   If a *PARAMETER_DUPLICATION card is present this can alter whether the first or the most recent definition of the parameter is used, and also whether or not a warning is issued.
   
   

PRIMER V18 onwards mimics this behaviour as follows:

Once keyword input is complete all parameters are examined to see whether any name clashes exist. If there are some then an attempt is made to resolve these using global vs _LOCAL rules. If name clashes remain in a given scope then behaviour depends on whether or not a *PARAMETER_DUPLICATION card is found, and any settings on this card. The results will be as follows:

If a *PARAMETER_DUPLICATION card is present:

• If it is set to "accept" (options 2 or 4) then the youngest , as in most recently read, of any clashing definitions is used.
  
  
• If it is set to "ignore but continue" (options 0, 1 or 5) then the oldest , as in first read, of any clashing definitions is used.
  
  
• If it is set to "ignore and terminate with error" (option 3) then the oldest definition is used. PRIMER will not terminate input, so the effect during model read is the same as for options 0, 1 or 5.

If a *PARAMETER_DUPLICATION card is not present:

• The effect is the same as option 3 above: the oldest definition is used, and younger clashing definitions are remembered and written out, but marked as being in error and to be ignored.

In all cases PRIMER "remembers" parameters that are ignored above. They will function as follows inside PRIMER :

• They will be visible in the *PARAMETER editing panel but marked as ignored. They can be inspected and edited, but an ignored definition of parameter name will not be used to resolve a reference &name on a data card.
  
  
• The order in which parameters are defined is remembered, so if a *PARAMETER_DUPLICATION card is created, or an existing one is edited, then a change on that card which changes how Ansys LS-DYNA would handle the deck will be reflected inside PRIMER . For example if the previous setting of 1 (use oldest) is changed to 2 (use youngest) then PRIMER will rebuild the model to use the younger parameters, marking the older ones as ignored.may change the usage of parameters such that one which is currently ignored will now become used, and its doppleganger which was previously used will now be ignored.
  
  
• During keyword output "ignored" parameters will be written out in the order in which they were read in, so the contents of the model will not change.

See Parameters that have clashing (duplicate) names below for more information about the treatment of multiply defined parameters, also The *PARAMETER_DUPLICATION keyword for more information about *PARAMETER_DUPLICATION .

Note that there is an implicit potential problem in this logic: the parameters that are actually used will depend not only on the settings of the *PARAMETER_DUPLICATION card, but also on the order in which include files are read .

This won't matter if multiple include files contain the same (global) parameter names with the same values, since then it doesn't matter which definition is used, but if include files contain clashing global parameter names with different values then the potential for mix-ups is all too clear. In this latter situation it is strongly recommended that the _LOCAL suffix is used to make explicit which parameters are to be used in which files.

Using the _MUTABLE option

The *PARAMETER_MUTABLE suffix was added in LS971 R7.1 to provide an alternative way of handling multiple definitions of the same parameter.

The parameter can be defined multiple times in the input deck, with a different value each time.

References to it use the most recently defined value.

The rules for its use in Ansys LS-DYNA are:

• It only applies to I nteger and R eal parameter types, it is ignored for C haracter ones.
• The _MUTABLE suffix must be added to the first definition of a mutable parameter, it is optional on subsequent ones.
• The effect is that each new definition of the parameter supersedes the previous value, becoming the "current" value for any references.
• This behaviour is independent of the *PARAMETER_DUPLICATION setting.

To understand the implications of this more clearly consider the following simple input deck:

*PARAMETER_MUTABLE
I ID1              1 

*MAT_ELASTIC
$      mid        ro         e        pr        da        db  
&ID1             1.0       1.0       0.3       0.0       0.0       0.0

*PARAMETER_MUTABLE
I ID1             10

*SECTION_SOLID
$    secid    elform       aet
&ID1               1         0

*PARAMETER
I ID1          100

*PART
$ title
Example part
$      pid     secid       mid     eosid      hgid      grav    adpopt      tmid
&ID1              10         1         0         0         0         0         0

From this example several points will become clear:

• The mutable parameter ID1 has three distinct values: 1 , 10 and 100.
• The order in which the parameter (re-)definitions appear in the input deck is significant.
• The order in which other cards referring to this parameter appear in the deck is also significant.

PRIMER has to handle this problem without losing definitions or muddling them up, and it does so as follows:

How PRIMER stores and manages mutable PARAMETER definitions

• Each definition of a mutable parameter is stored separately as a distinct internal entity.
• Each reference to a mutable parameter "knows" which of these entities it is using.

If we use the simple input deck above as an example the PARAMETER editing panel will show the following:

Each definition of ID1 is stored separately, in the order in which they appeared in the input deck.

When you start typing "&" into a data field to define a parameter you will be given a list of all possible candidates to choose from.

$
$ ===============
$ PARAMETER cards
$ ===============
$
*PARAMETER_MUTABLE
$PR_MPTAG 1
I ID1              1

*PARAMETER_MUTABLE
$PR_MPTAG 2
I ID1             10
$
*SECTION_SOLID
$    secid    elform       aet
&ID1               1         0
$

*PARAMETER_MUTABLE
$PR_MPTAG 1
I ID1            100
$
*PART                                                                    
Example part
$      pid     secid       mid     eosid      hgid      grav    adpopt      tmid
&ID1              10         1         0         0         0         0         0

*PARAMETER_MUTABLE
$PR_MPTAG 1
I ID1            100

*PARAMETER_MUTABLE
$PR_MPTAG 1
I ID1            100
$
*INCLUDE
filename

The *PARAMETER_DUPLICATION keyword

How it works in Ansys LS-DYNA

By default duplicate (multiply-defined) parameters that are not _LOCAL or _MUTABLE are illegal in Ansys LS-DYNA. The default behaviour is to take the first (oldest) definition as the correct one, and to ignore any later (younger) ones with an appropriate warning. The *PARAMETER_DUPLICATION card allows this default behaviour to be modified in the following ways by setting integer dflag to one of the following values:

= 1: issue a warning and ignore the new definition (default)
= 2: issue a warning and accept the new definition
= 3: issue an error and ignore (terminates at end of input)
= 4: accept silently
= 5: ignore silently

Thus options 1, 3 and 5 continue to use the oldest definition and options 2 and 4 use the youngest, with some differences in error/warning behaviour.

In Ansys LS-DYNA a model must contain either zero or one *PARAMETER_DUPLICATION cards, repeated definitions of the card are ignored with a warning. In addition the *PARAMETER_DUPLICATION card must appear in the deck before any *PARAMETER cards.

Editing *PARAMETER_DUPLICATION *PARAMETER_DUPLICATION can be created, edited and deleted using the Duplication option. As this example shows you choose whether or not to have a *PARAMETER_DUPLICATION card in each include file by using the Active tick box. In files where it is present you can set the dflag value accordingly, and different cards may have different dflag values. If multiple definitions exist the oldest (first) definition is the active one, since this is what Ansys LS-DYNA would use. Any subsequent definitions are remembered and will be written out in the appropriate include file, but will not affect how multiply-defined parameters are processed inside PRIMER . If you change the dflag value on the oldest (ie first ticked) definition in this editor and Update the card then parameter usage in the model will be scanned. If the new dflag setting would change which instance of a duplicate parameter would be used by Ansys LS-DYNA then the model is updated and rebuilt to reflect this change. The parameter editor itself will also be updated to show which version of a duplicate parameter is used and which other(s) are ignored.

*PARAMETER_DUPLICATION and error checking in PRIMER

PRIMER considers the settings on any *PARAMETER_DUPLICATION card when it encounters clashing parameter names, taking the following actions:

If a *PARAMETER_DUPLICATION card is present:

• If dflag is 1 or 5 duplicate parameters are "remembered but ignored". They will not be used to populate any &name statements, and in the parameter editor they will be marked as "ignored". A Check reports as a warning they are duplicates but have been ignored.
  
  
• If dflag is 3 duplicate parameters are treated as above, but in addition they are marked as "in error" in the parameter editor and a Check will report them (as a warning) as being illegal.
  
  
• If dflag is 2 or 4 duplicate parameters are accepted. The instance of a duplicate parameter that is used to satisfy a &name reference will depend on the relative locations of definition and usage: the most recent parameter definition will be used.
  

If a *PARAMETER_DUPLICATION card is not present:

• The behaviour is identical to the dflag = 3 case above: "ignored and illegal" in the parameter editor, reported (as a warning) as illegal in a Check.

In other words error checking will warn about any clashing parameters, treating clashes that would be resolved successfully by a *PARAMETER_DUPLICATION during Ansys LS-DYNA keyword input as warnings, and those which would result in error terminations as errors.

Error checking also considers the case of multiple *PARAMETER_DUPLICATION cards.

• The second and subsequent such cards are reported (as a warning) as being redundant.
• A check is also made for dflag being different on multiple cards, and if this is the case a further warning is issued.

Character parameter types

From Ansys LS-DYNA 971 R6 onwards the character ("C") parameter type has been introduced, and this is supported from PRIMER release 11 onwards. When they have first been supported in PRIMER , it was not known in what generality character parameters can be used in Ansys LS-DYNA, so PRIMER makes the following assumptions:

• Character parameters can be used in item label and data fields where character strings would be acceptable. For example the labels of Material, Section, Equation of state, Hourglass and Thermal material which can all (optionally) use character labels.
  
  
• Character parameters will not be used "long" text fields such as title and header strings.From release 17 onwards PRIMER also supports character parameters as *INCLUDE file names.
  
  
• Character and numeric (I or R) parameters are not interchangeable. PRIMER will only permit a parameter to be changed between these types if it is not referenced anywhere in the model.

Over time the possible use of character parameters in Ansys LS-DYNA has turned out to be wider. Support for other use of parameters will be added to future PRIMER versions as required.

Using the _TYPE option
*PARAMETER_TYPE was introduced in LS971 R7.1 and is intended to provide LS-PREPOST with information about how a parameter will be used in the analysis. The _TYPE suffix is incompatible with _ EXPRESSION , _LOCAL or _MUTABLE suffices, and PRIMER will treat an attempt to combine these suffices as an error.

The top level, shown here, lists all parameters in the model showing a summary of their attributes.

Changes made in this panel are applied to a scratch definition, and the permanent parameter definitions will not be updated until Update PARAMETERS is used. For more detailed editing, necessary when changing an EXPRESSION, use the Edit... button to map the detailed editing panel above.

The Find... button is an alternative way of selecting parameters to edit which may be useful in a model with many parameters. It works as follows:

• It maps a scrollable standard object menu of all parameter names.
• The standard filtering options, available from the Filter button in that menu, can be used to limit the list
• You select the wanted parameter from the list.

You may edit the following at this level.

When a parameter's attributes are changed the revised values are shown on a green background. In this example L1 has been changed from 4.0 above to 10.5. In addition because the EXPRESSION in parameter ALPHA also refers to L1 it too has changed.

Changes are "scratch", as explained above, and can be undone using the Reset button.

Sometimes changes to one parameter will create errors in an EXPRESSION that uses them.

In this example the parameter ALPHA has been changed to include " 1.0 / L1 " and the value of L1 has been changed to zero. This gives a divide by zero error when evaluating ALPHA , and it is shown on a red background to emphasise this.

PRIMER can tolerate arithmetic errors in expressions, and substitutes a value of zero. However there is no guarantee that the analysis code will handle this and you will be warned if you attempt to update and save any errors.

From PRIMER 9.3RC2 onwards editing panels, including generic keyword editor ones, display parameters either by name or by value wherever they are used.

By default they are displayed in exactly the same format as that used in keyword output files: &NAME , but this can be toggled to show values instead - see below.

Hovering the mouse over such a parameterised field will display a popup box giving the parameter name, type and value. In this example the user has hovered over data field Q1 which uses the parameter &Q1_FE . The popup box reveals that its value is 0.1 .

To edit this parameter use Edit...

Using to toggle Parameter display mode

An alternative to &NAME symtax is to show the value of the parameter, but underlined to emphasise that the value shown is parameterised. You can toggle between the two modes using the " P " button at the top right hand corner of any panel showing parameters.

This image shows the panel above displayed in this alternative format. Hovering the mouse above an underlined field will map the parameter popup box as shown above, giving information about the parameter name.

Setting programme-wide parameter display mode The "P" button on an editing panel only controls display for that panel. To set the default display mode for the whole programme use Options, Parameter Display and select: HINT Numeric values underlined with dots SHOWN Shown in &NAME format

Entering parameters in edit panel data fields.

In any data field where a parameter could be used in an Ansys LS-DYNA input deck the equivalent edit panel field may also use one. To enter a parameter do the following:

• Type an ampersand "&" into the text box field
• This will immediately map a popup box showing all currently defined parameters (if any exist)
• To choose an existing parameter simply select it from the popup.
• To narrow down the choice from many parameters type its initial letter(s), the list will contract to show only those that match.
• To enter a new, previously undefined, parameter type in its full name.

In the last case, entering a new parameter, the following happens:

• A new parameter definition using that name is created. It will be a plain parameter, ie not _EXPRESSION.
• It is given a type (Integer or Real) appropriate to the context
• It is given an initial value of zero, unless that would be illegal in that context in which case the smallest legal value is used.
• This value is entered into the data field, and the edit panel is updated.

The editing panel for the new parameter is then mapped, and you are invited to update its attributes. When you save these then its value on the "parent" editing panel will also be updated.

How to remove a parameter association

To change a parameterised value to a plain number simply rub out the &NAME (or underlined) field, and type in a simple number. This will break the association between parameter and data field, even if the number you type in is the same as the parameter's value.

Differences between implicit and normal parameters in PRIMER

These internal parameters are not normally shown in the top level PARAMETER editing panel, and it is necessary to turn on Show implicit parameters for them to be visible, as shown below.

Certain attributes of these parameters cannot be changed: they are forced to be of type _EXPRESSION , and cannot use _LOCAL, _MUTABLE or _TYPE suffices. You will observe that these buttons are greyed out for the implicit parameters in the image above.

Their name cannot be changed, and the syntax #P nnn would be illegal in Ansys LS-DYNA anyway. It is used to reinforce the point that these are not normal parameters.

It is normally the case that each implicit parameter is used only in a single context, which is where it has been written as <...> in a data field. PRIMER will permit you to enter &#P nnn into a data field to refer to an internal parameter, or to select it from a menu of parameter names, however the data field will always show the <...> expression rather than the & name reference.

The effect of editing a <...> field depends upon how you go about it:

• If you edit the <...> expression in the data field itself this will create a new #P nnn parameter exclusively for this data field, and any association with the "old" parameter definition will be lost. The old parameter remains in the model, and if it is used for any other data fields these will not be affected, otherwise it becomes an unused orphan. These orphans do no harm, but they can be deleted explicitly if desired using Remove, or automatically via Cleanup Unused.
  
  
• If instead you use the parameter editing panel to edit the #P nnn parameter definition itself this will behave like editing a normal parameter: the data field will continue to refer to the parameter and it will be updated as necessary to show the revised expression. Any other data fields referring to this parameter will also be updated.

To avoid possible confusion it is recommended that you do not make explicit references to implicit #P nnn parameters by name, preserving their one-to-one relationship with <...> data fields. In particular do not attempt to refer to #P nnn parameters by name in other parameter expression definitions: this will not work because #P nnn parameters are not written out to the keyout file.

Visualising LS_OPT expressions

These internal parameters are not normally shown in the top level PARAMETER editing panel, and it is necessary to turn on Show LS_OPT expressions for them to be visible, as shown below.

Certain attributes of these parameters cannot be changed: they cannot use _LOCAL, _MUTABLE or _TYPE suffices.

Their name cannot be changed, and the syntax #L nnn would be illegal in Ansys LS-DYNA anyway. It is used to reinforce the point that these are not normal parameters.

You can change the numerical value of these parameters, and such changes will be propagated through the model in the normal way.

What happens when the value in a parameterised field is changed by some other means

It is possible for the value in a parameterised field to be changed indirectly by some other operation in PRIMER, breaking the association between the field's true value and the associated parameter value. Consider the following sequence:

1. Parameter &X1 is used as the X coordinate of a node
2. The user chooses to ORIENT the model, translating it in X

After step (2) the the node's X coordinate will no longer match the value of parameter &X1. Other examples of such changes are "auto-fixing" in Check, contact de-penetration, mechanism/dummy positioning, item re-labelling, and there are many more such cases.

In these situations PRIMER will (silently) remove the association between the parameter and its usage in this context, so that if the deck is written out or the node displayed in an editing panel only the plain numeric value will be shown.

The test for whether or not there is a mismatch between data field and parameter value is as follows:

The special case of using Parameters in *INCLUDE_TRANSFORM files

A special situation arises when parameters are used in *INCLUDE files that are subject to transformation by the *INCLUDE_TRANSFORM keyword. When dealing with such files there are two requirements:

1. PRIMER must apply any transformations when it reads the input deck, so that it can display the model in its "as transformed" state.
2. PRIMER must "undo" the transforms on keyword output so that the original files are written out unchanged.

If parameters are used inside the *INCLUDE files this can lead to conflicts, since (1) may require the underlying values to change, invalidating the association between parameter and true values; yet (2) requires that the association be "remembered" in order that it can be restored on keyword output.

PRIMER deals with these conflicting requirements by setting a special internal flag against associations occurring inside *INCLUDE_TRANSFORM files. If the true value and the parameter value do not match in these cases then the following is done:

• The true value is used (as normal) for all calculations and display.
• In editing panels the true value is always displayed, but in red and underlined to designate it as a special parameter.
• On keyword output the inverse transformation is applied to the true value, and the parameter &NAME written if they still match (to within a small tolerance).

A typical editing panel field looks like this: here parameter &X1 is the node's X coordinate. The parameter popup mapped in response to hovering over the panel shows the parameter's actual value and gives a warning message about the mis-match.

The effect of editing parameterised items used inside *INCLUDE_TRANSFORM files is as follows:

• Entering an explicit number in a parameterised field will destroy the association between data field and parameter - as in the normal case above.
• Entering a parameter into a field will result in the as-transformed value of that field changing to the parameter's current value. This may or may not result in the parameter definition appearing in the keyword output deck, as this will depend upon whether or not the pre-output inverse transformation changes its value so that it no longer matches the underlying value.

If the value of a parameter definition used inside a *INCLUDE_TRANSFORM , or a *DEFINE_TRANSFORMATION to which is refers, is changed then:

• The contents of the *INCLUDE_TRANSFORM are "untransformed".
• Any data fields using that parameter are changed to the new parameter value.
• The include file contents are "retransformed".

For large include files this may take a significant amount of time, and the "untransform, modify, retransform" cycle may result in small numerical errors in the result. The process works, but it is better if it can be avoided!

This is a complex problem, which only gets worse if the same include file is used multiple times in different *INCLUDE_TRANSFORM statements to create multiple instances of parameterised data fields! Please contact Oasys Ltd Support for help and advice if you are having problems with this.

Using parameters for the label fields of items!!! It is best not to do this at all, or use them only if you won't change their values interactively during a PRIMER session.

It is ***STRONGLY*** recommended that you do not use parameters to define the labels of widely used items. (ie the labels of nodes, elements, parts, etc).

PRIMER will try to cope if you do, but changing the value of such a parameter could lead to all sorts of conflicts and problems. For example if you accidentally change the parameter value so that you generate duplicate labels the internal "rebuild" of the affected items may fail because of errors, and this may lead to items disappearing - or indeed the whole model being deleted to avoid internal inconsistencies.

PRIMER will read in and process decks that use parameters in this way, and all will be well so long as their values are not changed, but you should regard this as extremely dangerous modelling practice which will, if treated as anything other than "read only", cause severe problems.

If you choose to use PARAMETER_EXPRESSION to build up and define labels remember that the arithmetic rules used to calculate expression values will truncate integer expressions to an integer result. This may have unexpected consequences if your expression includes integer division, and you should read the section " Integer vs Floating evaluation of expressions" above very carefully.

Integer Parameters in PRIMER are stored using 64 bit values, and expressions are evaluated using double precision arithmetic, therefore they can be used to represent "large" format labels safely. (For more information on label sizes see Setting the current label limits in PRIMER.)

Using parameters in label field before the parameter values are known.

PRIMER 's normal behaviour when it encounters a parameter in a keyword deck that has yet to be defined is:

• Substitute a value of 0 (integer) or 0.0 (floating point)
• Add the parameter name to the internal list of latent items, with its type being set to "unknown"
• Continue the input operation using this value of zero.

Once input is complete, and the parameter definition has now been read, PRIMER revisits all locations where items used the parameter before its value was known and recreates them with the correct value.

Generally this works well, but if a parameter is used to define the label of an item then substituting zero does not work because this would be illegal, and PRIMER will reject the definition with a BAD LABEL error.

Prior to release 11.0 this would result in some or all of the input deck being rejected, and possibly the model deleted from memory. This behaviour was criticised by users who wished to view include files or other subsets of models which might use parameters defined elsewhere.

From release 11.0 onwards this behaviour has been modified as follows.

• When an unknown parameter is encountered in a label field PRIMER now substitutes an internal, unique "unknown label" value.
• This value is -ve and is accepted by PRIMER as a "place-holder" value during keyword input.
• The parameter is marked as latent and unknown as before, but it is now given this place-holder value.

Once input is complete:

• If the parameter has since been read the items that reference it are recreated using the correct labels instead of the place-holder value.
• If the parameter is still undefined the place-holder values are left unchanged.

In the latter case this means that PRIMER must manage the problem some item labels are unknown, and it does this as follows:

• In contexts where the label would normally be shown, for example in object menus or when labelling items on the screen, the parameter name (with &) is used instead.
  
  Therefore a part label might appear in an object menu as M1/P&abc
  
  
• Inspection of the parameter (using PARAMETER, MODIFY) will reveal that it is latent with a -ve value. This is its place-holder value, in a designated internal -ve label range set aside for this purpose, and you should only change this if it is to become a "correct" +ve value.
  

Working with unknown parameterised labels imposes some limitations:

• Keywords such as *INCLUDE_TRANSFORM where label offsets are used will almost certainly not work. Adding an offset to an internal -ve number will probably create a value that is illegal, or which clashes with some other labels.
  
  
• Renumbering labels may not work, for much the same reason. If -ve place-holder labels are changed to lie outside the permitted range set aside within PRIMER the consequences are undefined.
  
  ... and it is likely that many other operations that imply changing labels or relying (directly or implicitly) on label ranges also will not work.

Therefore the use of undefined parameters in label fields should be regarded as a "read only" facility for inspecting input decks, and you should not expect everything to work correctly.

Pre-reading parameters.

It is sometimes the case that PRIMER 's "one pass" approach to reading decks with parameters may fail if the parameters are defined after they are used. This can happen if a parameterised field on a card determines the format of the rest of the card. Consider the case of *MAT_FABRIC, material 34, whose card format is

Card 6 is only written if FORM on card 3 = 4.

Therefore if FORM is defined by a parameter, and the material card is encountered before the parameter value is known, then PRIMER 's standard approach of inserting zero and then rebuilding the card later once the parameter's true value is known will not work, because card 6 will not have beeen read. The only solution to this problem is to scan the input deck for parameter values before reading it "properly", and this can be done via Options on the Model Read panel.

Pre-reading parameters in this way will take a bit longer, but this pre-read is much faster than the "proper" read which follows - and it is infinitely preferable to having the deck read wrongly or failing to read altogether. For this reason it is recommended that you locate parameters at the top of the master file, or in an include file that is read before other include files.

The order in which parameters are defined

When PRIMER reads a model it will store parameters in the order in which they are read, and this becomes the internal order. Although parameters do not have numeric labels you can think of them as being stored in the ascending sequential label order 1 to N for N parameter definitions. The order in which they are stored can be significant in the following situations:

1. A parameter is referred to by name in a *PARAMETER_EXPRESSION before it is defined.
   
   Ansys LS-DYNA requires that all parameters referred to in expressions are defined (ie read in) before the expression definition. Failing to do this will cause keyword input to fail with a fatal error.
   
   PRIMER will attempt to read a deck in which expressions refer to unknown parameters by substituting zero for the missing parameter and evaluating the expression using this. Once (if) the missing parameter value is known the expression is re-evaluated and the model is updated as required with its new value. Pre-reading parameters is an alternative solution to this problem.
   
   
   
2. Parameters are referred to generally, eg &name in some data field, before they are defined.
   
   Anecdotally Ansys LS-DYNA has a limited capability to cope with this, but it is not good practice to rely on this behaviour.
   
   PRIMER uses exactly the same strategy as in #1 above: substitute a value of zero temporarily, then once (if) the parameter value is known it will re-evaluate the card(s) in question, rebuilding them with the new values. This can fail for the reasons given in pre-reading parameters above and using that feature may be a better strategy.
   
   
   
3. Parameters are multiply defined.
   
   Depending on the setting of the *PARAMETER_DUPLICATION card the initial definition may be retained and any subsequent ones ignored, or alternatively each new subsequent value will update the current parameter value - effectively making it "mutable". In the latter case the order in which parameters appear is significant.
   
   
   
4. Parameters are spread across multiple include files.
   
   On first reading the deck the order in which parameters are stored will depend on the order from which they are read from the various include files, so if include file order is changed subsequently this will change that order when it comes to output.
   

The order in which they are stored may not be the order in which they are subsequently output for the reasons given in the next section.

Output order of parameters in PRIMER

As the discussion above shows the order in which parameters are stored may or may not be significant, but what is more important is the order in which they are written out since that will determine how the subsequent Ansys LS-DYNA analysis "sees" them. The rules PRIMER uses are as follows:

• *PARAMETER cards are written out at the top of their file (after *KEYWORD and *TITLE)
  
  
• They are written in the order:
  
  - All plain parameters.
  - All _EXPRESSION parameters.
  
  
• However if an _EXPRESSION in a parent file refers to a parameter defined in a child include file then its output is deferred until after that include file's *INCLUDE statement.
  
  
• _MUTABLE parameters have separate rules and copies of these may be output immediately before they are referred to in order to ensure that the correct version of the parameter is used.

This may result in parameters being reordered with respect to the input file following a pass through PRIMER but this should not matter in itself. However this "keyout order" is important in the discussions below when checking and reordering of parameters is described.

Checking parameter order

The basic checking functions for parameters test for "referred to in a *PARAMETER_EXPRESSION before being defined" since this is illegal in Ansys LS-DYNA. If this situation is found you can:

• Ignore it. This might make sense if you know that you have only read part of a deck and errors and omissions are expected.
  
  
• Use the "auto-fix" to reorder parameters automatically. This tends to be successful if the referring and referred-to parameters are in the same include file, but if the problem is that they are in different include files then the only solution may be to change include file reading order or alternatively to move the offending parameter definitions to a different include file. It will not change include file order or contents so this problem will need to be fixed manually.
  
  
• Re-order parameters manually in the parameter editor. This is described below.

PRIMER does not currently check for a parameter being referred to on a normal data card (ie &name in a data field) before it is defined.

Re-ordering parameter definitions inside PRIMER Once inside PRIMER the order in which parameters are stored is irrelevant, since the code can access internal data in any order. However it contains logic to re-order parameters to deal with the problem of a *PARAMETER_EXPRESSION referring to another parameter that is defined after rather than before it. It can also check whether the order shown in the parameter editing table is in fact the order in which parameters will be output.
In this example parm_me is a parameter expression which refers to other parameters, and it has been moved up in the list so that it is "out of order", because it refers to parameters that are now below it, resulting in its " Move " button being coloured orange as shown here. This can be resolved as follows:
		Auto Re-order all will attempt to resort the parameter list automatically to resolve any ordering conflicts. It moves all plain (non _EXPRESSION ) parameters to the top of the list, and then tries to re-order any remaining _EXPRESSION definitions so that they only refer to their predecessors. It also resorts the list so that the order in this panel is the same as the order in which parameters will be output and hence reread. Check order checks the order of parameters and reports any discrepancies but does not actually reorder anything. It gives options to list details of ordering problems and also to reorder if required.
	Green means that the order is OK	Move provides a manual alternative to the above. Click on this button, and then use the keyboard up or down arrow keys to move this row up or down. Once the ordering conflict has been resolved the button will go green if it is in a correct position that can be achieved during keyout, or blue if you have resolved the sequence error but the position you have moved it to will not be achieved during keyout.
	Blue means it is not in keyout order, but is OK.
	Orange means it is out of order and is an error.

Internal order versus Keyout order, do the blue colours in the table matter?

So long as there are no orange entries in the parameter table and no sequence errors are reported when parameters are checked then no, it doesn't matter if the order in which parameters are stored inside PRIMER does not match the order in which they will be written out.

However you may wish to sort the internal list of parameters into the order in which they are written out for two reasons:

1. Consistency between how the output world, that is whatever reads the eventual output file, and the list here helps. Remember that if you write this model out and then reread it the effect will be to reorder to keyout order, so if you are comparing models this is likely to give more consistency.
   
   
2. It is easier to visualise sequence errors inside PRIMER if the order in this table matches keyout order.

Therefore it is recommended that if you have blue entries you use the Auto Reorder options to reorder, but this is only a recommendation - it is not necessary.

What happens to Parameters during a Units change operation

If a units change is applied to scale parameterised data fields, but the parameters themselves do not also have their values changed, then the association between the parameters and the data fields will be lost. PRIMER tries to handle this problem by inferring scale factors for parameters and hence scaling their values; this process is described in How Units change affects Parameters.

Parameters used in titles and other text strings

PRIMER does not attempt to evaluate parameters used in titles or other text strings, simply leaving them as "& name ". It also does not create a cross-reference between such usage and the parameter, meaning that they do not "know about one another" and a parameter used only in text strings will not be locked against deletion.

Ansys LS-DYNA handles "& name " in titles and text strings as follows:

• Release 971R4 (mid 2009) onwards will replace valid definitions with their numeric values. If "& name " is not a valid parameter then it will issue an error message and exit.
  
  
• Releases prior to this had inconsistent behaviour: some simply ignored "& name ", some attempted to substitute numeric values with varying degrees of success, some generated errors if "& name " was not a valid parameter definition and some did not seem to care.

Therefore from release 9.4 onwards PRIMER deals with "& name " in titles and text strings as follows:

• During normal interactive usage (editing, copying, etc) these definitions are simply reproduced verbatim and are treated as ordinary text strings with no special significance.
  
  
• During keyword output only for "& name " in a title or text string behaviour depends upon the primer*parameter_in_string preference:
  
  This preference can have one of four values:

The default AUTOMATIC output policy may not suit all possible circumstances, but it has the merit that it should prevent initialisation in Ansys LS-DYNA failing due to malformed text strings in titles.

It is recommended that you do not use the "&" character in titles and text strings unless you are certain that it prefixes a valid parameter name, and even then it may cause problems in all but the most recent versions of Ansys LS-DYNA.

Rules governing the length of *PARAMETER names

These rules have changed over the years as Ansys LS-DYNA has developed. A summary is

Therefore PRIMER adopts the following rules:

It is recommended to limit parameter names to a maximum of 9 characters, and to 7 characters if you want to use traditional "small" format without the need for promotion to "i10" or "large" formats (eg if you will write decks for reading by other software).

Reserved names that should not be used for parameters

We have received credible reports that certain versions of Ansys LS-DYNA will generate errors if "reserved" names are used for parameters. These names are:

• Intrinsic mathematical functions such as sin, cos, sqrt, etc.
• Names explicitly cited as reserved on the *DEFINE_FUNCTION keyword, such as PI, DTOR, etc
• Names that can be used in *DEFINE_CURVE_FUNCTION. such as DELAY, LC, etc

We have not been able to reproduce all these errors, but that is not the same as saying that they cannot occur in the right (or rather wrong) circumstances. Therefore as a precaution PRIMER checks for clashes and issues a warning during "check" operations if any are found. This warning may be reviewed or removed in future if it is proved to be wrong.

However whatever the elusive truth actually is it is *strongly* recommended that you do not use intrinsic mathematical function names for parameters that may be used in expressions. For example

If you have a parameter called SIN, then it would be possible to write a parameter expression "sin(SIN)", which is asking for trouble!