data

class laddu.data.BinnedDataset

A collection of Datasets binned by a Variable

BinnedDatasets can be indexed directly to access the underlying Datasets by bin

See also

laddu.Dataset.bin_by

edges

The edges of each bin in the BinnedDataset

n_bins

The number of bins in the BinnedDataset

range

The minimum and maximum values of the binning Variable used to create this BinnedDataset

class laddu.data.Dataset(events, *, p4_names=None, aux_names=None, aliases=None)

A set of Events

Datasets can be created from lists of Events or by using the constructor helpers such as laddu.io.read_parquet(), laddu.io.read_root(), and laddu.io.read_amptools()

Datasets can also be indexed directly to access individual Events

Parameters:

  • events (list of Event)

  • p4_names (list of str, optional) – Names assigned to each four-momentum; enables name-based lookups if provided.

  • aux_names (list of str, optional) – Names for auxiliary scalars stored alongside the events.

  • aliases (dict of {str: str or list[str]}, optional) – Additional particle identifiers that override aliases stored on the Events.

Notes

Explicit metadata provided here takes precedence over metadata embedded in the input Events.

Examples

>>> from laddu import Dataset, Event, Vec3
>>> event = Event(
...     [Vec3(0.0, 0.0, 1.0).with_mass(0.0), Vec3(0.0, 0.0, -1.0).with_mass(0.938)],
...     [0.4, 0.3],
...     1.0,
... )
>>> dataset = Dataset(
...     [event],
...     p4_names=['beam', 'proton'],
...     aux_names=['pol_magnitude', 'pol_angle'],
...     aliases={'target': 'proton'},
... )
>>> dataset[0].p4('target')
Vec4(px=0.0, py=0.0, pz=-1.0, e=1.371073...)
static empty_local(*, p4_names, aux_names=None, aliases=None)

Create an empty local Dataset with explicit metadata.

Parameters:

  • p4_names (list of str) – Names of the four-momenta expected in each pushed event.

  • aux_names (list of str, optional) – Names of auxiliary scalar columns expected in each pushed event.

  • aliases (dict of {str: str or list[str]}, optional) – Additional particle identifiers that reference one or more p4 names.

static from_events_global(events, *, p4_names=None, aux_names=None, aliases=None)

Create a global Dataset from a sequence of Events.

Under MPI, every rank must pass the same global event list. Rows are partitioned across ranks using laddu’s canonical contiguous partition.

static from_events_local(events, *, p4_names=None, aux_names=None, aliases=None)

Create a local Dataset from a sequence of Events.

add_aux_column_global(name, values)

Add an auxiliary scalar column collectively across all MPI ranks.

Under MPI, all ranks must call this method in the same order with the same column name. Each rank supplies values for its locally stored events.

add_aux_column_local(name, values)

Add an auxiliary scalar column to the local Dataset partition.

add_p4_column_global(name, values)

Add a four-momentum column collectively across all MPI ranks.

Under MPI, all ranks must call this method in the same order with the same column name. Each rank supplies values for its locally stored events.

add_p4_column_local(name, values)

Add a four-momentum column to the local Dataset partition.

aux_by_name(index, name)

Retrieve an auxiliary scalar by name for the event at index.

bin_by(variable, bins, range)

Separates a Dataset into histogram bins by a Variable value

Parameters:
Returns:

datasets – A structure containing Datasets binned by the given variable

Return type:

BinnedDataset

See also

laddu.Mass, laddu.CosTheta, laddu.Phi, laddu.PolAngle, laddu.PolMagnitude, laddu.Mandelstam

Examples

>>> from laddu.utils.variables import Mass
>>> binned = dataset.bin_by(Mass(['kshort1']), bins=10, range=(0.9, 1.5))
>>> len(binned)
10
Raises:

TypeError – If the given variable is not a valid variable

boost_to_rest_frame_of(names)

Boost all the four-momenta in all events to the rest frame of the given set of named four-momenta.

Parameters:

names (list of str) – The names of the four-momenta defining the rest frame

Returns:

The boosted dataset

Return type:

Dataset

Examples

>>> dataset.boost_to_rest_frame_of(['kshort1', 'kshort2'])
bootstrap(seed)

Generate a new bootstrapped Dataset by randomly resampling the original with replacement

The new Dataset is resampled with a random generator seeded by the provided seed

Parameters:

seed (int) – The random seed used in the resampling process

Returns:

A bootstrapped Dataset

Return type:

Dataset

Examples

>>> replica = dataset.bootstrap(2024)
>>> len(replica) == len(dataset)
True
evaluate(variable)

Get the value of a Variable over every event in the Dataset.

Parameters:

variable ({laddu.Mass, laddu.CosTheta, laddu.Phi, laddu.PolAngle, laddu.PolMagnitude, laddu.Mandelstam})

Returns:

values

Return type:

array_like

Examples

>>> from laddu.utils.variables import Mass
>>> masses = dataset.evaluate(Mass(['kshort1']))
>>> masses.shape
(len(dataset),)
event_global(index)

Alias for dataset[index].

Notes

This preserves the default global indexing semantics under MPI.

filter(expression)

Filter the Dataset by a given VariableExpression, selecting events for which the expression returns True.

Parameters:

expression (VariableExpression) – The expression with which to filter the Dataset

Returns:

The filtered Dataset

Return type:

Dataset

Examples

>>> from laddu.utils.variables import Mass
>>> heavy = dataset.filter(Mass(['kshort1']) > 1.0)
p4_by_name(index, name)

Retrieve a four-momentum by particle name for the event at index.

push_event_global(*, p4, aux=None, weight=1.0)

Append one named event collectively as a single global event.

Under MPI, all ranks must call this method in the same order. Exactly one rank stores each event, selected by round-robin global event index.

push_event_local(*, p4, aux=None, weight=1.0)

Append one named event to the local Dataset partition.

Parameters:

  • p4 (dict[str, Vec4]) – Four-momenta keyed by p4 name.

  • aux (dict[str, float], optional) – Auxiliary scalar values keyed by aux name.

  • weight (float, optional) – Event weight. Defaults to 1.0.

to_arrow(*, precision: Literal['f64', 'f32'] = 'f64') → Any
aux_names

Auxiliary scalar names associated with this Dataset.

events_global

Iterate over global Events in dataset order.

events_local

Iterate over Events stored on the current rank.

Notes

This is the explicit rank-local counterpart to events_global.

n_events

Get the number of Events in the Dataset

Notes

When MPI is enabled, this returns the global event count. It therefore matches len(dataset) and the valid range for dataset[i].

Returns:

n_events – The number of Events

Return type:

int

n_events_global

Alias for n_events.

n_events_local

Get the number of events owned by the current rank.

n_events_weighted

Get the weighted number of Events in the Dataset

Notes

When MPI is enabled, this returns the global weighted event count.

Returns:

n_events – The sum of all Event weights

Return type:

float

n_events_weighted_global

Alias for n_events_weighted.

n_events_weighted_local

Get the weighted number of local Events in the Dataset

Notes

When MPI is enabled, this returns the sum of the current rank’s Event weights.

Returns:

n_events – The sum of the current rank’s Event weights

Return type:

float

p4_names

Particle names used to construct four-momenta when loading from a Parquet file.

weights

The weights associated with the Dataset

Notes

When MPI is enabled, this returns the global weight vector in dataset order.

Returns:

weights – A numpy array of global Event weights

Return type:

array_like

weights_global

Alias for weights.

weights_local

The weights associated with the Dataset on the current rank.

Notes

This is the explicit rank-local counterpart to weights.

Returns:

weights – A numpy array of rank-local Event weights

Return type:

array_like

class laddu.data.Event(p4s, aux, weight, *, p4_names=None, aux_names=None, aliases=None)

A single event

Events are composed of a set of 4-momenta of particles in the overall center-of-momentum frame, optional auxiliary scalars (e.g. polarization magnitude or angle), and a weight.

Parameters:

  • p4s (list of Vec4) – 4-momenta of each particle in the event in the overall center-of-momentum frame

  • aux (list of float) – Scalar auxiliary data associated with the event

  • weight (float) – The weight associated with this event

  • p4_names (list of str, optional) – Human-readable aliases for each four-momentum. Providing names enables name-based lookups when evaluating variables.

  • aux_names (list of str, optional) – Aliases for auxiliary scalars corresponding to aux.

  • aliases (dict of {str: str or list[str]}, optional) – Additional particle identifiers that reference one or more entries from p4_names.

Examples

>>> from laddu import Event, Vec3
>>> event = Event(
...     [Vec3(0.0, 0.0, 1.0).with_mass(0.0), Vec3(0.0, 0.0, 1.0).with_mass(0.0)],
...     [],
...     1.0,
...     p4_names=['kshort1', 'kshort2'],
...     aliases={'pair': ['kshort1', 'kshort2']},
... )
>>> event.p4('pair')
Vec4(px=0.0, py=0.0, pz=2.0, e=2.0)
>>> event.aux['pol_angle']
0.3
boost_to_rest_frame_of(names)

Boost all the four-momenta in the event to the rest frame of the given set of four-momenta by indices.

Parameters:

names (list of str) – The names of the four-momenta whose rest frame should be used for the boost

Returns:

The boosted event

Return type:

Event

evaluate(variable)

Get the value of a Variable on the given Event

Parameters:

variable ({laddu.Mass, laddu.CosTheta, laddu.Phi, laddu.PolAngle, laddu.PolMagnitude, laddu.Mandelstam})

Return type:

float

Notes

Variables that rely on particle names require the event to carry metadata. Provide p4_names/aux_names when constructing the event or evaluate variables through a laddu.Dataset to ensure the metadata is available.

Examples

>>> from laddu import Event, Vec3
>>> from laddu.utils.variables import Mass
>>> event = Event(
...     [Vec3(0.0, 0.0, 1.0).with_mass(0.938)],
...     [],
...     1.0,
...     p4_names=['proton'],
... )
>>> event.evaluate(Mass(['proton']))
0.938
get_p4_sum(names)

Get the sum of the four-momenta within the event at the given indices

Parameters:

names (list of str) – The names of the four-momenta to sum

Returns:

The result of summing the given four-momenta

Return type:

Vec4

p4(name)

Retrieve a four-momentum by name.

aux

The auxiliary scalar values associated with the event

p4s

The list of 4-momenta for each particle in the event

weight

The weight of this event relative to others in a Dataset