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:
Abaqus
Cubit
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:
SConstruct: the project configuration
Workflow SConscript: named after the workflow or simulation, e.g.
rectangle_compressionPart/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")