Skip to main content
`Ctrl`+`K`

# Tutorial: Simulation via SSH

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!

Warning

The `waves.scons_extensions.ssh_builder_actions()` is a work-in-progress solution with some assumptions specific to the action construction used by WAVES. It _should_ work for most basic builders, but adapting this function to users’ custom builders will probably require some advanced SCons knowledge and inspection of the `waves.scons_extensions_ssh_builder_actions()` implementation.

This tutorial implements the same workflow introduced in Tutorial 04: Simulation, but executes the simulation on a remote server via SSH. You may need to update the server name to match your local system or local remote server.

This tutorial assumes that the local system has an installation of Abaqus and that the Abaqus installation on the local system is indentical to the installation on the remote server. You may need to update both Abaqus paths to match the respective systems.

## References

- `ssh`

- `rsync`

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

## 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 4 && mv tutorial_04_simulation_SConstruct SConstruct
    Destination directory: '/home/roppenheimer/waves-tutorials'

4. Download and copy the `tutorial_04_simulation` file to a new file named `tutorial_remote_execution` with the WAVES Command-Line Utility fetch subcommand.

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

## SConscript

A `diff` against the `tutorial_04_simulation` file from Tutorial 04: Simulation is included below to help identify the changes made in this tutorial.

waves-tutorials/tutorial_remote_execution

    --- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_04_simulation
    +++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_remote_execution
    @@ -5,6 +5,9 @@

     * ``env`` - The SCons construction environment with the following required keys

    +  * ``project_dir`` - String absolute path to the project project root directory
    +  * ``project_name`` - String project name
    +  * ``version`` - String project version number
       * ``unconditional_build`` - Boolean flag to force building of conditionally ignored targets
       * ``abaqus`` - String path for the Abaqus executable
     """
    @@ -14,9 +17,13 @@
     # Inherit the parent construction environment
     Import("env")

    +# Set project-wide paths with os-agnostic path separators
    +project_dir = env["project_dir"]
    +
     # Simulation variables
     build_directory = pathlib.Path(Dir(".").abspath)
     workflow_name = build_directory.name
    +relative_build_directory = build_directory.relative_to(project_dir)

     # Comment used in tutorial code snippets: marker-1

    @@ -73,7 +80,7 @@

     # Comment used in tutorial code snippets: marker-4

    -# Abaqus Solve
    +# Datacheck Solve. Performed locally.
     solve_source_list = [
         "rectangle_compression.inp",
         "assembly.inp",
    @@ -106,8 +113,9 @@

     # Comment used in tutorial code snippets: marker-5

    +# Remote Abaqus Solve with SSH
     workflow.extend(
    -    env.AbaqusSolver(
    +    env.SSHAbaqusSolver(
             target=[
                 "rectangle_compression.odb",
                 "rectangle_compression.dat",

## SConstruct

A `diff` against the `SConstruct` file from Tutorial 04: Simulation is included below to help identify the changes made in this tutorial.

waves-tutorials/SConstruct

    --- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_04_simulation_SConstruct
    +++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_remote_execution_SConstruct
    @@ -1,6 +1,7 @@
     #! /usr/bin/env python

     import os
    +import getpass
     import pathlib

     import waves
    @@ -90,7 +91,16 @@
     # Comments used in tutorial code snippets: marker-5

     # Add builders and pseudo-builders
    -env.Append(BUILDERS={})
    +user = getpass.getuser()
    +env.Append(
    +    BUILDERS={
    +        "SSHAbaqusSolver": waves.scons_extensions.ssh_builder_actions(
    +            waves.scons_extensions.abaqus_solver_builder_factory(program="/apps/abaqus/Commands/abq2024"),
    +            remote_server="sstbigbird.lanl.gov",
    +            remote_directory=f"/scratch/{user}/WAVES-TUTORIAL/tutorial_remote_execution",
    +        ),
    +    }
    +)

     # Comments used in tutorial code snippets: marker-6

    @@ -100,6 +110,7 @@
         "tutorial_02_partition_mesh",
         "tutorial_03_solverprep",
         "tutorial_04_simulation",
    +    "tutorial_remote_execution",
     ]
     for workflow in workflow_configurations:
         build_dir = env["variant_dir_base"] / workflow

## Build Targets

5. Build the new targets

    $ pwd
    /home/roppenheimer/waves-tutorials
    $ scons tutorial_remote_execution

## Output Files

Explore the contents of the `build` directory using the `tree` command against the `build` directory, as shown below. Note that the output files from the previous tutorials also exist in the `build` directory, but the directory is specified by name to reduce clutter in the ouptut shown.

    $ pwd
    /home/roppenheimer/waves-tutorials
    $ tree build/tutorial_remote_execution/