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 template implements 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].

  1. 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 template project. The Sphinx tutorial and Sphinx documentation assumes that users are building documentation with GNU Make [30]. Since the modsim template 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.

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 [52] is a software package that can retrieve a project version number from version control software, such as git [21].