---

name: environment-and-troubleshooting description: "Install GemPy reproducibly, inspect core and optional dependencies, select a safe compute backend, and diagnose import, validation, viewer, headless, and version-drift failures." disable-model-invocation: true metadata: disco-role: operating license: EUPL 1.2

Environment and troubleshooting

Use this route when GemPy cannot be installed, imported, computed, plotted, or validated, or when a working model behaves differently after an upgrade. It covers the package boundary and the first diagnostic only. After the first signal, send modeling/data, grid, or persistence problems to the owning route in the root GemPy skill.

Install a known capability set

Use a fresh Python environment with Python 3.10 or newer. The published source advertises Python 3.10--3.12; newer interpreters are not automatically proven compatible. Use python -m pip so pip belongs to the selected Python:

python -m pip install --upgrade pip
python -m pip install gempy                    # core NumPy-oriented install
python -m pip install "gempy[base]"             # viewer, pandas, and base use
python -m pip install "gempy[opt]"              # base plus optional data/plugins

The core install brings gempy_engine and NumPy. The base extra adds the companion gempy_viewer package and pandas; viewer workflows also need Matplotlib and, for 3-D rendering, PyVista as described by the viewer package. The opt extra adds GSTools, gempy_plugins, Pooch, SciPy, and scikit-image. Install PyTorch separately using its official selector when a PyTorch backend, gradients, or nugget optimization is actually required. Do not install all extras merely to make a core NumPy model run.

Prefer one release line for gempy, gempy_engine, and gempy_viewer. After installation, run the bundled environment checker from any directory:

python path/to/check_environment.py
python path/to/check_environment.py --backend numpy
python path/to/check_environment.py --require gempy_viewer --require pyvista
python path/to/check_environment.py --strict-optional --json

The checker never installs packages or accesses the network. It reports Python compatibility, distribution metadata, public imports, backend availability, Matplotlib's active backend, and whether a headless viewer needs off-screen configuration. Missing optional modules are warnings with a package-specific recovery command; required core failures return a non-zero status.

First import and provenance check

A minimal core probe is:

python -c "import gempy, gempy_engine; print(gempy.__version__)"
python -m pip check
python -m pip show gempy gempy-engine gempy-viewer

If gempy fails while gempy_engine is absent, repair the core install rather than adding viewer packages. If only gempy_viewer, pandas, PyVista, or another optional import fails, core NumPy modeling can remain usable; install the smallest extra for the operation that failed. Do not treat pip check failures in unrelated packages as GemPy API evidence, but record them when diagnosing a contaminated environment.

Before comparing a saved model or result, read the dependency matrix and refresh information in repo provenance. Compare the three GemPy package versions, Python version, backend, dtype, GPU choice, and optional-module set. Re-run the checker after any upgrade.

Choose the compute backend deliberately

For the most portable path, construct GemPyEngineConfig with gp.data.AvailableBackends.numpy and use_gpu=False. The source also exposes AvailableBackends.PYTORCH; use it only after torch imports successfully and its device is usable. GemPyEngineConfig reads GEMPY_USE_GPU and treats the exact value True as enabled. A GPU request can be made recoverable with GEMPY_GPU_FALLBACK=True; this changes an unavailable GPU request to CPU after the engine raises its runtime error. Validate the selected backend before a long computation and keep dtype consistent across a run.

A backend failure is not a data failure. First run:

python path/to/check_environment.py --backend numpy
python path/to/check_environment.py --backend pytorch

If the second command fails because Torch or its accelerator is unavailable, use the NumPy configuration for ordinary modeling or install the matching Torch build. Route model construction, interpolation options, and grid-shape errors to the modeling/grid route after recording this backend result.

Validation and viewer triage

compute_model validates by default. GeoModel.validate() raises gempy.ModelValidationError with field, reason, message, and context. The first diagnostic is normally more useful than the later engine traceback:

• empty_model: no surface points and no orientations.
• underdetermined_input: at most one surface point and no orientation.
• empty_fault_group or empty_non_fault_group: a structural group has no elements.
• basement_relation_on_non_last_group: a basement relation is not on the final structural group.

Fix the input or structural groups, then compute again. skip_validation=True is an explicit escape hatch for a known, intentionally deferred condition; it is not a repair and should not be the default. Detailed symptoms and recovery are in troubleshooting.

If core import and NumPy computation work but plotting fails, check viewer, Matplotlib, and PyVista independently. A viewer import failure does not imply that the core model is unusable. In a display-less process, set MPLBACKEND=Agg before importing Matplotlib for file-based 2-D output and use the viewer/PyVista off-screen option supported by the installed viewer for 3-D. Do not call interactive show() as a headless smoke test. For a direct PyVista file/render smoke test, configure the public off-screen switch before creating plots:

import pyvista
pyvista.OFF_SCREEN = True

A missing display, OpenGL/EGL problem, or PyVista import error is a visualization issue; route model/data errors separately.

Handoff boundary

Always preserve the exact command, package versions, backend, exception type, validation reason/field, and whether the process is headless. Then use the root route map for workflow-specific modeling/data/grid/ persistence help. This route owns environment and first-diagnostic facts, not maintainer documentation builds, deployment scripts, private tests, or a full modeling tutorial.