gridmarthe 0.3.0

python package to read/write/manage Marthe Grids

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.

Still, as Marthe meshes are always parallelepiped, the array does not necessarily follow the ugrid convention. This may be an evolution for future version if required.

The x, and y coordinates are the center of cell. Dx, Dy are the dimension of the cell.

Installation

From pip

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

pip install gridmarthe

For GNU/Linux and MacOS, the package needs gfotran/gcc to run.

Linux, example with debian/ubuntu:

sudo apt install gcc gfortran

MacOS:

brew install gcc gfortran

From conda-forge

gridmarthe is also available in the conda-forge channel. 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.

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 the package.

make

or, without the development mode :

pip install .

On a windows machine, it is possible to compile with gfortran (mingw project https://mingw-w64.org/ or https://winlibs.com/#download-release ; or choco install mingw). Neverless, the simpliest way is to use a conda environment (miniforge with mambalib is recommended) to install gcc/gfortran, and install the project.

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
pip install --no-deps .

Here, the development mode is not available (yet, with the meson build). One can add the -e flag in pip command, or use conda-build:

mamba env create -n gm -f environment.yml
mamba activate gm
mamba install conda-build
make lib
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

A. Manlay and J.P. Vergnes, (c) BRGM

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