Developer Manual#

Dependencies#

The development environment dependencies are found in the project’s environment.yml file. For convenience, the file is reproduced here

 1channels:
 2  - conda-forge
 3
 4dependencies:
 5  - matplotlib
 6  - pandas
 7  - pyyaml
 8  - pytest
 9  - scons >=4.6
10  - sphinx >=7.1
11  - sphinx-argparse
12  - sphinx-book-theme
13  - sphinxcontrib-bibtex
14  - waves
15  - xarray

In addition to the Conda environment managed packages, this project also requires a separately managed installation of TeXLive to build the PDF documentation.

The tutorials in this project may also require:

  1. Abaqus

  2. Cubit

  3. Matlab

Contribution Guidelines#

The modsim_template_2 project uses the Gitlab Flow [1] workflow model.

Git Commit Message#

Begin Git commit messages with one of the following headings:

  • BUG: bug fix

  • DOC: documentation

  • FEAT: feature

  • MAINT: maintenance

  • TST: tests

  • REL: release

  • WIP: work-in-progress

For example:

git commit -m "FEAT: short intent of new feature"
git commit -m "BUG: fixes nasty bug"
git commit -m "DOC: adds documentation for feature"

reStructured Text#

Sphinx reads in docstrings and other special portions of the code as reStructured text. Developers should follow styles in this Sphinx style guide.

Style Guide#

This project uses the Ruff autoformatting and style guide. The Ruff default options are found in pyproject.toml.in. See the Activate Environment section for a discussion about the need for templating the configuration file.

The style guide checks are run with the following alias

$ scons style

You can autoformat Python and SConscript files with the following command.

$ scons ruff-format

You can also run the style checks and format files with ruff directly, but bear in mind that the project uses a template pyproject.toml.in file, so any changes to the ruff configuration must be followed by a re-build of the pyproject.toml file prior to running checks and formatting commands. This dependence is explicitly captured in the style and ruff-format aliases, so it is not necessary to explicitly re-build the pyproject.toml configuration file when using the aliases.

$ scons pyproject.toml && ruff check . && ruff format . --check
$ scons pyproject.toml && ruff check . --fix; ruff format .

Documentation#

The documentation build is also automated with SCons as the documentation target alias.

  • Build all documentation targets

    $ scons documentation
    
  • Build the HTML documentation

    $ scons html
    

Creating Workflows#

This project uses three layers of SCons configuration files:

  1. SConstruct: the project configuration

  2. Workflow SConscript: named after the workflow or simulation, e.g. rectangle_compression

  3. Part/Assembly/Simulation SConscript: named after the re-usable task(s) purpose, e.g. when creating a part use the part name rectangle

There is one, and only one, SConstruct file, which is located in the project root directory. Every SConscript file must contain a module level docstring that describes the import/return requirements of that SConscript file. When updating or adding a new workflow, be sure to update the SConscript docstring to match any requirement changes.

The SConscript files must be located in a single, flat source directory: modsim_package. All project files are also located in the same modsim_package directory. These restrictions result from (1) the project design which intends to produce a single, flat build directory for each workflow and (2) the use of Abaqus input file scanning to determine implicit source/target dependencies. To achieve a single, flat build directory per workflow when re-using SConscript files, every SConscript file must be co-located in the same directory due to SCons target path construction behavior. Abaqus input files are scanned for implicit *INCLUDE statements, so the calling workflow SConscript files must be co-located with the Abaqus input files to resolve relative include paths correctly. These restrictions result in the requirement for a single, flat source directory. Because this directory will grow in proportion to the size of the project, the modsim_package directory may become quite large. Users and developers are encouraged to become comfortable sorting and finding files with grep and find in a bash command line terminal or seeking out the advanced behaviors for file sorting in their preferred GUI file browser.

SConstruct#

The project configuration SConstruct file is responsible for configuring project wide variables, command line options, construction environment(s), and workflows. The SConstruct file is responsible for calling workflow SConscript files with the workflow’s construction environment, alias, and parameters under the variable names env, alias, and parameters, respectively.

The workflow SConscript calls are constructed in the workflow_configurations variable as a dictionary of tuples where the key is an unique workflow alias and the tuple defines the: (1) workflow SConscript file workflow and (2) study definition study_definition.

SConstruct

202workflow_configurations = {
203    "rectangle_compression-nominal": (
204        "rectangle_compression.scons",
205        waves.parameter_generators.OneAtATime(
206            modsim_package.rectangle_compression.nominal(),
207            output_file=parameter_study_output / "nominal.yaml",
208            output_file_type="yaml",
209        ),
210    ),
211    "rectangle_compression-mesh_convergence": (
212        "rectangle_compression.scons",
213        waves.parameter_generators.CartesianProduct(
214            modsim_package.rectangle_compression.mesh_convergence(),
215            output_file=parameter_study_output / "rectangle_compression-mesh_convergence.h5",
216            previous_parameter_study=parameter_study_output / "rectangle_compression-mesh_convergence.h5",
217        ),
218    ),
219}
220for alias, (workflow, study_definition) in workflow_configurations.items():

The alias is constructed from the workflow Sconscript file name and the study name as f"{workflow}_{study_name}" and used to construct a unique build directory name. The workflow file name is assumed to be a base name for a file found in the modsim_package directory.

SConstruct

223    # Project naming conventions
224    workflow_build_directory = build_directory / alias
225    workflow_file = modsim_package_dir / workflow

To accommodate parameters defined by both WAVES parameter studies, which require iterative unpacking, and dictionaries the WAVES ParameterStudySConscript construction environment method is used as

ParameterStudySConscript(..., exports={"env": env, "alias": alias}, study=study_definition, ...)

where the ParameterStudySConscript method will unpack the study_definition and pass along parameter sets using the parameters variable name.

Workflow SConscript#

The workflow configuration SConscript files are named after the workflow, simulation, or assembly that they configure. These files should call SConscript files defining the re-usable portions of the workflow, such as parts and assembly configuration, and may optionally define workflow specific tasks. The workflow configuration files pass the env, and parameters through to the part or assembly SConscript files and are responsible for adding targets to the workflow alias(es). Any task definitions must unpack the workflow parameters variable.

Import("env", "alias", "parameters")

SConscript(..., exports={"env": env, "parameters": parameters}, ...)

env.Command(
    target=[...],
    source=[...],
    action=[...],
    **parameters,
)

env.Alias(alias, targets)

Part/Assembly/Simulation SConscript#

The final layer of SConscript files consists of re-usable task definitions. Most commonly, these contain part (or assembly) configuration files. This layer may also include any re-usable tasks if there are common simulation or post-processing task definitions that can be shared between workflows. These configuration files should accept the construction environment env and workflow parameters. The parameters should be unpacked into the part task definitions. These files may optionally return a list of target artifacts for the parent workflow SConscript file to use in alias definitions.

Import("env", "parameters")

env.Command(
    target=[...],
    source=[...],
    action=[...],
    **parameters,
)

Return("artifacts")