Skip to content

Custom distribution catalogs

FamilyCatalog extends the builtin catalog for one compilation. A custom definition pairs the existing checked DistributionFamily contract with a native distribution factory or FamilySpec. with_family returns a new catalog; definitions and implementations already held by another model retain their meanings. Constructor schemas follow the declared parameter names.

Pass families=catalog to Model, Compiler, or lower_qvr_to_qiec. Factories receive named natural-scale tensors and return a native distribution; the existing inference, response-law, raw likelihood, and prediction paths use that law. Construction validates parameter carriers and constraints, dependent event dimensions, batch geometry, discreteness, and any declared reparameterization. These checks cannot prove that a user density integrates to one or that its sampler implements that density.

Factories are never sampled or called to discover their support during source checking. A factory with non-real support therefore supplies an explicit native support constraint; FamilySpec already retains one. The runtime binds the semantic record to a shallow copy of the returned distribution, retaining its parameter tensors and autograd graph. This supplies the existing measure and atom machinery with the law's declared reference-measure contract without mutating a factory-owned object or registering its class globally.

Direct catalog construction preserves integer tensors. The existing packed source execution path accepts signed integer parameters within [-2**53, 2**53] and refuses larger magnitudes before mixing them with real-valued features. Boolean parameters retain Boolean tensors; finite trial counts retain their separate nonnegative bound. Declaring an integer parameter does not turn it into a trial count.

Catalog copies and refit snapshots retain catalog identity. Pickling executable factories is refused. QIEC serialization retains only custom semantic records; execution requires explicitly supplied native implementations. Native factories have no implicit pure-reference or external-target implementation, and those execution paths report a capability error instead of emitting an undefined family. Recorded-event censoring and restriction additionally require the law's existing interval/atom capabilities.

family_catalog

Immutable distribution contracts and native bindings for one compilation.

DistributionFactory

DistributionFactory = Callable[[Mapping[str, Tensor]], Distribution]

Build one native law from checked, named natural-scale parameters.

FamilyCatalog dataclass

FamilyCatalog()

Bases: Mapping[str, DistributionFamily]

An immutable, compilation-local extension of the builtin family catalog.

A catalog compares by identity and holds native implementations by identity. It never registers callbacks globally or serializes their executable code. Use :meth:with_family to obtain a new catalog sharing existing definitions.

Source code in src/quivers/family_catalog.py
def __init__(self) -> None:
    object.__setattr__(self, "_definitions", MappingProxyType({}))
    object.__setattr__(self, "_implementations", MappingProxyType({}))
    object.__setattr__(self, "_supports", MappingProxyType({}))

definitions property

definitions: tuple[DistributionFamily, ...]

Serializable custom contracts, excluding builtin records and callbacks.

RETURNS DESCRIPTION
tuple[DistributionFamily, ...]

Checked custom contracts in insertion order.

__getitem__

__getitem__(name: str) -> DistributionFamily

Look up a checked contract.

PARAMETER DESCRIPTION
name

Builtin or custom family name.

TYPE: str

RETURNS DESCRIPTION
DistributionFamily

Contract retained by this catalog.

Source code in src/quivers/family_catalog.py
def __getitem__(self, name: str) -> DistributionFamily:
    """Look up a checked contract.

    Parameters
    ----------
    name : str
        Builtin or custom family name.

    Returns
    -------
    DistributionFamily
        Contract retained by this catalog.
    """
    return self._definitions[name] if name in self._definitions else FAMILIES[name]

__iter__

__iter__() -> Iterator[str]

Iterate over family names.

RETURNS DESCRIPTION
Iterator[str]

Builtin names followed by custom names.

Source code in src/quivers/family_catalog.py
def __iter__(self) -> Iterator[str]:
    """Iterate over family names.

    Returns
    -------
    Iterator[str]
        Builtin names followed by custom names.
    """
    return iter((*FAMILIES, *self._definitions))

__len__

__len__() -> int

Count retained contracts.

RETURNS DESCRIPTION
int

Number of builtin and custom families.

Source code in src/quivers/family_catalog.py
def __len__(self) -> int:
    """Count retained contracts.

    Returns
    -------
    int
        Number of builtin and custom families.
    """
    return len(FAMILIES) + len(self._definitions)

__eq__

__eq__(other: object) -> bool

Compare compilation contexts by identity.

PARAMETER DESCRIPTION
other

Candidate compilation context.

TYPE: object

RETURNS DESCRIPTION
bool

Whether both references denote this catalog.

Source code in src/quivers/family_catalog.py
def __eq__(self, other: object) -> bool:
    """Compare compilation contexts by identity.

    Parameters
    ----------
    other : object
        Candidate compilation context.

    Returns
    -------
    bool
        Whether both references denote this catalog.
    """
    return self is other

__hash__

__hash__() -> int

Hash the immutable compilation context by identity.

RETURNS DESCRIPTION
int

Identity hash for this catalog.

Source code in src/quivers/family_catalog.py
def __hash__(self) -> int:
    """Hash the immutable compilation context by identity.

    Returns
    -------
    int
        Identity hash for this catalog.
    """
    return object.__hash__(self)

is_custom

is_custom(name: str) -> bool

Whether a name has a compilation-local native implementation.

PARAMETER DESCRIPTION
name

Family name to inspect.

TYPE: str

RETURNS DESCRIPTION
bool

Whether the name denotes a custom family.

Source code in src/quivers/family_catalog.py
def is_custom(self, name: str) -> bool:
    """Whether a name has a compilation-local native implementation.

    Parameters
    ----------
    name : str
        Family name to inspect.

    Returns
    -------
    bool
        Whether the name denotes a custom family.
    """
    return name in self._definitions

support

support(name: str) -> Constraint

Read declared support without constructing or sampling a law.

PARAMETER DESCRIPTION
name

Custom family name.

TYPE: str

RETURNS DESCRIPTION
Constraint

Declared native support.

Source code in src/quivers/family_catalog.py
def support(self, name: str) -> constraints.Constraint:
    """Read declared support without constructing or sampling a law.

    Parameters
    ----------
    name : str
        Custom family name.

    Returns
    -------
    torch.distributions.constraints.Constraint
        Declared native support.
    """
    return self._supports[name]

parameter_names

parameter_names(name: str) -> tuple[str, ...]

Return the canonical named constructor schema of a checked family.

PARAMETER DESCRIPTION
name

Family name in this catalog.

TYPE: str

RETURNS DESCRIPTION
tuple[str, ...]

Natural-scale parameter names in their declared order.

RAISES DESCRIPTION
KeyError

If the family is not in this catalog.

Source code in src/quivers/family_catalog.py
def parameter_names(self, name: str) -> tuple[str, ...]:
    """Return the canonical named constructor schema of a checked family.

    Parameters
    ----------
    name : str
        Family name in this catalog.

    Returns
    -------
    tuple[str, ...]
        Natural-scale parameter names in their declared order.

    Raises
    ------
    KeyError
        If the family is not in this catalog.
    """
    return self[name].parameter_names

with_family

with_family(semantic: DistributionFamily, implementation: DistributionFactory | FamilySpec, *, support: Constraint | None = None) -> FamilyCatalog

Return an isolated catalog containing one additional native law.

PARAMETER DESCRIPTION
semantic

Checked parameter, sample-carrier, shape, support and measure contract.

TYPE: DistributionFamily

implementation

Factory receiving named tensors, or an existing native family record. The implementation must return the normalized law declared by the contract; mathematical correctness remains the author's obligation.

TYPE: DistributionFactory or FamilySpec

support

Native support for a factory. Real-valued support defaults to real; other supports must be explicit. FamilySpec already retains support.

TYPE: Constraint or None DEFAULT: None

RETURNS DESCRIPTION
FamilyCatalog

New catalog; existing compilations retain their original bindings.

RAISES DESCRIPTION
ValueError

If a name or stable identity collides, or metadata disagrees.

TypeError

If the implementation is not a native record or callable.

Source code in src/quivers/family_catalog.py
def with_family(
    self,
    semantic: DistributionFamily,
    implementation: DistributionFactory | FamilySpec,
    *,
    support: constraints.Constraint | None = None,
) -> FamilyCatalog:
    """Return an isolated catalog containing one additional native law.

    Parameters
    ----------
    semantic : DistributionFamily
        Checked parameter, sample-carrier, shape, support and measure contract.
    implementation : DistributionFactory or FamilySpec
        Factory receiving named tensors, or an existing native family record.
        The implementation must return the normalized law declared by the
        contract; mathematical correctness remains the author's obligation.
    support : torch.distributions.constraints.Constraint or None
        Native support for a factory. Real-valued support defaults to real;
        other supports must be explicit. FamilySpec already retains support.

    Returns
    -------
    FamilyCatalog
        New catalog; existing compilations retain their original bindings.

    Raises
    ------
    ValueError
        If a name or stable identity collides, or metadata disagrees.
    TypeError
        If the implementation is not a native record or callable.
    """
    if semantic.name in self or any(
        item.id == semantic.id for item in self.values()
    ):
        raise ValueError(
            f"distribution family {semantic.name!r} is already defined"
        )
    if isinstance(implementation, FamilySpec):
        if (
            implementation.name != semantic.name
            or implementation.param_names != semantic.parameter_names
        ):
            raise ValueError(
                "native family name and parameters must match its semantic contract"
            )
        if support is not None:
            raise ValueError("FamilySpec already declares its native support")
        support = implementation.support
    elif not callable(implementation):
        raise TypeError(
            "a native family implementation must be a FamilySpec or factory"
        )
    if semantic.compositional:
        raise ValueError(
            "custom native families declare tensor parameters, not measure operators"
        )
    if semantic.targets:
        raise ValueError(
            "native custom families cannot claim external target implementations"
        )
    semantic = semantic.with_(targets=MappingProxyType({}))
    if support is None:
        if semantic.support != "real":
            raise ValueError(
                "custom factories with non-real support require explicit native support"
            )
        support = constraints.real
    if not isinstance(support, constraints.Constraint):
        raise TypeError("custom native support must be a torch Constraint")
    result = FamilyCatalog()
    object.__setattr__(
        result,
        "_definitions",
        MappingProxyType({**self._definitions, semantic.name: semantic}),
    )
    object.__setattr__(
        result,
        "_implementations",
        MappingProxyType({**self._implementations, semantic.name: implementation}),
    )
    object.__setattr__(
        result,
        "_supports",
        MappingProxyType({**self._supports, semantic.name: support}),
    )
    return result

with_catalog

with_catalog(other: FamilyCatalog) -> FamilyCatalog

Combine immutable extensions without replacing executable identities.

PARAMETER DESCRIPTION
other

Independently retained definitions to add to this catalog.

TYPE: FamilyCatalog

RETURNS DESCRIPTION
FamilyCatalog

A catalog sharing the original implementations and support objects. Identical repeated definitions are retained once.

RAISES DESCRIPTION
TypeError

If other is not a FamilyCatalog.

ValueError

If a repeated family name has another contract, implementation, or support identity, or a new name collides with a stable family id.

Source code in src/quivers/family_catalog.py
def with_catalog(self, other: FamilyCatalog) -> FamilyCatalog:
    """Combine immutable extensions without replacing executable identities.

    Parameters
    ----------
    other : FamilyCatalog
        Independently retained definitions to add to this catalog.

    Returns
    -------
    FamilyCatalog
        A catalog sharing the original implementations and support objects.
        Identical repeated definitions are retained once.

    Raises
    ------
    TypeError
        If other is not a FamilyCatalog.
    ValueError
        If a repeated family name has another contract, implementation,
        or support identity, or a new name collides with a stable family id.
    """
    if not isinstance(other, FamilyCatalog):
        raise TypeError("catalog composition requires a FamilyCatalog")
    result = self
    for name, semantic in other._definitions.items():
        implementation = other._implementations[name]
        support = other._supports[name]
        if name in result._definitions:
            if (
                result._definitions[name] != semantic
                or result._implementations[name] is not implementation
                or result._supports[name] is not support
            ):
                raise ValueError(
                    f"distribution family {name!r} has conflicting catalog definitions"
                )
            continue
        result = result.with_family(
            semantic,
            implementation,
            **(
                {}
                if isinstance(implementation, FamilySpec)
                else {"support": support}
            ),
        )
    return result

build

build(name: str, arguments: Mapping[str, Tensor]) -> Distribution

Construct and validate a custom law without sampling or detaching it.

PARAMETER DESCRIPTION
name

Custom family name.

TYPE: str

arguments

Named natural-scale values retaining batch and intrinsic axes.

TYPE: Mapping[str, Tensor]

RETURNS DESCRIPTION
Distribution

Native law with the declared event and parameter batch geometry.

RAISES DESCRIPTION
KeyError

If the custom implementation is absent.

(TypeError, ValueError)

If arguments or the returned native law violate the checked contract.

Source code in src/quivers/family_catalog.py
def build(self, name: str, arguments: Mapping[str, torch.Tensor]) -> Distribution:
    """Construct and validate a custom law without sampling or detaching it.

    Parameters
    ----------
    name : str
        Custom family name.
    arguments : Mapping[str, torch.Tensor]
        Named natural-scale values retaining batch and intrinsic axes.

    Returns
    -------
    torch.distributions.Distribution
        Native law with the declared event and parameter batch geometry.

    Raises
    ------
    KeyError
        If the custom implementation is absent.
    TypeError, ValueError
        If arguments or the returned native law violate the checked contract.
    """
    record = self._definitions[name]
    if set(arguments) != set(record.parameter_names):
        raise TypeError(
            f"custom family {name!r} requires parameters {record.parameter_names}"
        )
    values = dict(arguments)
    shapes = {}
    batches = []
    for parameter in record.parameters:
        value = values[parameter.name]
        if not isinstance(value, torch.Tensor):
            raise TypeError(
                f"custom family parameter {parameter.name!r} must be a tensor"
            )
        if parameter.constraint == "boolean":
            if value.dtype != torch.bool:
                raise TypeError(
                    f"custom family parameter {parameter.name!r} requires Bool"
                )
        elif value.dtype == torch.bool or value.is_complex():
            raise TypeError(
                f"custom family parameter {parameter.name!r} requires real numeric values"
            )
        condition = getattr(constraints, parameter.constraint, None)
        if isinstance(condition, constraints.Constraint):
            _validate_parameter(
                value,
                condition,
                description=f"custom family parameter {parameter.name!r} violates {parameter.constraint}",
            )
        if value.ndim < parameter.rank:
            raise ValueError(
                f"custom family parameter {parameter.name!r} has insufficient intrinsic rank"
            )
        shapes[parameter.name] = (
            tuple(value.shape[-parameter.rank :]) if parameter.rank else ()
        )
        batches.append(
            value.shape[: -parameter.rank] if parameter.rank else value.shape
        )
    implementation = self._implementations[name]
    result = (
        implementation.mixed_builder_override(
            [values[name] for name in record.parameter_names]
        )
        if isinstance(implementation, FamilySpec)
        and implementation.mixed_builder_override is not None
        else build_torch_distribution(implementation, values)
        if isinstance(implementation, FamilySpec)
        else implementation(MappingProxyType(values))
    )
    if not isinstance(result, Distribution):
        raise TypeError(f"custom family {name!r} must return a torch Distribution")
    native_support = result.support
    if (
        native_support is None
        or bool(native_support.is_discrete) != record.discrete
    ):
        raise TypeError(
            f"custom family {name!r} returned a different sample carrier"
        )
    if len(result.event_shape) != record.event_rank:
        raise ValueError(
            f"custom family {name!r} returned event rank {len(result.event_shape)}, expected {record.event_rank}"
        )
    match_family_shapes(
        record.effective_shape_signature,
        {
            key: tuple(IndexLiteral(value=size, sort=NAT) for size in shape)
            for key, shape in shapes.items()
        },
        tuple(IndexLiteral(value=size, sort=NAT) for size in result.event_shape),
    )
    expected_batch = torch.broadcast_shapes(*batches) if batches else torch.Size()
    if result.batch_shape != expected_batch:
        raise ValueError(
            f"custom family {name!r} returned batch shape {result.batch_shape}, expected {expected_batch}"
        )
    if record.reparameterizable and not result.has_rsample:
        raise TypeError(
            f"custom family {name!r} declares reparameterized sampling but its native law does not provide it"
        )
    result = copy(result)
    setattr(result, "_family_contract", record)
    return result

__copy__

__copy__() -> FamilyCatalog

Share this immutable catalog while retaining implementation identities.

RETURNS DESCRIPTION
FamilyCatalog

This immutable catalog.

Source code in src/quivers/family_catalog.py
def __copy__(self) -> FamilyCatalog:
    """Share this immutable catalog while retaining implementation identities.

    Returns
    -------
    FamilyCatalog
        This immutable catalog.
    """
    return self

__deepcopy__

__deepcopy__(memo: dict[int, object]) -> FamilyCatalog

Retain catalog identity when snapshotting fitting settings.

PARAMETER DESCRIPTION
memo

Objects already copied by the snapshot operation.

TYPE: dict[int, object]

RETURNS DESCRIPTION
FamilyCatalog

This immutable catalog.

Source code in src/quivers/family_catalog.py
def __deepcopy__(self, memo: dict[int, object]) -> FamilyCatalog:
    """Retain catalog identity when snapshotting fitting settings.

    Parameters
    ----------
    memo : dict[int, object]
        Objects already copied by the snapshot operation.

    Returns
    -------
    FamilyCatalog
        This immutable catalog.
    """
    memo[id(self)] = self
    return self

__reduce_ex__

__reduce_ex__(protocol: SupportsIndex) -> Never

Reject serialization of executable implementations.

PARAMETER DESCRIPTION
protocol

Requested pickle protocol.

TYPE: SupportsIndex

RAISES DESCRIPTION
TypeError

Always; implementations must be explicitly reattached.

Source code in src/quivers/family_catalog.py
def __reduce_ex__(self, protocol: SupportsIndex, /) -> Never:
    """Reject serialization of executable implementations.

    Parameters
    ----------
    protocol : SupportsIndex
        Requested pickle protocol.

    Raises
    ------
    TypeError
        Always; implementations must be explicitly reattached.
    """
    raise TypeError(
        "family catalogs contain live native implementations; retain semantic metadata and explicitly reattach implementations"
    )