pycsamt.ai.inversion.mapping2d#

Geometry-aware mapping between regular AI and Occam2D grids.

An AI inversion commonly predicts a regular array, whereas Occam2D uses unequal finite-element cells grouped into inversion parameters. This module interpolates an AI grid to physical Occam earth-cell centres and then computes an area-weighted mean for every parameter group defined by OccamModel.layers.

Functions

`build_occam_parameter_adjacency`(model)	Return 1-based Occam parameter pairs that are spatial neighbours.
`map_ai_grid_to_occam`(grid, model, mesh[, ...])	Map a regular AI grid to Occam parameter order.

pycsamt.ai.inversion.mapping2d.map_ai_grid_to_occam(grid, model, mesh, x_coordinates=None, z_coordinates=None)[source]

Map a regular AI grid to Occam parameter order.

AI values are bilinearly interpolated to physical Occam cell centres. Values within each model-parameter rectangle are then averaged with finite-element cell area as weight:

\[\bar m_j = \frac{\sum_{k \in G_j} m_k A_k} {\sum_{k \in G_j} A_k},\]

where \(G_j\) is parameter group \(j\) and \(A_k\) is the area of mesh cell \(k\). Air layers are excluded, and the returned vector follows the layer-major order used by Occam startup and iteration files.

Parameters:

grid (array-like of float, shape (n_depth, n_horizontal)) – Finite AI values on a regular or explicitly coordinated grid. Values are typically log10 resistivity or predictive standard deviation.
model (OccamModel) – Populated Occam model definition. Horizontal parameter codes give the number of mesh cells spanned, and n_merge gives the number of earth rows spanned vertically.
mesh (OccamMesh) – Populated Occam finite-element mesh supplying physical cell widths, layer thicknesses, node positions, and air-layer count.
x_coordinates (array-like of float, optional) – Strictly increasing horizontal coordinates of AI grid columns, in the same coordinate system as mesh.x_nodes. The length must equal grid.shape[1]. If omitted, uniformly spaced cell centres spanning the complete Occam horizontal domain are used.
z_coordinates (array-like of float, optional) – Strictly increasing AI depth coordinates, positive downward from the earth surface. The length must equal grid.shape[0]. If omitted, uniformly spaced cell centres spanning the Occam earth domain are used.

Returns:

Area-weighted values in Occam layer-major parameter order.

Return type:

numpy.ndarray of float, shape (model.n_params,)

Raises:

TypeError – Raised when model or mesh lacks the required Occam geometry interface.
ValueError – Raised for invalid grids or coordinates, non-positive mesh dimensions, model groups inconsistent with the mesh, or a returned parameter count inconsistent with model.n_params.

Notes

Values outside the supplied AI coordinate range use nearest-edge extrapolation through numpy.interp(). Publication workflows should normally supply coordinates spanning the complete inversion domain so extrapolation is unnecessary.

The mapping averages log10 resistivity when grid is in log10 units. It therefore preserves the parameterization optimized by Occam rather than arithmetic resistivity.

When grid contains predictive standard deviation, the same area-weighted spatial averaging is applied. This treats uncertainty as a spatial field and does not assume independent AI pixels; it is therefore not a standard-error reduction by the number of cells.

See also

pycsamt.ai.inversion.duhi2d.DUHIInverter2D: Uses this mapper for AI means and standard deviations.
pycsamt.models.occam2d.OccamModel: Defines the parameter grouping traversed here.
pycsamt.models.occam2d.OccamMesh: Defines the physical cell areas used as weights.

Examples

Map a grid after reading an Occam project:

>>> from pycsamt.ai.inversion.mapping2d import (
...     map_ai_grid_to_occam,
... )
>>> from pycsamt.models.occam2d import OccamMesh, OccamModel
>>> mesh = OccamMesh.read("occam_run/Occam2DMesh")
>>> model = OccamModel.read("occam_run/Occam2DModel")
>>> parameters = map_ai_grid_to_occam(
...     ai_grid,
...     model,
...     mesh,
...     x_coordinates=ai_x,
...     z_coordinates=ai_z,
... )
>>> parameters.shape == (model.n_params,)
True

pycsamt.ai.inversion.mapping2d.build_occam_parameter_adjacency(model)[source]

Return 1-based Occam parameter pairs that are spatial neighbours.

Two parameters are adjacent when their model bricks share a horizontal edge within the same layer, or share any horizontal overlap between two vertically consecutive layers. The traversal order and 1-based numbering exactly match map_ai_grid_to_occam()’s parameter order, so pairs returned here index directly into ai_mean_parameters/ ai_std_parameters-style vectors and into pycsamt.models.occam2d.OccamPrejudice’s one-based parameter_indices.

Parameters:

model (OccamModel) – Populated Occam model definition. Each layer’s params (horizontal span codes) is used to derive brick boundaries in mesh-column index space; no physical widths are required.

Returns:

Unique, unordered 1-based parameter-index pairs. Each pair appears once with the smaller index first.

Return type:

list of (int, int)

Raises:

TypeError – Raised when model lacks the required Occam model interface.
ValueError – Raised when model has no parameter layers or a layer has an invalid parameter-code array.