pyhs3.functions.InterpolationFunction¶

class pyhs3.functions.InterpolationFunction(*, name, high, low, nom, interpolationCodes, positiveDefinite, parameters)[source]¶

Piecewise interpolation function implementation.

Implements ROOT’s PiecewiseInterpolation logic to morph between nominal and variation distributions based on nuisance parameter values. Supports multiple interpolation codes (0-6) for different mathematical approaches.

Mathematical Formulations:

For additive interpolation modes (codes 0, 2, 3, 4):

\[\text{result} = \text{nominal} + \sum_i I_i(\theta_i; \text{low}_i, \text{nominal}, \text{high}_i)\]

For multiplicative interpolation modes (codes 1, 5, 6):

\[\text{result} = \text{nominal} \times \prod_i [1 + I_i(\theta_i; \text{low}_i/\text{nominal}, 1, \text{high}_i/\text{nominal})]\]

Interpolation Code Definitions:

Code 0 - Linear Interpolation/Extrapolation (Additive):

\[\begin{split}I_0(\theta) = \begin{cases} \theta(\text{high} - \text{nom}) & \text{if } \theta \geq 0 \\ \theta(\text{nom} - \text{low}) & \text{if } \theta < 0 \end{cases}\end{split}\]

Code 1 - Exponential Interpolation/Extrapolation (Multiplicative):

\[\begin{split}I_1(\theta) = \begin{cases} \left(\frac{\text{high}}{\text{nom}}\right)^{\theta} - 1 & \text{if } \theta \geq 0 \\ \left(\frac{\text{low}}{\text{nom}}\right)^{-\theta} - 1 & \text{if } \theta < 0 \end{cases}\end{split}\]

Code 2 - Exponential Interpolation + Linear Extrapolation (Additive): Uses \(\exp(\theta)\) behavior for \(|\theta| \leq 1\), linear extrapolation for \(|\theta| > 1\) with smooth transition at \(\theta = \pm 1\).

Code 3 - Exponential Interpolation + Different Linear Extrapolation (Additive): Uses \(\exp(\theta)\) behavior for \(|\theta| \leq 1\), different linear extrapolation for \(|\theta| > 1\) compared to code 2.

Code 4 - 6th Order Polynomial Interpolation + Linear Extrapolation (Additive):

\[\begin{split}I_4(\theta) = \begin{cases} \text{linear extrapolation} & \text{if } |\theta| \geq 1 \\ \theta \times (1 + \theta^2(-3 + \theta^2)/16) \times (\text{high} - \text{nom}) & \text{if } \theta \geq 0, |\theta| < 1 \end{cases}\end{split}\]

Code 5 - 6th Order Polynomial Interpolation + Exponential Extrapolation (Multiplicative): Uses exponential extrapolation for \(|\theta| \geq 1\), 6th order polynomial for \(|\theta| < 1\). Recommended for normalization factors.

Parameters:

name (str) – Name of the function
high (list[str]) – High variation parameter names
low (list[str]) – Low variation parameter names
nom (str) – Nominal parameter name
interpolationCodes (list[int]) – Interpolation method codes (0-6)
positiveDefinite (bool) – Whether function should be positive definite
parameters (list[str]) – Variable names this function depends on (nuisance parameters)

Note

At \(\theta_i = 0\), all codes return the nominal value
At \(\theta_i = \pm 1\), variations should match high/low values for appropriate codes
Polynomial codes (4,5,6) provide smoother interpolation with matching derivatives
Based on A.Bukin, Budker INP, Novosibirsk and ROOT’s RooFit implementation

__init__(*, name, high, low, nom, interpolationCodes, positiveDefinite, parameters)[source]¶

Initialize an InterpolationFunction.

Parameters:

name (str) – Name of the function
high (list[str]) – High variation parameter names
low (list[str]) – Low variation parameter names
nom (str) – Nominal parameter name
interpolationCodes (list[int]) – Interpolation method codes (0-6)
positiveDefinite (bool) – Whether function should be positive definite
parameters (list[str]) – Variable names this function depends on (nuisance parameters)

Raises:

UnknownInterpolationCodeError – If any interpolation code is not in range 0-6

Methods

`__init__`(*, name, high, low, nom, ...)	Initialize an InterpolationFunction.
`expression`(context)	Evaluate the interpolation function.
`from_dict`(config)	Create an InterpolationFunction from dictionary configuration.