Skip to content

Welcome to ModVis

image

A python package for model visualization.

  • Free software: GPL license
  • Documentation: https://pinshuai.github.io/modvis

Features

  • Visualize model outputs from hydrologic models including ATS, PFLOTRAN, and etc.
  • Plot unstructured meshes with variables such as groundwater table, saturation, and evapotranspiration.
  • Evaluate model performance using different metrics.

Installation

ModVis is available on PyPI. To install, run the following command:

1
pip install modvis

If you want to run the latest version of the code, you can install from git:

1
pip install -U git+https://github.com/pinshuai/modvis.git

Alternatively, if you want to debug and test the code, you can clone the repository and install from source:

1
2
3
git clone https://github.com/pinshuai/modvis.git
cd modvis
pip install -e .

Quick start

Plot variables on triangular meshes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import modvis.ats_xdmf as xdmf
import modvis.plot_vis_file as pv

# import visdump file
surface_vis = xdmf.VisFile(model_dir='.', domain='surface')
subsurface_vis = xdmf.VisFile(model_dir='.', domain=None, columnar=True)

# plot surface ponded depth
pv.plot_surface_data(surface_vis, var_name="surface-ponded_depth", log=True,
                              time_slice="2019-05-01", vmin=0.01, vmax=4)

# plot subsurface saturation. Note layer index is ordered from top to bottom (0--top).
pv.plot_layer_data(subsurface_vis, var_name = "saturation_liquid", 
                             layer_ind = 0, time_slice= 0,
                              cmap = "coolwarm")

Plot variables on mixed-element meshes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import modvis.ats_xdmf as xdmf
import modvis.plot_vis_file as pv

# import visdump file
surface_vis = xdmf.VisFile(model_dir='.', domain='surface', mixed_element=True)
subsurface_vis = xdmf.VisFile(model_dir='.', domain=None, mixed_element=True)

# plot surface ponded depth
pv.plot_surface_data(surface_vis, var_name="surface-ponded_depth", 
                              time_slice="2019-05-01", mixed_element=True)

# plot subsurface saturation. Note layer index is ordered from top to bottom (0--top).
pv.plot_layer_data(subsurface_vis, var_name = "saturation_liquid", 
                             layer_ind = 0, time_slice= 0, mixed_element=True)

Examples

Jupyter notebook examples can be found under examples/notebooks

How to cite?

Pin Shuai, Rathore, S., & Coon, E. (2025). pinshuai/modvis: ModVis v0.0.9 (v0.0.9). Zenodo. https://doi.org/10.5281/zenodo.17073812

Credits

This work is supported by LDRD funding from PNNL, with continuing support from the Utah Water Research Laboratory.

This package was created with Cookiecutter and the giswqs/pypackage project template.