Command-Line Utilities

Command-Line Utilities#

WAVES Command-Line Utility#

Provides a parameter generator, 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, build, cartesian_product, custom_study, latin_hypercube, sobol_sequence, one_at_a_time, print_study

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]
                   [--tutorial {0,1,2,3,4,5,6,7,8,9,10,11,12}] [--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)

--tutorial

Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12

Fetch all necessary files for specified tutorial. Appends to the positional FILE requests.

--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] [-o OUTPUT_FILE] [--sconstruct SCONSTRUCT]
                       [--input-file INPUT_FILE] [-e [EXCLUDE_LIST ...]]
                       [-r EXCLUDE_REGEX] [-n] [-c] [--height HEIGHT]
                       [--width WIDTH] [--font-size FONT_SIZE]
                       [--node-color NODE_COLOR] [--edge-color EDGE_COLOR]
                       [--vertical] [--transparent] [--break-paths]
                       [-g | --print-tree]
                       TARGET [TARGET ...]

Positional Arguments#

TARGET: SCons target(s)

Named Arguments#

-o, --output-file: Path to output image file with an extension supported by matplotlib, e.g. ‘visualization.svg’ (default: None)
--sconstruct: Path to SConstruct file (default: SConstruct)
--input-file: Path to text file with output from SCons tree command (default: None)
-g, --print-graphml: Print the visualization in graphml format and exit (default: False)
--print-tree: Print the output of the SCons tree command to the screen and exit (default: False)

graph options#

graph options affect plotting and graphml output

-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)
-n, --no-labels: Create visualization without labels on the nodes (default: False)
-c, --node-count: Add the node count as an node with no edges (default: False)

plot options#

plot options affect the output figure

--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)
--node-color: Node face color (default: ‘#5AC7CB’)
--edge-color: Edge (arrow) color (default: ‘#B7DEBE’)
--vertical: Display the graph in a vertical layout (default: False)
--transparent: Use a transparent background. Requires a format that supports transparency (default: False)
--break-paths: Format paths by breaking at path separator with a newline (default: False)

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

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.

usage: waves cartesian_product [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                               [-t {h5,yaml}] [-s SET_NAME_TEMPLATE]
                               [-p PREVIOUS_PARAMETER_STUDY]
                               [--require-previous-parameter-study]
                               [--overwrite] [--dry-run] [--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 the @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: h5, yaml

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)

--require-previous-parameter-study

Raise a RuntimeError if the previous parameter study file is missing (default: False)

--overwrite

Overwrite existing output files (default: False)

--dry-run

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.

usage: waves custom_study [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                          [-t {h5,yaml}] [-s SET_NAME_TEMPLATE]
                          [-p PREVIOUS_PARAMETER_STUDY]
                          [--require-previous-parameter-study] [--overwrite]
                          [--dry-run] [--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 the @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: h5, yaml

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)

--require-previous-parameter-study

Raise a RuntimeError if the previous parameter study file is missing (default: False)

--overwrite

Overwrite existing output files (default: False)

--dry-run

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.

usage: waves latin_hypercube [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                             [-t {h5,yaml}] [-s SET_NAME_TEMPLATE]
                             [-p PREVIOUS_PARAMETER_STUDY]
                             [--require-previous-parameter-study]
                             [--overwrite] [--dry-run] [--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 the @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: h5, yaml

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)

--require-previous-parameter-study

Raise a RuntimeError if the previous parameter study file is missing (default: False)

--overwrite

Overwrite existing output files (default: False)

--dry-run

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.

usage: waves sobol_sequence [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                            [-t {h5,yaml}] [-s SET_NAME_TEMPLATE]
                            [-p PREVIOUS_PARAMETER_STUDY]
                            [--require-previous-parameter-study] [--overwrite]
                            [--dry-run] [--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 the @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: h5, yaml

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)

--require-previous-parameter-study

Raise a RuntimeError if the previous parameter study file is missing (default: False)

--overwrite

Overwrite existing output files (default: False)

--dry-run

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)

one_at_a_time#

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.

usage: waves one_at_a_time [-h] [-o OUTPUT_FILE_TEMPLATE | -f OUTPUT_FILE]
                           [-t {h5,yaml}] [-s SET_NAME_TEMPLATE]
                           [-p PREVIOUS_PARAMETER_STUDY]
                           [--require-previous-parameter-study] [--overwrite]
                           [--dry-run] [--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 the @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: h5, yaml

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)

--require-previous-parameter-study

Raise a RuntimeError if the previous parameter study file is missing (default: False)

--overwrite

Overwrite existing output files (default: False)

--dry-run

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)

print_study#

Open and print a WAVES parameter study file as a table. Does not work with multi-file parameter study output, e.g. --output-file-template option. Not intended for piped shell commands. Output formatting subject to change

usage: waves print_study [-h] PARAMETER_STUDY_FILE

Positional Arguments#

PARAMETER_STUDY_FILE: Parameter study relative or absolute path

ODB Extract#

Extracts data from an Abaqus odb file. Writes two files ‘output_file.h5’ and ‘output_file_datasets.h5’

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

import xarray
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. If none is provided, takes the basename of the input file (default: None)

-f, --output-file-type

Possible choices: yaml, json, h5

Type of file in which to store output data (default: ‘h5’)

Default: 'h5'

-r, --odb-report-args

Arguments to give to the odbreport command (default: None)

-a, --abaqus-command

Abaqus command to use (default: ‘abq2024’)

Default: 'abq2024'

-d, --delete-report-file

Delete after parsing the file created by the odbreport command (default: False)

Default: False

-v, --verbose

Print all messages (default: False)

Default: False

Example: >> odb_extract sample.odb

Command-Line Utilities

Contents

Command-Line Utilities#

WAVES Command-Line Utility#

Named Arguments#

subcommands#

Sub-commands:#

docs#

Named Arguments#

fetch#

Positional Arguments#

Named Arguments#

visualize#

Positional Arguments#

Named Arguments#

graph options#

plot options#

build#

Positional Arguments#

Named Arguments#

cartesian_product#

Positional Arguments#

Named Arguments#

custom_study#

Positional Arguments#

Named Arguments#

latin_hypercube#

Positional Arguments#

Named Arguments#

sobol_sequence#

Positional Arguments#

Named Arguments#

one_at_a_time#

Positional Arguments#

Named Arguments#

print_study#

Positional Arguments#

ODB Extract#

Positional Arguments#

Named Arguments#