gwsource.export#
Reshape per-cell results to the model grid and save them: npz, netCDF, GeoPackage, CSV.
Grid shapes and dimensions:
- DIS: (nlay, nrow, ncol), dims (layer, row, col);
- DISV: (nlay, ncpl), dims (layer, icell2d);
- DISU and hand-built graphs: (nodes,), dim (node).
Index coordinates are 1-based, as in MODFLOW. Inactive cells are NaN.
npz keys are '<output>__<group>' for per-group arrays, '<output>__<group>__<package>' for the
by-term splits and '<output>_<statistic>__<group>' for transient statistics.
netCDF (xarray; optional dependency, extra 'export'): one variable per output with dims
(group, *grid) and (group, package, *grid) for the by-term splits; transient statistics are
'<output>_<statistic>' (group, *grid), and the analysed steps form a 'time' dimension (totim,
kstp, kper, weight, the per-step group inflow and, with keep_series, every step's outputs).
Variables carry long_name and units (from the model's LENGTH_UNITS and TIME_UNITS when known);
the 'provenance' attribute records the package version, model files, steps and options.
GeoPackage (FloPy modelgrid -> geopandas; optional): one polygon layer per model layer
('layer_1', ...) for DIS and DISV, one layer 'nodes' for DISU, with one column per output and
group. DISU needs cell vertices in the binary grid file; without them export fails with a
clear message.
Network steps (gwsource.network): to_grid() reshapes one model's part (model=, optional when
the step has one model). The single-result exports above take a network step with one model
directly (its cells only); with several models use save_network(), which writes one npz per
model ('<prefix>_<model>.npz'), the package-node results as CSV ('<prefix>_packages.csv', one row
per reach, lake, well or UZF cell) and, optionally, a GeoPackage with one polygon layer per
model layer ('<model>_layer_<k>') and a point layer 'package_nodes' (each package node placed at
the mean centre of the cells it exchanges water with).
Transient tracking (gwsource.tracking): tracking_dataset() gives (time, group, *grid) variables
(time = end of step forward, start of step backward) plus the per-step balance tables, for one
model's cells; save_tracking_npz() writes one npz per step ('<prefix>_<index>.npz'), gridded for
one model or flat over every global node of a network (package nodes included).
- gwsource.export.to_grid(step, values, model=None)[source]#
Return per-cell values reshaped to the grid, with inactive cells set to NaN. For a network step, the part of one model (model= may be omitted if there is only one).
- gwsource.export.single_model(step, result)[source]#
Return (step, result) cut to the only model of a network step; unchanged otherwise.
- Parameters:
step (FlowStep)
- gwsource.export.single_model_transient(result)[source]#
Return a TransientResult cut to the only model of its network template.
- gwsource.export.result_arrays(step, result)[source]#
Return every per-cell output as gridded arrays keyed '<output>__<group>[__<package>]'.
- Parameters:
step (FlowStep)
result (BackwardResult | ForwardResult)
- Return type:
- gwsource.export.transient_arrays(result)[source]#
Return every transient statistic as gridded arrays keyed '<output>_<stat>__<group>'.
- gwsource.export.save_npz(path, step, result)[source]#
Save a result's gridded arrays, the active mask, cell area and cycle ids to a .npz.
- Parameters:
step (FlowStep)
result (BackwardResult | ForwardResult)
- Return type:
- gwsource.export.save_transient_npz(path, result)[source]#
Save a transient result's statistics, step table, active mask and area to a .npz.
- gwsource.export.save_cycle_report(path, cycles)[source]#
Write a cycle report (diagnostics.cycle_report) to CSV, one row per cycle.
- gwsource.export.unit_string(step, kind)[source]#
Return a units string ('1', volume rate, flux, area or time) from the model's units.
- gwsource.export.provenance(step, extra)[source]#
Return a JSON provenance string: package version, model files, time and options.
- gwsource.export.inflow_long_name(mode, accounting)[source]#
Return the long_name of a group's destination (backward) or source (forward) inflow.
- gwsource.export.to_dataset(step, result)[source]#
Return an xarray Dataset of every output of a single-step result.
- Parameters:
step (FlowStep)
result (BackwardResult | ForwardResult)
- gwsource.export.transient_dataset(result)[source]#
Return an xarray Dataset of a transient result's statistics (and series, if kept).
- gwsource.export.to_netcdf(path, step_or_result, result=None)[source]#
Write a single-step result (step, result) or a TransientResult to a netCDF file.
- gwsource.export.cell_polygons(grb_file)[source]#
Return a GeoDataFrame of cell polygons from the binary grid file (FloPy modelgrid). One row per cell of a layer for DIS and DISV, one per node for DISU.
- gwsource.export.to_geopackage(path, step_or_result, result=None, grb_file=None, crs=None)[source]#
Write a single-step result (step, result) or a TransientResult to a GeoPackage. crs (e.g. 'EPSG:2193') sets the layer CRS; the grid file has none.
- gwsource.export.plot_map(grb_file, step, values, layer=0, ax=None, **kwargs)[source]#
Draw a quick-look map of per-cell values with FloPy's PlotMapView; return the collection.
- gwsource.export.cell_centres(grb_file)[source]#
Return the (x, y) centre of every user node from a binary grid file, shape (nodes, 2).
- gwsource.export.package_points(step)[source]#
Return {global package node: (x, y)}, the mean centre of the cells it exchanges with.
- gwsource.export.save_package_csv(path, step, result, points=None)[source]#
Write the package-node results (network.package_rows) to CSV, with x, y if known.
- gwsource.export.save_network(directory, step, result, prefix='trace', geopackage=False, crs=None)[source]#
Write a network result: one npz per model, package nodes as CSV, optional GeoPackage.
- Parameters:
step (FlowStep)
result (BackwardResult | ForwardResult)
prefix (str)
geopackage (bool)
- Return type:
- gwsource.export.tracking_dataset(result, model=None)[source]#
Return an xarray Dataset of a transient tracking result (time, group, *grid). Forward: tracked_source_fraction at the end of each step and the tagged-water balance per step and group ('balance_<key>'). Backward: tracked_fraction_through and tracked_volume_from at the start of each step, fraction_any_sink, fraction_in_storage_at_end and the destination outflow per step. For a network, one model's cells (model=); package nodes are in save_tracking_npz.
- Parameters:
model (str | None)
- gwsource.export.save_tracking_npz(directory, result, prefix='tracking', model=None)[source]#
Write one npz per time step of a tracking result ('<prefix>_<step index>.npz'). Each file holds the step's per-node outputs as '<output>__<group>' (gridded for a single model; for a network with model=None, flat over all global nodes, package nodes included), and its kstpkper, totim and delt.