Skip to content

Deterministic Morphisms

Dirac kernels for deterministic maps: cumulative sums for monotone splines, the softmax projection onto the simplex, and covariance reconstruction from a correlation Cholesky factor and scales.

deterministic

Deterministic morphisms in :math:\mathbf{Kern}.

Each builder returns a ContinuousMorphism whose runtime realisation is a Dirac kernel concentrated on a deterministic image: cumsum_morphism for ordinal monotone splines, softmax_morphism for the standard simplex projection, cholesky_quad_form_morphism for covariance reconstruction from a correlation Cholesky factor and a positive-scale vector.

Categorically a deterministic morphism :math:f : X \to Y is the unit-Kleisli image of a measurable map; its log-density is :math:-\infty everywhere except at :math:y = f(x) and zero there. The variational backend treats the sampling path as an identity reparameterization of the deterministic image and the log-density as a no-op (the surrounding KL terms absorb the Dirac indicator).

DeterministicMorphism 

DeterministicMorphism(domain: AnySpace, codomain: AnySpace, apply: Callable[[Tensor], Tensor], name: str)

Bases: ContinuousMorphism

Helper base for deterministic morphisms f : X → Y.

A deterministic morphism in :math:\mathbf{Kern} is a Dirac kernel concentrated on :math:f(x). Its log-density is :math:-\infty everywhere except at :math:y = f(x) and :math:0 (= :math:\log 1) there; for gradient-based inference we treat the sampling path as an identity reparameterization of the deterministic image.

Subclasses supply _apply(x) -> y.

Source code in src/quivers/continuous/deterministic.py 
49
50
51
52
53
54
55
56
57
58
def __init__(
    self,
    domain: AnySpace,
    codomain: AnySpace,
    apply: Callable[[torch.Tensor], torch.Tensor],
    name: str,
) -> None:
    super().__init__(domain, codomain)
    self._apply_fn = apply
    self._name = name

point_mass_value 

point_mass_value(x: Tensor) -> Tensor

The Dirac's location, :math:f(x).

Reporting it lets a composition through this morphism integrate over its codomain exactly, by evaluating the next kernel at the single point carrying all the mass, instead of approximating an integral that has no spread to resolve.

Source code in src/quivers/continuous/deterministic.py 
66
67
68
69
70
71
72
73
74
def point_mass_value(self, x: torch.Tensor) -> torch.Tensor:
    """The Dirac's location, :math:`f(x)`.

    Reporting it lets a composition through this morphism
    integrate over its codomain exactly, by evaluating the next
    kernel at the single point carrying all the mass, instead of
    approximating an integral that has no spread to resolve.
    """
    return self._apply_fn(x)

cumsum_morphism 

cumsum_morphism(dim: int) -> DeterministicMorphism

Cumulative sum cumsum : Euclidean(dim) → Euclidean(dim).

Maps :math:(x_1, \dots, x_K) to :math:(x_1, x_1 + x_2, \dots, \sum_i x_i). The canonical monotonic-spline parameterization for ordinal covariates (coef ~ Normal(0, sigma) followed by cumsum(coef - coef[0]) gives a 0-anchored, monotonically-increasing effect across the ordered levels).

Source code in src/quivers/continuous/deterministic.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def cumsum_morphism(dim: int) -> DeterministicMorphism:
    """Cumulative sum ``cumsum : Euclidean(dim) → Euclidean(dim)``.

    Maps :math:`(x_1, \\dots, x_K)` to
    :math:`(x_1, x_1 + x_2, \\dots, \\sum_i x_i)`. The canonical
    monotonic-spline parameterization for ordinal covariates
    (``coef ~ Normal(0, sigma)`` followed by ``cumsum(coef - coef[0])``
    gives a 0-anchored, monotonically-increasing effect across the
    ordered levels).
    """
    space = Euclidean(name="cumsum", dim=dim)
    return DeterministicMorphism(
        space, space, lambda x: torch.cumsum(x, dim=-1), name="cumsum"
    )

softmax_morphism 

softmax_morphism(dim: int) -> DeterministicMorphism

Softmax softmax : Euclidean(dim) → Simplex(dim).

The standard exponential normalizer onto the probability simplex. Useful for closed-form class-probability computations in posterior blocks where one would otherwise need a log-sum-exp aggregation by hand.

Source code in src/quivers/continuous/deterministic.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
def softmax_morphism(dim: int) -> DeterministicMorphism:
    """Softmax ``softmax : Euclidean(dim) → Simplex(dim)``.

    The standard exponential normalizer onto the probability
    simplex. Useful for closed-form class-probability computations
    in posterior blocks where one would otherwise need a
    log-sum-exp aggregation by hand.
    """
    src = Euclidean(name="softmax_in", dim=dim)
    tgt = Simplex(name="softmax_out", dim=dim)
    return DeterministicMorphism(
        src, tgt, lambda x: torch.softmax(x, dim=-1), name="softmax"
    )

cholesky_quad_form_morphism 

cholesky_quad_form_morphism(dim: int) -> ContinuousMorphism

Covariance reconstruction (L, s) -> diag(s) L L^T diag(s).

Given a Cholesky factor :math:L of a :math:K \times K correlation matrix and a positive-scale vector :math:s \in (0, \infty)^K, returns the corresponding covariance matrix :math:\Sigma = D R D^T with :math:R = L L^T and :math:D = \mathrm{diag}(s).

Domain is the product CholeskyFactor(K) <quivers.continuous.spaces.CholeskyFactor> * PositiveReals(K) <quivers.continuous.spaces.PositiveReals>; codomain is Euclidean(K * K) <quivers.continuous.spaces.Euclidean> flattened in row-major order so the result composes with downstream quivers.continuous.families.ConditionalMultivariateNormal consumers that accept a flat covariance vector.

Source code in src/quivers/continuous/deterministic.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def cholesky_quad_form_morphism(dim: int) -> ContinuousMorphism:
    """Covariance reconstruction ``(L, s) -> diag(s) L L^T diag(s)``.

    Given a Cholesky factor :math:`L` of a :math:`K \\times K`
    correlation matrix and a positive-scale vector
    :math:`s \\in (0, \\infty)^K`, returns the corresponding
    covariance matrix :math:`\\Sigma = D R D^T` with
    :math:`R = L L^T` and :math:`D = \\mathrm{diag}(s)`.

    Domain is the product
    `CholeskyFactor(K) <quivers.continuous.spaces.CholeskyFactor>` ``*``
    `PositiveReals(K) <quivers.continuous.spaces.PositiveReals>`;
    codomain is `Euclidean(K * K) <quivers.continuous.spaces.Euclidean>`
    flattened in row-major order so the result composes with
    downstream
    [`quivers.continuous.families.ConditionalMultivariateNormal`][quivers.continuous.families.ConditionalMultivariateNormal]
    consumers that accept a flat covariance vector.
    """
    cholesky = CholeskyFactor(name="L", dim=dim)
    scale = PositiveReals(name="scale", dim=dim)
    source = ProductSpace(components=(cholesky, scale))
    target = Euclidean(name="cov", dim=dim * dim)

    def _apply(xs: torch.Tensor) -> torch.Tensor:
        # xs : (batch, K*K + K) — the cholesky's flat lower-tri plus
        # the K-vector of scales, concatenated in that order. We
        # rehydrate L from the lower-triangular packing, apply the
        # quadratic form, then flatten.
        batch = xs.shape[0]
        chol_flat = xs[:, : dim * dim]
        scale_vec = xs[:, dim * dim :]
        L = chol_flat.reshape(batch, dim, dim)
        mask = torch.tril(torch.ones(dim, dim, device=xs.device, dtype=xs.dtype))
        L = L * mask
        R = L @ L.transpose(-1, -2)
        D = scale_vec.unsqueeze(-1) * torch.eye(dim, device=xs.device, dtype=xs.dtype)
        cov = D @ R @ D
        return cov.reshape(batch, dim * dim)

    return DeterministicMorphism(source, target, _apply, name="cholesky_quad_form")