Manipulating Fields for Boundary Conditions

ACT provides an API that enables you to manipulate boundary condition fields, managing the various time-, space-, or frequency-dependent values of boundary conditions during a simulation. A field has one or more inputs and a single output.

Mathematically speaking:

output = F(input1, input2, ...) 

Where F is the boundary condition field.

As with other types of ACT functionality available in Mechanical, the API-based actions for editing boundary condition fields mirror the actions that can be performed manually in the Mechanical GUI. The ACT API provides you with the capabilities of:

Input and Output Variables

The inputs and output are represented by objects of the type Variable. Input variables represent the various input values over the course of the simulation. Output variables represent the various values of the boundary conditions with regard to the input values.

For example, assume time is an input variable representing the various time values (in seconds) and magnitude is an output variable representing the magnitude of a force over time.

Variable Definition Types

The ACT API enables you to set input and output variables to one of three variable definition types (or modes):

Discrete

The variable contains a discontinuous set of values. By default, most variables are initially defined as discrete.

Formula

The variable is a continuous function depending on inputs, such as. time*10.

Free

Determines the selection’s freedom to move along the specified plane. This variable definition type (mode) is available only for certain boundary conditions such as displacements. It is not available for force or pressure.

Input Loading Data Definitions

For input variables, each variable definition type (or mode) corresponds to one of the input loading data definition options available in the Mechanical Details view. You can determine the loading data definition options available for a given input by checking its drop-down in the Mechanical GUI.

Input loading data definitions are ranked in terms of complexity:

ComplexityVariable Definition TypeInput Loading Data DefinitionDescription

1

Discrete

Constant (ramped)

Two values, with the first value always 0.

2

Discrete

Constant (time-stepping)

One value.

3

Discrete

Tabular

Values listed in tabular format.

4

Formula

Function

Values generated by the expression assigned to the variable.

NA

Free

NA

Indicates that the selection can move freely along the specified plane. (A value of 0 indicates that movement is fully constrained.)

Not supported by all types of boundary conditions.

When you use the ACT API to define boundary condition fields, ACT automatically opts for the least complex loading data definition that is applicable to the input. For example, if a given input could be defined as Constant (ramped) but you execute commands defining it as Tabular, ACT defines the input as Constant (ramped).

Setting the Variable Definition Type

The property Variable.DefinitionType provides both get and set capabilities, enabling you to set input variables to one of three variable definition types (which also specifies a corresponding input loading data definition) and then verify the variable type and definition in the ACT Console.


Note:  You can also change the variable definition type to Discrete or Free by using the property Variable.DiscreteValues as described in Setting Discrete Values for Variables.


Creating a Displacement and Verifying Its Variable Definition Types

You start by creating a displacement:

d=ExtAPI.DataModel.Project.Model.Analyses[0].AddDisplacement()

In Mechanical, you can see that by default, the variable definition types for the displacement’s X, Y, and Z components are set to Free.

You can verify this by executing the following commands in the ACT Console, one at a time.

d.XComponent.Output.DefinitionType
d.YComponent.Output.DefinitionType
d.ZComponent.Output.DefinitionType

In the following image, each of the variable’s components has a variable definition type of Free.


Note:  Even though the query d.XComponent.Output would produce the same output in the console when the component is Free, be aware that it returns an instance of the Variable class. This object is then converted into a string by the ACT Console. Appending .DefinitionType to the query consistently returns the actual enum value, whatever the mode.


Changing the Y Component from Free to Discrete and Verifying

Next, you change the variable definition type for the Y component from Free to Discrete and then verify the definition type change and the output values in the ACT Console:

d.YComponent.Output.DefinitionType =VariableDefinitionType.Discrete
d.YComponent.Output.DefinitionType
d.YComponent.Output

In the following image, you can see that:

  • The Y Component is set to Tabular Data because tabular data is the least complex discrete loading data definition that is applicable to this input.

  • The Tabular Data window is now populated with output values of 0 and 0. You can verify in the ACT Console that the output values are 0 and 0.

  • You can verify in the ACT Console that the variable definition type is set to Discrete.

Changing the Y Component Back to Free and Verifying

Finally, you change the variable definition type for the Y output from Discrete back to Free and verify the change in the ACT Console:

d.YComponent.Output.DefinitionType = VariableDefinitionType.Free
d.YComponent.Output.DefinitionType

In the following image, you can see that the Y Component is set back to Free and the Tabular Data window is now empty.

Setting Discrete Values for Variables

The property Variable.DiscreteValues provides both get and set capabilities for both input and output variables. Behavior of these capabilities varies according to whether it is being performed on an input or an output variable.

Getting and Setting Discrete Values for an Input Variable
Getting Discrete Input Values

You can get the discrete input values for a given input variable. For example, a force in a one-step analysis looks similar to the following image by default. The two rows in the Tabular Data window correspond to the discrete values of the single input variable, with 0s as the start time of the first step and 1s as the end time of the last step.


Note:  With a three-step analysis, you’d see four values by default: the start time and three end times (one end time for each step).


Setting Discrete Input Values

You can change discrete values for a given input variable. For example, the following code sample would add a discrete value, inserting a value of t=0.5s without defining an additional step in the analysis. In the following image, you can see that:

  • There is a new row for t=0.5.

  • The output cell for row t=1 has a yellow background. This is because a value has not been set for the output variable.

Removing Discrete Values

You can also remove a discrete value, deleting a row by defining a shorter list of values for the input variable. In the following image, you can see that:

  • You’ve specified a list with a single value, indicating that the other rows should be removed.

  • Although a single row is specified, two rows are still showing in the TabularData window. The value =0 is actually a repeat of the value in the row above and does not correspond to an actual value stored for the variable. This is because the tabular data in Mechanical always displays a row for time values that correspond to step end times.

Getting and Setting Discrete Values for an Output Variable

Output variables are not limited to the Discrete variable definition type, so the behavior when getting and setting outputs is slightly different from that of inputs.

Getting Discrete Output Values

The following table shows how the get capability behaves for the different variable definition types.

Variable Definition TypeBehavior

Discrete

Same as described earlier for getting discrete input values.

Free

For C#, the property returns null. For Python, the property returns None.

Formula

The property returns the series of variable values.

Setting Discrete Output Values

The following table shows how the set capability behaves according to the content of the list provided to the property.

List ContentBehavior

None or null

The variable is switched to the Free definition type if it is supported by the boundary condition. Otherwise, an error is issued.

Single Quantity object

The variable is switched to the Constant definition type if supported in the GUI. Otherwise, Constant (ramped) can be chosen. If neither of those two types are supported, Tabular Data is the default.

Two Quantity objects, with the first value being 0

The variable is switched to Constant (ramped) if supported in the GUI. Otherwise, Tabular Data is the default.

As many Quantity objects as Discrete values for the input variables

The variable is switched to Tabular Data.

Does not fall into any of the above categories

An error is issued, indicating that you should either:

  • Provide the appropriate number of values.

  • Change the number of input values first, as the input value count is used to determine the row count of the tabular data. Output values must then comply with this number of rows.

For a sample message, see the following image.

Setting Variable Definition Type by Acting on Discrete Values

Because values are interconnected with variable definitions, you can use the property Variable.DiscreteValues as an alternate way of switching your variable definition type. To set a variable to a particular variable type, you set the values that are consistent with that variable type. Examples follow:

  • To set an input variable to Tabular Data, assign values in tabular format:

    d.XComponent.Output.DiscreteValues = [Quantity("1 [m]"), Quantity("10 [m]")]
  • To set a variable to Free, assign None to its DiscreteValues:

    d.XComponent.Output.DiscreteValues = None

Release 18.2 - © ANSYS, Inc. All rights reserved.