distribution

Base classes for transformed distributions.

This module introduces the first architectural layer for derived probability distributions produced by transformations. The goal is to keep them fully compatible with the existing Distribution protocol and computation graph while still preserving transformation metadata.

class pysatl_core.transformations.distribution.ApproximatedDistribution(*, distribution_type, analytical_computations, support=None, sampling_strategy=None, computation_strategy=None)[source]

Bases: DerivedDistribution

Derived distribution whose analytical computations were materialized by an external approximator.

Parameters:

  • distribution_type (DistributionType) – Type descriptor of the approximated distribution.

  • analytical_computations (Mapping[) –

    GenericCharacteristicName, (

    AnalyticalComputation[Any, Any] | Mapping[LabelName, AnalyticalComputation[Any, Any]]

    ),

  • ] – Materialized methods produced by the approximator. They are exposed in analytical_computations for strategy resolution, but are never treated as fully analytical.

  • support (Support | None, optional) – Support of the approximated distribution.

  • sampling_strategy (SamplingStrategy | None, optional) – Sampling strategy to expose.

  • computation_strategy (ComputationStrategy | None, optional) – Characteristic resolution strategy.

__init__(*, distribution_type, analytical_computations, support=None, sampling_strategy=None, computation_strategy=None)[source]
Parameters:
Return type:

None

property parent_roles: tuple[ParentRole, ...]

Return empty parent roles for approximation-based derived distributions.

class pysatl_core.transformations.distribution.DerivedDistribution(*, distribution_type, bases, analytical_computations, transformation_name, support=None, sampling_strategy=None, computation_strategy=None, loop_analytical_flags=None)[source]

Bases: TransformationOperatorsMixin, Distribution

Base class for distributions obtained from one or more parents.

Parameters:

  • distribution_type (DistributionType) – Type descriptor of the derived distribution.

  • bases (Mapping[ParentRole, Distribution]) – Parent distributions participating in the transformation. Internally, they are stored as lightweight snapshots to avoid retaining full parent distribution objects.

  • analytical_computations (Mapping[) –

    GenericCharacteristicName, (

    AnalyticalComputation[Any, Any] | Mapping[LabelName, AnalyticalComputation[Any, Any]]

    ),

  • ] – Derived characteristic methods exposed by the transformation. Presence here means that at least one ancestor in the derivation chain is analytical.

  • transformation_name (TransformationName) – Logical name of the transformation.

  • support (Support | None, optional) – Support of the transformed distribution.

  • sampling_strategy (SamplingStrategy | None, optional) – Strategy used to generate random samples.

  • computation_strategy (ComputationStrategy | None, optional) – Strategy used to resolve characteristics.

  • loop_analytical_flags (Mapping[) – GenericCharacteristicName, Mapping[LabelName, bool],

  • None (] |) – Optional graph flags for loop analytical status. A loop has is_analytical=True only when all required ancestors of that characteristic are analytical.

  • optional – Optional graph flags for loop analytical status. A loop has is_analytical=True only when all required ancestors of that characteristic are analytical.

__init__(*, distribution_type, bases, analytical_computations, transformation_name, support=None, sampling_strategy=None, computation_strategy=None, loop_analytical_flags=None)[source]
Parameters:
Return type:

None

property bases: Mapping[ParentRole, pysatl_core.distributions.distribution.Distribution]

Get parent distributions grouped by their logical roles.

abstract property parent_roles: tuple[ParentRole, ...]

Get deterministic parent roles used by this transformed distribution.

property transformation_name: TransformationName

Get the logical name of the transformation.

loop_is_analytical(characteristic_name, label_name)[source]

Return transformation-aware analytical flag for a loop method.

The method returns True only when all required predecessors are analytical. A method can still be present in analytical_computations when this returns False.

Return type:

bool

Parameters:

  • characteristic_name (GenericCharacteristicName)

  • label_name (LabelName)

approximate(methods, **options)[source]

Approximate selected characteristics of the current derivation.

Parameters:

  • methods (Mapping[GenericCharacteristicName, CharacteristicApproximationMethod]) – Mapping from characteristic names to characteristic-level approximation methods.

  • **options (Any) – Extra options forwarded to each approximation method.

Returns:

Distribution with materialized approximations for selected characteristics.

Return type:

ApproximatedDistribution

class pysatl_core.transformations.distribution.LightweightDistribution(*, distribution_type, analytical_computations, support=None, sampling_strategy=None, computation_strategy=None, bases=None, loop_analytical_flags=None)[source]

Bases: Distribution

Lightweight Distribution implementation for transformation internals.

Parameters:

  • distribution_type (DistributionType) – Type descriptor of the distribution.

  • analytical_computations (Mapping[) –

    GenericCharacteristicName, (

    AnalyticalComputation[Any, Any] | Mapping[LabelName, AnalyticalComputation[Any, Any]]

    ),

  • ] – Labeled characteristic methods exposed by the snapshot.

  • support (Support | None, optional) – Support metadata copied from the source distribution.

  • sampling_strategy (SamplingStrategy | None, optional) – Sampling strategy attached to the snapshot.

  • computation_strategy (ComputationStrategy | None, optional) – Computation strategy attached to the snapshot.

  • bases (Mapping[ParentRole, LightweightDistribution] | None, optional) – Lightweight base snapshots for chained transformations.

  • loop_analytical_flags (Mapping[) – GenericCharacteristicName, Mapping[LabelName, bool],

  • None (] |) – Optional analytical flags for loop variants.

  • optional – Optional analytical flags for loop variants.

__init__(*, distribution_type, analytical_computations, support=None, sampling_strategy=None, computation_strategy=None, bases=None, loop_analytical_flags=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.

  • bases (Mapping[ParentRole, LightweightDistribution] | None)

  • loop_analytical_flags (Mapping[GenericCharacteristicName, Mapping[LabelName, bool]] | None)

Return type:

None

classmethod from_distribution(distribution)[source]

Build a lightweight snapshot from an arbitrary distribution.

The method copies only strategy-relevant fields and recursively snapshots known bases when the source distribution exposes them.

Parameters:

distribution (Distribution) – Source distribution.

Returns:

Lightweight snapshot compatible with Distribution.

Return type:

LightweightDistribution

property bases: Mapping[ParentRole, pysatl_core.distributions.distribution.Distribution]

Get lightweight base snapshots grouped by role.

loop_is_analytical(characteristic_name, label_name)[source]

Return preserved loop analytical flag for the snapshot.

Return type:

bool

Parameters:

  • characteristic_name (GenericCharacteristicName)

  • label_name (LabelName)