7.2. Getting Help

If you can’t solve an issue, here’s how to get help.

7.2.1. Documentation Resources

  1. Tutorials (this guide): Step-by-step learning

  2. How-To Guides: How-To Guides - Task-oriented solutions

  3. Reference: Reference - API documentation

  4. Explanation: Concepts & Explanations - Concept deep-dives

7.2.2. GitHub Issues

For bugs or feature requests:

  1. Go to https://github.com/imewei/NLSQ/issues

  2. Search existing issues first

  3. Create a new issue with:

    • NLSQ version (nlsq.__version__)

    • Python version

    • Operating system

    • Minimal reproducible example

    • Error message (full traceback)

Good issue template:

**Environment:**
- NLSQ version: 0.7.0
- Python: 3.12.0
- OS: Ubuntu 22.04
- JAX backend: gpu

**Description:**
Fit fails with large dataset.

**Minimal example:**
```python
from nlsq import fit
import jax.numpy as jnp
import numpy as np


def model(x, a, b):
    return a * jnp.exp(-b * x)


x = np.linspace(0, 10, 1000000)
y = 2 * np.exp(-0.5 * x) + np.random.randn(len(x)) * 0.1

popt, pcov = fit(model, x, y, p0=[2, 0.5])
```

**Error:**
```
[Full traceback here]
```

**Expected behavior:**
Fit should complete successfully.

7.2.3. Creating Minimal Examples

A good minimal example:

  1. Runs standalone: No external data files

  2. Reproduces the issue: Shows the exact problem

  3. Is minimal: Removes unnecessary complexity

# Good minimal example
from nlsq import fit
import jax.numpy as jnp
import numpy as np


def model(x, a, b):
    return a * jnp.exp(-b * x)


np.random.seed(42)
x = np.linspace(0, 10, 100)
y = 2 * np.exp(-0.5 * x) + 0.1 * np.random.randn(len(x))

# This fails with [error message]
popt, pcov = fit(model, x, y, p0=[1, 1])

7.2.4. Debugging Tips

Print intermediate values:

# Check data
print(f"x: min={x.min()}, max={x.max()}, shape={x.shape}")
print(f"y: min={y.min()}, max={y.max()}, shape={y.shape}")
print(f"NaN in y: {np.isnan(y).sum()}")

# Check model
y_test = model(x, 2.0, 0.5)
print(f"Model output: {y_test[:5]}")

Enable debug logging:

import os

os.environ["NLSQ_DEBUG"] = "1"

from nlsq import fit

# ... will print debug information

Check JAX configuration:

import jax

print(f"JAX version: {jax.__version__}")
print(f"Devices: {jax.devices()}")
print(f"Backend: {jax.default_backend()}")

7.2.5. Version Information

Include this in bug reports:

import nlsq
import jax
import numpy as np
import scipy
import sys

print(f"NLSQ: {nlsq.__version__}")
print(f"JAX: {jax.__version__}")
print(f"NumPy: {np.__version__}")
print(f"SciPy: {scipy.__version__}")
print(f"Python: {sys.version}")
print(f"Platform: {sys.platform}")

7.2.6. Common Solutions Summary

Problem

Quick Fix

Fit doesn’t converge

Better p0, add bounds, use auto_global

Wrong results

Check model uses jnp, plot data

Memory error

Set memory_limit_gb, use streaming optimizer

Slow

Use GPU, loosen tolerances

Covariance inf

Check fit quality, widen bounds

7.2.7. Next Steps