Tutorial: Part Image

Tutorial: Part Image#

This is an example implementation where an Abaqus Python script is used to export an assembly view image of an Abaqus model from an input or CAE file.

References#

Below is a list of references for more information about topics that are not explicitly covered in this tutorial.

Abaqus Scripting [42]
Abaqus Python Environment [42]

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.

Create the tutorials environment if it doesn’t exist

Linux/MacOS

$ 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

Windows

PS > conda create --name waves-tutorial-env --channel conda-forge waves scons matplotlib pandas pyyaml xarray seaborn numpy salib pytest

Activate the environment

Linux/MacOS

$ conda activate waves-tutorial-env

Windows

PS > 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.

Directory Structure#

Create and change to a new project root directory to house the tutorial files if you have not already done so. For example

Linux/MacOS

$ mkdir -p ~/waves-tutorials
$ cd ~/waves-tutorials
$ pwd
/home/roppenheimer/waves-tutorials

Windows

PS > New-Item $HOME\waves-tutorials -ItemType "Directory"
PS > Set-Location $HOME\waves-tutorials
PS > Get-Location

Path
----
C:\Users\roppenheimer\waves-tutorials

Note

If you skipped any of the previous tutorials, run the following commands to create a copy of the necessary tutorial files.

$ pwd
/home/roppenheimer/waves-tutorials
$ waves fetch --overwrite --tutorial 12 && mv tutorial_12_archival_SConstruct SConstruct
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

Download and copy the tutorial_12_archival.scons file to a new file named tutorial_part_image.scons with the WAVES Command-Line Utility fetch subcommand.

$ pwd
/home/roppenheimer/waves-tutorials
$ waves fetch --overwrite tutorials/tutorial_12_archival.scons && cp tutorial_12_archival.scons tutorial_part_image.scons
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

Part-Image script#

In the waves-tutorials/modsim_package/abaqus directory, create a file called export_abaqus_image.py using the contents below which contains the main() function.

waves-tutorials/modsim_package/abaqus/export_abaqus_image.py

"""Save an assembly view image of an Abaqus model from an input or CAE file."""

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

import abaqus
import abaqusConstants

import modsim_package.abaqus.abaqus_utilities as abaqus_utilities

default_x_angle = 0.0
default_y_angle = 0.0
default_z_angle = 0.0
default_image_size = (1920, 1080)
default_model_name = "Model-1"
default_part_name = "Part-1"
cli_description = "Save an assembly view image of an Abaqus model from an input or CAE file"

# One time dump from abaqus.session.viewports['Viewport: 1'].colorMappings.keys()) to stay Python 3 compatible for
# Sphinx documentation
# fmt: off
color_map_choices = [
    "Material", "Section", "Composite layup", "Composite ply", "Part", "Part instance", "Element set",
    "Averaging region", "Element type", "Default", "Assembly", "Part geometry", "Load", "Boundary condition",
    "Interaction", "Constraint", "Property", "Meshability", "Instance type", "Set", "Surface", "Internal set",
    "Internal surface", "Display group", "Selection group", "Skin", "Stringer", "Cell", "Face"
]
# fmt: on


def main(
    input_file,
    output_file,
    x_angle=default_x_angle,
    y_angle=default_y_angle,
    z_angle=default_z_angle,
    image_size=default_image_size,
    model_name=default_model_name,
    part_name=default_part_name,
    color_map=color_map_choices[0],
):
    """Save an assembly view image of an Abaqus model from an input or CAE file.

    Open an Abaqus CAE ``*.cae`` or input ``*.inp`` file and save an assembly view image.
    Abaqus CAE files are copied to a temporary file before opening to avoid file modification, which is necessary for
    compatibility with build systems such as SCons.

    :param str input_file: Abaqus input file. Supports ``*.inp`` and ``*.cae``.
    :param str output_file: Output image file. Supports ``*.png`` and ``*.svg``.
    :param float x_angle: Rotation about X-axis in degrees for ``abaqus.session.viewports[].view.rotate`` Abaqus Python
        method
    :param float y_angle: Rotation about Y-axis in degrees for ``abaqus.session.viewports[].view.rotate`` Abaqus Python
        method
    :param float z_angle: Rotation about Z-axis in degrees for ``abaqus.session.viewports[].view.rotate`` Abaqus Python
        method
    :param tuple image_size: Tuple containing height and width of the output image in pixels
    :param str model_name: model to query in the Abaqus model database
    :param str part_name: part to query in the specified Abaqus model
    :param str color_map: color map key

    :returns: writes image to ``{output_file}``
    """
    input_file_extension = os.path.splitext(input_file)[1]
    if input_file_extension.lower() == ".cae":
        with AbaqusNamedTemporaryFile(input_file=input_file, suffix=".cae", dir="."):
            image(
                output_file,
                x_angle=x_angle,
                y_angle=y_angle,
                z_angle=z_angle,
                image_size=image_size,
                model_name=model_name,
                part_name=part_name,
                color_map=color_map,
            )
    elif input_file_extension.lower() == ".inp":
        abaqus.mdb.ModelFromInputFile(name=model_name, inputFileName=input_file)
        image(
            output_file,
            x_angle=x_angle,
            y_angle=y_angle,
            z_angle=z_angle,
            image_size=image_size,
            model_name=model_name,
            part_name=part_name,
            color_map=color_map,
        )
    else:
        sys.exit("Unknown file extension {}".format(input_file_extension))

The export_abaqus_image.py file is an Abaqus journal file. The top of the file imports standard library modules, Abaqus modules, and the abaqus_utilities.py module create in Tutorial 02: Partition and Mesh. The main() function takes two required arguments: input_file which is an Abaqus CAE *.cae or Abaqus input *.inp file and output_file which is the file path of the assembly view image that this function will create.

In the waves-tutorials/modsim_package/abaqus directory, continue editing the file export_abaqus_image.py using the contents below which contains the rest of the script.

waves-tutorials/modsim_package/abaqus/export_abaqus_image.py

def image(
    output_file,
    x_angle=default_x_angle,
    y_angle=default_y_angle,
    z_angle=default_z_angle,
    image_size=default_image_size,
    model_name=default_model_name,
    part_name=default_part_name,
    color_map=color_map_choices[0],
):
    """Save an assembly view image of an Abaqus model from an input or CAE file.

    The viewer window is adjusted by the provided x, y, and z angles and the viewport is set to fit the assembly prior
    to saving an image of the viewport screen.

    If the model assembly has no instances, use ``part_name`` to generate one. The ``input_file`` is not modified to
    include this generated instance.

    :param str output_file: Output image file. Supports ``*.png`` and ``*.svg``.
    :param float x_angle: Rotation about X-axis in degrees for ``abaqus.session.viewports[].view.rotate`` Abaqus Python
        method
    :param float y_angle: Rotation about Y-axis in degrees for ``abaqus.session.viewports[].view.rotate`` Abaqus Python
        method
    :param float z_angle: Rotation about Z-axis in degrees for ``abaqus.session.viewports[].view.rotate`` Abaqus Python
        method
    :param tuple image_size: Tuple containing height and width of the output image in pixels
    :param str model_name: model to query in the Abaqus model database
    :param str part_name: part to query in the specified Abaqus model
    :param str color_map: color map key

    :returns: writes image to ``{output_file}``
    """
    output_file_stem, output_file_extension = os.path.splitext(output_file)
    output_file_extension = output_file_extension.lstrip(".")
    assembly = abaqus.mdb.models[model_name].rootAssembly
    if len(assembly.instances.keys()) == 0:
        part = abaqus.mdb.models[model_name].parts[part_name]
        assembly.Instance(name=part_name, part=part, dependent=abaqusConstants.ON)
    viewport = abaqus.session.viewports["Viewport: 1"]
    viewport.assemblyDisplay.setValues(
        optimizationTasks=abaqusConstants.OFF,
        geometricRestrictions=abaqusConstants.OFF,
        stopConditions=abaqusConstants.OFF,
    )
    viewport.setValues(displayedObject=assembly)
    viewport.view.rotate(xAngle=x_angle, yAngle=y_angle, zAngle=z_angle, mode=abaqusConstants.MODEL)
    viewport.view.fitView()
    viewport.enableMultipleColors()
    viewport.setColor(initialColor="#BDBDBD")
    cmap = viewport.colorMappings[color_map]
    viewport.setColor(colorMapping=cmap)
    viewport.disableMultipleColors()
    abaqus.session.printOptions.setValues(vpDecorations=abaqusConstants.OFF)
    abaqus.session.pngOptions.setValues(imageSize=image_size)

    output_format = abaqus_utilities.return_abaqus_constant(output_file_extension)
    abaqus.session.printToFile(fileName=output_file_stem, format=output_format, canvasObjects=(viewport,))


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):
        """Initialize the Abaqus temporary file class."""
        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):
        """Define the context manager construction method."""
        return self.temporary_file

    def __exit__(self, exc_type, exc_val, exc_tb):
        """Define the context manager cleanup method."""
        abaqus.mdb.close()
        self.temporary_file.close()
        os.remove(self.temporary_file.name)


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
    """
    file_name = inspect.getfile(lambda: None)
    base_name = os.path.basename(file_name)
    prog = "abaqus cae -noGui {} --".format(base_name)
    parser = argparse.ArgumentParser(description=cli_description, prog=prog)
    parser.add_argument(
        "--input-file",
        type=str,
        required=True,
        help="Abaqus input file. Supports ``*.inp`` and ``*.cae``.",
    )
    parser.add_argument(
        "--output-file",
        type=str,
        required=True,
        help="Output image from the Abaqus viewport. Supports ``*.png``, ``*.svg`` and ``*.eps``.",
    )
    parser.add_argument(
        "--x-angle",
        type=float,
        default=default_x_angle,
        help="Viewer rotation about X-axis in degrees (default: %(default)s)",
    )
    parser.add_argument(
        "--y-angle",
        type=float,
        default=default_y_angle,
        help="Viewer rotation about Y-axis in degrees (default: %(default)s)",
    )
    parser.add_argument(
        "--z-angle",
        type=float,
        default=default_z_angle,
        help="Viewer rotation about Z-axis in degrees (default: %(default)s)",
    )
    parser.add_argument(
        "--image-size",
        nargs=2,
        type=int,
        default=default_image_size,
        help="Image size in pixels (X, Y) (default: %(default)s)",
    )
    parser.add_argument(
        "--model-name",
        type=str,
        default=default_model_name,
        help="Abaqus model name (default: %(default)s)",
    )
    parser.add_argument(
        "--part-name",
        type=str,
        default=default_part_name,
        help="Abaqus part name (default: %(default)s)",
    )
    parser.add_argument(
        "--color-map",
        type=str,
        choices=color_map_choices,
        default=color_map_choices[0],
        help="Color map (default: %(default)s)",
    )
    return parser


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))

    sys.exit(
        main(
            args.input_file,
            args.output_file,
            x_angle=args.x_angle,
            y_angle=args.y_angle,
            z_angle=args.z_angle,
            image_size=args.image_size,
            model_name=args.model_name,
            part_name=args.part_name,
            color_map=args.color_map,
        )
    )

The image() function utilizes the rest of the optional arguments that were passed from the main() function. The arguments color_map, x_angle, y_angle, and z_angle are used to adjust the viewer window. The model_name and part_name are used to set the Abaqus part assembly. The image_size parameter can change the size of your output image. All of these arguments are optional and have default values to rely on if no value was specified.

SConscript#

Add the images task list and alias to the tutorial_part_image.scons SConscript file. A``diff`` against the tutorial_12_archival.scons file from Tutorial 12: Data Archival is included below to help identify the changes made in this tutorial.

waves-tutorials/tutorial_part_image.scons

--- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_12_archival.scons
+++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_part_image.scons
@@ -27,12 +27,13 @@
 # Simulation variables
 build_directory = pathlib.Path(Dir(".").abspath)
 workflow_name = build_directory.name
-workflow_configuration = [env["project_configuration"], f"{workflow_name}.scons"]
+workflow_configuration = [env["project_configuration"], workflow_name]
 parameter_study_file = build_directory / "parameter_study.h5"
 
 # Collect the target nodes to build a concise alias for all targets
 workflow = []
 datacheck = []
+images = []
 
 # Comment used in tutorial code snippets: marker-2
 
@@ -163,6 +164,19 @@
         )
     )
 
+    # Part images
+    script_options = (
+        "--input-file ${SOURCES[1].abspath} --output-file ${TARGET.file} --model-name ${model} --part-name ${model}"
+    )
+    images.extend(
+        env.AbaqusJournal(
+            target=[set_path / "rectangle_compression.png"],
+            source=["#/modsim_package/abaqus/export_abaqus_image.py", *solve_source_list],
+            subcommand_options=script_options,
+            model="rectangle",
+        )
+    )
+
 # Comment used in tutorial code snippets: marker-6
 
 # Post-processing
@@ -206,15 +220,11 @@
 env.Alias(f"{workflow_name}_datacheck", datacheck)
 env.Alias(env["datacheck_alias"], datacheck)
 env.Alias(env["regression_alias"], datacheck)
-archive_alias = f"{workflow_name}_archive"
-env.Alias(archive_alias, archive_target)
+env.Alias(f"{workflow_name}_archive", archive_target)
+env.Alias(f"{workflow_name}_images", images)
 
 if not env["unconditional_build"] and not env["ABAQUS_PROGRAM"]:
-    print(
-        "Program 'abaqus' was not found in construction environment."
-        f" Ignoring '{workflow_name}' and '{archive_alias}' target(s)"
-    )
+    print(f"Program 'abaqus' was not found in construction environment. Ignoring '{workflow_name}' target(s)")
     Ignore([".", workflow_name], workflow)
-    Ignore([".", archive_alias], archive_target)
     Ignore([".", f"{workflow_name}_datacheck"], datacheck)
     Ignore([".", env["datacheck_alias"], env["regression_alias"]], datacheck)

Generating images will be part of a separate workflow. To do this we have created an images list that will capture the SCons tasks and have mapped a new alias to that list.

SConstruct#

Add the tutorial_part_image.scons SConscript file to the workflow. A diff against the SConstruct file from Tutorial 12: Data Archival is included below to help identify the changes made in this tutorial.

waves-tutorials/SConstruct

--- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_12_archival_SConstruct
+++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_part_image_SConstruct
@@ -1,5 +1,5 @@
 #! /usr/bin/env python
-"""Configure the WAVES archive tutorial."""
+"""Configure the WAVES part image tutorial."""
 
 import inspect
 import os
@@ -122,6 +122,7 @@
     "tutorial_09_post_processing.scons",
     "tutorial_11_regression_testing.scons",
     "tutorial_12_archival.scons",
+    "tutorial_part_image.scons",
 ]
 for workflow in workflow_configurations:
     build_dir = env["variant_dir_base"] / pathlib.Path(workflow).stem

Build Targets#

Build the new targets

$ pwd
/home/roppenheimer/waves-tutorials
$ scons tutorial_part_image_images --jobs=4

Output Files#

View the output files. Notice that the output files from Tutorial 11: Regression Testing have been created with the addition of the .png output files.

$ pwd
/home/roppenheimer/waves-tutorials
$ tree build/tutorial_part_image/parameter_set0/
build/tutorial_part_image/parameter_set0/
├── abaqus1.rec
├── abaqus.rpy
├── abaqus.rpy.1
├── abaqus.rpy.2
├── abaqus.rpy.3
├── abaqus.rpy.4
├── assembly.inp
├── boundary.inp
├── field_output.inp
├── history_output.inp
├── materials.inp
├── parts.inp
├── rectangle_compression.inp
├── rectangle_compression.inp.in
├── rectangle_compression.png
├── rectangle_compression.png.stdout
├── rectangle_geometry.cae
├── rectangle_geometry.cae.stdout
├── rectangle_geometry.jnl
├── rectangle_mesh.cae
├── rectangle_mesh.inp
├── rectangle_mesh.inp.stdout
├── rectangle_mesh.jnl
├── rectangle_partition.cae
├── rectangle_partition.cae.stdout
└── rectangle_partition.jnl

0 directories, 26 files

Tutorial: Part Image

Contents

Tutorial: Part Image#

References#

Environment#

Directory Structure#

Part-Image script#

SConscript#

SConstruct#

Build Targets#

Output Files#