SNL-Delft3D-CEC-Verify is a python package for automated testing of SNL-Delft3D-CEC and SNL-Delft3D-FM-CEC which adds current energy converter (CEC) support to the Delft3D 4 (structured) and Delft3D Flexible Mesh suites, respectively. This package is used to verify the performance of SNL-Delft3D-CEC and SNL-Delft3D-FM-CEC by comparing against the 2014 flume experiment conducted by Mycek et al.[1].
Due to the many non-Python binary requirements of the package dependencies, installation requires the use of Anaconda Python or a fully free-to-use equivalent, such as Miniforge.
From a conda prompt create a named environment in which to install the
snl-delft3d-cec-verify conda package and then set up the channels required
for future updates:
(base) > conda create -y -n snld3d --override-channels -c conda-forge -c dataonlygreater snl-delft3d-cec-verify=0.8.2
(base) > conda activate snld3d
(snld3d) > conda config --env --add channels conda-forge --add channels dataonlygreater
(snld3d) > conda config --env --set channel_priority strict
After this, working with SNL-Delft3D-CEC-Verify requires that the snld3d
environment be activated:
(base) > conda activate snld3d
(snld3d) >
To update to the latest version of the conda package, using the snld3d
environment, type:
(snld3d) > conda update -y snl-delft3d-cec-verify
The following presents an example of running a case study using a flexible mesh
("fm") model, based on the Mycek experiment, and collecting results at the
turbine centre. Note that the token <D3D_BIN>, should be replaced with the
path to the bin directory of the compiled Delft3D source code.
>>> import tempfile
>>> from snl_d3d_cec_verify import MycekStudy, Result, Runner, Template
>>> template = Template()
>>> runner = Runner(<D3D_BIN>)
>>> case = MycekStudy()
>>> with tempfile.TemporaryDirectory() as tmpdirname:
... template(case, tmpdirname)
... runner(tmpdirname)
... result = Result(tmpdirname)
... print(result.faces.extract_turbine_centre(-1, case))
Dimensions: (dim_0: 1)
Coordinates:
$z$ int32 -1
time datetime64[ns] 2001-01-01T01:00:00
$x$ (dim_0) int32 6
$y$ (dim_0) int32 3
Dimensions without coordinates: dim_0
Data variables:
$\sigma$ (dim_0) float64 -0.5002
$u$ (dim_0) float64 0.7147
$v$ (dim_0) float64 4.472e-17
$w$ (dim_0) float64 -0.002604
$k$ (dim_0) float64 0.005182
To use a structured model in the above example, change line 3 to:
>>> template = Template("structured")
More detailed examples are provided in the section below.
Examples are provided in the examples.zip asset of the latest
release. Alternatively, they can be found in the examples folder of
the source code. Each example can be run using either the flexible mesh or
structured grid models.
As plots are generated in the examples, the matplotlib library is also
required. To install it, type:
(snld3d) > conda install -y matplotlib
The examples generate reports in Pandoc markdown format. These reports
can be optionally converted to Word format if the pypandoc package is
installed. To install it, type:
(snld3d) > conda install -y pypandoc pandoc
Currently, a compiled copy of SNL-Delft3D-CEC or SNL-Delft3D-FM-CEC must be
available for the examples to run. If the binaries are installed in the
standard location in the Delft3D source code (i.e. in the src/bin folder),
simply copy the required files for each example to the source code's
examples directory. A list of files required to run each example is provided
at the top of the subsections below.
Alternatively, the location of Delft3D binaries can specified by setting the
D3D_BIN environment variable, instead of copying the example files. To set
D3D_BIN, for example, using PowerShell:
(snld3d) > $env:D3D_BIN = "\path\to\SNL-Delft3D-FM-CEC\src\bin"
Required files:
basic.pyreference.docx(for conversion to Word format)
The basic example shows how to define a flexible mesh or structured model with varying parameters, run the model and then analyse the results.
To run the example, move to the directory containing basic.py and then call
the script using Python with the model type (either fm or structured) as
the second argument. For instance, for the flexible mesh model call:
(snld3d) > python basic.py fm
If successful, the report files (and images) will be placed into a
sub-directory based on the model type. For the flexible mesh model, this is
fm/basic_report.
By default, the temporary directories in which the models are run are deleted
upon completion. To keep these directories, use the --persistent flag. For
example:
(snld3d) > python basic.py structured --persistent
Required files:
validation.pyexamples.bib(for conversion to Word format)reference.docx(for conversion to Word format)
The validation example demonstrates comparison of a flexible mesh or structured model with the experimental results of Mycek et al.[1]
To run the example, move to the directory containing validation.py and then
call the script using Python with the model type (either fm or structured)
as the second argument. For instance, for the structured grid model call:
(snld3d) > python validation.py structured
If successful, the report files (and images) will be placed into a
sub-directory based on the model type. For the structured grid model, this is
structured/validation_report.
Required files:
grid_convergence.pyexamples.bib(for conversion to Word format)reference.docx(for conversion to Word format)
This is the first "production" example, designed to generate meaningful results. A grid convergence study (see e.g. [2]) is conducted to determine the free stream and turbine wake velocities and turbulence intensities at infinite grid resolution. The results are then compared to the results of Mycek et al.[1].
This example requires the convergence package to be installed. Issue the following command in the conda environment:
(snld3d) > pip install convergence
To run the example, move to the directory containing grid_convergence.py and
then call the script using Python with the model type (either fm or
structured) as the second argument. For instance, for the flexible mesh
model call:
(snld3d) > python grid_convergence.py fm
If successful, the report files (and images) will be placed into a
sub-directory based on the model type. For the flexible mesh model, this is
structured/grid_convergence_report. To avoid repeating simulations in the
event of an unexpected failure or change to the grid_convergence.py file,
the Delft3D simulations, and a copy of their case study parameters, are stored
in a sub-directory based on the model type. For the structured grid model, for
example, this is structured/runs. If the Delft3D solver is updated, ensure to
delete or move this folder, so that new simulations are conducted.
By default, the study is conducted using just one CPU thread. To reduce
simulation time of the fm model, assuming additional capacity is available,
increase the number of utilised threads using the --threads optional argument:
(snld3d) > python grid_convergence.py fm --threads 8
Note that this study takes a considerable amount of wall-clock time to
complete. On an Intel i7-4790, the full study required 78 hours. To run
an incomplete study, with a more tractable time scale, use the --experiments
optional argument to reduce the number of experiments. For example:
(snld3d) > python grid_convergence.py fm --threads 8 --experiments 3
Pre-calculated results of the full study are available in the online documentation.
Required files:
comparison.pyexamples.bib(for conversion to Word format)reference.docx(for conversion to Word format)
The second production example is a comparison of the flexible mesh and structured grid solvers for a turbine simulation using identical settings.
This example uses the pandoc-crossref package to reference sections and figures within the generated report. To install the package (for converting to Word format with pypandoc) issue the following command:
(snld3d) > conda install pandoc-crossref
For the example to run, two environment variable must be set. For path to
the flexible mesh solver, set the D3D_FM_BIN variable. In PowerShell, for
example:
(snld3d) > $env:D3D_FM_BIN = "\path\to\SNL-Delft3D-FM-CEC\src\bin"
For the path to the structured grid solver, set the D3D_4_BIN environment
variable. In PowerShell again:
(snld3d) > $env:D3D_4_BIN = "\path\to\SNL-Delft3D-CEC\src\bin"
Then move to the directory containing comparison.py and call the script using
Python:
(snld3d) > python comparison.py
If successful, the report files (and images) will be placed into a
sub-directory called comparison_report. To avoid repeating simulations, the
Delft3D simulations, and a copy of their case study parameters, are stored in
a sub-directory based on the model type. For the flexible mesh model this is
fm/runs and for the structured grid model it's structured/runs. If
either Delft3D solver is updated, ensure to delete or move these folders, so
that new simulations are conducted.
By default, the study is conducted using just one CPU thread. To reduce
simulation time of the fm model, assuming additional capacity is available,
increase the number of utilised threads using the --threads optional argument:
(snld3d) > python comparison.py --threads 8
Note that this study takes a considerable amount of wall-clock time to
complete. To run the simulations at lower resolution (and, therefore, more
rapidly), use the --grid-resolution optional argument. For example:
(snld3d) > python comparison.py --threads 8 --grid-resolution 0.25
Pre-calculated results of the study at the default resolution of 0.0625m is available in the online documentation.
API documentation, which describes the classes and functions used in the examples, can be found here. Documentation updates are ongoing.
git lfs clone when cloning the repository to download all of the
files and set up LFS. For example:
> git lfs clone https://github.com/Data-Only-Greater/SNL-Delft3D-CEC-Verify.git
Due to the many non-Python binary requirements of the package dependencies,
installation requires the use of Anaconda Python or a fully free-to-use
equivalent, such as Miniforge. Open a conda prompt and then change
directory into the package root. Use the following commands to install the
package, testing and documentation dependencies into the _snld3d environment.
(base) > conda env create --file .conda/environment.yml
Activate the _snld3d environment, setup the channels, and then install the
SNL-Delft3D-CEC-Verify package in development mode:
(base) > conda activate _snld3d
(_snld3d) > conda config --env --add channels conda-forge
(_snld3d) > conda config --env --set channel_priority strict
(_snld3d) > pip install --no-deps -e .
To run the unit tests and get a coverage report, type the following from the root directory:
(_snld3d) > pytest --cov-report term-missing --cov="./src/snl_d3d_cec_verify/"
To run the type tests, type the following from the root directory:
(_snld3d) > mypy --install-types --non-interactive src
To run doctests, type the following from the root directory:
(_snld3d) > pytest --doctest-modules src
To run all three test suites simultaneously, invoke tox from the root directory:
(_snld3d) > tox
Note that tox creates a dedicated environment for the tests, which can be time consuming on first run (or if there are any dependency changes).
HTML documentation is built using the Sphinx documentation system, with the sphinx-autodoc-typehints plugin and the insipid theme.
To build the documentation locally, activate the conda environment and move to
the docs directory:
(base) > conda activate _snld3d
(_snld3d) > cd docs
Then to build, for Windows:
(_snld3d) > .\make.bat html
Alternatively for Linux
(_snld3d) > make html
The documentation can then be opened at the path docs/_build/html/index.html.
Use python-semantic-release to update version numbers in the package. For instance, to add a commit that bumps the patch version, call:
(_snld3d) > semantic-release version --patch
To remove the conda environment containing SNL-Delft3D-CEC-Verify, open an Ananconda prompt and type:
(base) > conda remove --name _snld3d --all
You may need to deactivate the _snld3d environment first, if it is still
open, by typing:
(_snld3d) > conda deactivate
(base) > conda remove --name _snld3d --all
Some of the code in this package is derived from the delft3dfmpy project.
[1] Mycek, P., Gaurier, B., Germain, G., Pinon, G., & Rivoalen, E. (2014). Experimental study of the turbulence intensity effects on marine current turbines behaviour. Part I: One single turbine. Renewable Energy, 66, 729–746.
[2] Examining Spatial (Grid) Convergence. (2002). Retrieved 24 January 2022, from https://www.grc.nasa.gov/www/wind/valid/tutorial/spatconv.html