You're reading an old version of this documentation. If you want up-to-date information, please have a look at v0.8.2.

API

Subpackages

snl_d3d_cec_verify package

class snl_d3d_cec_verify.CaseStudy(dx=1, dy=1, sigma=3, x0=0, x1=18, y0=1, y1=5, bed_level=- 2, dt_max=1, dt_init=1, turb_pos_x=6, turb_pos_y=3, turb_pos_z=- 1, discharge=6.0574, horizontal_eddy_viscosity=1e-06, horizontal_eddy_diffusivity=1e-06, vertical_eddy_viscosity=1e-06, vertical_eddy_diffusivity=1e-06, simulate_turbines=True, horizontal_momentum_filter=True, stats_interval=None, restart_interval=0)

Bases: object

Class for defining variables for single or multiple case studies.

When defining multiple values for multiple variables, the given sequences must be the same length, e.g.:

>>> cases = CaseStudy(dx=[1, 2, 3, 4],
...                   dy=[4, 5, 6, 7])
>>> print(cases) 
CaseStudy(dx=[1, 2, 3, 4], dy=[4, 5, 6, 7], sigma=3, ...

The above example will generate an object representing 4 cases, which can then be iterated:

>>> for case in cases: 
...     print(case)
CaseStudy(dx=1, dy=4, ...
CaseStudy(dx=2, dy=5, ...
CaseStudy(dx=3, dy=6, ...
CaseStudy(dx=4, dy=7, ...
Parameters:
Raises:

ValueError – if variables with multiple values have different lengths

dx: Union[int, float, Sequence[Union[int, float]]] = 1

grid spacing in x-direction, in meters

dy: Union[int, float, Sequence[Union[int, float]]] = 1

grid spacing in y-direction, in meters

sigma: Union[int, float, Sequence[Union[int, float]]] = 3

number of vertical layers

x0: Union[int, float, Sequence[Union[int, float]]] = 0

minimum x-value, in metres

x1: Union[int, float, Sequence[Union[int, float]]] = 18

maximum x-value, in metres

y0: Union[int, float, Sequence[Union[int, float]]] = 1

minimum y-value, in metres

y1: Union[int, float, Sequence[Union[int, float]]] = 5

maximum y-value, in metres

bed_level: Union[int, float, Sequence[Union[int, float]]] = -2

uniform bed level, in metres

dt_max: Union[int, float, Sequence[Union[int, float]]] = 1

maximum time step, in seconds

dt_init: Union[int, float, Sequence[Union[int, float]]] = 1

initial time step, in seconds

turb_pos_x: Union[int, float, Sequence[Union[int, float]]] = 6

turbine x-position, in meters

turb_pos_y: Union[int, float, Sequence[Union[int, float]]] = 3

turbine y-position, in meters

turb_pos_z: Union[int, float, Sequence[Union[int, float]]] = -1

turbine z-position, in meters

discharge: Union[int, float, Sequence[Union[int, float]]] = 6.0574

inlet boundary discharge, in cubic meters per second

horizontal_eddy_viscosity: Union[int, float, Sequence[Union[int, float]]] = 1e-06

uniform horizontal eddy viscosity, in metres squared per second

horizontal_eddy_diffusivity: Union[int, float, Sequence[Union[int, float]]] = 1e-06

uniform horizontal eddy diffusivity, in metres squared per second

vertical_eddy_viscosity: Union[int, float, Sequence[Union[int, float]]] = 1e-06

uniform vertical eddy viscosity, in metres squared per second

vertical_eddy_diffusivity: Union[int, float, Sequence[Union[int, float]]] = 1e-06

uniform vertical eddy diffusivity, in metres squared per second

simulate_turbines: Union[bool, Sequence[bool]] = True

simulate turbines

horizontal_momentum_filter: Union[bool, Sequence[bool]] = True

use high-order horizontal momentum filter

stats_interval: Union[int, float, None, Sequence[Optional[Union[int, float]]]] = None

interval for simulation progress output, in seconds

restart_interval: Union[int, float, Sequence[Union[int, float]]] = 0

interval for restart file output, in seconds

class property fields: List[str]

Returns field names

Return type:

List[str]

property values: List[Any]

Returns field values

Return type:

List[Any]

get_case(index=0)

Return a unit case study, from the given index

Parameters:

index (int) – Index of study, defaults to 0

Return type:

CaseStudy

class snl_d3d_cec_verify.LiveRunner(d3d_bin_path, omp_num_threads=1, relative_input_parts=<factory>)

Bases: object

A wrapper around the run_dflowfm() function to allow reuse of settings across many Delft3D projects with real time output.

Call the LiveRunner object with the project path to execute the Delft3D model and read the output line by line, like a generator

>>> runner = LiveRunner("path/to/Delft3D/src/bin",
...                     omp_num_threads=8)
>>> for line in runner("path/to/project"): 
...     print(line)

Currently only available for Windows and Linux.

Parameters:

  • d3d_bin_path (Union[str, Path]) – path to the bin folder generated when compiling Delft3D

  • omp_num_threads (int) – The number of CPU threads to use, defaults to {omp_num_threads}

  • relative_input_parts (Optional[List[str]]) – list of components representing the relative path to folder containing the delft3D model files, from the project folder. Set to None to use given path directly. Defaults to ["input"]

__call__(project_path)

Run a simulation, given a prepared model, and yield stdout and stdin streams.

Parameters:

project_path (Union[str, Path]) – path to Delft3D project folder

Raises:

  • OSError – if function is called on an unsupported operating system

  • FileNotFoundError – if the Delft3D entry point or model folder could not be found

  • RuntimeError – if the Delft3D simulation outputs to stderr, for any reason

Return type:

Iterator[str]

d3d_bin_path: Union[str, Path]

path to the bin folder generated when compiling Delft3D

omp_num_threads: int = 1

The number of CPU threads to use

relative_input_parts: Optional[List[str]]

list of components representing the relative path to folder containing the delft3D model files, from the project folder. Set to None to given path directly

class snl_d3d_cec_verify.MycekStudy(dx=1, dy=1, sigma=3, dt_max=1, dt_init=1, discharge=6.0574, horizontal_eddy_viscosity=1e-06, horizontal_eddy_diffusivity=1e-06, vertical_eddy_viscosity=1e-06, vertical_eddy_diffusivity=1e-06, simulate_turbines=True, horizontal_momentum_filter=True, stats_interval=None, restart_interval=0)

Bases: CaseStudy

Class for defining cases corresponding to the Mycek study. Subclass of CaseStudy with the domain and turbine position fixed.

Parameters:
Raises:

ValueError – if variables with multiple values have different lengths

x0: Union[int, float, Sequence[Union[int, float]]] = 0

minimum x-value, in metres

x1: Union[int, float, Sequence[Union[int, float]]] = 18

maximum x-value, in metres

y0: Union[int, float, Sequence[Union[int, float]]] = 1

minimum y-value, in metres

y1: Union[int, float, Sequence[Union[int, float]]] = 5

maximum y-value, in metres

bed_level: Union[int, float, Sequence[Union[int, float]]] = -2

uniform bed level, in metres

turb_pos_x: Union[int, float, Sequence[Union[int, float]]] = 6

turbine x-position, in meters

turb_pos_y: Union[int, float, Sequence[Union[int, float]]] = 3

turbine y-position, in meters

turb_pos_z: Union[int, float, Sequence[Union[int, float]]] = -1

turbine z-position, in meters

class snl_d3d_cec_verify.Report(width=None, date_format=None)

Bases: object

Class for creating a report in Pandoc markdown format

The final report can be viewed by printing the Report object, for example:

>>> report = Report(70, "%d %B %Y")
>>> report.title = "Test"
>>> report.authors = ["Me", "You"]
>>> report.date = "1916-04-24"
>>> report.content.add_text("Lorem ipsum dolor sit amet, consectetur "
...                         "adipiscing elit. Maecenas vitae "
...                         "scelerisque magna.")
>>> print(report)
1: % Test
2: % Me; You
3: % 24 April 1916
4:
5: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas
6: vitae scelerisque magna.
7:

Note that line numbers are also printed. The report can also be saved to file, by iterating through each line:

>>> with open("report.md", "wt") as f: 
...     for line in report:
...         f.write(line)
Parameters:
content: Content

Container for the main body of the document. See the Content documentation for usage.

property width

The maximum paragraph width, in characters. Set to None for no limit.

Type:

Optional[int]

property date_format

format for document date as passed to datetime.date.strftime(). Set to None to use ISO 8601 format

Type:

Optional[str]

property title

Title for the document. Set to None to remove.

Type:

Optional[str]

property authors

The authors of the document, as a list. Set to None to remove.

Type:

Optional[List[str]]

property date

The date of the document. Can be set using ISO 8601 format or can be given as “today” to use the current date. Set to None to remove.

Type:

Optional[str]

class snl_d3d_cec_verify.Result(project_path, relative_map_parts=None)

Bases: object

Class for capturing the results of executed case studies. Contains metadata from the simulation. Data generated on the grid edges and faces are accessible from the edges and faces attributes.

>>> data_dir = getfixture('data_dir')
>>> result = Result(data_dir)
>>> result.x_lim
(0.0, 18.0)

>>> result.edges.extract_k(-1, 1) 
                                        geometry            u1   n0   n1
0      LINESTRING (1.00000 2.00000, 0.00000 2.00000) -3.662849e-17  0.0  1.0
...
Parameters:

  • project_path (Union[str, Path]) – path to the Delft3D project directory

  • relative_map_parts (Optional[List[str]]) – list of components representing the relative path to the FlowFM_map.nc file, from the project directory. Defaults to ["output", "FlowFM_map.nc"]

property x_lim

Domain limits in the x-direction, in metres

Type:

Tuple[float, float]

>>> data_dir = getfixture('data_dir')
>>> result = Result(data_dir)
>>> result.x_lim
(0.0, 18.0)
property y_lim

Domain limits in the y-direction, in metres

Type:

Tuple[float, float]

>>> data_dir = getfixture('data_dir')
>>> result = Result(data_dir)
>>> result.y_lim
(1.0, 5.0)
property times

Time steps of the Delft3D simulation

Type:

numpy.typing.NDArray[numpy.datetime64]

>>> data_dir = getfixture('data_dir')
>>> result = Result(data_dir)
>>> result.times
array(['2001-01-01T00:00:00.000000000', '2001-01-01T01:00:00.000000000'],
dtype='datetime64[ns]')
property edges

Results on the grid edges. See the Edges documentation for usage

Type:

Edges

property faces

Results on the grid faces. See the Faces documentation for usage

Type:

Faces

class snl_d3d_cec_verify.Runner(d3d_bin_path, omp_num_threads=1, show_stdout=False, relative_input_parts=<factory>)

Bases: object

A wrapper around the run_dflowfm() function to allow reuse of settings across many Delft3D projects.

Call the Runner object with the project path to execute the Delft3D model

>>> runner = Runner("path/to/Delft3D/src/bin",
...                  omp_num_threads=8)
>>> runner("path/to/project")

Currently only available for Windows and Linux.

Parameters:

  • d3d_bin_path (Union[str, Path]) – path to the bin folder generated when compiling Delft3D

  • omp_num_threads (int) – The number of CPU threads to use, defaults to {omp_num_threads}

  • show_stdout (bool) – show Delft3D logging to stdout in console, defaults to {show_stdout}

  • relative_input_parts (Optional[List[str]]) – list of components representing the relative path to folder containing the delft3D model files, from the project folder. Set to None to use given path directly. Defaults to ["input"]

__call__(project_path)

Run a simulation, given a prepared model.

Parameters:

project_path (Union[str, Path]) – path to Delft3D project folder

Raises:

  • OSError – if function is called on an unsupported operating system

  • FileNotFoundError – if the Delft3D entry point or model folder could not be found

  • RuntimeError – if the Delft3D simulation outputs to stderr, for any reason

d3d_bin_path: Union[str, Path]

path to the bin folder generated when compiling Delft3D

omp_num_threads: int = 1

The number of CPU threads to use

show_stdout: bool = False

show Delft3D logging to stdout in console

relative_input_parts: Optional[List[str]]

list of components representing the relative path to folder containing the delft3D model files, from the project folder. Set to None to given path directly

class snl_d3d_cec_verify.Template(template_path=None, exist_ok=False, no_template=<factory>)

Bases: object

Class for creating Delft3D projects from templates

Utilises the copier.copy() function to fill the template and the gridfm.write_gridfm_rectangle() function to create the flexible mesh grid. Note that the template files are copied on initialization, therefore changes to the template source will not affect the object’s output.

Call a Template object with a length one CaseStudy object and a path at which to create a Delft3D project. For example:

>>> import pprint
>>> import tempfile
>>> from pathlib import Path
>>> template = Template()
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     template(CaseStudy(), tmpdirname)
...     inputdir = Path(tmpdirname) / "input"
...     pprint.pprint(sorted([x.name for x in inputdir.iterdir()]))
['Discharge.bc',
 'FlowFM.mdu',
 'FlowFM_bnd.ext',
 'FlowFM_net.nc',
 'Inlet.pli',
 'Outlet.pli',
 'WaterLevel.bc',
 'curves.trb',
 'turbines.ini']
Parameters:

  • template_path – path to the Delft3D project template, defaults to Path("./templates/fm")

  • exist_ok – if True, allow an existing path to be overwritten, defaults to False

  • no_template – variables to ignore in the given CaseStudy objects when filling templates, defaults to ["dx", "dy"]

__call__(case, project_path, exist_ok=None)

Create a new Delft3D project from the given CaseStudy object, at the given path.

Note that boolean values are converted to integers and Nones are converted to empty strings.

Parameters:
Raises:
template_path: InitVar[StrOrPath] = None
exist_ok: bool = False

if True, allow an existing path to be overwritten

no_template: List[str]

variables to ignore in the given CaseStudy objects when filling templates

class snl_d3d_cec_verify.Validate(case=None, data_dir=None)

Bases: object

Store for Transect objects

Print the object to see the descriptions and indices of the stored Transect objects.

>>> validate = Validate()
>>> print(validate)
Validate(0: Centreline velocity
         1: Axial velocity at $x^*=5$)

>>> validate[0].to_xarray() 
<xarray.DataArray '$u_0$' (dim_0: 10)>
array([0.40064647, 0.40064647, 0.39288889, 0.38189899, 0.39806061,
       0.44460606, 0.49309091, 0.54610101, 0.56614141, 0.60622222])
Coordinates:
    $z$      ... 0
    $x$      (dim_0) float64 0.84 1.4 2.1 2.8 3.5 4.2 4.9 5.6 6.3 7.0
    $y$      (dim_0) float64 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
...

Use a CaseStudy object to translate the origin of the transects to the turbine position.

>>> from snl_d3d_cec_verify import MycekStudy
>>> case = MycekStudy()
>>> validate = Validate(case)
>>> validate[0].to_xarray() 
<xarray.DataArray '$u_0$' (dim_0: 10)>
array([0.40064647, 0.40064647, 0.39288889, 0.38189899, 0.39806061,
       0.44460606, 0.49309091, 0.54610101, 0.56614141, 0.60622222])
Coordinates:
    $z$      ... -1
    $x$      (dim_0) float64 6.84 7.4 8.1 8.8 9.5 10.2 10.9 11.6 12.3 13.0
    $y$      (dim_0) float64 3.0 3.0 3.0 3.0 3.0 3.0 3.0 3.0 3.0 3.0
...
Parameters:

  • case – Case study from which to get turbine position

  • data_dir – path to folder containing YAML files representing transects. Each file must have the attrs.description key set. Defaults to Path("./mycek2014")

Raises:

FileNotFoundError – if data_dir is not a directory