Public API reference

Only the symbols documented here are supported as v0.1 public API.

Constructors and transforms

stoch_ir.constant(value, *, plates=(), dtype=None)

Create an immutable concrete expression.

Parameters:

  • value (bool | float | generic | ndarray) – Boolean, integer, floating scalar, NumPy scalar, or NumPy array.

  • plates (Iterable[str]) – Named axes for non-scalar values in input array-axis order. The number of plates must equal the array rank. A bare string denotes one plate.

  • dtype (DataType | None) – Optional canonical dtype. When omitted, it is inferred from value.

Returns:

A deterministic expression containing a read-only NumPy value.

Return type:

RandomVariable

stoch_ir.Normal(mu, sigma, *, plates=None, rng_label=None)

Create a univariate normal random variable.

Parameters:

  • mu (RandomVariable | bool | float) – Symbolic or scalar location.

  • sigma (RandomVariable | bool | float) – Symbolic or scalar strictly positive scale.

  • plates (Iterable[str] | None) – Complete output plate layout. When omitted, the union of parameter plates is used.

  • rng_label (str | None) – Optional semantic label mixed into graph-derived node entropy.

Returns:

A symbolic normal draw with the resolved complete output plates.

Return type:

RandomVariable

stoch_ir.Uniform(low=0.0, high=1.0, *, plates=None, rng_label=None)

Create an elementwise continuous uniform random variable.

Parameters:

  • low (RandomVariable | bool | float) – Symbolic or scalar lower bound.

  • high (RandomVariable | bool | float) – Symbolic or scalar upper bound. It must be strictly greater than low. Literal bounds are checked during construction; symbolic bounds are checked exactly before sampling.

  • plates (Iterable[str] | None) – Complete output plate layout. When omitted, the union of parameter plates is used.

  • rng_label (str | None) – Optional semantic label mixed into graph-derived node entropy.

Returns:

A symbolic uniform draw with the resolved complete output plates.

Return type:

RandomVariable

stoch_ir.Bernoulli(p, *, plates=None, rng_label=None)

Create an elementwise Bernoulli random variable.

Parameters:

  • p (RandomVariable | bool | float) – Symbolic or scalar success probability in the closed interval [0, 1].

  • plates (Iterable[str] | None) – Complete output plate layout. When omitted, the parameter plates are used.

  • rng_label (str | None) – Optional semantic label mixed into graph-derived node entropy.

Returns:

A symbolic Boolean draw with the resolved complete output plates.

Return type:

RandomVariable

stoch_ir.exp(expr)

Apply the elementwise exponential transform.

Parameters:

expr (RandomVariable | bool | float)

Return type:

RandomVariable

stoch_ir.log(expr)

Apply the elementwise natural logarithm transform.

Parameters:

expr (RandomVariable | bool | float)

Return type:

RandomVariable

stoch_ir.softplus(expr)

Apply the elementwise softplus transform.

Parameters:

expr (RandomVariable | bool | float)

Return type:

RandomVariable

stoch_ir.sampling_phase(phase)

Assign a sampling phase to distributions created in the context.

Parameters:

phase (str) – Non-empty phase name. Phase names are unordered; graph dependencies determine when enabled distributions become ready.

Yields:

None – Control to the distribution-authoring block.

Return type:

Iterator[None]

Expressions and values

class stoch_ir.RandomVariable

Immutable symbolic random-variable expression.

Random variables form a directed acyclic graph. Deterministic operations return new expressions, while distributions remain symbolic until materialize() or realize() is called.

Notes

This class is a public inspection and authoring type, not a supported v0.1 subclassing interface.

property dependencies: Mapping[str, RandomVariable]

Return an immutable, name-sorted mapping of direct dependencies.

property plates: tuple[str, ...]

Return named plates in canonical lexicographic order.

property pending_phases: frozenset[str]

Return named sampling phases still present in this graph.

property has_value: bool

Whether the graph is deterministic and directly realizable.

property value_meta: ValueMeta

Return the expression’s inferred dtype and support metadata.

add_plates(*plates, expect=None)

Broadcast the existing value over new named plates.

Parameters:

  • *plates (str) – New plate names. Every name must be unique and absent from the expression.

  • expect (Iterable[str] | None) – Optional exact precondition for the expression’s existing plates.

Returns:

A new expression with the requested plates.

Return type:

RandomVariable

check_plates(*plates)

Validate the complete current plate set and return this expression.

Parameters:

plates (str)

Return type:

RandomVariable

reduce_plates(*plates, reduction)

Reduce named plates with a canonical reduction object.

Parameters:
Return type:

RandomVariable

mean(*plates)

Return the arithmetic mean over named plates.

Parameters:

plates (str)

Return type:

RandomVariable

sum(*plates)

Return the sum over named plates.

Parameters:

plates (str)

Return type:

RandomVariable

max(*plates)

Return the maximum over named plates.

Parameters:

plates (str)

Return type:

RandomVariable

min(*plates)

Return the minimum over named plates.

Parameters:

plates (str)

Return type:

RandomVariable

prod(*plates)

Return the product over named plates.

Parameters:

plates (str)

Return type:

RandomVariable

logsumexp(*plates)

Return a stable log-sum-exp over named plates.

Parameters:

plates (str)

Return type:

RandomVariable

exp()

Apply the elementwise exponential transform.

Return type:

RandomVariable

log()

Apply the elementwise natural logarithm transform.

Return type:

RandomVariable

softplus()

Apply the elementwise softplus transform.

Return type:

RandomVariable

abs()

Apply the elementwise absolute-value transform.

Return type:

RandomVariable

materialize(*, seed=None, plate_sizes=None, phases=None)

Partially materialize selected phases into an immutable checkpoint.

Parameters:

  • seed (int | None) – Run seed mixed with each graph-derived stochastic node entropy. None selects a fresh run seed.

  • plate_sizes (Mapping[str, int] | None) – Positive concrete sizes for every named plate in the graph.

  • phases (Iterable[str] | None) – Phases to enable. None enables all remaining phases.

Return type:

SamplingCheckpoint

realize(*, seed=None, plate_sizes=None)

Fully materialize the graph and return its concrete value.

Parameters:

  • seed (int | None)

  • plate_sizes (Mapping[str, int] | None)

Return type:

ConcreteValue

structurally_equal(other)

Compare exact computation structure with memoized DAG traversal.

Parameters:

other (RandomVariable)

Return type:

bool

class stoch_ir.SamplingCheckpoint(_root, _plate_sizes)

Opaque, immutable partially materialized stochastic graph.

Checkpoints fix graph-derived node entropy, resolved plate sizes, and any values sampled so far. They cannot participate in new expressions; call materialize(), realize(), or value() to continue.

Parameters:
property pending_phases: frozenset[str]

Return named sampling phases still present in the checkpoint.

property is_fully_materialized: bool

Whether the checkpoint has collapsed to one concrete constant.

structurally_equal(other)

Compare rewritten computation structure, ignoring resolved RNG data.

Parameters:

other (SamplingCheckpoint)

Return type:

bool

stochastically_equal(other)

Compare structure, stochastic sharing, and resolved RNG state.

Parameters:

other (SamplingCheckpoint)

Return type:

bool

materialize(*, seed=None, plate_sizes=None, phases=None)

Enable selected phases and return a new immutable checkpoint.

Parameters:

  • seed (int | None)

  • plate_sizes (Mapping[str, int] | None)

  • phases (Iterable[str] | None)

Return type:

SamplingCheckpoint

value()

Return concrete data or raise if stochastic nodes remain.

Return type:

ConcreteValue

realize(*, seed=None, plate_sizes=None)

Materialize every remaining phase and return concrete data.

Parameters:

  • seed (int | None)

  • plate_sizes (Mapping[str, int] | None)

Return type:

ConcreteValue

class stoch_ir.ConcreteValue(data, layout, meta)

Immutable NumPy value returned by realization.

Concrete storage is read-only and uses the canonical NumPy dtype declared by meta. Named plates follow the same lexicographic order as the corresponding array axes.

Notes

Construct concrete values through stoch_ir.constant() or expression realization rather than instantiating this class directly.

Parameters:

  • data (ndarray)

  • layout (PlateLayout)

  • meta (ValueMeta)

property shape: tuple[int, ...]

Return the concrete NumPy shape.

property plates: tuple[str, ...]

Return plate names in the canonical axis order.

property dtype: DataType

Return the canonical dtype metadata.

property support: ValueSupport

Return the conservative support metadata.

class stoch_ir.DataType(*values)

Canonical concrete dtype families supported by v0.1.

property numpy_dtype: dtype[Any]

Return the canonical NumPy dtype for this metadata member.

classmethod infer(value)

Infer a supported dtype family from concrete data.

Parameters:

value (bool | int | float | generic | ndarray)

Return type:

DataType

coerce(value)

Coerce concrete data into this dtype’s canonical NumPy storage.

Parameters:

value (bool | int | float | generic | ndarray)

Return type:

ndarray

class stoch_ir.ValueSupport(*values)

Conservative support metadata propagated through expressions.

contains(value)

Return whether every value satisfies this support.

Parameters:

value (ndarray)

Return type:

bool

class stoch_ir.ValueMeta(dtype, support)

Canonical dtype and conservative support for an expression value.

Parameters:

Reductions

Canonical reduction objects for named plate reductions.

Use these immutable singletons with stoch_ir.RandomVariable.reduce_plates(). Caller-defined reductions are not a supported v0.1 extension point.

class stoch_ir.reductions.Reduction

Opaque reduction type used by the public singleton objects.

Errors

Public exception hierarchy for Stochastic Program IR.

exception stoch_ir.errors.DuplicatePlateError

Raised when the same plate is introduced more than once.

exception stoch_ir.errors.GraphCycleError

Raised when a cycle is found in an expression graph.

exception stoch_ir.errors.GraphValidationError

Raised when an expression graph violates a structural invariant.

exception stoch_ir.errors.InvalidSupportError

Raised when an operation or distribution receives invalid support.

exception stoch_ir.errors.MaterializationError

Base class for staged materialization and realization failures.

exception stoch_ir.errors.MissingPlateSizeError

Raised when materialization needs a plate size that was not supplied.

exception stoch_ir.errors.PhaseError

Raised when a sampling phase name or selection is invalid.

exception stoch_ir.errors.PlateError

Base class for named-plate validation errors.

exception stoch_ir.errors.PlateExpectationError

Raised when an expression does not have the expected plates.

exception stoch_ir.errors.PlateSizeMismatchError

Raised when materialization conflicts with a resolved plate size.

exception stoch_ir.errors.PossibleInvalidSupportWarning

Warns when metadata cannot prove that a parameter is valid.

exception stoch_ir.errors.RngLabelError

Raised when a distribution receives an invalid RNG label.

exception stoch_ir.errors.StochIRError

Base class for all documented Stochastic Program IR errors.

exception stoch_ir.errors.StochIRWarning

Base class for all documented Stochastic Program IR warnings.

exception stoch_ir.errors.UnknownPlateError

Raised when an operation names a plate that is not present.

exception stoch_ir.errors.UnrealizedGraphError

Raised when concrete data is requested from an unrealized graph.

exception stoch_ir.errors.ValueValidationError

Raised when a concrete value violates dtype, rank, or support rules.