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
¶
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
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:
|
| RETURNS | DESCRIPTION |
|---|---|
DistributionFamily
|
Contract retained by this catalog. |
Source code in src/quivers/family_catalog.py
__iter__
¶
Iterate over family names.
| RETURNS | DESCRIPTION |
|---|---|
Iterator[str]
|
Builtin names followed by custom names. |
__len__
¶
Count retained contracts.
| RETURNS | DESCRIPTION |
|---|---|
int
|
Number of builtin and custom families. |
__eq__
¶
Compare compilation contexts by identity.
| PARAMETER | DESCRIPTION |
|---|---|
other
|
Candidate compilation context.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
Whether both references denote this catalog. |
Source code in src/quivers/family_catalog.py
__hash__
¶
Hash the immutable compilation context by identity.
| RETURNS | DESCRIPTION |
|---|---|
int
|
Identity hash for this catalog. |
is_custom
¶
Whether a name has a compilation-local native implementation.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Family name to inspect.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
Whether the name denotes a custom family. |
Source code in src/quivers/family_catalog.py
support
¶
support(name: str) -> Constraint
Read declared support without constructing or sampling a law.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Custom family name.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Constraint
|
Declared native support. |
Source code in src/quivers/family_catalog.py
parameter_names
¶
Return the canonical named constructor schema of a checked family.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Family name in this catalog.
TYPE:
|
| 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
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:
|
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:
|
support
|
Native support for a factory. Real-valued support defaults to real; other supports must be explicit. FamilySpec already retains support.
TYPE:
|
| 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
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 | |
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:
|
| 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
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:
|
arguments
|
Named natural-scale values retaining batch and intrinsic axes.
TYPE:
|
| 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
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 | |
__copy__
¶
__copy__() -> FamilyCatalog
Share this immutable catalog while retaining implementation identities.
| RETURNS | DESCRIPTION |
|---|---|
FamilyCatalog
|
This immutable catalog. |
__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:
|
| RETURNS | DESCRIPTION |
|---|---|
FamilyCatalog
|
This immutable catalog. |
Source code in src/quivers/family_catalog.py
__reduce_ex__
¶
Reject serialization of executable implementations.
| PARAMETER | DESCRIPTION |
|---|---|
protocol
|
Requested pickle protocol.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
Always; implementations must be explicitly reattached. |