[ENH] Add AD showcase tests, compute_grads config option, and documentation (#1094)

# Description

Adds `compute_grads` as a configurable option in `GemPyEngineConfig` and threads it through to `BackendTensor.change_backend_gempy` when calling `compute_model`. This allows gradient computation to be explicitly controlled via the engine config rather than being hardcoded or inferred.

The nugget optimizer is updated to handle backends that may not support the `grads` keyword argument gracefully, falling back to a call without it while still setting `BackendTensor.COMPUTE_GRADS = True` directly.

A new AD (automatic differentiation) test suite is introduced under `test/test_modules/test_ad/`, covering:

- **Scenario A**: Baseline AD smoke test and regression guard — verifies gradient existence, finiteness, and deterministic norm ranges for surface points and orientations.
- **Scenario B**: Full-grid Jacobian spatial sensitivity — computes the Jacobian of the scalar field with respect to all surface-point coordinates and identifies the most influential points.
- **Scenario C**: Numerical vs. autograd gradient comparison — validates AD correctness against central finite differences with coordinate-space scaling applied.
- **Scenario D**: Multi-target derivatives — compares gradients from the scalar field and lithology block targets, including cosine similarity between gradient vectors.
- **Scenario E**: Dual contouring intermediate sensitivity — backpropagates through DC edge gradients to surface-point coordinates.

A second visualization-focused test file (`test_ad_II.py`) is added, demonstrating AD gradients rendered as PyVista glyph arrows on both a fold model and a combination model, with highlighted mesh vertices, mocked borehole cylinders, and logarithmically scaled gradient magnitude colormaps.

Relates to #

# Checklist

- [x] My code uses type hinting for function and method arguments and return values.
- [x] I have created tests which cover my code.
- [x] The test code either 1. demonstrates at least one valuable use case (e.g. integration tests)
or 2. verifies that outputs are as expected for given inputs (e.g. unit tests).
- [x] New tests pass locally with my changes.

Author: Leguark

.gitignore

@@ -183,3 +183,5 @@ examples/tutorials/z_other_tutorials/json_io/combination_model.json
 examples/tutorials/z_other_tutorials/json_io/combination_model_computed.json
 /test/temp/
 test/test_modules/run_test.py
+
+.junie

gempy/API/compute_API.py

@@ -32,15 +32,16 @@ def compute_model(gempy_model: GeoModel, engine_config: Optional[GemPyEngineConf
     Returns:
         Solutions: The computed geological model.
     """
-    engine_config = engine_config or GemPyEngineConfig(use_gpu=False)
+    engine_config: GemPyEngineConfig = engine_config or GemPyEngineConfig(use_gpu=False)
 
     match engine_config.backend:
         case AvailableBackends.numpy | AvailableBackends.PYTORCH:
 
             BackendTensor.change_backend_gempy(
                 engine_backend=engine_config.backend,
                 use_gpu=engine_config.use_gpu,
-                dtype=engine_config.dtype
+                dtype=engine_config.dtype,
+                grads=engine_config.compute_grads
             )
 
             # TODO: To decide what to do with this.

gempy/core/data/gempy_engine_config.py

@@ -10,4 +10,5 @@ class GemPyEngineConfig:
     backend: AvailableBackends = config.DEFAULT_BACKEND # ? This can be grabbed from gempy.config file?
     use_gpu: bool = False
     dtype: Optional[str] = None  #: The data type used in the engine. If None, the default data type of the backend is used.
+    compute_grads: Optional[bool] = False
 

gempy/modules/optimize_nuggets/_optimizer.py

@@ -21,12 +21,20 @@ def nugget_optimizer(
     Returns the final nugget effect value.
     """
     # 1) Backend setup (ideally done once, not every call)
-    BackendTensor.change_backend_gempy(
-        engine_backend=engine_cfg.backend,
-        use_gpu=engine_cfg.use_gpu,
-        dtype=engine_cfg.dtype,
-        grads=True
-    )
+    BackendTensor.COMPUTE_GRADS = True
+    try:
+        BackendTensor.change_backend_gempy(
+            engine_backend=engine_cfg.backend,
+            use_gpu=engine_cfg.use_gpu,
+            dtype=engine_cfg.dtype,
+            grads=True
+        )
+    except TypeError:
+        BackendTensor.change_backend_gempy(
+            engine_backend=engine_cfg.backend,
+            use_gpu=engine_cfg.use_gpu,
+            dtype=engine_cfg.dtype
+        )
 
     # 2) Prepare data
 

requirements/requirements.txt

@@ -1,2 +1,2 @@
 # This install also numpy
-gempy_engine>=2026.0.1dev0,<2026.1.0
+gempy_engine>=2026.0.2dev0

test/test_model_types/test_example_models_I.py

@@ -1,17 +1,12 @@
-from typing import Any
-
-from numpy import dtype, ndarray
+import pytest
+from gempy_viewer import GemPyToVista
 
 import gempy as gp
-from gempy.core.data import GeoModel
 from gempy.core.data.enumerators import ExampleModel
 from gempy.optional_dependencies import require_gempy_viewer
 from gempy_engine.core.data.interp_output import InterpOutput
-from gempy_viewer import GemPyToVista
-
-from test.verify_helper import gempy_verify_array
-import pytest
 from test.conftest import TEST_SPEED, TestSpeed
+from test.verify_helper import gempy_verify_array
 
 # ! When importing the model is computed