root_mcp.extended.analysis.fitting module

Histogram fitting engine for ROOT-MCP extended mode.

Provides least-squares curve fitting via scipy.optimize.curve_fit for a registry of physics-motivated models:

  • Gaussian — symmetric peaks (resonances, detector resolutions)

  • Exponential — falling backgrounds

  • Polynomial (linear, quadratic, cubic) — smooth backgrounds

  • Crystal Ball — asymmetric peaks with a power-law tail (common in HEP)

  • Double Gaussian — overlapping resonances

  • Voigt — convolution of Gaussian detector resolution and Lorentzian natural width

  • Breit-Wigner — resonance line shape

The public entry point is HistogramFitter.

class root_mcp.extended.analysis.fitting.CompositeModel(components)[source]

Bases: object

Represents a sum of multiple models.

Parameters:

components (list[str | dict[str, Any]])

__init__(components)[source]
Parameters:

components (list[str | dict[str, Any]])

class root_mcp.extended.analysis.fitting.CustomModel(expr, params)[source]

Bases: object

Model defined by a string expression.

Parameters:
__init__(expr, params)[source]

Initialize custom model.

Parameters:

  • expr (str) – Mathematical expression string

  • params (list[str]) – List of parameter names in order

class root_mcp.extended.analysis.fitting.ModelInfo[source]

Bases: TypedDict

Type definition for model registry entries.

func: Callable[[...], ndarray]
n_params: int
param_names: list[str]
root_mcp.extended.analysis.fitting.crystal_ball(x, amp, mu, sigma, alpha, n)[source]

Crystal Ball function.

Parameters:
Return type:

ndarray

root_mcp.extended.analysis.fitting.exponential(x, amp, decay)[source]

Exponential function.

Parameters:
Return type:

ndarray

root_mcp.extended.analysis.fitting.fit_histogram(data, model, initial_guess=None, bounds=None, fixed_parameters=None)[source]

Fit a model to histogram data.

Parameters:

  • data (dict[str, Any]) – Histogram data dictionary

  • model (str | list[str | dict[str, Any]] | dict[str, Any]) – Model definition. Can be: - str: Name of built-in model (e.g., “gaussian”) - list[str]: List of built-in models (e.g., [“gaussian”, “exponential”]) - list[dict]: List of models with config (e.g., [{"name": "gaussian", "prefix": "s_"}]) - dict: Custom model definition (e.g. {“expr”: “A*x + B”, “params”: [“A”, “B”]})

  • initial_guess (list[float] | None) – Initial parameter values

  • bounds (list[list[float]] | None) – List of [min, max] pairs for each parameter. Use [-np.inf, np.inf] for no bound.

  • fixed_parameters (dict[str | int, float] | None) – Dictionary of parameters to fix. Keys can be index (int) or name (str).

Returns:

Dictionary with fitted parameters, errors, and stats

Return type:

dict[str, Any]

root_mcp.extended.analysis.fitting.fit_histogram_2d(x, y, z, z_errors=None, model='gaussian_2d', initial_params=None, fixed_params=None, bounds=None)[source]

Fit a 2D histogram with a model function.

Parameters:

  • x (ndarray) – X-coordinate array (flattened)

  • y (ndarray) – Y-coordinate array (flattened)

  • z (ndarray) – Z-values (bin contents, flattened)

  • z_errors (ndarray | None) – Errors on z-values

  • model (str) – Model name from MODEL_REGISTRY_2D

  • initial_params (list[float] | None) – Initial parameter guesses

  • fixed_params (dict[str, float] | None) – Dictionary of {param_name: value} for fixed parameters

  • bounds (tuple[list[float], list[float]] | None) – Tuple of (lower_bounds, upper_bounds)

Returns:

Dictionary with fit results

Return type:

dict[str, Any]

root_mcp.extended.analysis.fitting.gaussian(x, amp, mu, sigma)[source]

Gaussian function.

Parameters:
Return type:

ndarray

root_mcp.extended.analysis.fitting.gaussian_2d(xy, amp, mu_x, mu_y, sigma_x, sigma_y, rho=0.0)[source]

2D Gaussian function with correlation.

Parameters:

  • xy (tuple[ndarray, ndarray]) – Tuple of (x, y) coordinate arrays

  • amp (float) – Amplitude

  • mu_x (float) – Mean in x

  • mu_y (float) – Mean in y

  • sigma_x (float) – Standard deviation in x

  • sigma_y (float) – Standard deviation in y

  • rho (float) – Correlation coefficient (-1 to 1)

Returns:

Function values at (x, y) points

Return type:

ndarray

root_mcp.extended.analysis.fitting.polynomial(x, *coeffs)[source]

Polynomial function.

Parameters:
Return type:

ndarray

root_mcp.extended.analysis.fitting.polynomial_2d(xy, *coeffs)[source]

2D polynomial function.

Parameters:

  • xy (tuple[ndarray, ndarray]) – Tuple of (x, y) coordinate arrays

  • coeffs (float) – Polynomial coefficients [c00, c10, c01, c20, c11, c02, …]

Returns:

Function values at (x, y) points

Return type:

ndarray