Cokriging

[n0228a]

This pull request introduces a new cokriging subpackage to GSTools, providing a complete, extensible API for collocated cokriging using correlogram models. It adds both the core implementation and user-facing API, along with comprehensive documentation and usage examples. The main highlights are the new CollocatedCokriging base class, support for simple and intrinsic collocated cokriging algorithms, and integration of correlogram models (such as MarkovModel1). The package is fully integrated into the GSTools namespace and public API.

New cokriging subpackage and API:

• Added new gstools.cokriging subpackage with the following classes: CollocatedCokriging (base class), SimpleCollocated, IntrinsicCollocated, Correlogram, and MarkovModel1. This provides a flexible and extensible API for collocated cokriging methods. [1] [2]
• Implemented CollocatedCokriging base class supporting both simple and intrinsic collocated cokriging algorithms, with detailed parameter validation, variance estimation, and secondary data handling.

Documentation and examples:

• Added comprehensive docstrings, autosummary entries, and API documentation for all new classes and methods in both the main package and the new subpackage. [1] [2] [3]
• Added two new example scripts: 10_simple_collocated_cokriging.py and 11_intrinsic_collocated_cokriging.py, demonstrating the new API and comparing kriging and cokriging methods. [1] [2]

GSTools package integration:

• Registered the new cokriging subpackage and all its main classes in the GSTools public API and __all__ list, ensuring they are available for import from the main package namespace. [1] [2] [3] [4]

These changes collectively provide a robust foundation for multivariate geostatistical estimation in GSTools, with a modern, user-friendly interface and full documentation.had to move cokriging to new branch and start pull request again

[LSchueler]

For future references, this is a follow up of PR #394

[n0228a]

I let Claude ultrareview look for errors and corrected some architectural things, no algorithmic logic was touched: src/gstools/cokriging/base.py

final result — fixing self.field storing SK instead of cokriging , normalizer mixing , only_mean crash/corruption , and unnecessary variance solve
for ICCK

• _apply_simple_collocated: removed the spurious + kλm_Z mean term (residual-space arithmetic needs no explicit mean)
• _apply_intrinsic_collocated: computes lambda_Y0 = C_YZ0/C_Y0 locally from _compute_covariances() instead of reading fragile instance state
• _summate: full rewrite — computes sk_weights = krige_mat @ k_vec once in NumPy, derives field and variance directly, removes duplicate Cython call; drops dead
  ndim==1 branch, write-only _secondary_at_primary, and unreachable else: raise
• _prepare_secondary: validates secondary_data size against eval grid, raises ValueError with clear message on mismatch
• init (intrinsic block): validates secondary_cond_pos matches cond_pos; applies isfinite mask to secondary_cond_val before super().init so NaN-filtered
  primaries don't cause broadcast crash
• secondary_data is None guard: message now names CondSRF

src/gstools/cokriging/methods.py

• Removed duplicate isinstance(correlogram, Correlogram) checks from SimpleCollocated and IntrinsicCollocated (base already checks); removed now-unused import

src/gstools/init.py

• Added Correlogram and CollocatedCokriging to top-level imports and all

tests/test_cokriging.py — 11 new tests:

• test_scck_field_matches_full_system / test_icck_field_matches_full_system — independent full-system oracles locking the math
• test_field_stored_is_cokriging_result — self.field holds cokriging, not SK
• test_only_mean_not_supported — raises NotImplementedError
• test_zero_corr_with_normalizer_equals_sk — normalizer round-trip correctness
• test_secondary_data_wrong_length / test_secondary_data_structured_mesh — shape validation
• test_icck_nan_in_cond_val / test_icck_non_collocated_secondary_rejected — conditioning validation
• test_condsrf_gives_clear_error — CondSRF error message
• test_icck_summate_matches_oracle_with_chunks / test_top_level_exports — efficiency rewrite and export check

[LSchueler]

Awesome work! A few tiny and final things to add:

• please add yourself to the AUTHORS.md file
• please add cokriging to the "Purpose" and "Tutorials and Examples" sections of the README.md and docs/source/index.rst files
• please add a few lines to the CHANGELOG.md file, with a reference to this PR.

After that, we can finally merge this PR.