Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve spelling and grammar in the user guide #379

Merged
merged 9 commits into from
Mar 26, 2024
22 changes: 11 additions & 11 deletions docs/src/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## v0.6.3 - 2023-03-01

### Fixed
- Removed error when `_FillValue` is present in the time dimension of the forcing NetCDF
- Removed error when `_FillValue` is present in the time dimension of the forcing netCDF
file. The simulation is allowed to continue with the attribute present, given that there
are no missing values in the time dimension. This is checked by the code, and an error is
thrown if this is the case.
Expand All @@ -137,9 +137,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
counted).

### Changed
- `NCDatasets` version. Reading the `time` dimension of multifile NetCDF file became very
- `NCDatasets` version. Reading the `time` dimension of multifile netCDF file became very
slow since `NCDatasets` v0.12.4, this issue has been solved in v0.12.11.
- Store the `time` dimension of the forcing NetCDF file as part of the struct `NCreader`
- Store the `time` dimension of the forcing netCDF file as part of the struct `NCreader`
instead of calling `dataset["time"][:]` each time step when loading forcing data.

### Added
Expand Down Expand Up @@ -195,7 +195,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
parameters](@ref).
- Modify input parameters with an extra dimension at multiple indices with different `scale`
and `offset` values, through the TOML file. See also [Modify parameters](@ref).
- Added support for NetCDF compression for gridded model output, through the option
- Added support for netCDF compression for gridded model output, through the option
`compressionlevel` in the `[output]` section in the TOML file. The setting defaults to 0
(no compression), but all levels between 0 and 9 can be used.

Expand Down Expand Up @@ -257,10 +257,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Fixed how number of iterations `its` for kinematic wave river flow are calculated during
initialization when using a fixed sub-timestep (specified in the TOML file). For a model
timestep smaller than the fixed sub-timestep an InexactError was thrown.
- Fixed providing a cyclic parameter when the NetCDF variable is read during model
initialization with `ncread`, this gave an error about the size of the NetCDF `time`
- Fixed providing a cyclic parameter when the netCDF variable is read during model
initialization with `ncread`, this gave an error about the size of the netCDF `time`
dimension.
- Fixed CSV and NetCDF scalar output of variables with dimension `layer` (`SVector`).
- Fixed CSV and netCDF scalar output of variables with dimension `layer` (`SVector`).

## v0.5.1 - 2021-11-24

Expand Down Expand Up @@ -373,7 +373,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## v0.3.1 - 2021-05-19

### Fixed
- Ignore extra dimensions in input NetCDFs if they are size 1
- Ignore extra dimensions in input netCDFs if they are size 1

## v0.3.0 - 2021-05-10

Expand Down Expand Up @@ -406,7 +406,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
- Removed dependency of the `f` model parameter of wflow\_sbm on the parameters
``\theta_{s}``, ``\theta_{r}`` and ``M``. This approach is used in Topog\_SBM, but not
applicable for wflow\_sbm. The `f` parameter needs to be provided as part of the NetCDF
applicable for wflow\_sbm. The `f` parameter needs to be provided as part of the netCDF
model parameter file.
- Grid properties as cell length and elevation now stored as part of the
`model.land.network` component and not as part of the vertical model components, as it is
Expand All @@ -416,10 +416,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Removed parameter ``\theta_{e}`` from SBM struct (not used in update). Parameters
``\theta_{s}`` and ``\theta_{r}`` included separately (instead of ``\theta_{e}``) in
`LateralSSF struct`, now directly linked to SBM parameters.
- Improve error messages (NetCDF and cyclic flow graph).
- Improve error messages (netCDF and cyclic flow graph).

### Added
- Export of NetCDF scalar timeseries (separate NetCDF file from gridded timeseries). This
- Export of netCDF scalar timeseries (separate netCDF file from gridded timeseries). This
also allows for importing these timeseries by Delft-FEWS (General Adapter).

### Fixed
Expand Down
4 changes: 2 additions & 2 deletions docs/src/user_guide/additional_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,9 +262,9 @@ world.

This can be done without a model adapter that provides the interface between Delft-FEWS and
an external model (or module). This is possible because time information in the TOML
configuration file is optional and Delft-FEWS can import and export NetCDF files. When time
configuration file is optional and Delft-FEWS can import and export netCDF files. When time
information is left out from the TOML configuration file, the `starttime`, `endtime` and
`timestepsecs` (timestep) of the run is extracted from the NetCDF forcing file by Wflow.
`timestepsecs` (timestep) of the run is extracted from the netCDF forcing file by Wflow.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`timestepsecs` (timestep) of the run is extracted from the netCDF forcing file by Wflow.
`timestepsecs` (timestep) of the run is extracted from the netCDF forcing file by wflow.


To indicate that a Wflow model runs from Delft-FEWS, the following setting needs to be
specified in the main section of the TOML configuration file:
Expand Down
12 changes: 6 additions & 6 deletions docs/src/user_guide/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Wflow can be used in two different ways, depending on the required use of the co
version is available. This consists of a single executable, `wflow_cli`, allowing you to
run the model via the command line.

Below, we describe how to install both versions of wflow.
Below we describe how to install both versions of wflow.

## Installing as Julia package

Expand Down Expand Up @@ -75,7 +75,7 @@ have to pull in the latest changes yourself using `git pull`.

### Check installation of wflow

Finally, go back the Julia REPL and try to load wflow:
Finally, go back to the Julia REPL and try to load wflow:

```julia-repl
julia> using Wflow
Expand All @@ -85,7 +85,7 @@ The first time this will take longer as any package that is new or changed needs
pre-compiled first, to allow faster loading on subsequent uses. No error messages should
appear, indicating that you have now successfully installed wflow.

Before ending this section, we still want to recommend a few tools that can make using and
Before ending this section, we want to recommend a few tools that can make using and
developing Julia code easier.

!!! tip
Expand All @@ -108,15 +108,15 @@ Binaries of `wflow_cli` can be downloaded from our website
[download.deltares.nl](https://download.deltares.nl/en/download/wflow/), and are currently
available for Windows. Download and install the `.msi` file. After installing you can see
two folders in the installation directory. It is only the `bin/wflow_cli` that is used. The
artifacts folder contains binary dependencies such as NetCDF.
artifacts folder contains binary dependencies such as netCDF.

```
artifacts\
bin\wflow_cli
```

Check whether the installation was performed successfully, run `wflow_cli` with no
arguments in the command line will give the following message:
Check whether the installation was performed successfully by running `wflow_cli` with no
arguments in the command line. This will give the following message:

```
Usage: wflow_cli 'path/to/config.toml'
Expand Down
4 changes: 2 additions & 2 deletions docs/src/user_guide/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

The purpose of this user guide is to describe the steps to install the wflow julia software
and to set up a simple model. The user guide also contains a step-wise process how to
configure your model using the TOML file (model settings) and the NetCDF gridded datasets.
configure your model using the TOML file (model settings) and the netCDF gridded datasets.

Sample data and model set up is also included for the Moselle River Basin (a major tributary
of the Rhine River), which can be used to explore the model software. The model is set up
for the wflow\_sbm, wflow\_hbv and wflow\_sediment model concepts.

Finally information is provided on setting up your own model, including building a model
Finally, information is provided on setting up your own model, including building a model
from scratch or alternatively using Deltares [HydroMT](https://github.com/Deltares/hydromt)
model building tools which are open source.
6 changes: 3 additions & 3 deletions docs/src/user_guide/model-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,21 +97,21 @@ 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).
netCDF section](@ref) and [Output CSV section](@ref).

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

## hydroMT
[hydroMT](https://github.com/Deltares/hydromt) is a Python package, developed by Deltares,
to build and analysis hydro models. It provides a generic model api with attributes to
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.

For the following Wflow models:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For the following Wflow models:
For the following wflow models:

- wflow\_sbm + kinematic wave
- wflow_sediment

the Wflow plugin [hydroMT-wflow](https://github.com/Deltares/hydromt_wflow) of hydroMT can
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the Wflow plugin [hydroMT-wflow](https://github.com/Deltares/hydromt_wflow) of hydroMT can
the wflow plugin [hydroMT-wflow](https://github.com/Deltares/hydromt_wflow) of hydroMT can

be used to build and analyse these Wflow model types in an automated way.
be used to build and analyze these Wflow model types in an automated way.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
be used to build and analyze these Wflow model types in an automated way.
be used to build and analyze these wflow model types in an automated way.


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).
Expand Down
10 changes: 5 additions & 5 deletions docs/src/user_guide/sample_data.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ and [Command Line Interface](@ref cli).

## [wflow\_sbm + kinematic wave](@id wflow_sbm_data)
```julia
# urls to TOML and NetCDF of the Moselle example model
# urls to TOML and netCDF of the Moselle example model
toml_url = "https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sbm_config.toml"
staticmaps = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.7/staticmaps-moselle.nc"
forcing = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.6/forcing-moselle.nc"
Expand All @@ -39,7 +39,7 @@ download(toml_url, toml_path)

## wflow\_sbm + groundwater flow
```julia
# urls to TOML and NetCDF of the Moselle example model
# urls to TOML and netCDF of the Moselle example model
toml_url = "https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sbm_gwf_config.toml"
staticmaps = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.2/staticmaps-sbm-groundwater.nc"
forcing = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.1/forcing-sbm-groundwater.nc"
Expand All @@ -57,7 +57,7 @@ download(toml_url, toml_path)

## wflow\_hbv
```julia
# urls to TOML and NetCDF of the Moselle example model
# urls to TOML and netCDF of the Moselle example model
toml_url = "https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/hbv_config.toml"
staticmaps = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.1/staticmaps-lahn.nc"
forcing = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.0/forcing-lahn.nc"
Expand All @@ -75,7 +75,7 @@ download(toml_url, toml_path)

## [wflow\_flextopo](@id wflow_flextopo_data)
```julia
# urls to TOML and NetCDF of the Meuse example model
# urls to TOML and netCDF of the Meuse example model
toml_url = "https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/flextopo_config.toml"
staticmaps = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.8/staticmaps_flex_meuse.nc"
forcing = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.8/forcing_meuse.nc"
Expand All @@ -93,7 +93,7 @@ download(toml_url, toml_path)

## wflow\_sediment
```julia
# urls to TOML and NetCDF of the Moselle example model
# urls to TOML and netCDF of the Moselle example model
toml_url = "https://raw.githubusercontent.com/Deltares/Wflow.jl/master/test/sediment_config.toml"
staticmaps = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.3/staticmaps-moselle-sed.nc"
forcing = "https://github.com/visr/wflow-artifacts/releases/download/v0.2.3/forcing-moselle-sed.nc"
Expand Down
8 changes: 4 additions & 4 deletions docs/src/user_guide/step1_requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

In order to run wflow, several files are required. These consist of a settings file and
input data. The input data is typically separated into static maps and forcing data, both
are supplied in a NetCDF file, except for lake storage and rating curves that are supplied
are supplied in a netCDF file, except for lake storage and rating curves that are supplied
via CSV files. A brief overview of the different files:

- The `settings.toml` file contains information on the simulation period, links to the
input files (and their names in the NetCDF files), and links the correct names of the
variables in the NetCDF files to the variables and parameters of wflow.
input files (and their names in the netCDF files), and links the correct names of the
variables in the netCDF files to the variables and parameters of wflow.
- The `staticmaps.nc` file contains spatial information on the elevation, locations of the
gauges, land-use, drainage direction, etc. This file can also contain maps with parameter
values.
Expand All @@ -17,7 +17,7 @@ via CSV files. A brief overview of the different files:
There are several model configurations supported by wflow. These model configurations
require slightly different input requirements, yet the general structure is similar for each
model. A wflow model configuration consists of a `vertical` concept like the [SBM](@ref
vert_sbm), [HBV](@ref vert_hbv) or [FLEXTOPO](@ref vert_flextopo) vertical concept in
vert_sbm), [HBV](@ref vert_hbv) or [FLEXTOPO](@ref vert_flextopo) in
combination with `lateral` concepts that control how water is routed for example over the
land or river domain. For the wflow\_sbm model different model configurations are possible.
The following model configurations are supported in wflow:
Expand Down
28 changes: 14 additions & 14 deletions docs/src/user_guide/step2_settings_file.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The filepaths that are provided in this file are relative to the location of the
or to `dir_input` and `dir_output` if they are given.

## General time info
Time information is optional. When left out, for each timestamp in the forcing NetCDF Wflow
Time information is optional. When left out, for each timestamp in the forcing netCDF Wflow
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Time information is optional. When left out, for each timestamp in the forcing netCDF Wflow
Time information is optional. When left out, for each timestamp in the forcing netCDF wflow

will do computations, except for the first forcing timestamp that is considered equal to the
initial conditions of the Wflow model (state time). If you wish to calculate a subset of
this time range, or a different timestep, you can specify a `starttime`, `endtime` and
Expand All @@ -22,10 +22,10 @@ alternative calendars.

```toml
calendar = "standard" # optional, this is default value
starttime = 2000-01-01T00:00:00 # optional, default from forcing NetCDF
endtime = 2000-02-01T00:00:00 # optional, default from forcing NetCDF
starttime = 2000-01-01T00:00:00 # optional, default from forcing netCDF
endtime = 2000-02-01T00:00:00 # optional, default from forcing netCDF
time_units = "days since 1900-01-01 00:00:00" # optional, this is default value
timestepsecs = 86400 # optional, default from forcing NetCDF
timestepsecs = 86400 # optional, default from forcing netCDF
dir_input = "data/input" # optional, default is the path of the TOML
dir_output = "data/output" # optional, default is the path of the TOML
```
Expand Down Expand Up @@ -143,7 +143,7 @@ forcing = [

cyclic = ["vertical.leaf_area_index"]

[input.vertical] # Map internal model variable/parameter names to names of the variables in the NetCDF files
[input.vertical] # Map internal model variable/parameter names to names of the variables in the netCDF files
altitude = "wflow_dem"
c = "c"
cf_soil = "cf_soil"
Expand Down Expand Up @@ -189,15 +189,15 @@ n = "N"
slope = "Slope"
```

## Output NetCDF section
## Output netCDF section

### Grid data
This optional section of the TOML file contains the output netCDF file for writing gridded
model output, including a mapping between internal model parameter components and external
netCDF variables.

To limit the size of the resulting NetCDF file, file compression can be enabled. This causes
an increase in computational time, but can significantly reduce the file size of the NetCDF
To limit the size of the resulting netCDF file, file compression can be enabled. This causes
an increase in computational time, but can significantly reduce the file size of the netCDF
file. This can be enabled by setting the `compressionlevel` variable to any value between
`0` and `9`. A setting of `0` indicates that compression is not enabled, and values between
1 and 9 indicate different levels of compression (1: least compression, smallest impact on
Expand Down Expand Up @@ -234,24 +234,24 @@ h = "h_land"
```

### Scalar data
Besides gridded data, it is also possible to write scalar data to a NetCDF file. Below is an
example that writes scalar data to the file "output\_scalar\_moselle.nc". For each NetCDF
Besides gridded data, it is also possible to write scalar data to a netCDF file. Below is an
example that writes scalar data to the file "output\_scalar\_moselle.nc". For each netCDF
variable a `name` (external variable name) and `parameter` (internal model parameter) is
required. A `reducer` can be specified to apply to the model output, see for more
information the following section [Output CSV section](@ref). When a `map` is provided to
extract data for certain locations (e.g. `gauges`) or areas (e.g. `subcatchment`), the
NetCDF location names are extracted from these maps. For a specific location (grid cell) a
netCDF location names are extracted from these maps. For a specific location (grid cell) a
`location` is required. For layered model parameters and variables that have an extra
dimension `layer` and are part of the vertical `sbm` concept it is possible to specify an
internal layer index (see also example below). For model parameters and variables that have
an extra dimension `classes` and are part of the vertical `FLEXTopo` concept it is possible
to specify the class name. If multiple layers or classes are desired, this can be specified
in separate `[[netcdf.variable]]` entries. Note that the specification of the extra
dimension is not optional when Wflow is integrated with Delft-FEWS, for NetCDF scalar data
dimension is not optional when Wflow is integrated with Delft-FEWS, for netCDF scalar data
an extra dimension is not allowed by the `importNetcdfActivity` of the Delft-FEWS General
Adapter. In the section [Output CSV section](@ref), similar functionality is available for
CSV. For integration with Delft-FEWS, see also [Run from Delft-FEWS](@ref run_fews), it is
recommended to write scalar data to NetCDF format since the General Adapter of Delft-FEWS
recommended to write scalar data to netCDF format since the General Adapter of Delft-FEWS
can ingest this data format directly.

```toml
Expand Down Expand Up @@ -395,7 +395,7 @@ offset = 0.5

For input parameters with an extra dimension it is also possible to modify multiple indices
at once with different `scale` and `offset` values. In the example below the external
NetCDF variable `c` is modified at `layer` index 1 and 2, with a `scale` factor of 2.0 and
netCDF variable `c` is modified at `layer` index 1 and 2, with a `scale` factor of 2.0 and
1.5 respectively, and an `offset` of 0.0 for both indices:

```toml
Expand Down
Loading
Loading