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 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
    low: float = 0.0,
    high: float = 1.0,
) -> None:
    super().__init__(domain, codomain, quantale=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.

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 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
) -> None:
    super().__init__(domain, codomain, quantale=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.

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 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
) -> None:
    super().__init__(domain, codomain, quantale=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.

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 
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
def __init__(
    self,
    domain: SetObject,
    codomain: FinSet,
    low: float = 0.0,
    high: float = 1.0,
) -> None:
    super().__init__(domain, codomain, quantale=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.