deltares/imod-documentation

📚 Documentation of the iMOD suite.

iMOD Suite Documentation

The iMOD Suite documentation is generated here.

The documentation is set up using Quarto. Read here how to get started using Quarto.

If you want to contribute to the iMOD Suite documentation, please read the contributing guidelines.

Local Build

1. Install Quarto and pixi
2. git clone https://github.com/Deltares/iMOD-Documentation.git
3. cd iMOD-Documentation
4. pixi run install-pre-commit
5. pixi run docs
6. To render PDF (deleting any previously build documentation): quarto render docs --profile manual --to pdf

Project setup

The Quarto project is set up using different profiles, specified in the _quarto-<profile>.yml files. These are:

• website: The website, render as html
• manual: The full user manual, render as pdf
• install: The installation guide, render as pdf. Can be shipped with the release.
• tutorial: The tutorial pages, render as pdf. Can be used during trainings.

imod-documentation's Issues

Document iMOD Coupler architecture

As @Huite correctly pointed out, the architecture of imod coupler is currently under-documented.
Especially the following:

• The preprocessor for Ribasim
• The preprocessor for MODFLOW 6 (imod-python)
• The preprocessor (currently imod-python) for the coupling
• MODFLOW 6 XMI C API is a given
• Ribasim functionality, not necessarily a given
• imod_coupler: MODFLOW 6 XMI Wrapper is not necessarily a given
• imod_coupler: the actual driver
• Where are the test models exactly hosted?

All things need to be synchronized to get all pipelines running properly. In which order should you push the changes?

Jupyter notebooks missing on index page.

Two issues with current state (see screenshot)

• Incorrect title chosen for unstructured mesh
• No listing made for two tutorials added as jupyter notebook

PR in progress

Add example to convert an existing 'vanilla' Modflow 2005 model

People who want to transition to the iMOD Suite might have an existing Modflow 2005 model, the 'vanilla' USGS version, that is.

This model can be read using Flopy and consequently be written to a iMODFLOW or Modflow6 model using iMOD Python.
An example of this in either the iMOD Suite documentation or the iMOD Python documentation, would be very useful.

This might be something for the iMOD Python documentation.

Add preprocessing sections to the different driver docs

The current MetaMod coupler documentation section mentions:

• Configuration
• Technical reference
• Example

I think it makes a lot of sense to have another section called "preprocessing". This is obviously relevant to most users, as they will be quite involved with the spatial coupling logic (making sure models align for example).

Such a document should introduce the primod package, explain the requirements before a model can be coupled in terms of its schematization and concepts, mention how the automatic definition is exchanges is done (based on spatial locations), as well as mention the relevant components of all models. A full example is not required, but for readability, some duplication might be desirable.

unclear dll referencing in Coupled MetaSWAP - Modflow6 model example

In GitLab by @tvw11 on Nov 1, 2023, 10:44

By providing a few necessary paths to the modflow and metaswap libraries for iMOD Coupler, we can write the coupled models. You can download the modflow and metaswap libraries as part of the the last iMOD5 release <https://oss.deltares.nl/web/imod/download-imod5>_

mf6_dll = "./path/to/mf6.dll"
metaswap_dll = "./path/to/metaswap.dll"
metaswap_dll_dependency = "./path/to/metaswap/dll/dependency"

Downloading via the link went fine, but afterwards it is unclear which paths should be inserted here, especially the metaswap_dll_dependency, which should be the dir (probably renaming to metaswap_coupler_dir could already make it more clear).

Update QGIS requirements

Description of minimal qgis requirements is not clear.
See also issue on imod-qgis
https://github.com/Deltares/imod-qgis/issues/24

Move iMOD Coupler docs to iMOD Documentation

We should move the docs at https://deltares.github.io/imod_coupler/ to https://deltares.github.io/iMOD-Documentation/coupler_index.html

Installing mamba

At the default installation of mamba, mamba is not added to the PATH. mamba is then not recongnized

Add jupyter notebook of software days to tutorials sections

For the last Delft Software Days, we've made course material in the form of a jupyter notebook.
So far, we have not added that to the iMOD Documentation.

Quarto supports including Jupyter notebooks, so it shouldn't be too much work to add this.

Request for clarification in the documentation

I was asked by @Hofer-Julian to review the iMOD documentation and there are a couple of points that I would like to address:

Introduction

https://deltares.github.io/iMOD-Documentation/introduction.html#tbl-iMOD-comparison

The comparison table uses the terms iMOD GUI and MODFLOW 2005, iMOD 3D Viewer. To me it is unclear if the iMOD GUI and the iMOD 3D Viewer are the same. And I also understand that it should be iMODFLOW and not MODFLOW 2005, since it is a heavily modified fork of MODFLOW 2005.

iMOD Viewer

https://deltares.github.io/iMOD-Documentation/viewer_install.html#sec-install_QGIS

Link is not formatted correctly. Probably a simple whitespace issue.

Collect more FAQ from users

A few years ago, @Huite and @jc-hunink created a FAQ section in the iMOD Python documentation.

We should evaluate if this is still up to date or should be extended (probably the latter).
Places to collect questions:

• iMOD Python Teams chat
• iMOD Python discussion board
• Ask them directly

Fix erronous URL links

From Frans:

Ter info: op de pagina https://deltares.github.io/iMOD-Documentation/index.html staat een link naar de iMOD 5 informatie.
Die link is https://oss.deltares.nl/nl/web/imod maar werkt niet. Dat komt omdat er een “/nl/” te veel staat.

Also:

The references to imod.xyz should be changed to:
https://gitlab.com/deltares/imod/imod-python/pages

• Fix oss.deltares.nl link
• Replace references to imod.xyz with gitlab pages link

Add supported ipf formats to documentation

Not all ipf formats are supported in iMOD Suite tools. Add the supported ipf formats as known issue to the documentation.

Add practical tip and known tip: How to enable long paths

Quite commonly errors are thrown because long paths not enabled. This is especially common on Windows computational servers, which consist of virtual machines which have long paths disabled (usually this is standard, unfortunately). What makes this more annoying, is that the virtual machines not always print the actual paths (which are long, containing all kinds of hashes and words like "SNAPVOLUMES"), so little clues are left to the source of problems.

For example, I just had a colleague where Deltaforge threw a vague "Extraction failed" error (Miniconda installer as well), and the issue in the end was resolved by enabling long paths.

Relevant tip how to fix (can probably link):
https://www.howtogeek.com/266621/how-to-make-windows-10-accept-file-paths-over-260-characters/