Getting Started

On this page you will find information on how to get started with nlmod.

Getting Python

To install nlmod, a working version of Python 3.10 or higher has to be installed on your computer. We recommend using the Anaconda Distribution of Python.

Installing nlmod

Install the module by typing:

pip install nlmod

For installing in development mode, clone the repository and install by typing pip install -e . from the module root directory.

Using nlmod

This section provides a brief introduction to nlmod. To start using nlmod, start Python and import the module:

import nlmod

nlmod contains many methods for loading data from online data sources, .e.g. from the hydrogeological subsurface model REGIS (see Data Sources for more information on available data sources):

extent = [116_500, 120_000, 439_000, 442_000]  # define extent
regis_ds = nlmod.read.regis.download_regis(extent)  # download REGIS data

The basic building block for groundwater models in nlmod is the model Dataset. A model dataset can either be created from scratch, or derived from a hydrogeological subsurface model such as REGIS:

# start from scratch
ds = nlmod.get_ds(extent, model_ws="./my_model", model_name="my_model")

# OR convert REGIS data to a model dataset
ds = nlmod.to_model_ds(regis_ds, model_ws="./my_model", model_name="my_model")

This dataset should eventually contain all the (rasterized) information required to build the groundwater model. Manipulating the spatial discretization is possible through all kinds of functions in nlmod.grid and nlmod.resample. Adding time settings to the model dataset is done through functions in nlmod.time.

Building the groundwater model is performed using flopy. nlmod is not a replacement of flopy, but does offer convenience methods to build MODFLOW models using the model dataset as input. An minimal example of code to build a MODFLOW 6 model given a model dataset:

sim = nlmod.sim.sim(ds)                       # simulation
tdis = nlmod.sim.tdis(ds, sim)                # time discretization
ims = nlmod.sim.ims(sim)                      # ims solver
gwf = nlmod.gwf.gwf(ds, sim)                  # groundwater flow model
dis = nlmod.gwf.dis(ds, gwf)                  # spatial discretization
npf = nlmod.gwf.npf(ds, gwf)                  # node property flow
sto = nlmod.gwf.sto(ds, gwf)                  # storage (if transient)
ic = nlmod.gwf.ic(ds, gwf, starting_head=0.0) # initial conditions
oc = nlmod.gwf.oc(ds, gwf)                    # output control

# ... add some boundary condition packages (RCH, GHB, RIV, DRN, ...)

The MODFLOW 6 executable is automatically downloaded and installed to your system when building the first model.

Writing and running the model can then be done using:

nlmod.sim.write_and_run(sim, ds)

The output from a model can be read using:

head = nlmod.gwf.get_heads_da(ds)

And plotting the mean head in one of the layers:

nlmod.plot.map_array(head.sel(layer="BXz2").mean("time"), ds=ds)

This was a very brief overview of some of the features in nlmod. There is a lot more to discover, so we recommend taking a look at the sections Data Sources, Example Models, Utilities, Workflows, and Advanced Stress Packages.

Dependencies

This module has the following dependencies that should be installed automatically when installing nlmod.

  • flopy

  • xarray

  • netcdf4

  • rioxarray

  • geopandas

  • matplotlib

  • dask

  • requests

  • scipy

  • bottleneck

On top of that there are some optional dependecies:

  • geocube (used in nlmod.util.zonal_statistics)

  • rasterstats (used in nlmod.util.zonal_statistics)

  • contextily (nlmod.plot.add_background_map)

  • scikit-image (used in nlmod.read.rws.calculate_sea_coverage)

  • py7zr (used in nlmod.read.bofek.download_bofek_gdf)

  • joblib (used in nlmod.cache)

  • tqdm (used for showing progress in long-running methods)

  • hydropandas (used in nlmod.read.knmi and nlmod.read.bro)

  • owslib (used in nlmod.read.ahn.get_latest_ahn_from_wcs)

  • pyshp (used in nlmod.grid.refine)

  • h5netcdf (used in nlmod.read.knmi_data_platform)

These dependencies are only needed (and imported) in a single module or method. They can be installed using pip install nlmod[full] or pip install -e .[full].