Developer Manual

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 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 does not yet have a full style guide. Generally, wherever a style can’t be inferred from surrounding code this project falls back to PEP-8-like styles. There are two notable exceptions to the notional PEP-8 fall back:

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. The project convention is to place SConscript files in the project root directory. If SConscript files are relocated, the workflow configuration unpacking for loop in the SConstruct file must be updated to accommodate the file structure change. 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.

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 reponsible for calling workflow SConscript files with the workflow’s construction environment

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

and a unique build directory. By project convention, there is one workflow SConscript file per workflow, so the workflow SConscript file is used as the build directory name. The SConscript calls are constructed in the workflow_configurations variable as a list of workflow SConscript file names.

SConstruct

166workflow_configurations = [
167    "rectangle_compression-nominal",
168    "rectangle_compression-mesh_convergence",
169]
170for workflow in workflow_configurations:
171    build_dir = env["variant_dir_base"] / workflow
172    SConscript(workflow, variant_dir=build_dir, exports={"env": env}, duplicate=False)

Because the project assumes that SConscript files are located in the project root, the logic contained in this workflow configuration loop must be updated if the SConscript files are relocated. The only contraints placed by the project design is the construction of a unique build directory for every iteration of the for loop.

Workflow SConscript#

The workflow configuration SConscript files are named after the workflow, simulation, or assembly that they configure. They are responsible for defining the workflow parameters and for adding targets to the workflow alias(es). The project convention is to construct the workflow alias from the build directory supplied by the SConstruct file. The workflow 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. Any task definitions must unpack the workflow parameters variable.

Import("env")

build_directory = pathlib.Path(Dir(".").abspath)
workflow_name = build_directory.name

parameters = {parameter: value, ...}

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

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

env.Alias(workflow_name, 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)
Contents