Amplitude Core

Core expression types and parameter helpers. These are exposed from laddu.amplitudes in Python.

High-level amplitude construction helpers.

This module re-exports the Rust-backed amplitude building blocks as a cohesive Python API.

Examples

>>> from laddu.amplitudes import parameter, scalar
>>> scalar_amp = scalar.Scalar('mag', value=parameter('mag'))  # overall magnitude
>>> rho = scalar.ComplexScalar('rho', re=parameter('rho_re'), im=parameter('rho_im'))
>>> expr = scalar_amp * rho
>>> expr
×
├─ mag(id=0)
└─ rho(id=1)

Use laddu.amplitudes.resonance or the other submodules for concrete physics models.

class laddu.amplitudes.CompiledExpression

A class which can be used to display the compiled form of an Expression

Notes

This should not be used for anything other than diagnostic purposes.

class laddu.amplitudes.Evaluator

A class which can be used to evaluate a stored Expression

See also

laddu.Expression.load

activate(arg, *, strict=True)

Activates Amplitude use-sites in the Expression by tag or glob selector.

Parameters:

arg (str or list of str) – Tags or */? glob selectors of Amplitudes to be activated

Raises:

TypeError – If arg is not a str or list of str
ValueError – If arg or any items of arg match no tagged Amplitudes

:raises strict : bool, default=True: When True, raise an error if any selector matches no amplitudes. When False, silently skip selectors with no matches.

activate_all(): Activates all Amplitude use-sites in the Expression.

deactivate(arg, *, strict=True)

Deactivates Amplitude use-sites in the Expression by tag or glob selector.

Deactivated Amplitudes act as zeros in the Expression

Parameters:

arg (str or list of str) – Tags or */? glob selectors of Amplitudes to be deactivated

Raises:

TypeError – If arg is not a str or list of str
ValueError – If arg or any items of arg match no tagged Amplitudes

:raises strict : bool, default=True: When True, raise an error if any selector matches no amplitudes. When False, silently skip selectors with no matches.

deactivate_all(): Deactivates all tagged Amplitude use-sites in the Expression.

evaluate(parameters, *, threads=None)

Evaluate the stored Expression over the stored Dataset

Parameters:

parameters (list of float) – The values to use for the free parameters
threads (int, optional) – The number of threads to use (setting this to None or 0 uses the current global or context-managed default; any positive value overrides that default for this call only)

Returns:

result – A numpy array of complex values for each Event in the Dataset

Return type:

array_like

Raises:

Exception – If there was an error building the thread pool

evaluate_batch(parameters, indices, *, threads=None)

Evaluate the stored Expression over a subset of the stored Dataset

Parameters:

parameters (list of float) – The values to use for the free parameters
indices (list of int) – The indices of events to evaluate
threads (int, optional) – The number of threads to use (setting this to None or 0 uses the current global or context-managed default; any positive value overrides that default for this call only)

Returns:

result – A numpy array of complex values for each indexed Event in the Dataset

Return type:

array_like

Raises:

Exception – If there was an error building the thread pool

evaluate_gradient(parameters, *, threads=None)

Evaluate the gradient of the stored Expression over the stored Dataset

Parameters:

parameters (list of float) – The values to use for the free parameters
threads (int, optional) – The number of threads to use (setting this to None or 0 uses the current global or context-managed default; any positive value overrides that default for this call only)

Returns:

result – A numpy 2D array of complex values for each Event in the Dataset

Return type:

array_like

Raises:

Exception – If there was an error building the thread pool or problem creating the resulting numpy array

evaluate_gradient_batch(parameters, indices, *, threads=None)

Evaluate the gradient of the stored Expression over a subset of the stored Dataset

Parameters:

parameters (list of float) – The values to use for the free parameters
indices (list of int) – The indices of events to evaluate
threads (int, optional) – The number of threads to use (setting this to None or 0 uses the current global or context-managed default; any positive value overrides that default for this call only)

Returns:

result – A numpy 2D array of complex values for each indexed Event in the Dataset

Return type:

array_like

Raises:

Exception – If there was an error building the thread pool or problem creating the resulting numpy array

fix_parameter(name, value): Fix a parameter used by this Evaluator.

free_parameter(name): Mark a parameter used by this Evaluator as free.

isolate(arg, *, strict=True)

Isolates Amplitude use-sites in the Expression by tag or glob selector.

Activates the tagged Amplitudes given in arg and deactivates the rest.

Parameters:

arg (str or list of str) – Tags or */? glob selectors of Amplitudes to be isolated

Raises:

TypeError – If arg is not a str or list of str
ValueError – If arg or any items of arg match no tagged Amplitudes

:raises strict : bool, default=True: When True, raise an error if any selector matches no amplitudes. When False, silently skip selectors with no matches.

rename_parameter(old, new): Rename a single parameter used by this Evaluator.

rename_parameters(mapping): Rename several parameters used by this Evaluator.

set_active_mask(mask): Apply an active-amplitude mask.

active_mask: Return the current active-amplitude mask.

compiled_expression: Return a tree-like diagnostic view of the compiled Expression.

expression: Return the Expression represented by this Evaluator.

n_fixed: Number of fixed parameters

n_free: Number of free parameters

n_parameters: Total number of parameters

parameters

The free parameters used by the Evaluator

Returns:: parameters – The parameter map.
Return type:: ParameterMap

class laddu.amplitudes.Expression

A mathematical expression formed from amplitudes.

cis(): The complex phase factor exp(i * expression)

conj(): The complex conjugate of a complex Expression

cos(): The cosine of an Expression

exp(): The exponential of an Expression

fix_parameter(name, value): Fix a parameter used by this Expression.

free_parameter(name): Mark a parameter used by this Expression as free.

imag(): The imaginary part of a complex Expression

load(dataset)

Load an Expression by precalculating each term over the given Dataset

Parameters:: dataset (Dataset) – The Dataset to use in precalculation
Returns:: An object that can be used to evaluate the expression over each event in the dataset
Return type:: Evaluator

log(): The natural logarithm of an Expression

norm_sqr(): The norm-squared of a complex Expression

power(power): Raise an Expression to an int, float, or Expression power

real(): The real part of a complex Expression

rename_parameter(old, new): Rename a single parameter used by this Expression.

rename_parameters(mapping): Rename several parameters used by this Expression.

sin(): The sine of an Expression

sqrt(): The square root of an Expression

compiled_expression: Return a tree-like diagnostic view of the compiled Expression.

n_fixed: Number of fixed parameters

n_free: Number of free parameters

n_parameters: Total number of parameters

parameters

The parameters used by the Expression.

Returns:: parameters – The parameter map.
Return type:: ParameterMap

class laddu.amplitudes.Parameter

bounds

description

fixed

initial

latex

name

unit

laddu.amplitudes.One(): A convenience class representing a unit-valued Expression

laddu.amplitudes.TestAmplitude(*tags, re, im): An amplitude used only for internal testing which evaluates (p0 + i * p1) * event.p4s[0].e.

laddu.amplitudes.Zero(): A convenience class representing a zero-valued Expression

laddu.amplitudes.expr_product(terms): A convenience method to multiply sequences of Expressions

laddu.amplitudes.expr_sum(terms): A convenience method to sum sequences of Expressions

laddu.amplitudes.parameter(name, fixed=None, *, initial=None, bounds=Ellipsis, unit=None, latex=None, description=None)

A free parameter which floats during an optimization

Parameters:

name (str) – The name of the free parameter
fixed (float, optional) – If specified, the parameter will be fixed to this value
initial (float, optional) – If specified, the parameter will always be initialized to this value
bounds (tuple of (float or None, float or None)) – Specify the lower and upper bounds for the parameter (None corresponds to no bound)
unit (str, optional) – Optional unit string which may be used to annotate the parameter
latex (str, optional) – Optional LaTeX representation of the parameter
description (str, optional) – Optional description of the parameter

Returns:

An object that can be used as the input for many Amplitude constructors

Return type:

laddu.Parameter

Notes

Two free parameters with the same name are shared in a fit.

Attempting to set both the fixed and initial value will result in an overwrite (both will be set to the “fixed” value).