Skip to content

Troubleshooting

Common issues and solutions.

ImportError after Installation

Problem: Cannot import gp4c after running pip install.

Solution: Rebuild the Cython extension:

python setup.py build_ext --inplace

Or reinstall:

pip install -e . --force-reinstall --no-cache-dir

Cholesky Decomposition Failed

Problem: Error message like "Cholesky decomposition failed" or "Matrix not positive definite".

Causes:

  1. Very small length scales
  2. Duplicate or very close evaluation points
  3. Numerical precision issues

Solutions:

Increase Jitter

Edit gp4c/_sampler.c and increase jitter:

// Change from 1e-8 to 1e-6
const double jitter = 1e-6;

Rebuild:

python setup.py build_ext --inplace

Use Larger Length Scale

# Instead of
result = sample_prior(spec, ell=0.05)  # Too small

# Use
result = sample_prior(spec, ell=0.2)   # Better

Check Evaluation Points

Ensure points are not duplicated:

x = np.unique(x)  # Remove duplicates
x = x[np.isfinite(x)]  # Remove inf/nan

Numerical Issues with Derivatives

Problem: Unstable or extreme values in derivative samples.

Explanation: Derivative kernel has variance \(O(1/\ell^2)\):

  • Small \(\ell\) → Very large derivative variance
  • Can exceed numerical precision

Solutions:

Use Larger Length Scale

# Instead of ell=0.1
result = sample_prior(spec, ell=0.5, n_samples=5)

Increase Derivative Jitter

The implementation uses higher jitter (1e-6) for derivative blocks. If still unstable, increase further in _sampler.c.

Avoid Boundaries

Sample derivatives at interior points:

x = np.linspace(0, 5, 100)
x_interior = x[5:-5]  # Drop boundary points

spec = SamplingSpec(x_f=x, x_h=x_interior)

GSL Not Found

Problem: Installation fails with "GSL not found".

Solution: Install GSL first:

brew install gsl

sudo apt-get install libgsl-dev

sudo dnf install gsl-devel

Slow Performance

Problem: Sampling takes too long.

Solutions:

  1. Use coarser grids - Especially for integrals
  2. Sample only what you need - Skip unused quantities
  3. Batch samples - Generate multiple samples in one call
  4. Larger length scales - Reduces required grid resolution

See Performance Guide for details.

Memory Issues

Problem: Out of memory for large grids.

Solution: Memory usage is \(O(n^2)\) for covariance matrix.

For grid size \(n > 1000\):

  • Use coarser grids where possible
  • Split problem into smaller regions
  • Consider sparse/low-rank approximations

Posterior Doesn't Interpolate

Problem: Posterior mean doesn't pass through training points.

Causes:

  1. High observation noise
  2. Poor length scale choice
  3. Mismatched observation locations

Solutions:

Reduce Noise

# Instead of
obs = Observations(x_f=x_train, y_f=y_train, noise_f=0.1)

# Use
obs = Observations(x_f=x_train, y_f=y_train, noise_f=0.001)

Tune Length Scale

Try different values:

for ell in [0.5, 1.0, 2.0]:
    result = sample_posterior(obs, spec, ell=ell, n_samples=5)
    # Evaluate fit quality

Verify Observation Points

# Check observations are in prediction range
assert np.all(obs.x_f >= spec.x_f.min())
assert np.all(obs.x_f <= spec.x_f.max())

Build Errors on Windows

Problem: Compilation fails on Windows.

Solution: gp4c is primarily tested on Linux/macOS. For Windows:

  1. Use WSL (Windows Subsystem for Linux)
  2. Install GSL via vcpkg
  3. Use MinGW with GSL

Or use pre-built Docker container (if available).

Reproducibility Issues

Problem: Different results with same seed.

Causes:

  1. Different NumPy/GSL versions
  2. Floating point operations depend on BLAS backend
  3. Platform differences

Solutions:

  • Pin package versions
  • Use same BLAS library
  • Accept small numerical differences (\(< 10^{-10}\))

Getting Help

If issues persist:

  1. Check GitHub Issues
  2. Provide minimal reproducible example
  3. Include versions: pip list | grep -E 'gp4c|numpy|scipy'
  4. Include platform: uname -a (Linux/macOS) or ver (Windows)

Next Steps