Skip to main content
`Ctrl`+`K`

# WAVES-TUTORIAL API

## abaqus

### rectangle_geometry.py

modsim_package.abaqus.rectangle_geometry.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

  Return type:

    argparse.ArgumentParser

modsim_package.abaqus.rectangle_geometry.main(output_file, model_name, part_name, width, height)

  Create a simple rectangle geometry.

  This script creates a simple Abaqus model with a single rectangle part.

  Parameters:

    - output_file (str) – The output file for the Abaqus model. Will be stripped of the extension and `.cae` will be used.

    - model_name (str) – The name of the Abaqus model

    - part_name (str) – The name of the Abaqus part

    - width (float) – The rectangle width

    - height (float) – The rectangle height

  Returns:

    writes `output_file`.cae and `output_file`.jnl

### rectangle_partition.py

modsim_package.abaqus.rectangle_partition.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

  Return type:

    argparse.ArgumentParser

modsim_package.abaqus.rectangle_partition.main(input_file, output_file, model_name, part_name, width, height)

  Partition the simple rectangle geometry created by `rectangle_geometry.py`

  This script partitions a simple Abaqus model with a single rectangle part.

  Feature labels:

  - `bottom_left` - bottom left vertex

  - `bottom_right` - bottom right vertex

  - `top_right` - top right vertex

  - `top_left` - top left vertex

  - `left` - left edge

  - `top` - top edge

  - `right` - right edge

  - `bottom` - bottom edge

  Parameters:

    - input_file (str) – The Abaqus model file created by `rectangle_geometry.py`. Will be stripped of the extension and `.cae` will be used.

    - output_file (str) – The output file for the Abaqus model. Will be stripped of the extension and `.cae` will be used.

    - model_name (str) – The name of the Abaqus model

    - part_name (str) – The name of the Abaqus part

    - width (float) – The rectangle width

    - height (float) – The rectangle height

  Returns:

    writes `output_file`.cae and `output_file`.jnl

### rectangle_mesh.py

modsim_package.abaqus.rectangle_mesh.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

  Return type:

    argparse.ArgumentParser

modsim_package.abaqus.rectangle_mesh.main(input_file, output_file, model_name, part_name, global_seed)

  Mesh the simple rectangle geometry partitioned by `rectangle_partition.py`

  This script meshes a simple Abaqus model with a single rectangle part.

  Feature labels:

  - `NODES` - all part nodes

  - `ELEMENTS` - all part elements

  Parameters:

    - input_file (str) – The Abaqus model file created by `rectangle_partition.py`. Will be stripped of the extension and `.cae` will be used.

    - output_file (str) – The output file for the Abaqus model. Will be stripped of the extension and `.cae` and `.inp` will be used for the model and orphan mesh output files, respectively.

    - model_name (str) – The name of the Abaqus model

    - part_name (str) – The name of the Abaqus part

    - global_seed (float) – The global mesh seed size

  Returns:

    `output_file`.cae, `output_file`.jnl, `output_file`.inp

### abaqus_utilities.py

modsim_package.abaqus.abaqus_utilities.export_mesh(model_object, part_name, orphan_mesh_file)

  Export an orphan mesh for the specified part instance in an Abaqus model

  Using an abaqus model object (`model_object = abaqus.mdb.models[model_name]`) with part(s) that are meshed and instanced in an assembly, get the `*.inp` keyword blocks and save an orphan mesh file, `orphan_mesh_file`.inp, for the specific `part_name`.

  Parameters:

    - model_object (abaqus.mdb.models[model_name]) – Abaqus model object

    - part_name (str) – Part name to export as an orphan mesh

    - orphan_mesh_file (str) – File name to write for the orphan mesh. Will be stripped of the extension and `.cae` will be used, e.g. `orphan_mesh_file`.inp

  Returns:

    writes `orphan_mesh_file`.inp

modsim_package.abaqus.abaqus_utilities.return_abaqus_constant(search)

  If search is found in the abaqusConstants module, return the abaqusConstants object.

  Parameters:

    search (str) – string to search in the abaqusConstants module attributes

  Return value:

    abaqusConstants attribute

  Return type:

    abaqusConstants.<search>

  Raises:

    ValueError – If the search string is not found.

## cubit

### rectangle_geometry.py

modsim_package.cubit.rectangle_geometry.main(output_file, width, height)

  Create a simple rectangle geometry.

  This script creates a simple Cubit model with a single rectangle part.

  Parameters:

    - output_file (str) – The output file for the Cubit model. Will be stripped of the extension and `.cub` will be used.

    - width (float) – The rectangle width

    - height (float) – The rectangle height

  Returns:

    writes `output_file`.cub

### rectangle_partition.py

modsim_package.cubit.rectangle_partition.main(input_file, output_file, width, height)

  Partition the simple rectangle geometry created by `rectangle_geometry.py`

  This script partitions a simple Cubit model with a single rectangle part.

  Feature labels:

  - `bottom_left` - bottom left vertex

  - `bottom_right` - bottom right vertex

  - `top_right` - top right vertex

  - `top_left` - top left vertex

  - `left` - left edge nodes

  - `top` - top edge nodes

  - `right` - right edge nodes

  - `bottom` - bottom edge nodes

  - `elset_left` - left edge elements

  - `elset_top` - top edge elements

  - `elset_right` - right edge elements

  - `elset_bottom` - bottom edge elements

  Parameters:

    - input_file (str) – The Cubit model file created by `rectangle_geometry.py`. Will be stripped of the extension and `.cub` will be used.

    - output_file (str) – The output file for the Cubit model. Will be stripped of the extension and `.cub` will be used.

    - width (float) – The rectangle width

    - height (float) – The rectangle height

  Returns:

    writes `output_file`.cub

### rectangle_mesh.py

modsim_package.cubit.rectangle_mesh.main(input_file, output_file, global_seed, element_type='QUAD', solver='abaqus')

  Mesh the simple rectangle geometry partitioned by `rectangle_partition.py`

  This script meshes a simple Cubit model with a single rectangle part.

  Feature labels:

  - `NODES` - all part nodes

  - `ELEMENTS` - all part elements

  Parameters:

    - input_file (str) – The Cubit model file created by `rectangle_partition.py`. Will be stripped of the extension and `.cub` will be used.

    - output_file (str) – The output file for the Cubit model. Will be stripped of the extension and `.cub` and `.inp` will be used for the model and orphan mesh output files, respectively.

    - global_seed (float) – The global mesh seed size

    - element_type (str) – The model element type. Must be a supported Cubit 4 node element type.

    - solver (str) – The solver type to use when exporting the mesh

  Returns:

    writes `output_file`.cub and `output_file`.inp

  Raises:

    RuntimeError – If the solver is not supported

### cube_geometry.py

modsim_package.cubit.cube_geometry.main(output_file, width, height, depth)

  Create a simple cube geometry.

  This script creates a simple Cubit model with a single cube part.

  Parameters:

    - output_file (str) – The output file for the Cubit model. Will be stripped of the extension and `.cub` will be used.

    - width (float) – The cube width (X-axis)

    - height (float) – The cube height (Y-axis)

    - depth (float) – The cube depth (Z-axis)

  Returns:

    writes `output_file`.cub

### cube_partition.py

modsim_package.cubit.cube_partition.main(input_file, output_file)

  Partition the simple cube geometry created by `cube_geometry.py`

  This script partitions a simple Cubit model with a single cube part.

  Feature labels:

  - `top`: +Y surface

  - `bottom`: -Y surface

  - `left`: -X surface

  - `right`: +X surface

  - `front`: +Z surface

  - `back`: -Z surface

  Parameters:

    - input_file (str) – The Cubit model file created by `cube_geometry.py`. Will be stripped of the extension and `.cub` will be used.

    - output_file (str) – The output file for the Cubit model. Will be stripped of the extension and `.cub` will be used.

  Returns:

    writes `output_file`.cub

### cube_mesh.py

modsim_package.cubit.cube_mesh.main(input_file, output_file, global_seed, element_type='QUAD', solver='abaqus')

  Mesh the simple cube geometry partitioned by `cube_partition.py`

  This script meshes a simple Cubit model with a single cube part.

  Feature labels:

  - `NODES` - all part nodes

  - `ELEMENTS` - all part elements

  Parameters:

    - input_file (str) – The Cubit model file created by `cube_partition.py`. Will be stripped of the extension and `.cub` will be used.

    - output_file (str) – The output file for the Cubit model. Will be stripped of the extension and `.cub` and `.inp` will be used for the model and orphan mesh output files, respectively.

    - global_seed (float) – The global mesh seed size

    - element_type (str) – The model element type. Must be a supported Cubit 4 node element type.

    - solver (str) – The solver type to use when exporting the mesh

  Returns:

    writes `output_file`.cub and `output_file`.inp

  Raises:

    RuntimeError – If the solver is not supported

## python

### rectangle_compression_nominal.py

Parameter sets and schemas for the rectangle compression simulation

modsim_package.python.rectangle_compression_nominal.parameter_schema(width=1.0, height=1.0, global_seed=1.0, displacement=-0.01)

  Return nominal simulation variables dictionary

  Parameters:

    - width (float) – The rectangle width

    - height (float) – The rectangle height

    - global_seed (float) – The global mesh seed size

    - displacement (float) – The rectangle top surface displacement

  Returns:

    nominal simulation variables

  Return type:

    dict

### rectangle_compression_cartesian_product.py

Parameter sets and schemas for the rectangle compression simulation

modsim_package.python.rectangle_compression_cartesian_product.parameter_schema(width=[1.0, 1.1], height=[1.0, 1.1], global_seed=[1.0], displacement=[-0.01])

  Return WAVES CartesianProduct parameter schema

  Parameters:

    - width (list) – The rectangle width

    - height (list) – The rectangle height

    - global_seed (list) – The global mesh seed size

    - displacement (list) – The rectangle top surface displacement

  Returns:

    WAVES CartesianProduct parameter schema

  Return type:

    dict

### post_processing.py

Example of catenating WAVES parameter study results and definition

modsim_package.python.post_processing.combine_data(input_files, group_path, concat_coord)

  Combine input data files into one dataset

  Parameters:

    - input_files (list) – list of path-like or file-like objects pointing to h5netcdf files containing Xarray Datasets

    - group_path (str) – The h5netcdf group path locating the Xarray Dataset in the input files.

    - concat_coord (str) – Name of dimension

  Returns:

    Combined data

  Return type:

    xarray.DataArray

modsim_package.python.post_processing.main(input_files, output_file, group_path, x_var, x_units, y_var, y_units, selection_dict, parameter_study_file=None)

  Catenate `input_files` datasets along the `set_name` dimension and plot selected data.

  Optionally merges the parameter study results datasets with the parameter study definition dataset, where the parameter study dataset file is assumed to be written by a WAVES parameter generator.

  Parameters:

    - input_files (list) – list of path-like or file-like objects pointing to h5netcdf files containing Xarray Datasets

    - output_file (str) – The plot file name. Relative or absolute path.

    - group_path (str) – The h5netcdf group path locating the Xarray Dataset in the input files.

    - x_var (str) – The independent (x-axis) variable key name for the Xarray Dataset “data variable”

    - x_units (str) – The independent (x-axis) units

    - y_var (str) – The dependent (y-axis) variable key name for the Xarray Dataset “data variable”

    - y_units (str) – The dependent (y-axis) units

    - selection_dict (dict) – Dictionary to define the down selection of data to be plotted. Dictionary `key: value` pairs must match the data variables and coordinates of the expected Xarray Dataset object.

    - parameter_study_file (str) – path-like or file-like object containing the parameter study dataset. Assumes the h5netcdf file contains only a single dataset at the root group path, .e.g. `/`.

modsim_package.python.post_processing.merge_parameter_study(parameter_study_file, combined_data)

  Merge parameter study to existing dataset

  Parameters:

    - parameter_study_file (str) – path-like or file-like object containing the parameter study dataset. Assumes the h5netcdf file contains only a single dataset at the root group path, .e.g. `/`.

    - combined_data (xarray.DataArray) – XArray Dataset that will be merged.

  Returns:

    Combined data

  Return type:

    xarray.DataArray

modsim_package.python.post_processing.save_plot(combined_data, x_var, y_var, selection_dict, concat_coord, output_file)

  Save scatter plot with given x and y labels

  Parameters:

    - combined_data (xarray.DataArray) – XArray Dataset that will be plotted.

    - x_var (str) – The independent (x-axis) variable key name for the Xarray Dataset “data variable”

    - y_var (str) – The dependent (y-axis) variable key name for the Xarray Dataset “data variable”

    - selection_dict (dict) – Dictionary to define the down selection of data to be plotted. Dictionary `key: value` pairs must match the data variables and coordinates of the expected Xarray Dataset object.

    - concat_coord (str) – Name of dimension for which you want multiple lines plotted.

    - output_file (str) – The plot file name. Relative or absolute path.

modsim_package.python.post_processing.save_table(combined_data, selection_dict, output_file)

  Save csv table

  Parameters:

    - combined_data (xarray.DataArray) – XArray Dataset to be written as a CSV.

    - selection_dict (dict) – Dictionary to define the down selection of data to be plotted. Dictionary `key: value` pairs must match the data variables and coordinates of the expected Xarray Dataset object.

    - output_file (str) – The CSV file name. Relative or absolute path.

### regression.py

modsim_package.python.regression.csv_files_match(current_csv, expected_csv, index_column='time', sort_columns=['time', 'set_name'])

  Compare two pandas DataFrame objects and determine if they match.

  Parameters:

    - current_csv (pandas.DataFrame) – Current CSV data of generated plot.

    - expected_csv (pandas.DataFrame) – Expected CSV data.

  Returns:

    True if the CSV files match, False otherwise.

  Return type:

    bool

modsim_package.python.regression.get_parser() → ArgumentParser

  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

  Return type:

modsim_package.python.regression.main(first_file: Path, second_file: Path, output_file: Path) → None

  Compare CSV files and return an error code if they differ

  Parameters:

    - first_file – path-like or file-like object containing the first CSV dataset

    - second_file – path-like or file-like object containing the second CSV dataset

modsim_package.python.regression.sort_dataframe(dataframe, index_column='time', sort_columns=['time', 'set_name'])

  Return a sorted dataframe and set an index

  1. sort columns by column name

  2. sort rows by column values `sort_columns`

  3. set an index

  Returns:

    sorted and indexed dataframe

  Return type:

    pandas.DataFrame

### argparse_types.py

Python 2/3 compatible argparse types for input verification

modsim_package.argparse_types.positive_float(argument)

  Type function for argparse - positive floats

  Abaqus Python 2 and Python 3 compatible argparse type method: https://docs.python.org/3.12/library/argparse.html#type.

  Parameters:

    argument (str) – string argument from argparse

  Returns:

    argument

  Return type:

    float

  Raises:

    ValueError –

    - The argument can’t be cast to float

    - The argument is less than 0.0 in a float comparison

### solver.py

Example for common commercial and research solver behavior and handling

Warning

The solver I/O handling and CLI are NOT good behaviors for authors and developers of command line utilities. They are intended to be examples of representative types of challenging behaviors to consider when writing SCons builders.

Solver I/O behaviors:

1. Log files are written to the current working directory. Log files are never overwritten and must be cleaned manually. Log files are automatically incremented from `solver.log` to `solver.log10`. If no free log file number is found and the maximum number of 10 is found, the solver exits with a non-zero exit code.

2. The output file name is built in preferred order: CLI `--output-file` argument or the `--input-file` argument with the replacement extension `.out`.

3. The implicit and explicit routines write output file(s) based on the requested number of threads. If only one thread is requested, the output file name is used. If more than one thread, N, is requested, each thread writes to a separately numbered output file 0 to (N-1) as `output_file.out{number}`.

4. If any output file exists and the overwrite behavior is not requested, the solver exits with a non-zero exit code.

Runtime errors are returned as non-zero exit codes. Internal errors are returned as the appropriate exception.

Exit codes:

1. error loading YAML input file

2. mismatched subcommand and input file routine request

3. output file exists and no overwrite was requested

4. reached max log file integer before finding a free file name

solver.configure(args: Namespace) → dict

  Return the configuration with appended executable information

  Parameters:

    args – The command line argument namespace

  Raises:

    RuntimeError – if the subcommand doesn’t match the input file routine

solver.explicit(args: Namespace) → None

  Explicit routine

  Parameters:

    args – The command line argument namespace

solver.get_parser() → ArgumentParser

  Return the argparse CLI parser

solver.implicit(args: Namespace) → None

  Implicit routine

  Parameters:

    args – The command line argument namespace

solver.main()

  Main function implementing the command line interface and program flow

solver.name_log_file(log_file: Path, max_iterations: int = 10) → Path

  Return the first free log file name

  Parameters:

    - log_file – Log file base name

    - max_iterations – Maximum number of allowable log files

  Raises:

    RuntimeError – if no log file name is free within the max iterations

solver.name_output_file(input_file: Path, output_file: Path) → Path

  Create the output file name from the input file if not specified

solver.positive_nonzero_int(argument)

  Type function for argparse - positive, non-zero integers

  Parameters:

    argument (str) – string argument from argparse

  Returns:

    argument

  Return type:

    int

  Raises:

    ValueError –

    - The argument can’t be cast to int

    - The argument is less than 1

solver.read_input(input_file: Path) → dict

  Return the configuration by reading the input file and handling common errors

  Parameters:

    input_file – The input YAML file absolute or relative path

  Raises:

    RuntimeError – if the YAML file can not be read

solver.solve(configuration: dict) → None

  Common solve logic because we do not really have separate routines

  Parameters:

    configuration – The solver configuration

  Raises:

    RuntimeError – if any output file already exists and overwrite is not requested.

solver.solve_output_files(output_file: Path, solve_cpus: int) → List[Path]

  Return the solve output file list to match the number of solve cpus

  Parameters:

    - output_file – base name for the output file

    - solve_cpus – integer number of solve cpus