Troubleshooting Guide

This guide provides solutions to 15+ common problems encountered when fitting rheological models.

Fitting Problems

Problem: Optimization Does Not Converge

Symptoms: “Optimization did not converge” error, max iterations reached

Solutions:

  1. Increase max iterations: model.fit(x, y, max_iter=5000)

  2. Relax tolerances: model.fit(x, y, ftol=1e-6, xtol=1e-6)

  3. Use smart initialization (fractional models, oscillation mode)

  4. Try simpler model (Maxwell before FractionalMaxwellLiquid)

  5. Check data quality (remove outliers, smooth noise)

Problem: Unphysical Parameters

Symptoms: Negative moduli, tau < 10⁻⁹ s, alpha > 1

Solutions:

  1. Tighten parameter bounds: model.parameters.set_bounds('alpha', (0.1, 0.95))

  2. Enable compatibility checking: model.fit(x, y, check_compatibility=True)

  3. Verify correct test_mode: ‘oscillation’ not ‘relaxation’ for SAOS

  4. Try different model family

Problem: Poor Fit Quality (Error > 10%)

Symptoms: Systematic deviations, curvature mismatch

Solutions:

  1. Try more complex model (Classical → Fractional)

  2. Check if model is appropriate using compatibility checking

  3. Verify data preprocessing (units, scaling)

  4. Consider multi-mode model

Data Problems

Problem: File Not Loading

Solutions:

  1. Use auto_read(): data = auto_read('file.txt')

  2. Check file encoding (UTF-8 vs. Latin-1)

  3. Try specific reader: read_trios(), read_csv()

  4. Verify file path (absolute vs. relative)

Problem: Test Mode Not Detected

Solutions:

  1. Manually set: data.metadata['test_mode'] = 'relaxation'

  2. Check data characteristics (monotonic, domain)

  3. Verify column names match expected patterns

Model Selection Problems

Problem: Don’t Know Which Model to Use

Solutions:

  1. Use decision flowchart: Model Selection Guide

  2. Enable compatibility checking for suggestions

  3. Start with classical (Maxwell, Zener), upgrade if needed

  4. Check material classification: Material Classification

Problem: Model Compatibility Warning

Example: “FZSS expects power-law decay but detected exponential”

Solutions:

  1. Follow suggested alternatives in warning message

  2. Use compatibility checking before fitting

  3. Verify test mode is correct

Bayesian Inference Problems

Problem: Low ESS (Effective Sample Size < 400)

Solutions:

  1. Increase num_samples: fit_bayesian(num_samples=5000)

  2. Use NLSQ warm-start (done automatically)

  3. Check for multimodal posterior

  4. Increase num_warmup

Problem: High R-hat (> 1.1)

Solutions:

  1. Increase num_warmup: fit_bayesian(num_warmup=2000)

  2. Use warm-start from NLSQ fit

  3. Run multiple chains: num_chains=4

Quick Reference Flowchart

[Problem Category]
   │
   ├─→ Convergence failure
   │      └─→ Increase max_iter, relax tol, smart init
   │
   ├─→ Unphysical parameters
   │      └─→ Tighten bounds, compatibility check
   │
   ├─→ Poor fit (error > 10%)
   │      └─→ Try complex model, check compatibility
   │
   ├─→ File loading issues
   │      └─→ Use auto_read(), check encoding
   │
   └─→ Model selection
          └─→ Use flowchart, compatibility checking

Getting More Help

  1. Check Fitting Strategies and Troubleshooting for advanced techniques

  2. Review example notebooks in examples/

  3. Consult model-specific pages in Models Handbook

  4. Open GitHub issue with minimal reproducible example