Tutorial 07: Cartesian Product

Tutorial 07: Cartesian Product#

References#

WAVES Parameter Generators API: waves.parameter_generators.CartesianProduct()
Cartesian Product
Xarray and the xarray dataset [41, 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

$ 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

Activate the environment
```
$ 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.

Warning

STOP! Before continuing, check that the documentation version matches your installed package version.

You can find the documentation version in the upper-left corner of the webpage.
You can find the installed WAVES version with waves --version.

If they don’t match, you can launch identically matched documentation with the WAVES Command-Line Utility docs subcommand as waves docs.

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

$ mkdir -p ~/waves-tutorials
$ cd ~/waves-tutorials
$ pwd
/home/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 6 && mv tutorial_06_include_files_SConstruct SConstruct
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

Download and copy the tutorial_06_include_files file to a new file named tutorial_07_cartesian_product with the WAVES Command-Line Utility fetch subcommand.

$ pwd
/home/roppenheimer/waves-tutorials
$ waves fetch --overwrite tutorials/tutorial_06_include_files && cp tutorial_06_include_files tutorial_07_cartesian_product
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

Parameter Study File#

In this tutorial, we will use an included parameter study python file to define a parameter study using a Cartesian Product sampling methodology.

What is Cartesian Product

A “cartesian product” is a set of all ordered pairs of the elements for a series of list objects. Another commonly used synonym for Cartesian Product is Full Factorial.

Take a parameter study defined by variables A which has three samples, B which has two samples, and C which has one sample. The result will be a parameter study that contains six (3x2x1) simulations.

For more information, see this Cartesian Product Wiki page.

Create a new file modsim_package/python/rectangle_compression_cartesian_product.py from the content below.

waves-tutorials/modsim_package/python/rectangle_compression_cartesian_product.py

"""Parameter sets and schemas for the rectangle compression simulation"""


def parameter_schema(
    width=[1.0, 1.1],
    height=[1.0, 1.1],
    global_seed=[1.0],
    displacement=[-0.01],
):
    """Return WAVES CartesianProduct parameter schema

    :param list width: The rectangle width
    :param list height: The rectangle height
    :param list global_seed: The global mesh seed size
    :param list displacement: The rectangle top surface displacement

    :returns: WAVES CartesianProduct parameter schema
    :rtype: dict
    """
    schema = {
        "width": width,
        "height": height,
        "global_seed": global_seed,
        "displacement": displacement,
    }
    return schema

The rectangle_compression_cartesian_product.py file you just created is very similar to the rectangle_compression_nominal.py file from Tutorial 06: Include Files. The significant difference between the two files is the new definition of multiple values for the width and height parameters. Also note that the global_seed and displacement parameters are both defined with a list, even though the parameters only have a single value. The waves.parameter_generators.CartesianProduct() API explains this requirement for the “schema values” to be an iterable. You can view the parameter schema documentation in the WAVES-TUTORIAL API for rectangle_compression_cartesian_product.py.

In the parameter_schema, we have defined two parameters with two samples each and two parameters with one sample each. This will result in four (2x2x1x1) total simulations.

SConscript#

The diff for changes in the SConscript file for this tutorial is extensive because of the for loop indent wrapping the task generation for each parameter set. For convenience, the full source file is included below to aid in a wholesale copy and paste when creating the new SConscript file.

Note

In the Directory Structure section of this tutorial, you were instructed to copy the tutorial_06_include_files file to the tutorial_07_cartesian_product file. If you prefer, you may start with a blank tutorial_07_cartesian_product file and simply copy and paste the contents below into your blank file.

After viewing the full file contents below, continue to read the Step-By-Step SConscript Discussion for building the tutorial_07_cartesian_product file from scratch.