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: GNU Make - https://swcarpentry.github.io/make-novice/ [1, 9, 30]

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 [55] 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 [57] 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 [57] journal files, and others.

The templates use setuptools_scm [55] 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 [49] 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.