Scripting Parametric Studies

Use the aStudy=ParStudy scripting command (see aStudy=ParStudy()) to create a parametric study and select the independent parameters to be considered for variation. aStudy is the Python variable name assigned by you to the parametric study object created by the command. The methods of the parametric study object are used to carry out all the actions of the parametric study.

aStudy=ParStudy (par=, name=, verbose=, directory=)

Use the aStudy.define command (see aStudy.define()) to specify the parameter type (choose the CONTINUOUS or the DISCRETE token; a token is a symbolic constant used to select an option within a specific command) and, optionally, to specify the domain of possible parameter values and a reference value for the parameter. If the domain and/or reference value are not specified in this command, they can be specified in the parameter sampling.

Redefinitions of a parameter are treated as complete redefinitions; that is, no information is retained from the previous definition of that parameter.

aStudy.define (token, par=, domain=, reference=)

Use the aStudy.sample command (see aStudy.sample()) and choose one of the available tokens (INTERVAL, NUMBER, REFERENCE, or VALUES) to select how the sampling is done. The sampling data that must be given depend on how the sampling is done, as described next.

aStudy.sample (INTERVAL, par=, interval=, domain=)

aStudy.sample (NUMBER, par=, number=, domain=)

aStudy.sample (REFERENCE, par=, reference=, interval=, numSymPairs=, domain=)

aStudy.sample (VALUES, par=, values=)

Use the aStudy.combine command (see aStudy.combine()) to create sets of design points from the parameter samples. Choose how the combining is done using one of the following tokens: MESH, TUPLE, or CROSS. The use of each combination command results in the creation of a number of design points, which are grouped into design sets. If a combine operation creates a design that duplicates a design in an existing design set, the duplicate design is deleted immediately. The total number of designs in a parametric study (before the application of any design constraints) is the sum of the number of designs in each design set.

You can name a design set; if you do not, it is named by default. The default naming convention is p1 for the first non-user-named design set in the parametric study, p2 for the second non-user-named design set, and so on. The design set name is used to help identify individual designs. A design set named by you with a name identical to a previously specified design set name indicates that it is a respecification of the design set and, thus, overwrites the previously existing one.

aStudy.combine (token, name=)

MESH Combination

This combine option indicates that every sampled value for a parameter is to be combined with every sampled value of every other parameter in the parametric study.

The following examples illustrate the use of the MESH combine option. In a two-parameter study with the parameters defined and sampled as

study=ParStudy(par=('par1', 'par2')) 
study.define(DISCRETE, par='par1', 
    domain=(1, 3, 5, 7, 9, 11, 13)) 
study.sample(REFERENCE, par='par1', reference=0,
    interval=2, numSymPairs=2)
study.define(CONTINUOUS, par='par2', domain=(10., 60.)) 
study.sample(INTERVAL, par='par2', interval=20.)

the combine command

study.combine(MESH, name='dSet1')

creates the following 12 design points (par1, par2): (1, 10.), (5, 10.), (9, 10.), (1, 30.), (5, 30.), (9, 30.), (1, 50.), (5, 50.), (9, 50.), (1, 60.), (5, 60.), and (9, 60.) (see Figure 1).

Figure 1. Design points in design set dSet1 created with the MESH option of the combine command.

A second use of the combine command preceded by a respecification of the parameter sampling

study.sample(NUMBER, par='par1', number=3) 
study.sample(NUMBER, par='par2', number=3) 
study.combine(MESH, name='dSet2')

creates designs at the following nine points: (1, 10.), (7, 10.), (13, 10.), (1, 35.), (7, 35.), (13, 35.), (1, 60.), (7, 60.), and (13, 60.) (see Figure 2). The extreme and center values of both parameters are combined.

Figure 2. Design points in design set dSet2 created with the MESH option of the combine command after the parameter sampling is redefined.

TUPLE Combination

This combine option creates design sets consisting of n-tuples of the sampled parameter values, where n is the number of parameters in the parametric study. Each n-tuple consists of one sampled value for each parameter. For example, in a three-parameter study the first sampled value of each of the three parameters makes up the first 3-tuple, the second sampled value of each of the three parameters makes up the second 3-tuple, and so on. The creation of tuples ceases when any of the parameter samples runs out of sampled values.

The following examples illustrate the use of the TUPLE combination operation. For a two-parameter study with the parameters defined and sampled as

study=ParStudy(par=('par1', 'par2')) 
study.define(DISCRETE, par='par1', 
    domain=(1, 3, 5, 7, 9, 11, 13)) 
study.define(CONTINUOUS, par='par2', domain=(10., 60.)) 
study.sample(INTERVAL, par='par1', interval=1) 
study.sample(INTERVAL, par='par2', interval=10.)

the combination operation

study.combine(TUPLE, name='dSet3')

creates designs at the following 6 points: (1, 10.), (3, 20.), (5, 30.), (7, 40.), (9, 50.), and (11, 60.) (see Figure 3). This represents a diagonal pattern in the two-parameter space. We see that all par2 values are used in the tuple combination but the last par1 value is not used because there are no more par2 sample values to form additional tuples.

Figure 3. Design points in design set dSet3 created with the TUPLE option of the combine command.

A second invocation of the above combine command after respecifying the par2 sampling as

study.sample(INTERVAL, par='par2', interval=-10.) 
study.combine(TUPLE, name='dSet4')

creates designs at the following 6 points: (1, 60.), (3, 50.), (5, 40.), (7, 30.), (9, 20.), and (11, 10.) (see Figure 4). This represents the other diagonal in the two-parameter space.

Figure 4. Design points in design set dSet4 created with the TUPLE option of the combine command after the parameter sampling is redefined.

CROSS Combination

This combine option creates designs in the form of “cross-shaped” patterns as follows: each value sampled for an individual parameter is combined with the reference value, as specified in the define command, of all the other parameters used in the parametric study. To use the CROSS combine option, it is necessary to specify a reference value in the define command for all parameters in the parametric study.

The reference value specified for a parameter in the define command does not have to coincide with a value sampled by that parameter's sampling rule. However, if the reference value does not coincide with a sampled value, the reference parameter value is not added to the list of sampled values for that parameter; it is used only to form the CROSS combination.

The following examples illustrate the use of the CROSS combine option. For a two-parameter study with the parameters defined and sampled as

study=ParStudy(par=('par1', 'par2')) 
study.define(DISCRETE, par='par1', 
    domain=(1, 3, 5, 7, 9, 11, 13), reference=3) 
study.define(CONTINUOUS, par='par2', 
    domain=(10., 60.), reference=40.) 
study.sample(REFERENCE, par='par1', interval=1,
    numSymPairs=3) 
study.sample(INTERVAL, par='par2', interval=10.)

the combine cross option

study.combine(CROSS, name='dSet5')

creates designs at the following 12 points: (1, 40.), (3, 40.), (5, 40.), (7, 40.), (9, 40.), (11, 40.), (13, 40.), (7, 10.), (7, 20.), (7, 30.), (7, 50.), and (7, 60.) (see Figure 5). This combination is a cross-shaped pattern where the cross intersection is at (7, 40.) as specified [7 is the fourth value (reference=3) of the discrete parameter par1].

Figure 5. Design points in design set dSet5 created with the CROSS option of the combine command.

A second invocation of the above combine command after respecifying par2 as

study.define(CONTINUOUS, par='par2', domain=(10., 60.),
    reference=45.) 
study.combine(CROSS, name='dSet6')

creates designs at the following 13 design points: (1, 45.), (3, 45.), (5, 45.), (7, 45.), (9, 45.), (11, 45.), (13, 45.), (7, 10.), (7, 20.), (7, 30.), (7, 40.), (7, 50.), and (7, 60.) (see Figure 6).

Figure 6. Design points in design set dSet6 created with the CROSS option of the combine command when the parameter par2 is redefined.

A constraint that determines the allowable design points in the parametric study can be specified using the aStudy.constrain scripting command (see aStudy.constrain()). When such a constraint is specified, existing designs that violate the constraint are eliminated immediately.

For example, the constrain command

aStudy.constrain('height*width < 12.')

where height and width are parameters in the parametric study, can be used to enforce that the cross-sectional area of a rectangular beam must be less than 12.0 in all designs.

aStudy.constrain ('constraint expression')

Use the aStudy.generate scripting command (see aStudy.generate()) to generate an input file for each design.

The name of the parametrized template input file from which the input files of each design are generated must be specified.

The naming convention for the input files generated by the parametric study is as follows:

• The name of each analysis job will start with the template input file name; for example, shell.

• The name of the parametric study (specified by you in the ParStudy command using the name= option) is appended, preceded by an underscore (_); for example, shell_thickness for a parametric study defined with the study = ParStudy(name='thickness') command. (If no parametric study name has been given, the parametric study name defaults to the name of the Python script file in which the study is defined.) If the template input file name and parametric study name are the same, the name is not repeated.

• The name of the design set (specified or created by default in the combine command) is appended, preceded by an underscore (_); for example, shell_thickness_p1 for the first design set (named by default) of the above parametric study.

• The design name (created automatically in the combine command) is appended, preceded by an underscore (_); for example, shell_thickness_p1_c1 for the first design in the first design set of the above parametric study.

As usual, the input files each have the extension .inp. You can examine and/or edit these input files before execution.

The generate command creates a file with the .var extension that contains a description of the parametric study. This file is given the parametric study name—for example, studyName.var—and contains a list of all the designs generated, together with the parameter values associated with each design. You can examine and/or edit this file; however, editing this file will affect the gathering of results across the designs of the parametric study (see “Gathering results”).

Each time the generate command is used, new versions of the studyName.var files are created reflecting the designs specified by all previous combine commands.

The define, sample, and combine steps are performed before the generate command is executed. It is, thus, possible for you to refer to parameters that do not exist or are not independent parameters in the template input file. These errors are detected and flagged by the generate command.

aStudy.generate (template)

Use the aStudy.execute command (see aStudy.execute()) to execute the analysis of the designs of the study.

The command will submit a number of analysis jobs for execution under the control of a Python process. All designs can be evaluated without further user interaction by specifying the ALL or DISTRIBUTED options of this command, or you can control the execution of the analyses interactively by specifying the INTERACTIVE option. In the interactive case you are prompted for further execution instructions. The prompt allows you to:

• Specify a number of analyses to be executed before the process pauses and prompts you again.

• Execute the remaining analyses without further user interaction.

• Specify a number of analyses whose execution is to be skipped before the process pauses and prompts you again.

• Stop execution.

The interactive option is useful because it provides the opportunity to:

• Study the results of the analyses already executed.

• Delete unnecessary files generated by the analyses to conserve disk space when many designs are being analyzed.

• Analyze only certain designs of the parametric study.

The ALL and INTERACTIVE tokens are used for sequential execution of the Abaqus analyses on your machine. The DISTRIBUTED token can be used to schedule analysis jobs on multiple machines or multiple CPUs of one machine.

The DISTRIBUTED option is available only on variants of the Linux operating system. In particular the implementation depends on the operating system for support of the rsh, rcp, and xhostLinux commands. Because of the use of these commands, it is necessary that for distributed execution of parametric studies the parametric study must itself be executed on your local computer. If binary results are output during the analyses, both the local and remote computers must be binary compatible. Before the distributed execution capability can be used, it is necessary to configure the appropriate queue interfaces in the Abaqus environment file.

Each analysis of a design of the parametric study that is executed when you issue the execute command is, by default, executed by Abaqus in background mode, irrespective of the command option used. Files created by the Abaqus analysis of each design will overwrite any existing files of the same name without you being prompted.

You can add any necessary Abaqus execution options (refer to Abaqus/Standard and Abaqus/Explicit Execution) to the execution command for each of the analyses by specifying them with the execOptions option.

aStudy.execute (token, files= , queues= , execOptions= )

Use the aStudy.gather command (see aStudy.gather()) to gather results from the results file or output database of each of the analyses.

In each use of the gather command you must specify a name that is associated with the gathered result record. This label is used to refer to the results record in the report commands.

When gathering results from the results (.fil) file, each result record to be gathered must be chosen by specifying one of the available output variable identifier keys appearing under the .fil column heading in Abaqus/Standard Output Variable Identifiers or Abaqus/Explicit Output Variable Identifiers. For example, the U or S variable identifier keys can be specified, but the U1 or S11 variable identifier keys cannot be specified. In addition, the MODAL variable identifier key can be specified to gather eigenvalue results records (those written to the results file with the record key 1980); in this case, no variable location data are required.

When gathering results from the output (.odb) database, each result record to be gathered is chosen by specifying one of the available output variable identifier keys appearing under the .odb column heading in Abaqus/Standard Output Variable Identifiers or Abaqus/Explicit Output Variable Identifiers. For field output the component must not be specified, while for history output the component number is required; for example, the U or S variable identifier keys can be specified for field output, while the U1 or S11 variable identifier keys can be specified for history output. Unless the output is at the assembly level, an instance name must be provided as an argument to the gather command. An exception to this instance-name requirement is the case where the output (.odb) database is generated from a model not defined as an assembly of part instances, which is inferred from the presence in the output database of a single assembly named Assembly-1 and a single part instance named PART–1–1. In this case you need not explicitly refer to the instance PART–1–1.

The names of components of the result records are created automatically. For example, the command

myStudy.gather(results='e52_stress', variable='S', element=52)

creates a result record e52_stress whose six components (in the case of a three-dimensional solid element) are named: e52_stress.1 (the S11 stress component), e52_stress.2 (the S22 stress component), e52_stress.3 (the S33 stress component), e52_stress.4 (the S12 stress component), e52_stress.5 (the S13 stress component), and e52_stress.6 (the S23 stress component).

The variable location data that must be given depend on the output variable identifier key specified. (Refer to aStudy.gather() for a description of the location data.) Enough variable location data must be given to define a unique result record.

aStudy.gather (request=, results=, step=, frameValue= | inc= | mode=,
variable=, additional location data)

Use the aStudy.report scripting command (see aStudy.report()) to report results gathered from the results files of the parametric study. Use the PRINT, FILE, or XYPLOT options to specify the kind of report to be produced:

• PRINT indicates that a table of results (with headings) is to be printed to the default output device (the screen). You may wish to limit the number of columns in a table so as to make the table readable.

• FILE indicates that a table of results (with headings) is to be written to an ASCII file.

• XYPLOT indicates that a table of results (without headings) is to be written to an ASCII file.

Each row in a table represents a design in the parametric study. A column in a table can represent values of a parameter, values of a gathered result, or design names.

One or more parameters can be specified in the report command. If no parameters are specified, the default is that all parameters in the parametric study are included in the table. The column corresponding to each parameter shows the value of that parameter in each of the designs included in the table.

A design set name can be specified to restrict the rows in the table to designs that are part of the set (refer to the combine command described earlier). If a design set is not specified, the default is that all designs are included in the table.

Use variations=ON to specify that the first column in a table must show the design names. If variations=ON is not specified or variations=OFF is included, the column of design names is not included in the table.

The names of the results to be reported must be specified as a sequence; for example, the von Mises stress of element 33, the S22 stress of element 52, and the U3 displacement of node 10 are gathered in the following three separate commands:

myStudy.gather(results='e33_sinv', variable='SINV', element=33) 
myStudy.gather(results='e52_s', variable='S', element=52) 
myStudy.gather(results='n10_u', variable='U', node=10)

These results can be printed in a single table using the following report command:

myStudy.report(PRINT, 
    results=('e33_sinv.1', 'e52_s.2', 'n10_u.3'))

This example shows not only how gathered results of different types (element, nodal, etc.) can be collected in a single table but also how to refer to components of results records (the von Mises stress is the first component of SINV, S22 is the second component of S, and U3 is the third component of U—refer to Results File or the for a description of how the results are stored in the results file and the output database, respectively).

When either the FILE token or the XYPLOT token is used, a file name must be given to specify the file to which the results are to be written. A subsequent report command issued in the same session using the same file name will append the new results to the file. However, a subsequent report command issued in a different session using the same file name overwrites the existing file.

aStudy.report (token, results=, par=, designSet=, variations=, file=)

You may want to gather and report results multiple times, after the parametric variations of the study have been executed. It is possible to define, generate, and execute a parametric study in one session and gather and report results in a separate session. Only the command used to create the parametric study needs to be reissued when you start a new session.

Comments must be preceded by the # symbol. The comment is understood to continue to the end of the line. For example,

# 
# This parametric study ... 
# 
studyTempEffects.generate(template='shell') #use shell input file

All variable and method names, tokens, and character string literals are case sensitive across all operating systems. For example,

study.execute( ) # is valid 
study.Execute( ) # is not valid because of the capital E

study.sample(NUMBER, ...) # uses the valid token NUMBER
study.sample(number, ...) # lower case token is not valid 

study.generate(template='aFile') # 'aFile' is different 
study.generate(template='afile') # from 'afile'

Character strings are indicated by using paired single (' ') or double (” ”) quotation marks. Backward single quotation marks (` `) cannot be used for this purpose. For example,

"double quoted string" 
'single quoted string' 

The Python print command can be used to obtain a printed representation of any Python object. For example,

print 'MY TEXT'

will print MY TEXT on the standard output device.

The scripting methods for parametric studies accept integer, real, and character string types. These primitive types can, in many cases, optionally be contained within tuple or list structures. Although there are some differences between lists and tuples in Python, they can be used interchangeably in the parametric study scripting commands; they simply represent ordered sequences of items. Items in lists or tuples must be separated by commas and enclosed in parentheses or brackets. For example,

aStudy.define(CONTINUOUS, par=('xCoord',))# tuple contains a 
                                          # single string item 
aStudy.define(CONTINUOUS, par=['xCoord']) # list contains a 
                                          # single string item 
aStudy.define(CONTINUOUS, par=('xCoord', 'yCoord')) # tuple  
aStudy.define(CONTINUOUS, par=['xCoord', 'yCoord']) # list

Python uses indentation to group blocks of statements. Therefore, a Python statement should begin in the same column as the preceding statement except where grouping of statements is required by Python.

A parametric study has the following repositories and objects as data members:

• aStudy.parameter: A repository for parameter objects keyed by parameter name. Each parameter object has a name, type, domain, reference, and sample data member.

• aStudy.designSet: A repository for design sets keyed by design set name. Each design set is represented as a list of design points.

• aStudy.job: A repository for analysis job objects keyed by the name of the corresponding analysis input file name (without the .inp extension). Each job object has a design, status, root, designSet, and designName data member.

• aStudy.resultData: A repository for result records keyed by a name constructed by successively appending the result name, the underscore character (_), and the design name. For results retrieved from the result (.fil) file, each result record is in the format of the result (.fil) file record for the corresponding output variable. For field results retrieved from the output (.odb) database, each result record will be a tuple containing the components of the results. The result record for history results from the output (.odb) database, which can only be retrieved for a single component, will be a tuple containing a single value.

• aStudy.table: A table object containing a representation of the table formatted by the last use of the report command. The table object has title, variation, designs, and results data members.