Skip to main content
`Ctrl`+`K`

# ModSim Templates

Users who are are ready to create their own modsim repository can use the WAVES Command-Line Utility fetch subcommand to access the project ModSim Templates. The template files include project documentation built with SCons and Sphinx and two simulation configurations for the rectangle project developed in the tutorials: nominal and mesh convergence. The fetch subcommand may be used to recursively fetch directories or to fetch individual files from both the ModSim Templates and the tutorials.

## Prerequisites

1. Computational Practices - Build System

2. Software Carpentry: SCons Novice - https://carpentries-incubator.github.io/scons-novice/ [1, 9]

3. Software Carpentry: Python - https://swcarpentry.github.io/python-novice-inflammation/ [1, 8]

In addition to the tutorial prerequisites, the modsim templates implement documentation with Sphinx. The Sphinx tutorial below is a good introduction to writing documentation with reStructuredText [29]. The Sphinx documentation also contains a useful reference in the reStructuredText Primer [12].

4. Sphinx tutorial: https://www.sphinx-doc.org/en/master/tutorial/index.html [12, 13]

There is one significant difference between the Sphinx tutorial and the modsim templates documentation. The Sphinx tutorial and Sphinx documentation assumes that users are building documentation with GNU Make [30]. Since the modsim templates and WAVES already use the SCons [31] build system for running workflows, the documentation template files also use SCons as the build system. Users can find the available documentation commands with `scons -h` and the documentation configuration is found in the `modsim_template/docs/SConscript` file, which should look familiar to SCons users but may require some translation from the Sphinx manual build commands.

## Template comparisons

There are currently two template projects available: `modsim_template` and `modsim_template_2`. The first `modsim_template` is most similar to the tutorials and will be the easiest starting point for novice SCons and WAVES users. It allows for a great deal of flexibility in both source and build tree structure. The second `modsim_template_2` has advantages for advanced SCons and WAVES users but places restrictions on the source and build tree structures and may be difficult for novice command line users to navigate.

`modsim_template_2` uses the SCons SConscript `duplicate=True` default behavior [31, 32] to reduce the number of explicit file copy operations with `waves.scons_extensions.copy_substfile()` and the Abaqus input file scanner, `waves.scons_extensions.abaqus_input_scanner()`, to reduce the size of Abaqus solver source file lists. This template also uses the `waves.scons_extensions.parameter_study_sconscript`()` call to further reduce task duplication. These features help reduce SConstruct and SConscript verbosity and aid in automated source list construction.

However, these advanced features restrict source and/or build tree structure. The `duplicate=True` and `waves.scons_extensions.abaqus_input_scanner()` features require that the SConscript files must be co-located with the source files they describe. Therefore, the part and simulation SConscript files (`rectangle` and `rectangle_compression`) are found in the `modsim_package` directory in `modsim_template_2`.

The `scons_extensions.parameter_study_sconscript()` feature allows projects to unpack parameter studies during an SConscript call. This removes the need for separate `nominal` and `mesh_convergence` simulation workflow files, which are replaced by a single `rectangle_compression` workflow file. Combining these simulation workflows reduces new simulation definitions to an entry in SConstruct, but does require that workflow specific post-processing tasks be moved to dedicated SConscript files: `rectangle_compression-nominal-regression` and `rectangle_compression-mesh_convergence-post_processing`.

To preserve the build tree structure with nested SConscript calls, all SConscript files must be found in the same parent directory, so the downstream workflow SConscript files (`rectangle_compression-nominal-regression` and `rectangle_compression-mesh_convergence-post_processing`) must also be located in the `modsim_package` directory. This template requires a totally flat `modsim_package` structure, which may be cumbersome for large projects, particularly if users tend to rely on graphical file browsers.

## Fetch Template Files

See the fetch subcommand for a complete discussion of behavior and options. The examples below are included as a recommended starting place when creating a modsim project from scratch. This will create a complete and functional modsim project in the user’s home directory. If the directory already exists and is populated, existing files will not be overwritten.

    $ waves fetch modsim_template --destination ~/modsim_template

You can view the list of available files as below.

    $ waves fetch --print-available

In addition to the modsim template files, the subcommand can also fetch all of the tutorial files, so the list may be quite long. To view a shorter list, or to preview the file copy operations prior to execution, use the following option

    $ waves fetch modsim_template --destination ~/modsim_template --dry-run

## Version Control

The modsim template in this project does not require users to implement version control, but version control is highly recommended. The purpose and benefits of using version control for modsim files can be found in the Computational Practices Version Control discussion. The modsim template can be updated to use dynamic versioning with the Tutorial: setuptools_scm, where setuptools_scm [60] is a software package that can retrieve a project version number from version control software, such as git [21].

# External Resources

## Sphinx Documentation

- `docs/conf.py.in`

- `docs/SConscript`

- `docs/_static/custom.css`

- `report/conf.py.in`

- `report/SConscript`

The modsim templates makes use of Sphinx documentation, which uses compiled reStructuredText [29]. For more details on using Sphinx, see the main Sphinx documentation [12].

The Sphinx configuration file `conf.py.in` is set up with the modsim template metadata, variables, extensions, and settings required to build the documentation. Note the added `.in` extension for parameter substitution compatibility.

The templates use Sphinx automodule capability. This automatically reads the Sphinx-formatted docstrings within Python files and adds it to the Sphinx pages. The `conf.py.in` file includes definition of mock modules required to run the Sphinx automodule on functions importing modules that are unavailable in the Conda Python 3 environment. By default, the templates include Abaqus and Cubit [62] mock module imports.

The `docs/SConscript` file includes a list of the documentation files to construct both the source file list and the `.html` targets list.

A custom theme is defined in the configuration file: `_static/custom.css`. The theme is defined in CSS format and, for the templates, simply defines the max width of the generated pages.

The modsim templates set up separate building of the documentation and the report. The report uses its own shorter `conf.py.in` and separate `index.rst`. The tasks defined in `report/SConscript` copy files from the `docs/` directory to build the report, allowing both the report and the documentation to share documentation text, reference, and target files.

## Git

- `.gitignore`

- `pyproject.toml`

The modsim templates are designed to use Git [21] for version control: a `.gitignore` file is included in each template root directory. By default, it includes common build artifacts that are not usually tracked with version control, such as the `build/` directory, Abaqus and Cubit [62] journal files, and others.

The templates use setuptools_scm [60] to assist with version numbering using Git metadata. A tutorial on its usage can be found as part of the WAVES Tutorial: setuptools_scm.

## pytest

- `modsim_package/tests/test_*.py`

- `pyproject.toml`

For unit testing, pytest [54] is implemented for the rectangle compression workflow. These tests can be found in `modsim_package/tests/`. The prepackaged tests currently include testing on inputs passed to argparse, mesh convergence, and helper functions used for the rectangle compression simulation. There are 13 tests in total. Tests can be run using `scons unit_testing`.

Within the `pyproject.toml` file, pytest configuration options are set to use the default pytest options.