Gridmarthe

gridmarthe is a Python project for (fast) Marthe grid operations.

MARTHE is a hydrogeological modelling code developped at BRGM, French Geological Survey (Thiery, 2020), and is available at https://www.brgm.fr/en/software/marthe-modelling-software-groundwater-flows

gridmarthe in a nutshell

gridmarthe allow users to read/write efficiently Marthe Grids (v9, v8, constant_data, etc.) with python, for any MARTHE variable.

With the gridmarthe API, data are stored in a xarray dataset, and can be manage with xarray functions (or numpy). Specific treatments/functions are also provided by gridmarthe.

The package also install different command line tools: ncmart to convert Marthe Grid to netCDF format, martshp to convert in shapefile/geopackage, cleanmgrid to fix marthe grid format.

Full documentation and tutorials can be founded at https://gridmarthe.readthedocs.io

Grids are stored as a 2 dimensions matrix composed of a 1D spatial vector and a time dimension (Reduced Horizontal Grid, as recommended for lossless compression by gathering in cf-conventions: see cf-compression-gathering and cf-reduced-horizontal-grid). This means that the spatial domain is flatten in grid, and each point is associated with a index, a x coordinate, a y coordinate, eventually a z coordinate (number of layer in most cases), and dx, dy values.

The x, and y coordinates are the center of cell. dx, dy are the dimensions of the cell.

Installation

From pip

On pip, gridmarthe is available for GNU/Linux, and Windows for python >=3.10. Users can install it with:

pip install gridmarthe
# or with all optional dependencies
pip install gridmarthe[opt]

For UNIX systems, the package needs gfortran/gcc shared libraries to run. For example, using a Debian-based GNU/Linux distribution, one can install gcc with:

sudo apt install gcc gfortran

From conda-forge

gridmarthe is also available in the conda-forge channel (Linux, Windows). Conda users can install it with:

conda install gridmarthe
# or, with mamba
mamba install gridmarthe

From sources

gridmarthe use some Fortran modules which need to be compiled before local installation, hence user/developer who want to install from sources will need a Fortran and a C compiler.

Compilation and installation

Get the sources :

git clone https://gitlab.com/brgm/hydrogeological-modelling/marthe-tools/gridmarthe
cd gridmarthe

With pip (Unix-like OS)

On a Unix-like machine, with gfortran, ninja-build, python3, the project Makefile will compile Fortran sources and install in development mode (i.e. with editable flag) the package.

make requirements
make

or, without the development/editable mode :

pip install .

On a Windows machine, it is possible to compile with gfortran/gcc (mingw project https://mingw-w64.org/ or https://winlibs.com/#download-release ; it can also be installed with chocolatey choco install mingw, or with conda with conda-forge packages mingw-w64, gcc and gfortran).

With conda (recommended on Windows)

It is also possible to install gridmarthe in a conda environment. An environment file is provided (example with mamba):

mamba env create -n gm -f environment.yml
mamba activate gm
make

This will install the library using pip editable mode, but with dependencies installed from conda-forge.

Alternatively, you can use conda-build and the conda develop command to install the library in development mode.

mamba env create -n gm -f environment.yml
mamba activate gm
make conda-dev

On Windows, it is also possible to use a different compiler, for compatibility issues with other libraries. For example, use llvm compilers (flang and clang) instead of gfortran and gcc. To do so, use the following command:

mamba env create -n gm -f tools/env/conda_dev_llvm.yml
mamba activate gm
make conda-dev FC=flang CC=clang LD=lld

Warning: this approach requires an installation of VStudio.

Usage

Simple examples can be found in the documentation.

License

This program is free software and released under the terms of the GNU General Public License (version 3 or later).

Authors and acknowledgment

gridmarthe is released by (C) BRGM, French Geological Survey

Authors and contributors:

• A. Manlay,
• J.P. Vergnes,
• S. Wang,
• S. Lopez,
• S. Magne,
• T. Hallouin

References

Thiery, D. (2020). Guidelines for MARTHE v7.8 computer code for hydro-systems modelling (English version) (Report BRGM/RP-69660-FR; p. 246 p.) http://ficheinfoterre.brgm.fr/document/RP-69660-FR