Functions¶

version ¶

version() -> str

Return the version string of the installed mp3du library.

hydrate_cell_properties ¶

hydrate_cell_properties(top: NDArray[float64], bot: NDArray[float64], porosity: NDArray[float64], retardation: NDArray[float64], hhk: NDArray[float64], vhk: NDArray[float64], disp_long: NDArray[float64], disp_trans_h: NDArray[float64], disp_trans_v: NDArray[float64]) -> CellProperties

Hydrate per-cell physical properties from NumPy arrays.

All arrays must have shape (n_cells,) and be in cell-ID order.

Parameters:

Name	Type	Description	Default
`top`	`NDArray[float64]`	Top elevation of each cell (model units).	required
`bot`	`NDArray[float64]`	Bottom elevation of each cell (model units).	required
`porosity`	`NDArray[float64]`	Effective porosity (dimensionless, 0–1).	required
`retardation`	`NDArray[float64]`	Retardation factor (dimensionless, ≥ 1).	required
`hhk`	`NDArray[float64]`	Horizontal hydraulic conductivity (L/T).	required
`vhk`	`NDArray[float64]`	Vertical hydraulic conductivity (L/T).	required
`disp_long`	`NDArray[float64]`	Longitudinal dispersivity (L).	required
`disp_trans_h`	`NDArray[float64]`	Horizontal transverse dispersivity (L).	required
`disp_trans_v`	`NDArray[float64]`	Vertical transverse dispersivity (L).	required

Returns:

Type	Description
`CellProperties`	A `CellProperties` object ready for use in `fit_waterloo()`.

hydrate_cell_flows ¶

hydrate_cell_flows(head: NDArray[float64], water_table: NDArray[float64], q_top: NDArray[float64], q_bot: NDArray[float64], q_vert: NDArray[float64], q_well: NDArray[float64], q_other: NDArray[float64], q_storage: NDArray[float64], has_well: NDArray[bool_], face_offset: NDArray[uint64], face_flow: NDArray[float64], face_neighbor: NDArray[int64], bc_cell_ids: Optional[NDArray[int64]] = None, bc_iface: Optional[NDArray[int32]] = None, bc_flow: Optional[NDArray[float64]] = None, bc_type_id: Optional[NDArray[int32]] = None, bc_type_names: Optional[List[str]] = None, is_domain_boundary: Optional[NDArray[bool_]] = None, has_water_table: Optional[NDArray[bool_]] = None) -> CellFlows

Hydrate cell flow data from NumPy arrays.

mp3du API convention (target):

face_flow: positive = into cell.
q_well: negative = extraction, positive = injection (raw MODFLOW sign).

The transformation from raw MODFLOW output depends on version:

MODFLOW-USG / MF6 (FLOW-JA-FACE): raw is positive = IN. Pass directly: face_flow = flowja.
MODFLOW-2005 / NWT (after directional→per-face assembly): result is positive = OUT. Negate: face_flow = -assembled.

Pass the same face_flow array to both hydrate_cell_flows() and hydrate_waterloo_inputs(). No per-function negation needed.

Never negate q_well. See docs/reference/units-and-conventions.md for the full reference.

hydrate_waterloo_inputs ¶

hydrate_waterloo_inputs(centers_xy: NDArray[float64], radii: NDArray[float64], perimeters: NDArray[float64], areas: NDArray[float64], q_vert: NDArray[float64], q_well: NDArray[float64], q_other: NDArray[float64], face_offset: NDArray[uint64], face_vx1: NDArray[float64], face_vy1: NDArray[float64], face_vx2: NDArray[float64], face_vy2: NDArray[float64], face_length: NDArray[float64], face_flow: NDArray[float64], noflow_mask: NDArray[bool_]) -> WaterlooInputs

Hydrate Waterloo velocity-fitting inputs from NumPy arrays.

mp3du API convention (target):

face_flow: positive = INTO cell — same as hydrate_cell_flows().
q_well: raw MODFLOW sign (negative = extraction). Do NOT negate.

Pass the same face_flow array used for hydrate_cell_flows(). No per-function negation or sign flip is needed.

The Waterloo method subtracts the analytic well singularity during fitting and adds it back during evaluation; both must use the same q_well sign. See docs/reference/units-and-conventions.md for the full reference.

build_grid ¶

build_grid(vertices: List[List[Tuple[float, float]]], centers: List[Tuple[float, float, float]]) -> GridHandle

Compile an unstructured polygon grid into a GridHandle.

Parameters:

Name	Type	Description	Default
`vertices`	`List[List[Tuple[float, float]]]`	For each cell, an ordered list of `(x, y)` vertex coordinates defining the cell polygon.	required
`centers`	`List[Tuple[float, float, float]]`	For each cell, a `(x, y, z)` tuple giving the cell centroid (x, y) and representative elevation (z).	required

Returns:

Type	Description
`GridHandle`	A `GridHandle` that can be passed to `fit_waterloo()` or
`GridHandle`	`fit_sspa()`. The handle is consumed (invalidated) by the
`GridHandle`	fitting call.

fit_waterloo ¶

fit_waterloo(config: WaterlooConfig, grid: GridHandle, fit_inputs: WaterlooInputs, cell_properties: CellProperties, cell_flows: CellFlows) -> WaterlooFieldHandle

Fit the Waterloo velocity field.

Consumes the GridHandle (it will no longer be loaded after the call). Well locations are derived automatically from cell_flows.has_well and the grid cell centres.

Sign conventions: fit_inputs must use face_flow positive = INTO cell (same array as hydrate_cell_flows; q_well = raw MODFLOW sign). See hydrate_waterloo_inputs() and docs/reference/units-and-conventions.md.

hydrate_sspa_inputs ¶

hydrate_sspa_inputs(heads: NDArray[float64], porosity: NDArray[float64], well_mask: NDArray[bool_], hydraulic_conductivity: Optional[NDArray[float64]] = None, hhk: Optional[NDArray[float64]] = None) -> SspaInputs

Hydrate SSP&A fitting inputs from NumPy arrays.

Parameters:

Name	Type	Description	Default
`heads`	`NDArray[float64]`	Simulated hydraulic heads, shape `(n_cells,)`.	required
`porosity`	`NDArray[float64]`	Effective porosity per cell, shape `(n_cells,)`.	required
`well_mask`	`NDArray[bool_]`	Boolean array marking cells that contain a well, shape `(n_cells,)`.	required
`hydraulic_conductivity`	`Optional[NDArray[float64]]`	Horizontal hydraulic conductivity per cell, shape `(n_cells,)`. Provide exactly one of `hydraulic_conductivity` or `hhk`.	`None`
`hhk`	`Optional[NDArray[float64]]`	Alias for `hydraulic_conductivity` (legacy shorthand). Provide exactly one of `hydraulic_conductivity` or `hhk`.	`None`

Returns:

Type	Description
`SspaInputs`	An `SspaInputs` object ready to pass to `fit_sspa()`.

fit_sspa ¶

fit_sspa(config: SspaConfig, grid: GridHandle, inputs: SspaInputs, drifts: List[Dict[str, Any]]) -> VelocityFieldHandle

Fit the SSP&A (kriging-based) velocity field.

Consumes the GridHandle (it will no longer be loaded after the call).

run_simulation ¶

run_simulation(config: SimulationConfig, velocity_field: VelocityFieldHandle, particles: List[ParticleStart], parallel: bool = True) -> List[TrajectoryResult]

Run particle tracking on a fitted velocity field.

Well capture is controlled by capture.capture_radius in the SimulationConfig: - Omitted / null: capture immediately on cell entry (strong sink). - A positive number (e.g. 0.5): capture only when within that distance of the cell centre (weak sink).