Tutorial 07: Latin Hypercube

Tutorial 07: Latin Hypercube#

Warning

This tutorial is in a draft outline state. It is provided as reference and will be fleshed out in future releases. Be sure to check back in on this tutorial or watch the Changelog for updates!

References#

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.

  1. 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

  2. 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.

  1. You can find the documentation version in the upper-left corner of the webpage.

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

  1. 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 7 && mv tutorial_07_cartesian_product_SConstruct SConstruct
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

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

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

Parameter Study File#

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

waves-tutorials/modsim_package/python/rectangle_compression_latin_hypercube.py

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


def parameter_schema(
    num_simulations=4,
    width={"distribution": "norm", "loc": 1, "scale": 0.1},
    height={"distribution": "norm", "loc": 1, "scale": 0.1},
):
    """Return WAVES Scipy LatinHypercube parameter schema

    :param int num_simulations: Number of samples to generate
    :param dict width: The rectangle width Scipy distribution definition
    :param dict height: The rectangle height Scipy distribution definition

    :returns: WAVES Scipy LatinHypercube parameter schema
    :rtype: dict
    """
    schema = {
        "num_simulations": num_simulations,
        "width": width,
        "height": height,
    }
    return schema

SConscript#

A diff against the tutorial_07_cartesian_product file from Tutorial 07: Cartesian Product is included below to help identify the differences between the two parameter generators.

Note

Note that the kwargs variable sets a fixed seed for the random number generator. This is required to make the parameter set reproducible during SCons configuration. Without this seed, every call of scons will produce a complete and unique parameter study. This will result in the full workflow re-executing on every scons call.

If a fixed seed is not acceptable, users may protect the parameter study generation with a command-line option or generate the parameter study manually and use the waves.parameter_generators.CustomStudy() to instantiate the parameter study object.

waves-tutorials/tutorial_07_latin_hypercube

--- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_07_cartesian_product
+++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_07_latin_hypercube
@@ -13,7 +13,7 @@
 
 import waves
 
-from modsim_package.python.rectangle_compression_cartesian_product import parameter_schema
+from modsim_package.python.rectangle_compression_latin_hypercube import parameter_schema
 
 # Inherit the parent construction environment
 Import("env")
@@ -24,6 +24,11 @@
 build_directory = pathlib.Path(Dir(".").abspath)
 workflow_name = build_directory.name
 parameter_study_file = build_directory / "parameter_study.h5"
+simulation_constants = {
+    "global_seed": 1,
+    "displacement": -0.01,
+}
+kwargs = {"seed": 42}
 
 # Collect the target nodes to build a concise alias for all targets
 workflow = []
@@ -31,11 +36,12 @@
 
 # Comment used in tutorial code snippets: marker-2
 
-# Parameter Study with Cartesian Product
-parameter_generator = waves.parameter_generators.CartesianProduct(
+# Parameter Study with Latin Hypercube
+parameter_generator = waves.parameter_generators.LatinHypercube(
     parameter_schema(),
     output_file=parameter_study_file,
     previous_parameter_study=parameter_study_file,
+    **kwargs,
 )
 parameter_generator.write()
 
@@ -44,7 +50,7 @@
 # Parameterized targets must live inside current simulation_variables for loop
 for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
     set_name = pathlib.Path(set_name)
-    simulation_variables = parameters
+    simulation_variables = {**parameters, **simulation_constants}
 
     # Comment used in tutorial code snippets: marker-4

SConstruct#

A diff against the SConstruct file from Tutorial 07: Cartesian Product is included below to help identify the changes made in this tutorial.

waves-tutorials/SConstruct

--- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_07_cartesian_product_SConstruct
+++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_07_latin_hypercube_SConstruct
@@ -105,6 +105,7 @@
     "tutorial_05_parameter_substitution",
     "tutorial_06_include_files",
     "tutorial_07_cartesian_product",
+    "tutorial_07_latin_hypercube",
 ]
 for workflow in workflow_configurations:
     build_dir = env["variant_dir_base"] / workflow

Build Targets#

  1. Build the new targets

$ pwd
/home/roppenheimer/waves-tutorials
$ scons tutorial_07_latin_hypercube --jobs=4

Output Files#

$ pwd
/home/roppenheimer/waves-tutorials
$ tree build/tutorial_07_latin_hypercube/parameter_set0/
build/tutorial_07_latin_hypercube/parameter_set0/
|-- abaqus.rpy
|-- abaqus.rpy.1
|-- abaqus.rpy.2
|-- assembly.inp
|-- boundary.inp
|-- field_output.inp
|-- history_output.inp
|-- materials.inp
|-- parts.inp
|-- rectangle_compression.com
|-- rectangle_compression.dat
|-- rectangle_compression.inp
|-- rectangle_compression.inp.in
|-- rectangle_compression.msg
|-- rectangle_compression.odb
|-- rectangle_compression.prt
|-- rectangle_compression.sta
|-- rectangle_compression.stdout
|-- rectangle_geometry.cae
|-- rectangle_geometry.jnl
|-- rectangle_geometry.stdout
|-- rectangle_mesh.cae
|-- rectangle_mesh.inp
|-- rectangle_mesh.jnl
|-- rectangle_mesh.stdout
|-- rectangle_partition.cae
|-- rectangle_partition.jnl
`-- rectangle_partition.stdout

0 directories, 28 files

Workflow Visualization#

$ pwd
/home/roppenheimer/waves-tutorials
$ waves visualize tutorial_07_latin_hypercube --output-file tutorial_07_latin_hypercube.png --width=36 --height=12 --exclude-list /usr/bin .stdout .jnl .prt .com .msg .dat .sta

$ pwd
/home/roppenheimer/waves-tutorials
$ waves visualize tutorial_07_latin_hypercube --output-file tutorial_07_latin_hypercube_set0.png --width=28 --height=6 --exclude-list /usr/bin .stdout .jnl .prt .com .msg .dat .sta --exclude-regex "set[1-9]"
Contents