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:

mamba env create -n gm -f environment.yml
mamba activate gm
mamba install conda-build
make lib  # only compile shared library for python bindings
conda develop src/

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

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