Figure Catalog#

Figures live in hydromodpy.display and consume the persisted hydromodpy.results.run.Run interface. They are solver-agnostic: the same figure name can render MODFLOW-NWT, MODFLOW 6, or Boussinesq outputs when the required result fields exist.

Basic usage#

import hydromodpy as hmp

hmp.figure(run, "piezometric_map", save="figures/")
hmp.figure(run, "cross_section", orientation="sn")

The lower-level registry stays available when you need the figure object itself:

from hydromodpy.display import get, list_figures

list_figures()
get("piezometric_map").plot(run, save_path="head.png")

From the CLI:

hmp viz list
hmp viz show <sim_id> <figure>
hmp viz gallery project.toml
hmp run project.toml --no-display

Registered figure names#

The catalog below is auto-generated from the hydromodpy.display.list_figures() registry. Each entry shows the figure name, the title rendered in plots, and the result fields or tables the figure reads at render time. Run python -m tools.doc_figures to refresh the partial without rebuilding the rest of the documentation; the Sphinx build also regenerates it on every run.

Spatial maps#

Mesh- or raster-backed scalar maps of one persisted field.

Figure name	Title	Required inputs
`accumulation_map`	Accumulated drainage flux	fields `accumulation_flux`
`boundary_package_map`	Boundary packages	(no fixed input)
`concentration_map`	Concentration	fields `concentration`
`depression_map`	Closed depressions of the routing surface	(no fixed input)
`downslope_distance_map`	Downslope distance	fields `release_flux`
`flow_direction_map`	Flow direction	(no fixed input)
`mesh_map`	Solver mesh	fields `topography`
`piezometric_map`	Water-table elevation	fields `watertable_elevation`
`recharge_map`	Recharge	fields `recharge`
`seepage_map`	Seepage areas	fields `seepage_mask`
`sfr_reach_network`	SFR reach network	tables `timeseries`
`simulated_active_network`	Simulated active network	fields `accumulation_flux`
`watertable_depth_map`	Water-table depth	fields `watertable_depth`

Cross-sections#

Vertical or transverse cuts through a persisted field.

Figure name	Title	Required inputs
`cross_section`	Cross-section	fields `watertable_elevation`, `topography`

Time series#

Chronicles read from the catalog timeseries table.

Figure name	Title	Required inputs
`bisection_bracket_trace`	Bisection bracket trace	tables `calibration_iterations`
`calibration_convergence`	Calibration convergence	tables `calibration_iterations`
`calibration_trace`	Calibration parameter trace	tables `calibration_iterations`
`downslope_distance_crossing`	Downslope distance crossing	tables `calibration_iterations`
`duration_curve`	Flow-duration curve	tables `timeseries`
`hydrograph`	Discharge hydrograph	tables `timeseries`
`parameter_cost_profile`	Parameter cost profile	tables `calibration_iterations`
`recession`	Recession analysis	tables `timeseries`
`seasonal_boxplot`	Seasonal box-plot	tables `timeseries`
`sfr_longitudinal_profile`	SFR longitudinal profile	tables `timeseries`
`sfr_reach_timeseries`	SFR reach time series	tables `timeseries`

Budgets and balances#

Integrated budget or mass-balance summaries.

Figure name	Title	Required inputs
`flux_timeseries`	Water-balance components	tables `budgets`
`water_budget`	Water budget	tables `budgets`

Particle tracking#

Pathline or particle-track outputs.

Figure name	Title	Required inputs
`particle_tracks`	Particle pathlines	fields `particles`

Comparisons and overlays#

Multi-panel views combining one or several runs, observed data, or calibration traces.

Figure name	Title	Required inputs
`calibration_landscape`	Calibration objective landscape	tables `calibration_iterations`
`calibration_objective_surface`	Calibration objective surface	tables `calibration_iterations`
`calibration_pairplot`	Calibration parameter pairs	tables `calibration_iterations`
`calibration_posterior`	Calibration parameter posteriors	tables `calibration_iterations`
`conditioning_impact_map`	Conditioning impact on the DEM	(no fixed input)
`difference_map`	Difference map	(no fixed input)
`ensemble_band`	Ensemble envelope	tables `timeseries`
`hydrograph_log_nse`	Hydrograph on a log axis with NSElog	tables `timeseries`
`hydrograph_sim_obs`	Discharge hydrograph (sim vs obs)	tables `timeseries`
`hydrographic_network_comparison`	Hydrographic network comparison	(no fixed input)
`hydrographic_network_generated`	Generated hydrographic network	(no fixed input)
`hydrographic_network_generated_extra_only`	Generated extra-only view	(no fixed input)
`hydrographic_network_reference`	BD Topage hydrographic network	(no fixed input)
`hydrographic_network_reference_missing_only`	Reference missing-only view	(no fixed input)
`lake_abacus_comparison`	Lake abacus comparison	(no fixed input)
`lake_stage_sim_obs`	Lake stage (sim vs obs)	tables `timeseries`
`lake_volume_sim_obs`	Lake storage (sim vs obs)	tables `timeseries`
`matching_hydrographic_network_card`	Matching the hydrographic network: two-stage card	tables `calibration_iterations`
`piezo_timeseries_sim_obs`	Piezometric head (sim vs obs)	tables `timeseries`
`residuals`	Residuals (sim - obs)	tables `timeseries`
`roptim_validity_chart`	Optimal agreement and validity bound	(no fixed input)
`scatter_one_to_one`	Sim vs obs scatter (1:1)	tables `timeseries`
`seepage_network_confusion_map`	Seepage network confusion	fields `release_flux`
`seepage_network_reference_overlay`	Simulated network over reference	fields `release_flux`
`side_by_side`	Side-by-side map	(no fixed input)
`simulated_active_network_reference_overlay`	Simulated active network vs reference	fields `accumulation_flux`
`watershed_id_card`	Watershed identity card	(no fixed input)

Hydrochemistry diagrams#

Tabular hydrochemistry diagrams built from water-quality samples.

Figure name	Title	Required inputs
`piper_diagram`	Piper diagram	(no fixed input)
`schoeller_diagram`	Schoeller diagram	(no fixed input)
`stiff_diagram`	Stiff diagram	(no fixed input)

Choosing figures in TOML#

A run renders exactly the figures listed under [display].figures. Every name is validated against the registry when the configuration loads, so a typo fails hmp config check instead of silently producing one figure less.

[display]
figures = ["piezometric_map", "water_budget", "simulated_active_network"]
# "warn" (default) logs a figure that fails to render and continues;
# "raise" propagates, which is what example and CI configs want.
on_error = "warn"

Per-figure options go under [display.overrides], keyed by figure name. They are the same keywords hydromodpy.figure() accepts:

[display.overrides.cross_section]
orientation = "sn"
through = [152687.5, 6857800.0]

[display.overrides.flux_timeseries]
units = "mm/period"

Use hmp viz gallery project.toml to rerender all figures after a run, hmp viz show <sim_id> <figure> to rerender one figure, and --no-display during hmp run when the workflow should persist results without rendering report figures.

Overlays#

Spatial figures accept an overlays list, so a composite map is a configuration choice rather than a bespoke script:

[display.overrides.watertable_depth_map]
overlays = ["watershed", "seepage", "particles", "wells", "outlet"]

Available overlays: watershed (catchment outline), seepage (outcropping cells), particles (pathlines), network (reference hydrographic network), wells (pumping and injection cells read from the well budget) and outlet. An overlay whose data the run does not carry is logged and skipped, so the same declaration works across projects.

Applicability rule#

Figure names are stable entry points, but every figure depends on what the run persisted. Each figure declares its requirements in its FigureSpec (required_fields, required_tables, required_solvers); the display layer checks them before rendering and skips the figure with an explicit reason when the run does not satisfy them. A configuration can therefore list every figure it may want: a run without particle tracking simply does not produce particle_tracks.

List the names and their requirements with:

hmp viz list

To inspect what a given run actually holds:

hmp catalog show <sim_id> --detail

For low-level display objects, see API Reference.