Release 0.10.0

README.md

@@ -1,7 +1,5 @@
 # nlmod
 
-<img src="docs/_static/logo_10000_2.png" width="256"/>
-
 [![nlmod](https://github.com/gwmod/nlmod/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gwmod/nlmod/actions/workflows/ci.yml)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/f1797b66e98b42b294bc1c5fc233dbf3)](https://app.codacy.com/gh/gwmod/nlmod/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/f1797b66e98b42b294bc1c5fc233dbf3)](https://app.codacy.com/gh/gwmod/nlmod/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
@@ -30,6 +28,10 @@ The functions in `nlmod` have four main objectives:
 More information can be found on the documentation-website:
 https://nlmod.readthedocs.io/.
 
+<p align="center">
+  <img src="docs/_static/logo_10000_2.png" width="256"/>
+</p>
+
 ## Installation
 
 Install the module with pip:

docs/examples/00_model_from_scratch.ipynb

@@ -125,7 +125,9 @@
     "ims = nlmod.sim.ims(sim, complexity=\"SIMPLE\")\n",
     "gwf = nlmod.gwf.gwf(ds, sim)\n",
     "dis = nlmod.gwf.dis(ds, gwf)\n",
-    "npf = nlmod.gwf.npf(ds, gwf)\n",
+    "npf = nlmod.gwf.npf(\n",
+    "    ds, gwf, save_flows=True, save_specific_discharge=True, save_saturation=True\n",
+    ")\n",
     "ic = nlmod.gwf.ic(ds, gwf, starting_head=1.0)\n",
     "oc = nlmod.gwf.oc(ds, gwf, save_head=True)"
    ]

docs/examples/01_basic_model.ipynb

@@ -35,22 +35,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create model\n",
-    "\n",
-    "With the code below we create a modflow model with the name 'IJmuiden'. This model has the following properties:\n",
+    "## Model settings\n",
     "\n",
+    "We create a modflow model with the name 'IJmuiden'. This model has the following properties:\n",
     "- an extent that covers part of the Northsea, Noordzeekanaal and the small port city IJmuiden.\n",
-    "- a structured grid based on the subsurface models [Regis](https://www.dinoloket.nl/regis-ii-het-hydrogeologische-model) and [Geotop](https://www.dinoloket.nl/detaillering-van-de-bovenste-lagen-met-geotop). The Regis layers that are not present within the extent are removed. In this case we use 'MSz1' as the bottom layer of the model. Use `nlmod.read.regis.get_layer_names()` to get all the layer names of Regis. All Regis layers below this layer are not used in the model. Geotop is used to replace the Holocene layer in Regis because there is no kh or kv defined for the Holocene in Regis. Part of the model is in the North sea. Regis and Geotop have no data there. Therefore the Regis and Geotop layers are extrapolated from the shore and the seabed is added using bathymetry data from [Jarkus](https://www.openearth.nl/rws-bathymetry/2018.html).\n",
-    "- starting heads of 1 in every cell.\n",
+    "- a structured grid with cells of 100 x 100 m2\n",
     "- the model is a steady state model with a single time step.\n",
-    "- big surface water bodies (Northsea, IJsselmeer, Markermeer, Noordzeekanaal) within the extent are added as a general head boundary. The surface water bodies are obtained from a [shapefile](..\\data\\shapes\\opp_water.shp).\n",
-    "- surface drainage is added using the Dutch DEM ([ahn](https://www.ahn.nl)) and a default conductance of $1000 m^2/d$\n",
-    "- recharge is added using data from [knmi](https://www.knmi.nl/nederland-nu/klimatologie/daggegevens) using the following steps:\n",
-    "   1. Check for each cell which KNMI weather and/or rainfall station is closest.\n",
-    "   2. Download the data for the stations found in 1. for the model period. For a steady state stress period the average precipitation and evaporation of 8 years before the stress period time is used.\n",
-    "   3. Combine precipitation and evaporation data from step 2 to create a recharge time series for each cell,\n",
-    "   4. Add the timeseries to the model dataset and create the recharge package.\n",
-    "- constant head boundaries are added to the model edges in every layer. The starting head is used as the specified head."
+    "- starting heads of 1 m NAP in every cell."
    ]
   },
   {
@@ -68,33 +59,116 @@
     "delc = 100.0\n",
     "steady_state = True\n",
     "start_time = \"2015-1-1\"\n",
-    "add_northsea = True\n",
     "starting_head = 1.0"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download data\n",
+    "\n",
+    "First, download the data needed for the model from online sources. It is recommended to store a copy somewhere in case the online dataset changes. For this model we download data from these sources:\n",
+    "- regis (layer model)\n",
+    "- geotop (layer model)\n",
+    "- rijkswaterstaat (surface water)\n",
+    "- jarkus (bathymetry)\n",
+    "- ahn (digital elevation model)\n",
+    "- knmi (precipitation and evaporation)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# layer models\n",
+    "regis_ds = nlmod.read.regis.download_regis(extent, botm_layer=\"MSz1\",\n",
+    "                                            cachedir=cachedir,\n",
+    "                                            cachename=\"regis.nc\")\n",
+    "\n",
+    "geotop_ds = nlmod.read.geotop.download_geotop(extent,\n",
+    "                                              cachedir=cachedir,\n",
+    "                                              cachename=\"geotop.nc\")\n",
+    "\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "layer_model = nlmod.read.regis.get_combined_layer_models(\n",
-    "    extent,\n",
-    "    use_regis=True,\n",
-    "    regis_botm_layer=\"MSz1\",\n",
-    "    use_geotop=True,\n",
-    "    cachedir=cachedir,\n",
-    "    cachename=\"combined_layer_ds.nc\",\n",
+    "# read surface water data\n",
+    "gdf_surface_water = nlmod.read.rws.get_gdf_surface_water(\n",
+    "    extent=extent, cachedir=cachedir, cachename=\"rws_surface_water.pklz\"\n",
     ")\n",
     "\n",
-    "# create a model ds by changing grid of layer_model\n",
+    "# bathymetry\n",
+    "bathymetry_da = nlmod.read.jarkus.download_bathymetry(extent=extent,\n",
+    "                                                      cachedir=cachedir,\n",
+    "                                                      cachename=\"bathymetry.nc\")\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Digital elevation model\n",
+    "ahn_da = nlmod.read.ahn.download_ahn(extent, cachedir=cachedir, cachename=\"ahn\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# knmi data\n",
+    "oc_knmi = nlmod.read.knmi.download_knmi(extent=extent, delr=delr, delc=delc, start='2000-1-1', end='2020-1-1')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Create model\n",
+    "\n",
+    "Now create the modflow model:\n",
+    "- Build a layer model using Regis and Geotop. Use MSz1 as the bottom layer; all deeper Regis layers are excluded. Use `nlmod.read.regis.get_layer_names()` to list available layers.\n",
+    "- Replace the Holocene layer in Regis with Geotop due to missing hydraulic properties.\n",
+    "- Extend Regis/Geotop layers into the North Sea using shoreline extrapolation and Jarkus bathymetry data.\n",
+    "- Add large water bodies (e.g. North Sea, IJsselmeer) as general head boundaries.\n",
+    "- Add surface drainage using the AHN with a conductance of 1000 m²/d.\n",
+    "- Calculate recharge from precipitation and evaporation time series\n",
+    "- Add constant head boundaries on all model edges using the starting head."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create layer model\n",
+    "layer_model = nlmod.read.regis.add_geotop_to_regis_layers(regis_ds,\n",
+    "                                                          geotop_ds,\n",
+    "                                                          layers=\"HLc\")\n",
+    "\n",
+    "# create a dataset from they layer model\n",
     "ds = nlmod.to_model_ds(layer_model, model_name, model_ws, delr=delr, delc=delc)\n",
     "\n",
     "# add time discretisation\n",
     "ds = nlmod.time.set_ds_time(ds, start=start_time, steady=steady_state, perlen=365 * 5)\n",
     "\n",
-    "if add_northsea:\n",
-    "    ds = nlmod.read.rws.add_northsea(ds, cachedir=cachedir)"
+    "# add northsea and bathymetry to modelgrid\n",
+    "ds.update(nlmod.read.rws.discretize_northsea(ds, gdf=gdf_surface_water))\n",
+    "ds.update(nlmod.read.jarkus.discretize_bathymetry(ds, bathymetry_da, cachedir=cachedir, cachename=\"bathymetry.nc\"))\n",
+    "ds = nlmod.dims.add_bathymetry_to_layer_model(ds)"
    ]
   },
   {
@@ -134,16 +208,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# voeg grote oppervlaktewaterlichamen toe o.b.v. shapefile\n",
-    "da_name = \"rws_oppwater\"\n",
-    "rws_ds = nlmod.read.rws.get_surface_water(\n",
-    "    ds, da_name, cachedir=ds.cachedir, cachename=da_name\n",
+    "# discretize surface water bodies from geodataframe\n",
+    "rws_ds = nlmod.read.rws.discretize_surface_water(\n",
+    "    ds, gdf=gdf_surface_water, da_basename=\"rws_oppwater\"\n",
     ")\n",
+    "\n",
     "# add data to model dataset\n",
     "ds.update(rws_ds)\n",
     "\n",
     "# build ghb package\n",
-    "ghb = nlmod.gwf.ghb(ds, gwf, bhead=f\"{da_name}_stage\", cond=f\"{da_name}_cond\")"
+    "ghb = nlmod.gwf.ghb(ds, gwf, bhead=\"rws_oppwater_stage\", cond=\"rws_oppwater_cond\")"
    ]
   },
   {
@@ -152,8 +226,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# surface level drain\n",
-    "ahn_ds = nlmod.read.ahn.get_ahn(ds, cachedir=ds.cachedir, cachename=\"ahn\")\n",
+    "# discretize ahn\n",
+    "ahn_ds = nlmod.read.ahn.discretize_ahn(ds, ahn_da)\n",
+    "\n",
     "# add data to model dataset\n",
     "ds.update(ahn_ds)\n",
     "\n",
@@ -178,8 +253,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# download knmi recharge data\n",
-    "knmi_ds = nlmod.read.knmi.get_recharge(ds, cachedir=ds.cachedir, cachename=\"recharge\")\n",
+    "# discretize knmi recharge data\n",
+    "knmi_ds = nlmod.read.knmi.discretize_knmi(ds, oc_knmi, cachedir=cachedir, cachename=\"recharge\")\n",
+    "\n",
     "# update model dataset\n",
     "ds.update(knmi_ds)\n",
     "\n",
@@ -191,7 +267,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A big part of the model data is stored in the variable `ds` which is an `xarray.Dataset`. The data is shown below."
+    "Model data is stored in the variable `ds` which is an `xarray.Dataset`."
    ]
   },
   {
@@ -208,10 +284,10 @@
    "metadata": {},
    "source": [
     "## Write and Run\n",
-    "Now that we've created all the modflow packages we need to write them to modflow files. You always have to write the modflow data to the model workspace before you can run the model. You can write the model files and run the model using the function `nlmod.sim.write_and_run)` as shown below. This function has two additional options:\n",
+    "Write the model files and run the model using the function `nlmod.sim.write_and_run)` as shown below. This function has two additional options:\n",
     "\n",
-    "1. Write the model dataset to the disk if `write_ds` is `True`. This makes it easier and faster to load model data if you ever need it. \n",
-    "2. Write a copy of this Jupyter Notebook to the same directory as the modflow files if `nb_path` is the name of this Jupyter Notebook. It can be useful to have a copy of the script that created the modflow files, together with the files. "
+    "1. Saving the model dataset (`write_ds=True`) for faster future loading.\n",
+    "2. Saving a copy of the current notebook (nb_path=\"<notebook_name>.ipynb\") alongside the model files."
    ]
   },
   {
@@ -228,7 +304,7 @@
    "metadata": {},
    "source": [
     "## Visualise\n",
-    "Using the `ds` and `gwf` variables it is quite easy to visualise model data. Below the modelgrid together with the surface water is shown."
+    "Plot the modelgrid and surface water"
    ]
   },
   {
@@ -245,7 +321,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Data from a model with a structured grid can be easily visualised using the model dataset. Below are some examples:"
+    "Plot model input data."
    ]
   },
   {
@@ -269,8 +345,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "nlmod2025",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
   }
  },
  "nbformat": 4,

docs/examples/02_surface_water.ipynb

@@ -89,7 +89,7 @@
    "source": [
     "fname_ahn = os.path.join(cachedir, \"ahn.tif\")\n",
     "if not os.path.isfile(fname_ahn):\n",
-    "    ahn = nlmod.read.ahn.get_ahn4(extent)\n",
+    "    ahn = nlmod.read.ahn.download_ahn4(extent)\n",
     "    ahn.rio.to_raster(fname_ahn)\n",
     "ahn = rioxarray.open_rasterio(fname_ahn, mask_and_scale=True)[0]"
    ]
@@ -110,7 +110,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "bgt = nlmod.read.bgt.get_bgt(extent)"
+    "bgt = nlmod.read.bgt.download_bgt(extent)"
    ]
   },
   {
@@ -337,7 +337,7 @@
    "outputs": [],
    "source": [
     "# layer model\n",
-    "layer_model = nlmod.read.get_regis(\n",
+    "layer_model = nlmod.read.download_regis(\n",
     "    extent, cachedir=cachedir, cachename=\"layer_model.nc\"\n",
     ")\n",
     "layer_model"
@@ -797,8 +797,14 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "nlmod2025",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "name": "python",
+   "version": "3.12.9"
   }
  },
  "nbformat": 4,