distribution

Distribution Interface

This module defines the public Distribution protocol that serves as the abstract interface for all probability distributions in the system.

class pysatl_core.distributions.distribution.Distribution(distribution_type, analytical_computations, support=None, sampling_strategy=None, computation_strategy=None)[source]

Bases: ABC

Protocol defining the interface for probability distributions.

This protocol is the central abstraction used throughout the system. Concrete distribution implementations must provide the properties and methods defined here.

Parameters:
distribution_type

Type information about the distribution (kind, dimension, etc.).

Type:

DistributionType

analytical_computations

Distribution-provided characteristic methods. For non-transformed distributions every method in this mapping is fully analytical, so this mapping matches the set of loops with is_analytical=True in the graph view.

Type:

Mapping

sampling_strategy

Strategy for generating random samples.

Type:

SamplingStrategy

computation_strategy

Strategy for computing characteristics and conversions.

Type:

ComputationStrategy

support

Support of the distribution, if defined.

Type:

Support or None

Notes

Array semantics for analytical characteristics

Analytical characteristic methods (e.g. pdf, cdf) should be implemented to accept and return NumPy arrays directly (array semantics). This is the recommended approach because it enables efficient vectorised evaluation.

If a method accepts only scalar inputs, the computation infrastructure will wrap it automatically via numpy.vectorize, but this incurs a per-element Python call overhead and is significantly slower for large inputs.

__init__(distribution_type, analytical_computations, support=None, sampling_strategy=None, computation_strategy=None)[source]

Initialize common distribution state.

Parameters:

  • distribution_type (DistributionType) – Type information about the distribution (kind, dimension, etc.).

  • analytical_computations (Mapping) –

    Distribution-provided characteristic methods. For non-transformed distributions these methods are fully analytical.

    Note

    Each characteristic callable should accept and return NumPy arrays (array semantics). Scalar-only callables are wrapped automatically via numpy.vectorize, but at a significant per-element overhead cost.

  • support (Support or None, default None) – Support of the distribution.

  • sampling_strategy (SamplingStrategy or None, default None) – Sampling strategy instance. If omitted, univariate default is used.

  • computation_strategy (ComputationStrategy or None, default None) – Computation strategy instance. If omitted, default strategy is used.

Return type:

None

property distribution_type: pysatl_core.types.DistributionType

Return type metadata of the distribution (kind, dimension, etc.).

property analytical_computations: Mapping[GenericCharacteristicName, Mapping[LabelName, AnalyticalComputation[Any, Any]]]

Return distribution-provided characteristic methods.

For non-transformed distributions this mapping coincides with graph loops marked as is_analytical=True.

loop_is_analytical(characteristic_name, label_name)[source]

Tell whether a self-loop method is fully analytical in the graph.

Parameters:

  • characteristic_name (GenericCharacteristicName) – Characteristic name of the self-loop.

  • label_name (LabelName) – Label of the analytical computation variant.

Returns:

True when every required predecessor in the transformation chain is analytical.

Return type:

bool

Notes

Presence in analytical_computations means that a characteristic has at least one analytical ancestor in its derivation chain. For non-transformed distributions these notions coincide, therefore this method always returns True.

property sampling_strategy: pysatl_core.distributions.strategies.SamplingStrategy

Return the currently attached sampling strategy.

property computation_strategy: pysatl_core.distributions.strategies.ComputationStrategy

Return the currently attached computation strategy.

property support: Support | None

Return the support of the distribution, if it is defined.

with_sampling_strategy(sampling_strategy)[source]

Return a copy of this distribution with an updated sampling strategy.

Return type:

Self

Parameters:

sampling_strategy (SamplingStrategy | None)

with_computation_strategy(computation_strategy)[source]

Return a copy of this distribution with an updated computation strategy.

Return type:

Self

Parameters:

computation_strategy (ComputationStrategy | None)

with_strategies(*, sampling_strategy=<object object>, computation_strategy=<object object>)[source]

Return a copy of this distribution with updated strategies.

Return type:

Self

Parameters:
query_method(characteristic_name, options=None, *, characteristic_options=None, computation_defaults=None)[source]

Query a computation method for a specific characteristic.

Parameters:

  • characteristic_name (str) – Name of the characteristic to compute (e.g., “pdf”, “cdf”).

  • options (StepOptions | None, default None) – Per-step options built via ComputationPlan.with_options(). When None, every edge uses its declared defaults.

  • characteristic_options (Mapping[str, Any] | None, default None) – Shared characteristic options broadcast to every step that declares a matching CharacteristicOption. These are intrinsic to the characteristic (e.g. eps, x0 for PPF) and affect the meaning of the result and the cache key.

  • computation_defaults (Mapping[str, Any] | None, default None) – Per-call computation option defaults. Override the strategy-level defaults and hardcoded descriptor defaults, but are overridden by per-step values in options. Do not affect the cache key.

Returns:

Callable method that computes the characteristic.

Return type:

Method

explain_computation_path(characteristic_name)[source]

Describe how the attached computation strategy will compute a characteristic.

Returns an ComputationPlan listing every step (loop or conversion edge) and the option descriptors that will be consulted at each step. The plan is also pinned by the strategy, so a subsequent query_method() / calculate_characteristic() call for the same characteristic_name follows exactly the same edges – which is useful for introspection and protects against non-deterministic strategy choices.

Parameters:

characteristic_name (str) – Name of the characteristic to introspect.

Returns:

The plan describing the resolution path.

Return type:

ComputationPlan

calculate_characteristic(characteristic_name, value, options=None, *, characteristic_options=None, computation_defaults=None)[source]

Calculate a characteristic at the given value.

Parameters:

  • characteristic_name (str) – Name of the characteristic to compute.

  • value (Any) – Point(s) at which to evaluate the characteristic.

  • options (StepOptions | None, default None) – Per-step options built via ComputationPlan.with_options().

  • characteristic_options (Mapping[str, Any] | None, default None) – Shared characteristic options broadcast to every step that declares a matching CharacteristicOption.

  • computation_defaults (Mapping[str, Any] | None, default None) – Per-call computation option defaults.

Returns:

Value of the characteristic at the given point(s).

Return type:

Any

sample(n, **options)[source]

Generate random samples from the distribution.

Parameters:

  • n (int) – Number of samples to generate.

  • **options (Any) – Additional sampling options forwarded to the underlying sampling strategy.

Returns:

NumPy array containing n generated samples. The exact array shape depends on the distribution and the sampling strategy.

Return type:

NumericArray