Families

Parametric families of stochastic distributions.

families

Discretized parametric distribution families.

Provides learnable morphisms backed by discretized versions of standard probability distributions (normal, logit-normal, beta, truncated normal).

DiscretizedNormal

DiscretizedNormal(domain: SetObject, codomain: FinSet, low: float = 0.0, high: float = 1.0)

Bases: Morphism

A morphism whose codomain fibers are discretized normal densities.

For each domain element, produces a probability distribution over the codomain by evaluating a normal density at evenly spaced bin centers and normalizing.

The location μ and log-scale log(σ) are learnable parameters. When domain has size > 1, each domain element gets its own (μ, σ).

PARAMETER	DESCRIPTION
domain	Source object. TYPE: SetObject
codomain	Target object (bins of the discretized distribution). TYPE: FinSet
low	Lower bound of the discretization interval. TYPE: float DEFAULT: 0.0
high	Upper bound of the discretization interval. TYPE: float DEFAULT: 1.0

Examples:

>>> A = FinSet(name="A", cardinality=2)
>>> B = FinSet(name="response", cardinality=7)
>>> f = DiscretizedNormal(A, B, low=0.0, high=1.0)
>>> t = f.tensor  # shape (2, 7), rows sum to ~1

Source code in src/quivers/stochastic/families.py

def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
    low: float = 0.0,
    high: float = 1.0,
) -> None:
    super().__init__(domain, codomain, algebra=MARKOV)
    self._low = low
    self._high = high
    n_bins = codomain.cardinality

    # bin centers
    centers = torch.linspace(low, high, n_bins)

    self._module = _DiscretizedModule()
    self._module.register_buffer("centers", centers)

    # learnable parameters: one (μ, log_σ) per domain element
    dom_size = domain.size
    self._module.register_parameter("mu", nn.Parameter(torch.zeros(dom_size)))
    self._module.register_parameter(
        "log_sigma", nn.Parameter(torch.zeros(dom_size))
    )

tensor property

tensor: Tensor

Discretized normal probabilities.

RETURNS	DESCRIPTION
Tensor	Shape (*domain.shape, codomain.cardinality), rows sum to ~1.

module

module() -> Module

Return the nn.Module holding this morphism's parameters.

RETURNS	DESCRIPTION
Module	The parameter container.

Source code in src/quivers/stochastic/families.py

def module(self) -> nn.Module:
    """Return the ``nn.Module`` holding this morphism's parameters.

    Returns
    -------
    nn.Module
        The parameter container.
    """
    return self._module

DiscretizedLogitNormal

DiscretizedLogitNormal(domain: SetObject, codomain: FinSet)

Bases: Morphism

A morphism with discretized logit-normal codomain fibers.

The logit-normal distribution is a normal distribution on the logit scale: if X ~ Normal(μ, σ), then logistic(X) ~ LogitNormal(μ, σ). Useful for probabilities and bounded quantities.

PARAMETER	DESCRIPTION
domain	Source object. TYPE: SetObject
codomain	Target object (bins on (0, 1)). TYPE: FinSet

Source code in src/quivers/stochastic/families.py

def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
) -> None:
    super().__init__(domain, codomain, algebra=MARKOV)
    n_bins = codomain.cardinality

    # bin centers in (0, 1), excluding endpoints
    centers = torch.linspace(0.0, 1.0, n_bins + 2)[1:-1]

    self._module = _DiscretizedModule()
    self._module.register_buffer("centers", centers)

    dom_size = domain.size
    self._module.register_parameter("mu", nn.Parameter(torch.zeros(dom_size)))
    self._module.register_parameter(
        "log_sigma", nn.Parameter(torch.zeros(dom_size))
    )

tensor property

tensor: Tensor

Discretized logit-normal probabilities.

RETURNS	DESCRIPTION
Tensor	Shape (*domain.shape, codomain.cardinality), rows sum to ~1.

module

module() -> Module

Return the nn.Module holding this morphism's parameters.

RETURNS	DESCRIPTION
Module	The parameter container.

Source code in src/quivers/stochastic/families.py

def module(self) -> nn.Module:
    """Return the ``nn.Module`` holding this morphism's parameters.

    Returns
    -------
    nn.Module
        The parameter container.
    """
    return self._module

DiscretizedBeta

DiscretizedBeta(domain: SetObject, codomain: FinSet)

Bases: Morphism

A morphism with discretized beta-distribution codomain fibers.

The beta distribution Beta(α, β) is parameterized via learnable log-concentration parameters. Bin centers are placed in (0, 1).

PARAMETER	DESCRIPTION
domain	Source object. TYPE: SetObject
codomain	Target object (bins on (0, 1)). TYPE: FinSet

Source code in src/quivers/stochastic/families.py

def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
) -> None:
    super().__init__(domain, codomain, algebra=MARKOV)
    n_bins = codomain.cardinality

    # bin centers in (0, 1)
    centers = torch.linspace(0.0, 1.0, n_bins + 2)[1:-1]

    self._module = _DiscretizedModule()
    self._module.register_buffer("centers", centers)

    dom_size = domain.size
    # parameterize via log(α), log(β) for positivity
    self._module.register_parameter(
        "log_alpha", nn.Parameter(torch.zeros(dom_size))
    )
    self._module.register_parameter("log_beta", nn.Parameter(torch.zeros(dom_size)))

tensor property

tensor: Tensor

Discretized beta probabilities.

RETURNS	DESCRIPTION
Tensor	Shape (*domain.shape, codomain.cardinality), rows sum to ~1.

module

module() -> Module

Return the nn.Module holding this morphism's parameters.

RETURNS	DESCRIPTION
Module	The parameter container.

Source code in src/quivers/stochastic/families.py

def module(self) -> nn.Module:
    """Return the ``nn.Module`` holding this morphism's parameters.

    Returns
    -------
    nn.Module
        The parameter container.
    """
    return self._module

DiscretizedTruncatedNormal

DiscretizedTruncatedNormal(domain: SetObject, codomain: FinSet, low: float = 0.0, high: float = 1.0)

Bases: Morphism

A morphism with discretized truncated-normal codomain fibers.

Normal distribution truncated to [low, high]. Bin centers are placed within the truncation interval.

PARAMETER	DESCRIPTION
domain	Source object. TYPE: SetObject
codomain	Target object (bins within [low, high]). TYPE: FinSet
low	Lower truncation bound. TYPE: float DEFAULT: 0.0
high	Upper truncation bound. TYPE: float DEFAULT: 1.0

Source code in src/quivers/stochastic/families.py

def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
    low: float = 0.0,
    high: float = 1.0,
) -> None:
    super().__init__(domain, codomain, algebra=MARKOV)
    self._low = low
    self._high = high
    n_bins = codomain.cardinality

    # bin centers strictly within [low, high]
    centers = torch.linspace(low, high, n_bins)

    self._module = _DiscretizedModule()
    self._module.register_buffer("centers", centers)

    dom_size = domain.size
    self._module.register_parameter(
        "mu", nn.Parameter(torch.full((dom_size,), (low + high) / 2.0))
    )
    self._module.register_parameter(
        "log_sigma", nn.Parameter(torch.zeros(dom_size))
    )

tensor property

tensor: Tensor

Discretized truncated-normal probabilities.

RETURNS	DESCRIPTION
Tensor	Shape (*domain.shape, codomain.cardinality), rows sum to ~1.

module

module() -> Module

Return the nn.Module holding this morphism's parameters.

RETURNS	DESCRIPTION
Module	The parameter container.

Source code in src/quivers/stochastic/families.py

def module(self) -> nn.Module:
    """Return the ``nn.Module`` holding this morphism's parameters.

    Returns
    -------
    nn.Module
        The parameter container.
    """
    return self._module