PetscDALETKFSetLocalizationCoordinates#

Provides the geometry used to lazily build the localization matrix Q for a built-in PETSCDALETKF kernel.

Synopsis#

PetscErrorCode PetscDALETKFSetLocalizationCoordinates(PetscDA da, const Vec xyz[3], const PetscReal bd[3], Mat H)

Collective

Input Parameters#

da - the PetscDA context
xyz - length-3 array of coordinate vectors, one per spatial dimension; set unused trailing slots to NULL (the spatial dimension is taken to be the index of the first NULL, so {x, y, NULL} is 2D and {x, NULL, NULL} is 1D)
bd - length-3 array of periodic-domain extents (use 0 for non-periodic dimensions); pass NULL to mean fully non-periodic
H - the observation operator (used to map state-space coordinates to observation locations)

Notes#

The xyz array must always have three slots even in 1D or 2D; trailing slots are set to NULL. This matches the internal cached layout coord_xyz[3] and the layout used by both Q backends.

The localization matrix Q is built on first analysis (or whenever the type, radius or coordinates change) using the kernel selected by PetscDALETKFSetLocalizationType(). If the current type is PETSCDA_LETKF_LOC_NONE, the coordinates are cached but the analysis continues to run the NONE fast path; switch to a distance-based kernel via PetscDALETKFSetLocalizationType() for the cached coordinates to take effect. The reference counts on xyz and H are increased; the caller may destroy them afterwards.

The cached coordinate Vecs are referenced, not deep-copied. If the caller mutates the contents of any element of xyz after this call (for example, after a remesh or recoordinate step), the cached Q will not be rebuilt automatically; call PetscDALETKFResetLocalization() to invalidate Q and force a rebuild on the next analysis.

The columns of Q are global indices into the observation vector, derived from the row ownership and sparsity of the H cached here. The H passed to PetscDAEnsembleAnalysis() must therefore use the same global row indexing (same observation ordering and the same global obs-space size) as the H cached here. The analysis-time H may differ from the cached H in MPI row partition or vec type - the obs-scatter is templated on the analysis-time H, so those differences are absorbed automatically. A structurally different H (rows referring to different physical observations) will produce wrong analyses without raising an error; in that case, call PetscDALETKFSetLocalizationCoordinates() again with the new H to rebuild Q.