pyFitting

pyFitting is a modular curve-fitting framework for scientific Python workflows. It provides a clean pipeline around:

• data containers and masking
• reusable model classes
• interchangeable loss functions
• local/global optimizers
• fit-quality metrics and result export

The package is built around composable interfaces so you can start with built-ins and add your own models/losses/optimizers when needed.

Installation

# from this repository
pip install -e .

# with developer dependencies (tests + plotting)
pip install -e .[dev]

Quick Start

import numpy as np
from pyFitting import Fitter, ArrayData, GaussianModel

# synthetic data
rng = np.random.default_rng(0)
x = np.linspace(0.0, 10.0, 120)
y = 2.5 * np.exp(-0.5 * ((x - 5.0) / 1.2) ** 2) + 0.3
y += rng.normal(0.0, 0.05, size=x.shape)

# fit
data = ArrayData(x, y)
result = Fitter(data, GaussianModel()).fit()

print(result.success)
print(result.parameters.values)
print(result.metrics["r2"])

Core Workflow

1. Wrap data in ArrayData
2. Pick a model (GaussianModel, ExponentialModel, custom BaseModel subclass)
3. Optional: configure loss and optimizer
4. Fit with Fitter(...).fit()
5. Inspect FitResult metrics/parameters/residuals

Built-in Components

Data

• ArrayData
• DataSmoother, quick_smooth (in pyFitting.data)

Models

• GaussianModel
• ExponentialModel
• LinearModel
• PowerLawModel
• PolynomialModel

Losses

• MSELoss
• Chi2Loss
• CorrelationLoss
• HybridLoss
• OverlapLoss

Optimizers

• LocalOptimizer methods: SLSQP, L-BFGS-B, TNC, trust-constr, Powell, Nelder-Mead, COBYLA
• GlobalOptimizer
• HybridOptimizer
• MultiStartOptimizer

Evaluation

• StandardEvaluator with common metrics (r2, r2_log, chi2_reduced, rmse, mae, correlations, overlap, etc.)

Common Patterns

Parameter Bounds

model = GaussianModel()
model.set_bounds(A=(0.0, 10.0), mu=(0.0, 10.0), sigma=(0.1, 3.0), c=(-1.0, 1.0))
result = Fitter(data, model).fit()

Fixed Parameters

model = GaussianModel()
model.fix_parameter("mu", value=5.0)
result = Fitter(data, model).fit()  # fits A, sigma, c only

Weighted Fitting

weights = np.ones_like(x)
weights[(x > 4.0) & (x < 6.0)] = 5.0
data_weighted = ArrayData(x, y, weights=weights)
result = Fitter(data_weighted, GaussianModel()).fit()

Custom Loss + Optimizer

from pyFitting import CorrelationLoss, LocalOptimizer

loss = CorrelationLoss(use_log=True)
optimizer = LocalOptimizer("trust-constr")
result = Fitter(data, GaussianModel(), loss=loss, optimizer=optimizer).fit()

Result Object (FitResult)

FitResult stores:

• parameters (values, bounds, fixed/free flags)
• metrics
• y_fit
• optimizer metadata (success, message, nfev, nit)

Useful helpers:

result.summary()
residuals = result.get_residuals()
relative_residuals = result.get_relative_residuals_percent()
result_dict = result.to_dict()
result_df = result.to_dataframe()

Visualization

Visualization is optional (matplotlib).

from pyFitting import plot_fit, plot_fit_with_residuals

plot_fit(result)
plot_fit_with_residuals(result)

Running Examples

python examples/simple_examples.py
python examples/advance_examples.py

Running Tests

pytest -q

See docs/TESTING.md for test coverage details.

Documentation Index

• Quick_Guide.md: practical quickstart
• docs/API_REFERENCE.md: API by component
• docs/TESTING.md: test strategy and coverage
• TUTORIAL.md: extended walkthrough and examples

Project Layout

pyFitting/
  core/          # interfaces, types, result container
  data/          # ArrayData + smoothing utilities
  models/        # built-in models + BaseModel
  loss/          # objective/loss functions
  optimizers/    # local/global/hybrid optimization
  evaluation/    # fit metrics
  workflow/      # Fitter orchestration
  visualization/ # optional plotting helpers
examples/
  simple_examples.py
  advance_examples.py
tests/
  pytest suite