Skip to content

Commit

Permalink
rewrap text
Browse files Browse the repository at this point in the history
  • Loading branch information
@JoostBuitink
JoostBuitink committed Oct 30, 2024
1 parent 496d90c commit 9135395
Show file tree
Hide file tree
Showing 31 changed files with 1,577 additions and 1,564 deletions.
12 changes: 9 additions & 3 deletions docs/changelog.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ title: "Changelog"

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this
project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## v1.0.0

Expand All @@ -21,7 +21,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## v0.x releases

### [unreleased]
### v0.8.1 - 2024-08-27

#### Fixed
- Reduce allocations in update of vertical `SBM` concept.

### v0.8.0 - 2024-08-19

#### Fixed
- Added missing BMI function `get_grid_size`, it is used for unstructured grids, for example
Expand Down Expand Up @@ -115,6 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Local inertial routing to `sbm_gwf` model type.
- Water demand and allocation computations for model types `sbm` and `sbm_gwf`.


### v0.7.3 - 2024-01-12

#### Fixed
Expand Down
7 changes: 4 additions & 3 deletions docs/developments/guide.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@ title: Developers guide

## Contributions and reporting issues

We welcome reporting of issues on [our GitHub page](https://github.com/Deltares/Wflow.jl/issues/new/choose).
Please provide a minimum working example so we are able to reproduce the issue. Furthermore, we
welcome contributions. We follow the [ColPrac guide for collaborative practices](https://github.com/SciML/ColPrac). New
We welcome reporting of issues on [our GitHub
page](https://github.com/Deltares/Wflow.jl/issues/new/choose). Please provide a minimum working
example so we are able to reproduce the issue. Furthermore, we welcome contributions. We follow
the [ColPrac guide for collaborative practices](https://github.com/SciML/ColPrac). New
contributors should make sure to read that guide.

## Style/decisions
Expand Down
38 changes: 18 additions & 20 deletions docs/developments/julia_structs.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ title: Julia structures

## Model

Below the composite type that represents all different aspects of a `Wflow.Model`, such as
the network, parameters, clock, model type, configuration and input and output.
Below the composite type that represents all different aspects of a `Wflow.Model`, such as the
network, parameters, clock, model type, configuration and input and output.

```julia
struct Model{N,L,V,R,W,T}
Expand All @@ -21,9 +21,9 @@ end
```

The `lateral` field of the `struct Model` can contain different lateral concepts. For each
wflow model these different lateral concepts are mapped through the use of a `NamedTuple`.
The `vertical` field of the `struct Model` always contains one vertical concept, for example
the SBM vertical concept.
wflow model these different lateral concepts are mapped through the use of a `NamedTuple`. The
`vertical` field of the `struct Model` always contains one vertical concept, for example the
SBM vertical concept.

Below an example how lateral concepts are mapped for the SBM model through a `NamedTuple`:

Expand All @@ -32,22 +32,21 @@ Below an example how lateral concepts are mapped for the SBM model through a `Na
```

The `subsurface` part is mapped to the lateral subsurface flow kinematic wave concept, the
`land` part is mapped the overland flow kinematic wave concept and the `river` part is
mapped to the river flow kinematic wave concept. Knowledge of this specific mapping is
required to understand and correctly set input, output and state variables in the TOML
configuration file, see also [Config and TOML](@ref config_toml). This mapping is described in more
detail for each model in the section Models. Also the `struct` of each mapped concept is
provided, so one can check the internal variables in the code. These structs are defined as
a parametric composite type, with type parameters between curly braces after the `struct`
name. See also the next paragraph [Vertical and lateral models](@ref) for a more
detailed description.
`land` part is mapped the overland flow kinematic wave concept and the `river` part is mapped
to the river flow kinematic wave concept. Knowledge of this specific mapping is required to
understand and correctly set input, output and state variables in the TOML configuration file,
see also [Config and TOML](@ref config_toml). This mapping is described in more detail for each
model in the section Models. Also the `struct` of each mapped concept is provided, so one can
check the internal variables in the code. These structs are defined as a parametric composite
type, with type parameters between curly braces after the `struct` name. See also the next
paragraph [Vertical and lateral models](@ref) for a more detailed description.

## Vertical and lateral models
The different model concepts used in wflow are defined as parametric [composite
types](https://docs.julialang.org/en/v1/manual/types/#Composite-Types). For example the
vertical `SBM` concept is defined as follows: `struct SBM{T,N,M}`. `T`, `N` and `M` between
curly braces after the `struct` name refer to type parameters, for more information about
type parameters you can check out [Type
curly braces after the `struct` name refer to type parameters, for more information about type
parameters you can check out [Type
parameters](https://docs.julialang.org/en/v1/manual/types/#man-parametric-composite-types).
Since these parameters can be of any type, it is possible to declare an unlimited number of
composite types. The type parameters are used to set the type of `struct` fields, below an
Expand Down Expand Up @@ -78,10 +77,9 @@ example with a part of the `SBM` struct:
```

The type parameter `T` is used in wflow as a subtype of `AbstractFloat`, allowing to store
fields with a certain floating point precision (e.g. `Float64` or `Float32`) in a flexible
way. `N` refers to the maximum number of soil layers of the `SBM` soil column, and `M`
refers to the maximum number of soil layers + 1. See also part of the following instance of
`SBM`:
fields with a certain floating point precision (e.g. `Float64` or `Float32`) in a flexible way.
`N` refers to the maximum number of soil layers of the `SBM` soil column, and `M` refers to the
maximum number of soil layers + 1. See also part of the following instance of `SBM`:

```julia
sbm = SBM{Float,maxlayers,maxlayers + 1}(
Expand Down
96 changes: 47 additions & 49 deletions docs/getting_started/building_a_model.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,12 @@ title: Building a model from scratch

## HydroMT-wflow

[hydroMT](https://github.com/Deltares/hydromt) is a Python package, developed by Deltares,
to build and analyze hydro models. It provides a generic model api with attributes to
access the model schematization, (dynamic) forcing data, results and states.
[hydroMT](https://github.com/Deltares/hydromt) is a Python package, developed by Deltares, to
build and analyze hydro models. It provides a generic model api with attributes to access the
model schematization, (dynamic) forcing data, results and states.

The wflow plugin
[hydroMT-wflow](https://github.com/Deltares/hydromt_wflow) of hydroMT can be used to build
and analyze the following model configurations:
The wflow plugin [hydroMT-wflow](https://github.com/Deltares/hydromt_wflow) of hydroMT can be
used to build and analyze the following model configurations:

- [wflow\_sbm + kinematic wave routing](../model_docs/model_configurations.html#sbm-kinematic-wave)
- [wflow\_sbm + local inertial river and floodplain](../model_docs/model_configurations.html#sbm-local-inertial-river)
Expand All @@ -20,19 +19,19 @@ and analyze the following model configurations:
To learn more about the wflow plugin of this Python package, we refer to the [hydroMT-wflow
documentation](https://deltares.github.io/hydromt_wflow/latest/index.html).

To inspect or modify (for example in QGIS) the netCDF static data of these wflow models it
is convenient to export the maps to a raster format. This can be done as part of the
hydroMT-wflow plugin, see also the following [example]
To inspect or modify (for example in QGIS) the netCDF static data of these wflow models it is
convenient to export the maps to a raster format. This can be done as part of the hydroMT-wflow
plugin, see also the following [example]
(https://deltares.github.io/hydromt_wflow/latest/_examples/convert_staticmaps_to_mapstack.html).
It is also possible to create again the netCDF static data file based on the modified raster
map stack.


## Data requirements
The actual data requirements depend on the application of the Model and the Model type. Both
forcing and static data should be provided in netCDF format, with the same grid definition
for forcing and static data. The only exception is storage and rating curves for lakes, that
should be provided in CSV format, see also [Additional settings](@ref).
forcing and static data should be provided in netCDF format, with the same grid definition for
forcing and static data. The only exception is storage and rating curves for lakes, that should
be provided in CSV format, see also [Additional settings](@ref).

* Forcing data:
- Precipitation
Expand All @@ -52,15 +51,14 @@ An approach to generate `ldd` data is to make use of the Python package
[pyflwdir](https://github.com/Deltares/pyflwdir):

+ to [upscale existing flow direction
data](https://deltares.github.io/pyflwdir/latest/_examples/upscaling.html) as the 3 arcsec MERIT
Hydro data (Yamazaki et al., 2019)
data](https://deltares.github.io/pyflwdir/latest/_examples/upscaling.html) as the 3 arcsec
MERIT Hydro data (Yamazaki et al., 2019)
+ or to [derive flow directions from elevation
data](https://deltares.github.io/pyflwdir/latest/_examples/from_dem.html),

see also Eilander et al. (2021) for more information.
Pyflwdir is also used by the [hydroMT](@ref) Python package described in the next paragraph.
Another approach to generate `ldd` data is to make use of PCRaster functionality, see for
example
see also Eilander et al. (2021) for more information. Pyflwdir is also used by the
[hydroMT](@ref) Python package described in the next paragraph. Another approach to generate
`ldd` data is to make use of PCRaster functionality, see for example
[lddcreate](https://pcraster.geo.uu.nl/pcraster/4.3.1/documentation/pcraster_manual/sphinx/op_lddcreate.html).

Optionally, but also not directly part of a model component are `gauge` locations, that are
Expand All @@ -73,24 +71,24 @@ section of Model parameters. For wflow\_sbm models there are two ways to include
flow:

1. The kinematic wave approach (see section [Subsurface flow routing](@ref)) as part of the
`sbm` model type. Parameters that are part of this component are described in the
[Lateral subsurface flow](@ref params_ssf) section of Model parameters. Input parameters
for this component are derived from the SBM vertical concept and the land slope. One
external parameter [`ksathorfrac`](@ref params_ssf) is used to calculate the horizontal
hydraulic conductivity at the soil surface `kh_0`.
2. Groundwater flow (see section [Groundwater flow component](@ref lateral_gwf)) as part of
the `sbm_gwf` model type. For the unconfined aquifer the input parameters are described
in the section [Unconfined aquifer](@ref) of Model parameters. The bottom (`bottom`) of
the groundwater layer is derived from from the `soilthickness` [mm] parameter of `SBM`
and the provided surface elevation `altitude` [m] as part of the static input. The `area`
parameter is derived from the model grid. Parameters that are part of the boundary
conditions of the unconfined aquifer are listed under [Constant Head](@ref) and [Boundary
conditions](@ref) of the Model parameters section.
`sbm` model type. Parameters that are part of this component are described in the [Lateral
subsurface flow](@ref params_ssf) section of Model parameters. Input parameters for this
component are derived from the SBM vertical concept and the land slope. One external
parameter [`ksathorfrac`](@ref params_ssf) is used to calculate the horizontal hydraulic
conductivity at the soil surface `kh_0`.
2. Groundwater flow (see section [Groundwater flow component](@ref lateral_gwf)) as part of the
`sbm_gwf` model type. For the unconfined aquifer the input parameters are described in the
section [Unconfined aquifer](@ref) of Model parameters. The bottom (`bottom`) of the
groundwater layer is derived from from the `soilthickness` [mm] parameter of `SBM` and the
provided surface elevation `altitude` [m] as part of the static input. The `area` parameter
is derived from the model grid. Parameters that are part of the boundary conditions of the
unconfined aquifer are listed under [Constant Head](@ref) and [Boundary conditions](@ref) of
the Model parameters section.

Most hydrological model configurations make use of the kinematic wave surface routing (river
flow, overland flow or both) and input data required for the river and overland flow
components is described in [Surface flow](@ref). There is also the option to use the local
inertial model as part of the wflow\_sbm models (model types `sbm` and `sbm_gwf`):
flow, overland flow or both) and input data required for the river and overland flow components
is described in [Surface flow](@ref). There is also the option to use the local inertial model
as part of the wflow\_sbm models (model types `sbm` and `sbm_gwf`):
+ for river flow, see also the [Local inertial river and floodplain](@ref
config_sbm_gwf_lie_river) model.
+ for 1D river flow and 2D overland flow combined, see also the [Local inertial river (1D)
Expand All @@ -105,25 +103,25 @@ Reservoirs or lakes can be part of the kinematic wave or local inertial model fo
and input parameters are described in [Reservoirs](@ref reservoir_params) and [Lakes](@ref
lake_params).

The [wflow\_sediment](@ref config_sediment) model configuration consists of the vertical
[Soil Erosion](@ref) concept and the input parameters for this concept are described in the
[Sediment](@ref params_sediment) section of the Model parameters. The parameters of the
lateral [Sediment Flux in overland flow](@ref) concept are described in the [Overland
flow](@ref) section of the Model parameters. Parameters of this component are not directly
set by data from static input. The input parameters of the lateral concept [River Sediment
Model](@ref) are listed in [River flow](@ref) of the Model parameters section.
The [wflow\_sediment](@ref config_sediment) model configuration consists of the vertical [Soil
Erosion](@ref) concept and the input parameters for this concept are described in the
[Sediment](@ref params_sediment) section of the Model parameters. The parameters of the lateral
[Sediment Flux in overland flow](@ref) concept are described in the [Overland flow](@ref)
section of the Model parameters. Parameters of this component are not directly set by data from
static input. The input parameters of the lateral concept [River Sediment Model](@ref) are
listed in [River flow](@ref) of the Model parameters section.

The Model parameters section lists all the parameters per Model component and these Tables
can also be used to check which parameters can be part of the output, see also [Output
netCDF section](@ref) and [Output CSV section](@ref).
The Model parameters section lists all the parameters per Model component and these Tables can
also be used to check which parameters can be part of the output, see also [Output netCDF
section](@ref) and [Output CSV section](@ref).

Example models can be found in the [Example models section](@ref sample_data).

## References
+ Yamazaki, D., Ikeshima, D., Sosa, J., Bates, P. D., Allen, G. H. and Pavelsky, T. M.:
MERIT Hydro: A high‐resolution global hydrography map based on latest topography datasets,
Water Resour. Res., 2019WR024873, doi:10.1029/2019WR024873, 2019.
+ Eilander, D., van Verseveld, W., Yamazaki, D., Weerts, A., Winsemius, H. C., and Ward, P.
J.: A hydrography upscaling method for scale-invariant parametrization of distributed
+ Yamazaki, D., Ikeshima, D., Sosa, J., Bates, P. D., Allen, G. H. and Pavelsky, T. M.: MERIT
Hydro: A high‐resolution global hydrography map based on latest topography datasets, Water
Resour. Res., 2019WR024873, doi:10.1029/2019WR024873, 2019.
+ Eilander, D., van Verseveld, W., Yamazaki, D., Weerts, A., Winsemius, H. C., and Ward, P. J.:
A hydrography upscaling method for scale-invariant parametrization of distributed
hydrological models, Hydrol. Earth Syst. Sci., 25, 5287–5313,
<https://doi.org/10.5194/hess-25-5287-2021>, 2021.
10 changes: 5 additions & 5 deletions docs/getting_started/download_example_models.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,18 @@ title: Download example models
---

For each wflow Model a test model is available that can help to understand the data
requirements and the usage of each Model. The TOML configuration file per available model
are listed in the Table below:
requirements and the usage of each Model. The TOML configuration file per available model are
listed in the Table below:

| model | TOML configuration file |
|:--------------- | ------------------|
| wflow\_sbm + kinematic wave | [sbm_config.toml](https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sbm_config.toml) |
| wflow\_sbm + groundwater flow | [sbm\_gwf\_config.toml](https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sbm_gwf_config.toml) |
| wflow_sediment | [sediment_config.toml](https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sediment_config.toml) |

The associated Model files (input static, forcing and state files) can easily be downloaded
and for this we share the following Julia code (per Model) that downloads the required files
to your current working directory. For running these test model see also [Usage](@ref run_wflow)
The associated Model files (input static, forcing and state files) can easily be downloaded and
for this we share the following Julia code (per Model) that downloads the required files to
your current working directory. For running these test model see also [Usage](@ref run_wflow)
and [Command Line Interface](@ref cli).

## wflow\_sbm + kinematic wave
Expand Down
Loading

0 comments on commit 9135395

Please sign in to comment.