5.2 ABAQUS Scripting Interface documentation style

This section describes the style that is used to describe a command in the ABAQUS Scripting Reference Manual. You may want to refer to the ABAQUS Scripting Reference Manual while you read this section and compare the style of a documented command with the descriptions provided here. The following topics are covered:


5.2.1 How the commands are ordered

The following list describes the order in which commands are documented in the ABAQUS Scripting Reference Manual:


5.2.2 Access

The description of each object in the ABAQUS Scripting Reference Manual begins with a section that describes how you access an instance of the object. The import statements are provided for completeness. ABAQUS/CAE imports all modules when you start a session, and you do not need to include the import module name statement in your scripts. However, you must import the ABAQUS Scripting Interface Symbolic Constants with the following statement:

from abaqusConstants import *
These should be the first statement in all your ABAQUS Scripting Interface scripts.

The following is the access description for the Material object:

import material
mdb.models[name].materials[name]
The first line of the access description indicates the module that ABAQUS/CAE imported to make this object, and its methods and members, available to your script.

The access description also specifies where instances of the object are located in the data model. In the previous example the second line indicates how your script can access Material objects from a particular model. You must qualify a material object, command, or member with the variable mdb, as described in Functions and modules, Section 4.6.5. For example,

mdb.models[crash].Material[steel]
mdb.models[crash].materials[steel].Elastic(
    table=((30000000.0, 0.3), ))
elasticityType = mdb.models[crash].materials[steel].elastic.type

Similarly, if you are reading from an output database, the following is the access description for the HistoryRegion object:

import odbAccess
session.odbs[name].steps[name].historyRegions[name]
The first line indicates that ABAQUS/CAE imported the odbAccess module to make the Odb objects, methods, and members available to your ABAQUS Scripting Interface script. The second line indicates how your script can access HistoryRegion objects from a particular step.

The Access description for the FieldOutput object is

session.odbs[name].steps[name].frames[i].fieldOutputs[name]
The following statements show how you use the object described by this Access description:
sideLoadStep = session.odbs['Forming loads'].steps['Side load']
lastFrame = sideLoadStep.frames[-1]
stressData = lastFrame.fieldOutputs['S']
integrationPointData = stressData.getSubset(
    position=INTEGRATION_POINT)
invariantsData = stressData.validInvariants
  • The next to last line shows the getSubset method of the FieldOutput object.

  • The last line shows the validInvariants member of the FieldOutput object.


5.2.3 Path

A method that creates an object is called a “constructor.” The ABAQUS Scripting Interface uses the convention that constructors begin with an uppercase character. In contrast, methods that operate on an object begin with a lowercase character. The description of each constructor in the ABAQUS Scripting Reference Manual includes a path to the command. For example, the following describes the path to the Viewport constructor:

session.Viewport
Some constructors include more than one path. For example, you can create a datum that is associated with either a Part object or the RootAssembly object, and each path is listed.
mdb.models[name].parts[name].DatumAxisByCylFace
mdb.models[name].rootAssembly.DatumAxisByCylFace
The path is not listed if the method is not a constructor.

If you are using the ABAQUS Scripting Interface to read data from an output database, the objects exist when you open the output database, and you do not have to use constructors to create them. However, if you are creating or writing to an output database, you may need to use constructors to create new objects, such as part instances and steps. The documentation describes the path to the constructors that create objects in an output database.

For example, the Path description for the FieldOutput constructor is

session.odbs[name].steps[name].frames[i].FieldOutput
The following statement creates a FieldOutput object:
myFieldOutput = session.odbs[name].steps['Side load'].frames[-1].\
    FieldOutput(name='S', description='stress', 
    type=TENSOR_3D_FULL)


5.2.4 Arguments

The ellipsis (...) in the command description indicates that the command takes one or more arguments. For example, the Viewport constructor takes arguments.

Viewport(...)
In contrast, the makeCurrent method takes no arguments.
makeCurrent()

Some arguments of a command are required, and some arguments are optional. In the ABAQUS Scripting Reference Manual the required arguments are listed first, followed by the optional arguments. If the argument is optional, ABAQUS provides the documented default or initial value.

In most cases the documentation describes the “default value” of an argument to a method. The default value is the value used for an optional argument when you call a method and omit the argument.

Some objects have no constructors; ABAQUS creates the objects for you. For such objects the documentation describes the “initial value” of an optional argument. The initial value given for the argument is the initial value assigned to the corresponding member when ABAQUS creates the object. For example, the defaultViewportAnnotationOptions object has no constructor; ABAQUS creates the defaultViewportAnnotationOptions object when you start a session. When you create a new viewport, the settings are copied from the current viewport.

You can use the setValues method to modify the value of a member; for example, to modify the value of the triad member of the defaultViewportAnnotationsOptions object. When you call session.defaultViewportAnnotationOptions.setValues(triad=OFF), the value of the triad member is set to off. The other member values remain unchanged; this behavior is called “as is” behavior because the values remain “as is.” The setValuesInStep method displays similar “as is” behavior.

Keyword and positional arguments are described in Creating functions, Section 4.6.1. We recommend that you use keyword arguments since they can be supplied in any order and they make your scripts easier to read and debug; for example,

newViewport = session.Viewport(name='myViewport', 
    origin=(10, 10), width=100, height=50)
If you choose not to use keywords, the arguments must be provided in the order in which they are documented.
newViewport = session.Viewport('myViewport', 
    (10, 10), 100, 50)
You can use a combination of keyword and positional arguments. Keyword arguments can be supplied after positional arguments; however, positional arguments cannot be entered after keyword arguments. For example, you can use the following statement:
newViewport = session.Viewport('myViewport', 
    (10, 10), width=100, height=50)
However, you cannot use the following statement:
newViewport = session.Viewport(name='myViewport', 
    (10, 10), 100, 50)
You will find it easier to use keyword arguments so that you do not have to concern yourself with the positional requirements.


5.2.5 Return value

All commands return a value. Many commands return the None object described in Python None, Section 4.5.6. Constructors (methods that create an object) always return the object being created. The return value of a command can be assigned to a Python variable. For example, in the following statement the Viewport constructor returns a Viewport object, and the variable newViewport refers to this new object.

newViewport = session.Viewport(name='myViewport', 
    origin=(10, 10), width=100, height=50)
You can use the object returned by a command in subsequent statements. For example, the titlebar member of a Viewport object is a Boolean specifying whether the viewport title bar is displayed and can have a value of either ON or OFF. The following statement tests the titlebar member of the new viewport created by the previous statement:
if newViewport.titleBar:
    print 'The title bar will be displayed.'