API Reference

prophys.symbolic
prophys.frames
prophys.structures
prophys.transformations
prophys.distributions
prophys.domain
prophys.engine
prophys.export
prophys.plot

Symbolic core

class prophys.symbolic.Expr

Base class for all symbolic nodes.

Subclasses must implement _evaluate() and _children(). Operators are implemented once here in terms of Op, so new leaf/operator types automatically get + - * / ** @ etc.

evaluate(env=None)

Evaluate this expression to a concrete jax.numpy array.

env maps Param/Input names to values; leaves without an entry fall back to their declared default/init value (for Param) or raise if no default exists (for Input).

Parameters:

env (Mapping[str, Any] | None)

Return type:

Any

params()

Collect all distinct Param leaves reachable from this node.

Return type:

dict[str, Expr]

class prophys.symbolic.Const(value)

A fixed constant (Python scalar, NumPy array, or JAX array).

Parameters:

value (Any)

class prophys.symbolic.Input(name, shape=None)

A named placeholder for data supplied at evaluation time (e.g. observations). Unlike Param, an Input is never optimized.

Parameters:

• name (str)

• shape (tuple[int, ...] | None)

class prophys.symbolic.Param(name, shape=(), init=0.0, bounds=None, transform=None)

A named, learnable/optimizable leaf.

bounds=(lo, hi) constrains the unconstrained optimization variable through a sigmoid transform; transform=”softplus” constrains to positive values. The raw (unconstrained) value lives in the parameter dict used by the engine; _evaluate always applies the forward transform, so downstream expressions see the constrained value.

Parameters:

• name (str)

• shape (tuple[int, ...])

• init (Any)

• bounds (tuple[float, float] | None)

• transform (str | None)

unconstrained_init()

Initial value in unconstrained space (what the optimizer sees).

Return type:

Any

forward(raw)

Map an unconstrained value to the constrained value seen by the graph.

Parameters:

raw (Any)

Return type:

Any

class prophys.symbolic.Surrogate(fn, *args, name='surrogate')

Wrap an arbitrary pure JAX-compatible callable as a symbolic node.

Use this for user-supplied physics (e.g. a noise propagation formula or a power curve) that doesn’t need to be expressed in terms of other prophys primitives, but must still be differentiable.

Parameters:

• args (Any)

• name (str)

class prophys.symbolic.BinaryState(name, init=0.5, mode=None, tau=None)

A learnable on/off state.

Evaluates to a scalar in [0, 1]: exactly 0/1 in eval mode (hard threshold at logit 0), and sigmoid(logit / tau) in opt mode, so a design optimizer can trade the state continuously and the final hard decision is read off the same graph.

Multiply it into any expression to gate that term:

flow = pipe_capacity * prp.BinaryState("valve_a", init=0.9)

Parameters:

• name (str)

• init (float)

• mode (str | None)

• tau (float | None)

class prophys.symbolic.CategoricalState(name, k, init=None, mode=None, tau=None)

A learnable choice among k discrete states.

Evaluates to a (k,) assignment vector on the probability simplex: a hard one-hot argmax in eval mode, and a tempered softmax(logits / tau) in opt mode. Dot it with a vector of per-state consequences to make the choice differentiable:

setting = prp.dot(prp.CategoricalState("pump_mode", 3), jnp.array([0.0, 0.5, 1.0]))

Parameters:

• name (str)

• k (int)

• mode (str | None)

• tau (float | None)

Domain layer

class prophys.domain.UncertainAttribute(name, distribution, unit='', domain='')

A named, documented uncertain quantity — the primary unit of meaning in prophys. Carries metadata (unit, domain description) used by diagnostics, plotting, and export, in addition to the plain RandomVariable graph behavior.

Parameters:

• name (str)

• unit (str)

• domain (str)

upstream_random_variables()

All RandomVariable leaves this attribute’s distribution depends on (e.g. an attribute whose mean is derived from wind speed/direction).

Return type:

dict[str, RandomVariable]

class prophys.domain.AttributeInteractions(attributes, coupling)

A joint dependence structure over several UncertainAttribute objects (Gaussian copula or plain correlation), used when attributes shouldn’t be assumed independent.

Parameters:

• attributes (Sequence[UncertainAttribute])

• coupling (Any)

class prophys.domain.ProbabilityModel(*attributes, interactions=None)

A named collection of UncertainAttribute`s (optionally coupled by `AttributeInteractions), representing one probabilistic model.

This is the standardized handoff object: build it once from symbolic pieces, then call .compile(…) to obtain a CompiledModel with a stable log_prob/sample/expectation interface.

Parameters:

• attributes (UncertainAttribute)

• interactions (AttributeInteractions | None)

random_variables()

All upstream RandomVariable leaves referenced anywhere in the model (e.g. wind speed/direction feeding a noise surrogate).

compile(mode='eval', tau=1.0, n_samples=256, seed=0)

Compile this model into a CompiledModel.

mode="eval" uses hard min/max/contains everywhere in the geometry graph (exact evaluation); mode="opt" uses the smooth (soft) approximations at temperature tau, suitable for gradient- based calibration/design optimization. n_samples and seed control the default Monte-Carlo marginalization sample size and PRNG seed for any upstream RandomVariable leaves. n_samples is not license-limited (see License) — the free-tier object gate applies to structural model size (points, polygon vertices, segments, …), not to Monte-Carlo marginalization precision.

Parameters:

• mode (str)

• tau (float)

• n_samples (int)

• seed (int)

class prophys.domain.RandomVariable(name, distribution)

A named stochastic leaf backed by a Distribution.

Evaluating a RandomVariable requires either:

• a bound concrete value in env[name] (e.g. an observation), or

• a pre-drawn sample in env[“__rv_samples__”][name], which is how the engine’s Monte-Carlo marginalization feeds samples through the graph while keeping everything inside a single JAX trace.

Parameters:

name (str)

Frames

class prophys.frames.Frame(name, ndim=2, units='m', crs=None)

A named coordinate system.

Parameters

name:

Unique identifier used for equality/compatibility checks.

ndim:

2 or 3.

units:

Free-text unit label (e.g. "m"), used only for documentation and plotting.

crs:

Optional EPSG/CRS tag, purely informational — used by the optional geo I/O extras when projecting external data into this frame.

Parameters:

• name (str)

• ndim (int)

• units (str)

• crs (str | None)

class prophys.frames.FrameTransform(from_, to, matrix=None, offset=None)

A differentiable affine map between two frames: y = R @ x + t.

matrix has shape (to.ndim, from_.ndim), offset has shape (to.ndim,). Both are plain arrays (not Expr) — frame alignment is considered a fixed, known calibration, not an optimizable quantity.

Parameters:

• from_ (Frame)

• to (Frame)

• matrix (Any)

• offset (Any)

apply(points)

Map an (..., ndim_from) array of points into to’s frame.

Parameters:

points (Any)

Return type:

Any

class prophys.frames.FrameRegistry

Process-local registry of transforms between frames.

A tiny convenience so structures declared in different (but related) frames can still be combined without the user re-threading transforms through every call.

align(points, from_, to)

Return points expressed in to’s frame, applying a registered transform if the frames differ.

Parameters:

• points (Any)

• from_ (Frame)

• to (Frame)

Return type:

Any

class prophys.frames.FrameError

Raised when two structures with incompatible frames are combined.