Troubleshooting Guide #

Common problems and their solutions.

Installation Issues #

Problem: “ModuleNotFoundError: No module named ‘chemparseplot’”#

**Cause:** Package not installed in current Python environment.

**Solution:**

# Check which Python is active
which python
python --version

# Install in correct environment
python -m pip install chemparseplot

# Or use full path
/path/to/python -m pip install chemparseplot

Problem: “ImportError: No module named ‘matplotlib’”#

**Cause:** Plotting dependencies not installed.

**Solution:**

pip install "chemparseplot[plot]"

Problem: “ImportError: No module named ‘opi’”#

**Cause:** OPI not installed (needed for ORCA 6.1+ parsing).

**Solution:**

pip install orca-pi

Or use legacy parser for ORCA < 6.1:

from chemparseplot.parse.orca.neb import parse_orca_neb_fallback
data = parse_orca_neb_fallback("job", Path("calc"))

Parsing Issues #

Problem: “FileNotFoundError: [Errno 2] No such file or directory: ‘job.json’”#

**Cause:** ORCA 6.1+ JSON output not found.

**Solution:**

Ensure ORCA 6.1+ was used
Check ORCA input includes JSON output:

%output
  Print[JSON] true
end

Verify job completed successfully

Problem: “ValueError: No energy data in neb_data"#

**Cause:** NEB calculation did not produce energy data.

**Solution:**

Check ORCA/eOn output for errors
Verify NEB calculation completed
Check .interp file exists (for legacy parser)

Problem: “ValueError: Surface prediction produced no finite values for contourf”#

**Cause:** Gradient surface models (often grad_imq) returned a non-finite grid—common on very dense single-ended movies (e.g. eOn LBFGS force-eval dumps).

**Solution:** Opt in to fit thinning (default remains off):

from chemparseplot.plot.neb import SurfaceFitConfig, plot_landscape_surface

plot_landscape_surface(
    ax, rmsd_r, rmsd_p, grad_r, grad_p, z_data,
    method="grad_imq",
    surface_fit=SurfaceFitConfig(auto_thin=True, max_surface_points=64),
)

Or pass auto_thin=True / max_surface_points=64 kwargs. From rgpycrumbs CLIs, set the same keys in --config TOML under [shared] or [min] / [neb] (not as CLI flags).

Problem: “RMSD coordinates required for landscape plot”#

**Cause:** Geometry output not available.

**Solution:** Add to ORCA input:

%output
  Print[P_Molden] true
  Print[MOs] true
end

Plotting Issues #

Problem: “Contour levels must be increasing”#

**Cause:** Energy data has numerical issues or duplicate values.

**Solution:**

import numpy as np

# Check for issues
print(f"Min energy: {energies.min()}")
print(f"Max energy: {energies.max()}")
print(f"Unique values: {len(np.unique(energies))}")

# Filter or smooth if needed
from scipy.ndimage import gaussian_filter1d
energies_smooth = gaussian_filter1d(energies, sigma=1)

Problem: “Spline failed (only integer scalar arrays can be converted to a scalar index)”#

**Cause:** Spline interpolation issue with array indices.

**Solution:** Use alternative interpolation method:

plot_orca_neb_energy_profile(
    data, "profile.pdf",
    method="spline"  # Instead of "hermite"
)

Problem: “Module ‘jax’ is not installed”#

**Cause:** JAX required for GP surface fitting.

**Solution:**

pip install "jax[cpu]"  # CPU-only
# or
pip install "jax[cuda12]"  # With CUDA support

Or use simpler interpolation:

plot_orca_neb_landscape(
    data, "landscape.pdf",
    method="rbf"  # Instead of "grad_matern"
)

Performance Issues #

Problem: Batch plotting is very slow #

**Cause:** Sequential processing of many plots.

**Solution:** Use parallel processing:

rgpycrumbs chemgp batch -c config.toml -j 8

Problem: Landscape plotting takes too long #

**Cause:** Surface fitting is computationally expensive.

**Solution:**

Reduce number of points (downsample)
Use simpler method:

plot_orca_neb_landscape(
    data, "landscape.pdf",
    method="rbf",  # Faster than GP methods
    n_inducing=100  # Fewer inducing points
)

Common Error Messages #

Error	Cause	Solution
“No images found”	NEB calculation incomplete	Check ORCA output for errors
“Barrier is negative”	Product higher than saddle	Check calculation converged
“RMSD values are identical”	Structures not loaded	Verify .xyz/.con files exist
“Color map not found”	Invalid colormap name	Use “cmc.batlow” or “viridis”

Getting Help #

If these solutions don’t help:

Check FAQ for common questions
Search Glossary for term definitions
Create issue on GitHub Issues

Include:

chemparseplot version
Python version
ORCA/eOn version
Minimal reproducible example
Full error message