Command Line Utilities

WAVES Command Line Utility

Provides a minimal SCons build wrapper, access to locally packaged HTML documentation, and modsim template file generator.

usage: waves [-h] [-V] {subcommand} ...

Named Arguments

-V, --version: show program’s version number and exit

subcommands

{subcommand}: Possible choices: docs, fetch, visualize, quickstart, build, cartesian_product, custom_study, latin_hypercube, sobol_sequence

Sub-commands:

docs

Open the packaged WAVES HTML documentation in the system default web browser

usage: waves docs [-h] [-p]

Named Arguments

-p, --print-local-path: Print the path to the locally installed documentation index file. As an alternative to the docs sub-command, open index.html in a web browser (default: False)

fetch

Fetch and copy WAVES modsim template files and directories. If no FILE is specified, all available files will be created. Directories are recursively copied. pathlib.Path recursive pattern matching is possible. The source path is truncated to use the shortest common file prefix, e.g. requesting two files common/source/file.1 and common/source/file.2 will create /destination/file.1 and /destination/file.2, respectively.

usage: waves fetch [-h] [--destination DESTINATION] [--overwrite] [--dry-run]
                   [--print-available]
                   [FILE ...]

Positional Arguments

FILE: modsim template file or directory

Named Arguments

--destination: Destination directory. Unless --overwrite is specified, conflicting file names in the destination will not be copied. (default: PWD)
--overwrite: Overwrite any existing files (default: False)
--dry-run: Print the destination tree and exit (default: False)
--print-available: Print available modsim template files and exit (default: False)

visualize

Create a visual representation of the directed acyclic graph used by your SCons project

usage: waves visualize [-h] [--sconstruct SCONSTRUCT] [-o OUTPUT_FILE]
                       [--height HEIGHT] [--width WIDTH]
                       [--font-size FONT_SIZE] [-e [EXCLUDE_LIST ...]]
                       [-r EXCLUDE_REGEX] [-g | --print-tree] [--vertical]
                       [-n] [--input-file INPUT_FILE]
                       TARGET

Positional Arguments

TARGET: SCons target

Named Arguments

--sconstruct: Path to SConstruct file (default: “SConstruct”)
-o, --output-file: Path to output image file with an extension supported by matplotlib, e.g. ‘visualization.svg’ (default: None)
--height: Height of visualization in inches if being saved to a file (default: 12)
--width: Width of visualization in inches if being saved to a file (default: 36)
--font-size: Font size of file names in points (default: 10)
-e, --exclude-list: If a node starts or ends with one of these string literals, do not visualize it (default: [‘/usr/bin’])
-r, --exclude-regex: If a node matches this regular expression, do not visualize it (default: None)
-g, --print-graphml: Print the visualization in graphml format (default: False)
--print-tree: Print the output of the scons tree command to the screen (default: False)
--vertical: Display the graph in a vertical layout (default: False)
-n, --no-labels: Create visualization without labels on the nodes (default: False)
--input-file: Path to text file with output from scons tree command (default: None). Scons target must still be specified and must be present in the input file.

build

Thin SCons wrapper to programmatically re-run SCons until all targets are reported up-to-date.

usage: waves build [-h] [-m MAX_ITERATIONS] [-g GIT_CLONE_DIRECTORY]
                   TARGET [TARGET ...]

Positional Arguments

TARGET: SCons target list

Named Arguments

-m, --max-iterations: Maximum number of SCons command iterations (default: 5)
-g, --git-clone-directory: Perform a full local git clone operation to the specified directory before executing the scons command, git clone --no-hardlinks ${PWD} ${GIT_CLONE_DIRECTORY} (default: None)

cartesian_product

Generates parameter studies in various output formats. Writes parameter study to STDOUT by default. If an output file template is specified, output one file per parameter set. Output file(s) are written if the file doesn’t exist and overwritten when the file contents have changed. The overwrite option will always overwrite all files. The dry run option will print a list of files and contents that would have been written. The ‘h5’ output is the only output type that contains both the parameter samples and quantiles.

usage: waves cartesian_product [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                               [-t {yaml,h5}] [-s SET_NAME_TEMPLATE]
                               [-p PREVIOUS_PARAMETER_STUDY] [--overwrite]
                               [--dryrun] [--write-meta]
                               [INPUT_FILE]

Positional Arguments

INPUT_FILE: YAML formatted parameter study schema file (default: STDIN)

Named Arguments

-o, --output-file-template

Output file template. May contain pathseps for an absolute or relative path template. May contain @number set number placeholder in the file basename but not in the path. If the placeholder is not found, it will be appended to the template string. Output files are overwritten if the content of the file has changed or if overwrite is True (default: None)

-f, --output-file

Output file name. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if overwrite is True (default: None)

-t, --output-file-type

Possible choices: yaml, h5

Output file type (default: “yaml”)

-s, --set-name-template

Parameter set name template. Overridden by output_file_template, if provided (default: “parameter_set@number”)

-p, --previous-parameter-study

A relative or absolute file path to a previously created parameter study Xarray Dataset (default: None)

--overwrite

Overwrite existing output files (default: False)

--dryrun

Print contents of new parameter study output files to STDOUT and exit (default: False)

--write-meta

Write a meta file named ‘parameter_study_meta.txt’ containing the parameter set file names (default: False)

custom_study

Generates parameter studies in various output formats. Writes parameter study to STDOUT by default. If an output file template is specified, output one file per parameter set. Output file(s) are written if the file doesn’t exist and overwritten when the file contents have changed. The overwrite option will always overwrite all files. The dry run option will print a list of files and contents that would have been written. The ‘h5’ output is the only output type that contains both the parameter samples and quantiles.

usage: waves custom_study [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                          [-t {yaml,h5}] [-s SET_NAME_TEMPLATE]
                          [-p PREVIOUS_PARAMETER_STUDY] [--overwrite]
                          [--dryrun] [--write-meta]
                          [INPUT_FILE]

Positional Arguments

INPUT_FILE: YAML formatted parameter study schema file (default: STDIN)

Named Arguments

-o, --output-file-template

Output file template. May contain pathseps for an absolute or relative path template. May contain @number set number placeholder in the file basename but not in the path. If the placeholder is not found, it will be appended to the template string. Output files are overwritten if the content of the file has changed or if overwrite is True (default: None)

-f, --output-file

Output file name. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if overwrite is True (default: None)

-t, --output-file-type

Possible choices: yaml, h5

Output file type (default: “yaml”)

-s, --set-name-template

Parameter set name template. Overridden by output_file_template, if provided (default: “parameter_set@number”)

-p, --previous-parameter-study

A relative or absolute file path to a previously created parameter study Xarray Dataset (default: None)

--overwrite

Overwrite existing output files (default: False)

--dryrun

Print contents of new parameter study output files to STDOUT and exit (default: False)

--write-meta

Write a meta file named ‘parameter_study_meta.txt’ containing the parameter set file names (default: False)

latin_hypercube

Generates parameter studies in various output formats. Writes parameter study to STDOUT by default. If an output file template is specified, output one file per parameter set. Output file(s) are written if the file doesn’t exist and overwritten when the file contents have changed. The overwrite option will always overwrite all files. The dry run option will print a list of files and contents that would have been written. The ‘h5’ output is the only output type that contains both the parameter samples and quantiles.

usage: waves latin_hypercube [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                             [-t {yaml,h5}] [-s SET_NAME_TEMPLATE]
                             [-p PREVIOUS_PARAMETER_STUDY] [--overwrite]
                             [--dryrun] [--write-meta]
                             [INPUT_FILE]

Positional Arguments

INPUT_FILE: YAML formatted parameter study schema file (default: STDIN)

Named Arguments

-o, --output-file-template

Output file template. May contain pathseps for an absolute or relative path template. May contain @number set number placeholder in the file basename but not in the path. If the placeholder is not found, it will be appended to the template string. Output files are overwritten if the content of the file has changed or if overwrite is True (default: None)

-f, --output-file

Output file name. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if overwrite is True (default: None)

-t, --output-file-type

Possible choices: yaml, h5

Output file type (default: “yaml”)

-s, --set-name-template

Parameter set name template. Overridden by output_file_template, if provided (default: “parameter_set@number”)

-p, --previous-parameter-study

A relative or absolute file path to a previously created parameter study Xarray Dataset (default: None)

--overwrite

Overwrite existing output files (default: False)

--dryrun

Print contents of new parameter study output files to STDOUT and exit (default: False)

--write-meta

Write a meta file named ‘parameter_study_meta.txt’ containing the parameter set file names (default: False)

sobol_sequence

Generates parameter studies in various output formats. Writes parameter study to STDOUT by default. If an output file template is specified, output one file per parameter set. Output file(s) are written if the file doesn’t exist and overwritten when the file contents have changed. The overwrite option will always overwrite all files. The dry run option will print a list of files and contents that would have been written. The ‘h5’ output is the only output type that contains both the parameter samples and quantiles.

usage: waves sobol_sequence [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                            [-t {yaml,h5}] [-s SET_NAME_TEMPLATE]
                            [-p PREVIOUS_PARAMETER_STUDY] [--overwrite]
                            [--dryrun] [--write-meta]
                            [INPUT_FILE]

Positional Arguments

INPUT_FILE: YAML formatted parameter study schema file (default: STDIN)

Named Arguments

-o, --output-file-template

Output file template. May contain pathseps for an absolute or relative path template. May contain @number set number placeholder in the file basename but not in the path. If the placeholder is not found, it will be appended to the template string. Output files are overwritten if the content of the file has changed or if overwrite is True (default: None)

-f, --output-file

Output file name. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if overwrite is True (default: None)

-t, --output-file-type

Possible choices: yaml, h5

Output file type (default: “yaml”)

-s, --set-name-template

Parameter set name template. Overridden by output_file_template, if provided (default: “parameter_set@number”)

-p, --previous-parameter-study

A relative or absolute file path to a previously created parameter study Xarray Dataset (default: None)

--overwrite

Overwrite existing output files (default: False)

--dryrun

Print contents of new parameter study output files to STDOUT and exit (default: False)

--write-meta

Write a meta file named ‘parameter_study_meta.txt’ containing the parameter set file names (default: False)

ODB Extract

Extracts data from an Abaqus odb file. Calls odbreport feature of Abaqus, parses resultant file, and creates output file. Most simulation data lives in a group path following the instance and set name, e.g. /INSTANCE/FieldOutputs/ELEMENT_SET, and can be accessed with xarray as xarray.open_dataset(“sample.h5”, group=”/INSTANCE/FieldOutputs/ELEMENT_SET”). You can view all group paths with h5ls -r sample.h5. Additional ODB information is available in the /odb group path. The /xarray/Dataset group path contains a list of group paths that contain an xarray dataset.

Format of HDF5 file

/                 # Top level group required in all hdf5 files
/<instance name>/ # Groups containing data of each instance found in an odb
    FieldOutputs/      # Group with multiple xarray datasets for each field output
        <field name>/  # Group with datasets containing field output data for a specified set or surface
                       # If no set or surface is specified, the <field name> will be 'ALL_NODES' or 'ALL_ELEMENTS'
    HistoryOutputs/    # Group with multiple xarray datasets for each history output
        <region name>/ # Group with datasets containing history output data for specified history region name
                       # If no history region name is specified, the <region name> will be 'ALL NODES'
    Mesh/              # Group written from an xarray dataset with all mesh information for this instance
/<instance name>_Assembly/ # Group containing data of assembly instance found in an odb
    Mesh/              # Group written from an xarray dataset with all mesh information for this instance
/odb/             # Catch all group for data found in the odbreport file not already organized by instance
    info/              # Group with datasets that mostly give odb meta-data like name, path, etc.
    jobData/           # Group with datasets that contain additional odb meta-data
    rootAssembly/      # Group with datasets that match odb file organization per Abaqus documentation
    sectionCategories/ # Group with datasets that match odb file organization per Abaqus documentation
/xarray/          # Group with a dataset that lists the location of all data written from xarray datasets

usage: odb_extract [-h] [-o sample.h5] [-f h5] [-r "step=step1 results"]
                   [-a /path/to/abaqus] [-d] [-v]
                   sample.odb

Positional Arguments

sample.odb: odb or odbreport file for extracting data

Named Arguments

-o, --output-file

file for printing output

-f, --output-file-type

Possible choices: yaml, json, h5

Type of file in which to store output data

Default: “h5”

-r, --odb-report-args

Arguments to give to the odbreport command. Require the option=value interface style.

-a, --abaqus-command

Abaqus command to use

Default: “abq2023”

-d, --delete-report-file

Delete after parsing the file created by the odbreport command

Default: False

-v, --verbose

Print all messages

Default: False

Example: >> odb_extract sample.odb

Sta Parse

Extracts data from an Abaqus sta file. Parses passed in sta file and writes the output to a yaml file

usage: sta_parse [-h] [-o sample.yaml] sample.sta

Positional Arguments

sample.sta: sta file for parsing data

Named Arguments

-o, --output-file: file for printing output

Example: >> sta_parse sample.sta

Msg Parse

Extracts data from an Abaqus msg file. Parses passed in msg file and writes the output to a yaml file

usage: msg_parse [-h] [-o sample.yaml] [-s] [-a] [-y] sample.msg

Positional Arguments

sample.msg: msg file for parsing data

Named Arguments

-o, --output-file

file for printing output

-s, --write-summary

Write a summary of the data in a table

Default: False

-a, --write-all

Write the parsed data in an organized format that is also easy to visually parse

Default: False

-y, --write-yaml

Write the parsed data into a yaml file

Default: True

Example: >> msg_parse sample.msg