Trace types

The site and trace records.

trace_types

Data types for execution traces.

SampleSite and Trace live here in a leaf module so both the effect-handler interpreter and the thin quivers.inference.trace wrapper import them without introducing a cycle. The effects package produces traces; the inference package consumes them.

SiteAddress

SiteAddress = tuple[str, tuple[tuple[str, str | int], ...], tuple[int, ...]]

The kernel's dynamic address of one occurrence of a site.

SampleSite dataclass

SampleSite(name: str, morphism: ContinuousMorphism | None, value: Tensor, log_prob: Tensor, is_observed: bool = False, is_deterministic: bool = False, sampleable: TorchSampleable | None = None, address: SiteAddress | None = None, metadata: dict[str, object] = dict())

Record of a single site in a program trace.

Holds a torch.Tensor per site; not a value type.

PARAMETER	DESCRIPTION
name	Variable name bound at this site. TYPE: str
morphism	The distribution morphism (None for let bindings and scores). TYPE: ContinuousMorphism or None
value	The sampled, observed, or computed value. TYPE: Tensor
log_prob	The density the site contributed to the run's score, after every score transformer on the stack. Zero for let bindings and for intervened sites. TYPE: Tensor
is_observed	Whether this site was conditioned on an observed value. TYPE: bool DEFAULT: False
is_deterministic	Whether this is a let binding, a score step, or an intervened site. TYPE: bool DEFAULT: False
sampleable	The sampleable the site's request carried, with the morphism and the input it was conditioned on; None for let bindings and scores. TYPE: TorchSampleable or None DEFAULT: None
address	The kernel's dynamic address of the site's request, which is one identity for the run's trace and for every handler that answered it. TYPE: SiteAddress or None DEFAULT: None
metadata	Annotations handlers attached to the site. TYPE: dict[str, object] DEFAULT: dict()

Trace dataclass

Trace(sites: dict[str, SampleSite] = dict(), output: Tensor | dict[str, Tensor] | None = None, log_joint: Tensor | None = None)

Complete execution trace of a monadic program.

Mutable accumulator: sites grows as the program executes; not a value type.

PARAMETER	DESCRIPTION
sites	All sites keyed by variable name. TYPE: dict[str, SampleSite] DEFAULT: dict()
output	The program's return value. TYPE: Tensor or dict[str, Tensor] DEFAULT: None
log_joint	Sum of log-densities across all sites. Shape (batch,). TYPE: Tensor DEFAULT: None

stochastic_sites property

stochastic_sites: dict[str, SampleSite]

The sites that are not deterministic.

RETURNS	DESCRIPTION
dict[str, SampleSite]	Every sampled or observed site.

latent_sites property

latent_sites: dict[str, SampleSite]

The sites that are neither observed nor deterministic.

RETURNS	DESCRIPTION
dict[str, SampleSite]	Every sampled latent site.

observed_sites property

observed_sites: dict[str, SampleSite]

The observed sites.

RETURNS	DESCRIPTION
dict[str, SampleSite]	Every site conditioned on an observation.