Tutorial: Abaqus CAE

While the core tutorials focus on script based, non-interactive workflows, it is possible to mix interactive and graphical elements into a workflow, too. Interactive tasks remove many of the benefits of a build system, such as large batch execution (parameter studies) and reproducibility. However, they are sometimes unavoidable.

An example of an unavoidable, non-graphical, interactive task is authentication against access controls like when a user is required to enter a password. Interactive tasks may also be necessary when the cost of scripting project files is prohibitively high. For example, a project may require editing binary files where the cost of scripting the edits is not justified, as when the files undergo whole-sale changes frequently, when the edits are difficult to program and require significant analyst judgement, or when large, legacy files are relatively static. In particular, proprietary binary files may be more convenient to edit with the tools provided by the proprietary graphical software, like geometric CAD files.

When adding interactive elements to a workflow, you can preserve some value of automation and reproducibility by limiting interactive tasks to the earliest portions of the workflow and putting interactively modified files under version control. The editing process may be interactive, but preserving the file with version control makes the downstream workflow reproducible for all project members. To regain the benefits of a build system, the downstream workflow must still be executable from a command line interface.

This tutorial will cover one possible solution to incorporate the graphical, interactive tasks of Abaqus model creation in Abaqus CAE with an automated, non-interactive job submission task. Similar solutions are limited by third-party interfaces, but should be possible in most cases where a scripting interface is available.

Environment

SCons and WAVES can be installed in a Conda environment with the Conda package manager. See the Conda installation and Conda environment management documentation for more details about using Conda.

Note

The SALib and numpy versions may not need to be this strict for most tutorials. However, Tutorial: Sensitivity Study uncovered some undocumented SALib version sensitivity to numpy surrounding the numpy v2 rollout.

1. Create the tutorials environment if it doesn’t exist

   $ conda create --name waves-tutorial-env --channel conda-forge waves 'scons>=4.6' matplotlib pandas pyyaml xarray seaborn 'numpy>=2' 'salib>=1.5.1' pytest
   

2. Activate the environment

   $ conda activate waves-tutorial-env
   

Some tutorials require additional third-party software that is not available for the Conda package manager. This software must be installed separately and either made available to SConstruct by modifying your system’s PATH or by modifying the SConstruct search paths provided to the waves.scons_extensions.add_program() method.

Warning

STOP! Before continuing, check that the documentation version matches your installed package version.

1. You can find the documentation version in the upper-left corner of the webpage.

2. You can find the installed WAVES version with waves --version.

If they don’t match, you can launch identically matched documentation with the WAVES Command-Line Utility docs subcommand as waves docs.

Directory Structure

3. Create the project directory structure and copy the tutorial files into the ~/waves-tutorials/tutorial_abaqus_cae sub-directory with the WAVES Command-Line Utility fetch subcommand.

$ waves fetch tutorials/tutorial_abaqus_cae --destination ~/waves-tutorials/tutorial_abaqus_cae
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae'
$ cd ~/waves-tutorials/tutorial_abaqus_cae
$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae

SConscript File

For this tutorial, we will not discuss the main SCons configuration file named SConstruct, which contains project setup boilerplate. Tutorial 00: SConstruct has a more complete discussion about the contents of the SConstruct file.

The SConscript file contains the workflow task definitions. This tutorial contains two sets of tasks. The first set of tasks prepare the Abaqus CAE cantilever beam model from the tutorials provided by the Abaqus documentation and retrieved with the fetch command [37]. These tasks are not strictly part of the tutorial. Instead they produce a job submission ready beam.cae file. See the Abaqus manual for a tutorial on using Abaqus CAE.

tutorial_abaqus_cae/SConscript

# Create the job-ready beam example CAE file
cae_prep.extend(
    env.Command(
        target=["beamExample.py"],
        source=["SConscript"],
        action=[
            "cd ${TARGET.dir.abspath} && ${abaqus} fetch job=beamExample",
            "echo \"mdb.saveAs(pathName='beam.cae')\" >> ${TARGET.abspath}",
        ],
        abaqus=env["ABAQUS_PROGRAM"],
    )
)

cae_prep.extend(
    env.AbaqusJournal(
        target=["beam.cae"],
        source=["beamExample.py"],
    )
)

The tutorial task is a single Abaqus journal file execution. It should look similar to the journal file tasks introduced in the core tutorials: Tutorial 01: Geometry and Tutorial 02: Partition and Mesh. You can read more about the behavior of the AbaqusJournal builder in the function API waves.scons_extensions.abaqus_journal_builder_factory() and the core tutorials.

tutorial_abaqus_cae/SConscript

# Run the tutorial CAE job submission solution
workflow.extend(
    env.AbaqusJournal(
        target=["beam.odb"],
        source=["submit_cae.py", "beam.cae"],
        subcommand_options="--input-file ${SOURCES[1].abspath} --job-name beam --model-name Beam",
    )
)

Abaqus Journal File

The Abaqus journal file is a small command line utility designed to open job submission ready CAE model files and submit the simulation. You can read more about journal file design in the core tutorials: Tutorial 01: Geometry and Tutorial 02: Partition and Mesh. This journal file shares many of the same features, such as docstrings for the API, a command line interface, default execution values, input file handling to avoid accidental source modification during workflow execution, and function separation to smaller unit tasks.

tutorial_abaqus_cae/submit_cae.py

import os
import sys
import shutil
import inspect
import tempfile
import argparse

import abaqus
import abaqusConstants
import job


default_model_name = "Model-1"
default_cpus = None


def main(input_file, job_name, model_name=default_model_name, cpus=default_cpus, write_inp=False, **kwargs):
    """Open an Abaqus CAE model file and submit the job.

    If the job already exists, ignore the model name and update the job options. If the job does not exist, create it
    using the job attributes passed in from the API/CLI, e.g. ``cpus`` and ``kwargs``.

    Because Abaqus modifies CAE files on open, a temporary copy of the file is created to avoid constant job rebuilds in
    build tools like SCons or Make.

    See ``mdb.Job`` in the "Abaqus Scripting Reference Guide" for job behavior and keyword arguments.

    :param str input_file: CAE file to open by absolute or relative path. Must include the extension.
    :param str job_name: The name of the Abaqus job
    :param str model_name: The name of the Abaqus model
    :param int cpus: The number of CPUs for the Abaqus solver
    :param bool write_inp: write an Abaqus ``job.inp`` file and exit without submitting the job
    :param kwargs: The ``abaqus.mdb.Job`` keyword arguments. If the job exists, these overwrite existing job
        attributes. If provided, the ``cpus`` argument overrides both existing job attributes _and_ the kwargs.
    """
    if cpus is not None:
        kwargs.update({"numCpus": cpus})

    with AbaqusNamedTemporaryFile(input_file=input_file, suffix=".cae", dir="."):

        if job in abaqus.mdb.jobs.keys():
            script_job = abaqus.mdb.jobs[job]
            script_job.setValues(**kwargs)
            model_name = script_job.model

        if model_name in abaqus.mdb.models.keys():
            script_job = abaqus.mdb.Job(name=job_name, model=model_name, **kwargs)
        else:
            raise RuntimeError("Could not find model name '{}' in file '{}'\n".format(model_name, input_file))

        if write_inp:
            script_job.writeInput(consistencyChecking=abaqusConstants.OFF)
        else:
            script_job.submit()
            script_job.waitForCompletion()


def get_parser():
    """Return parser for CLI options

    All options should use the double-hyphen ``--option VALUE`` syntax to avoid clashes with the Abaqus option syntax,
    including flag style arguments ``--flag``. Single hyphen ``-f`` flag syntax often clashes with the Abaqus command
    line options and should be avoided.

    :returns: parser
    :rtype: argparse.ArgumentParser
    """
    filename = inspect.getfile(lambda: None)
    basename = os.path.basename(filename)

    default_json_file = None

    prog = "abaqus cae -noGui {} --".format(basename)
    cli_description = (
        "Open an Abaqus CAE model file and submit the job."
        "If the job already exists, ignore the model name and update the job options. If the job does not exist, "
        "create it using the job attributes passed in from the API/CLI, e.g. ``cpus`` and ``kwargs``. "
        "Because Abaqus modifies CAE files on open, a temporary copy of the file is created to avoid constant job "
        "rebuilds in build tools like SCons or Make."
    )
    parser = argparse.ArgumentParser(description=cli_description, prog=prog)
    parser.add_argument(
        "--input-file",
        type=str,
        required=True,
        help="The Abaqus CAE model file with extension, e.g. ``input_file.cae``",
    )
    parser.add_argument(
        "--job-name",
        type=str,
        required=True,
        help="The name of the Abaqus job",
    )
    parser.add_argument(
        "--model-name",
        type=str,
        default=default_model_name,
        help="The name of the Abaqus model (default %(default)s)",
    )
    parser.add_argument(
        "--cpus",
        type=int,
        default=default_cpus,
        help="The number of cpus for the Abaqus simulation (default %(default)s)",
    )
    parser.add_argument(
        "--json-file",
        type=str,
        default=default_json_file,
        help="A JSON file containing a dictionary of keyword arguments for ``abaqus.mdb.Job`` " "(default %(default)s)",
    )
    parser.add_argument(
        "--write-inp",
        "--write-input",
        action="store_true",
        help="Write an Abaqus ``job.inp`` file and exit without submitting the job " "(default %(default)s)",
    )
    return parser


class AbaqusNamedTemporaryFile:
    """Open an Abaqus CAE ``input_file`` as a temporary file. Close and delete on exit of context manager.

    Provides Windows compatible temporary file handling. Required until Python 3.12 ``delete_on_close=False`` option is
    available in Abaqus Python.

    :param str input_file: The input file to copy before open
    """

    def __init__(self, input_file, *args, **kwargs):
        self.temporary_file = tempfile.NamedTemporaryFile(*args, delete=False, **kwargs)
        shutil.copyfile(input_file, self.temporary_file.name)
        abaqus.openMdb(pathName=self.temporary_file.name)

    def __enter__(self):
        return self.temporary_file

    def __exit__(self, exc_type, exc_val, exc_tb):
        abaqus.mdb.close()
        self.temporary_file.close()
        os.remove(self.temporary_file.name)


def return_json_dictionary(json_file):
    """Open a JSON file and return a dictionary compatible with Abaqus keyword arguments

    If the JSON file is ``None``, return an empty dictionary. Convert unicode strings to str. If a value is found in
    ``abaqusConstants`` convert the value.

    :param str json_file: path to a JSON file

    :returns: Abaqus compatible keyword argument dictionary
    :rtype: dict
    """
    kwargs = {}
    if json_file is not None:
        with open(json_file) as json_open:
            dictionary = json.load(json_open)
        for key, value in dictionary.items():
            if isinstance(key, unicode):
                key = str(key)
            if isinstance(value, unicode):
                value = str(value)
            if hasattr(abaqusConstants, value):
                value = getattr(abaqusConstants, value)
        kwargs[key] = value
    return kwargs


if __name__ == "__main__":
    parser = get_parser()
    try:
        args, unknown = parser.parse_known_args()
    except SystemExit as err:
        sys.exit(err.code)
    possible_typos = [argument for argument in unknown if argument.startswith("--")]
    if len(possible_typos) > 0:
        raise RuntimeError("Found possible typos in CLI option(s) {}".format(possible_typos))

    kwargs = return_json_dictionary(args.json_file)

    sys.exit(
        main(
            input_file=args.input_file,
            job_name=args.job_name,
            model_name=args.model_name,
            cpus=args.cpus,
            write_inp=args.write_inp,
            **kwargs  # fmt: skip
        )
    )

After command line utility design, Python coding practices, and the Python style guide, the most unique aspect of this journal file is the return_json_dictionary function. This is necessary to convert string based job arguments to Abaqus scripting objects found in the abaqusConstants module. In an active modsim project, this function would be broken into yet smaller units of re-usable work and placed in a shared utilities module as introduced in Tutorial 02: Partition and Mesh.

Here it is kept as a limited use function implemented directly in the calling script for the convenience of documenting this tutorial and maintaining the tutorial suite. See the ModSim Templates for examples of more re-usable utility functions and unit testing.

Building targets

The tutorial may be executed by a single call of the submit_beam_cae alias. However, to demonstrate the interactive use of a CAE file, a second alias is provided, create_beam_cae.

First, create the CAE file

$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae
$ scons create_beam_cae

This intermediate workflow will fetch the beamExample.py file from the Abaqus tutorial repository with abaqus fetch, append a CAE model save command, and execute the journal file. The Abaqus tutorial includes job execution with the name beam_tutorial, so you will see job output in the build directory along with the desired beam.cae file.

$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae
$ ls build/beam.cae
build/beam.cae
$ tree build/
build/
|-- SConscript
|-- abaqus.rpy
|-- beam.cae
|-- beam.cae.stdout
|-- beam.jnl
|-- beamExample.py
|-- beam_tutorial.com
|-- beam_tutorial.dat
|-- beam_tutorial.inp
|-- beam_tutorial.log
|-- beam_tutorial.msg
|-- beam_tutorial.odb
|-- beam_tutorial.prt
`-- beam_tutorial.sta

0 directories, 14 files

Take some time to open the CAE file and look for familiar CAE model and job data. Since this model is job ready, there is nothing to edit.

Finally, run the post-interactive workflow that is the subject of this tutorial

$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae
$ scons submit_beam_cae

This workflow calls the submit_cae.py journal file to submit the job defined in beam.cae. The new files should look identical (except for timestamps and job name) to the output produced by the beamExample.py job.

$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae
$ tree build -P "beam.*"
build
|-- beam.cae
|-- beam.cae.stdout
|-- beam.com
|-- beam.dat
|-- beam.inp
|-- beam.jnl
|-- beam.log
|-- beam.msg
|-- beam.odb
|-- beam.odb.stdout
|-- beam.prt
`-- beam.sta

0 directories, 13 files

To better understand the mixed workflow, open the build/beam.cae file and edit it with Abaqus CAE. When you’ve finished editing the file, save it, close Abaqus CAE, and re-run the scons submit_beam_cae command. Observe the SCons output during execution and the timestamp changes in the build directory. It should look similar to the example output below.

$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae
$ scons submit_beam_cae --debug=explain
scons: Reading SConscript files ...
Checking whether /apps/abaqus/Commands/abq2024 program exists.../apps/abaqus/Commands/abq2024
Checking whether abq2024 program exists...no
scons: done reading SConscript files.
scons: Building targets ...
scons: rebuilding `build/beam.odb' because `build/beam.cae' changed
cd /home/roppenheimer/waves-tutorials/tutorial_abaqus_cae/build && /apps/abaqus/Commands/abq2024 cae -noGui /home/roppenheimer/waves-tutorials/tutorial_abaqus_cae/build/submit_cae.py -- --input-file /home/roppenheimer/waves-tutorials/tutorial_abaqus_cae/build/beam.cae --job-name beam --model-name Beam > /home/roppenheimer/waves-tutorials/tutorial_abaqus_cae/build/beam.odb.stdout 2>&1
scons: done building targets.

Output Files

The full output directory should look like the following

$ pwd
/home/roppenheimer/waves-tutorials/tutorial_abaqus_cae
$ tree build
build
|-- SConscript
|-- abaqus.rpy
|-- abaqus.rpy.1
|-- beam.cae
|-- beam.cae.stdout
|-- beam.com
|-- beam.dat
|-- beam.inp
|-- beam.jnl
|-- beam.log
|-- beam.msg
|-- beam.odb
|-- beam.odb.stdout
|-- beam.prt
|-- beam.sta
|-- beamExample.py
|-- beam_tutorial.com
|-- beam_tutorial.dat
|-- beam_tutorial.inp
|-- beam_tutorial.log
|-- beam_tutorial.msg
|-- beam_tutorial.odb
|-- beam_tutorial.prt
|-- beam_tutorial.sta
`-- submit_cae.py

0 directories, 26 files