Skip to main content
`Ctrl`+`K`

# Tutorial 07: One-at-a-Time

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

- WAVES Parameter Generators API: `waves.parameter_generators.OneAtATime()`

- Xarray and the xarray dataset [46, 47]

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

   Linux/MacOS

       $ 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

   Windows

       PS > conda create --name waves-tutorial-env --channel conda-forge waves scons matplotlib pandas pyyaml xarray seaborn numpy salib pytest

2. Activate the environment

   Linux/MacOS

       $ conda activate waves-tutorial-env

   Windows

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

3. Create and change to a new project root directory to house the tutorial files if you have not already done so. For example

Linux/MacOS

    $ mkdir -p ~/waves-tutorials
    $ cd ~/waves-tutorials
    $ pwd
    /home/roppenheimer/waves-tutorials

Windows

    PS > New-Item $HOME\waves-tutorials -ItemType "Directory"
    PS > Set-Location $HOME\waves-tutorials
    PS > Get-Location

    Path
    ----
    C:\Users\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'

4. Download and copy the `tutorial_07_cartesian_product` file to a new file named `tutorial_07_one_at_a_time` 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_one_at_a_time
    WAVES fetch
    Destination directory: '/home/roppenheimer/waves-tutorials'

## Parameter Study File

In this tutorial, we will use the previous parameter study python file used in Tutorial 07: Cartesian Product to define the parameter study.

In the `parameter_schema`, there are two parameters with two samples each and two parameters with one sample each. The nominal parameter set is constructed from the first sample of each parameter. This will result in three total simulations: one for the nominal parameter set and two using each off-nominal value.

The idea behind one-at-a-time parameter sets is that, for each parameter set, only one value of one single parameter has changed compared to the nominal values.

## SConscript

5. Modify the SConscript file `tutorial_07_one_at_a_time` to utilize the `waves.parameter_generators.OneAtATime()` builder.

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.

waves-tutorials/tutorial_07_one_at_a_time

    --- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_07_cartesian_product
    +++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_07_one_at_a_time
    @@ -31,8 +31,8 @@

     # Comment used in tutorial code snippets: marker-2

    -# Parameter Study with Cartesian Product
    -parameter_generator = waves.parameter_generators.CartesianProduct(
    +# Parameter Study with One-at-a-Time
    +parameter_generator = waves.parameter_generators.OneAtATime(
         parameter_schema(),
         output_file=parameter_study_file,
         previous_parameter_study=parameter_study_file,

## SConstruct

6. Add the workflow `tutorial_07_one_at_a_time` to the SConstruct file.

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_one_at_a_time_SConstruct
    @@ -92,7 +92,11 @@
     # Comments used in tutorial code snippets: marker-5

     # Add builders and pseudo-builders
    -env.Append(BUILDERS={})
    +env.Append(
    +    BUILDERS={
    +        "AbaqusSolver": waves.scons_extensions.abaqus_solver(program=env["ABAQUS_PROGRAM"]),
    +    }
    +)

     # Comments used in tutorial code snippets: marker-6

    @@ -105,6 +109,7 @@
         "tutorial_05_parameter_substitution",
         "tutorial_06_include_files",
         "tutorial_07_cartesian_product",
    +    "tutorial_07_one_at_a_time",
     ]
     for workflow in workflow_configurations:
         build_dir = env["variant_dir_base"] / workflow

## Build Targets

7. Build the new targets.

    $ pwd
    /home/roppenheimer/waves-tutorials
    $ scons tutorial_07_one_at_a_time --jobs=3

## Output Files

    $ pwd
    /home/roppenheimer/waves-tutorials
    $ tree build/tutorial_07_one_at_a_time/parameter_set0/
    build/tutorial_07_one_at_a_time/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_one_at_a_time --output-file tutorial_07_one_at_a_time.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_one_at_a_time --output-file tutorial_07_one_at_a_time_set0.png --width=28 --height=6 --exclude-list /usr/bin .stdout .jnl .prt .com .msg .dat .sta --exclude-regex "set[1-9]"