options

Option descriptor abstractions.

Provides CharacteristicOption, ComputationOption, and EdgeOptionsDescriptor for declaring metadata about fitters and evaluators.

Option taxonomy

CharacteristicOption

Describes a parameter that is intrinsic to the characteristic itself (e.g. eps or x0 for PPF). These options are shared between the fitter (pre-computation / caching path) and the evaluator (direct-query path). Because they affect the meaning of the result they must be encoded into the cache key.

ComputationOption

Describes a parameter that controls the numerical algorithm used to compute the characteristic (e.g. max_iter, x_tol). These are specific to a particular fitter implementation and do not affect the evaluator.

Passing options — TypedDict + Unpack pattern

Concrete fitters and evaluators declare their accepted keyword arguments via TypedDict subclasses and annotate their signatures with **kwargs: Unpack[MyOptionsDict]. This gives static type-checkers full visibility while keeping the runtime interface simple **kwargs.

Example:

from typing import TypedDict
from typing_extensions import Unpack

class PpfCharacteristicOptions(TypedDict, total=False):
    eps: float
    x0: float

class PpfComputationOptions(TypedDict, total=False):
    max_iter: int
    x_tol: float

def fit_cdf_to_ppf(
    distribution: Distribution,
    /,
    **kwargs: Unpack[PpfComputationOptions],
) -> FittedComputationMethod: ...
class pysatl_core.distributions.computations.options.CharacteristicOption(name, type, default, description='', validate=None)[source]

Bases: _BaseOption

Option that is intrinsic to the characteristic being computed.

Characteristic options are shared between the fitter (pre-computation / caching path) and the evaluator (direct-query path). Because they affect the meaning of the result they must be encoded into the cache key.

Examples: eps (tail threshold for PPF), x0 (starting point for bound search), excess (excess kurtosis flag).

These options are declared in FitterDescriptor.characteristic_options and EvaluatorDescriptor.characteristic_options.

Parameters:

  • name (str)

  • type (type)

  • default (Any)

  • description (str)

  • validate (Callable[[Any], bool] | None)

__init__(name, type, default, description='', validate=None)
Parameters:
Return type:

None

class pysatl_core.distributions.computations.options.ComputationOption(name, type, default, description='', validate=None)[source]

Bases: _BaseOption

Option that controls the numerical algorithm used to compute a characteristic.

Computation options are specific to a particular fitter implementation and do not affect the evaluator. They influence only the speed / accuracy trade-off of the fitting step, not the semantics of the result.

Examples: max_iter (bisection iterations), x_tol (bracket tolerance), limit (quad subdivisions), n_q_grid (PPF grid size).

These options are declared in FitterDescriptor.computation_options.

Parameters:
__init__(name, type, default, description='', validate=None)
Parameters:
Return type:

None

class pysatl_core.distributions.computations.options.EdgeOptionsDescriptor(name='', characteristic_options=(), computation_options=())[source]

Bases: object

Compact, graph-level form of a computation descriptor.

A short descriptor carries only the metadata required by the strategy when resolving caller-supplied **options against a specific edge in the characteristic graph. It is the graph-level primitive: it is immutable, decoupled from the heavy fitter/evaluator callable, and cheap to attach to every ComputationEdgeMeta so the strategy can route options per-edge along a multi-hop conversion path.

Parameters:
name

Descriptor identifier (matches the originating FitterDescriptor / EvaluatorDescriptor name). Empty by default for edges that were declared without a descriptor.

Type:

str

characteristic_options

Options intrinsic to the characteristic.

Type:

tuple[CharacteristicOption, ]

computation_options

Options controlling the numerical algorithm.

Type:

tuple[ComputationOption, ]

name: str
characteristic_options: tuple[CharacteristicOption, ...]
computation_options: tuple[ComputationOption, ...]
property options: tuple[_BaseOption, ...]

All options (characteristic first, then computation).

resolve_characteristic_options(kwargs)[source]

Resolve only the characteristic options from kwargs.

Return type:

dict[str, Any]

Parameters:

kwargs (dict[str, Any])

resolve_computation_options(kwargs)[source]

Resolve only the computation options from kwargs.

Return type:

dict[str, Any]

Parameters:

kwargs (dict[str, Any])

resolve_options(kwargs)[source]

Resolve all declared options (characteristic + computation) from kwargs.

Consumes recognised keys from kwargs and returns a dict of {option_name: resolved_value}. Unrecognised keys are left in kwargs untouched.

Return type:

dict[str, Any]

Parameters:

kwargs (dict[str, Any])

with_values(**kwargs)[source]

Validate and resolve option values, returning a ResolvedEdgeOptions.

This is the recommended way to build per-step options for ComputationStrategy.query_method(). Values are validated eagerly (type-cast + predicate check) so errors surface immediately rather than deep inside the strategy.

Parameters:

**kwargs (Any) – Option values keyed by option name. Unrecognised keys are silently ignored (they are not consumed by this descriptor).

Returns:

Immutable container with the validated values.

Return type:

ResolvedEdgeOptions

Raises:

  • TypeError – If a value cannot be cast to the declared type.

  • ValueError – If a value fails the option’s validation predicate.

Example

plan = distr.explain_computation_path("ppf")
resolved = plan.steps[0].options_descriptor.with_values(tol=0.1)
__init__(name='', characteristic_options=(), computation_options=())
Parameters:
Return type:

None

class pysatl_core.distributions.computations.options.ResolvedEdgeOptions(descriptor, values)[source]

Bases: object

Immutable container holding validated option values for one edge.

Instances are created via EdgeOptionsDescriptor.with_values() and passed to the strategy inside a StepOptions mapping.

Parameters:
descriptor

The descriptor that produced these values (retained for introspection and cache-key generation).

Type:

EdgeOptionsDescriptor

values

Resolved {option_name: value} mapping.

Type:

dict[str, Any]

descriptor: EdgeOptionsDescriptor
values: dict[str, Any]
__init__(descriptor, values)
Parameters:
Return type:

None