Skip to main content
`Ctrl`+`K`

# 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, qoi

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

#### qoi

Quantity of interest (QOI) tools

    usage: waves qoi [-h] {qoi_subcommand} ...

##### QOI subcommands

`{qoi_subcommand}`

  Possible choices: accept, diff, check, aggregate, report, archive, plot-archive

##### Sub-commands

###### accept

Update expected values to match calculated values

    waves qoi accept [-h] [--calculated CALCULATED] [--expected EXPECTED]

###### Named Arguments

`--calculated`

  Calculated QOI file

`--expected`

  Expected QOI file

###### diff

Compare expected values to calculated values

    waves qoi diff [-h] [--expected EXPECTED] [--calculated CALCULATED]
                   [--output OUTPUT]

###### Named Arguments

`--expected`

  Expected values

`--calculated`

  Calculated values

`--output`

  Difference from expected values

###### check

Raise error if expected values do not match calculated values

    waves qoi check [-h] [--diff DIFF]

###### Named Arguments

`--diff`

  Calculated vs expected diff CSV file

###### aggregate

Combine parameter study QOIs

    waves qoi aggregate [-h] [--parameter-study-file PARAMETER_STUDY_FILE]
                        [--output-file OUTPUT_FILE]
                        QOI_SET_FILE [QOI_SET_FILE ...]

###### Positional Arguments

`QOI_SET_FILE`

###### Named Arguments

`--parameter-study-file`

  Path to parameter study definition file

`--output-file`

  post-processing output file

###### report

Generate QOI tolerance check report

    waves qoi report [-h] [--output OUTPUT] QOI_ARCHIVE_H5

###### Positional Arguments

`QOI_ARCHIVE_H5`

###### Named Arguments

`--output`

  Report file

###### archive

Combine QOIs across multiple simulations

    waves qoi archive [-h] [--output OUTPUT] [--version VERSION] [--date DATE]
                      QOI_SET_FILE [QOI_SET_FILE ...]

###### Positional Arguments

`QOI_SET_FILE`

###### Named Arguments

`--output`

  Report file

`--version`

  override existing QOI ‘version’ attributes with this text (e.g. a git commit hash).

`--date`

  override existing QOI ‘date’ attributes with this text (e.g. a git commit date).

###### plot-archive

Generate QOI history report

    waves qoi plot-archive [-h] [--output OUTPUT]
                           QOI_ARCHIVE_H5 [QOI_ARCHIVE_H5 ...]

###### Positional Arguments

`QOI_ARCHIVE_H5`

###### Named Arguments

`--output`

  output file

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