laplacekit 0.1a0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
laplacekit/__init__.py ADDED
@@ -0,0 +1,169 @@
1
+ """Laplace approximations for PyTorch."""
2
+
3
+ import importlib
4
+ from types import ModuleType
5
+ from typing import TYPE_CHECKING
6
+
7
+ from laplacekit import (
8
+ core,
9
+ curvature,
10
+ data,
11
+ distributed,
12
+ function_space,
13
+ likelihoods,
14
+ objectives,
15
+ predictive,
16
+ priors,
17
+ subsets,
18
+ testing,
19
+ tuning,
20
+ )
21
+ from laplacekit._health import (
22
+ HealthCheck,
23
+ HealthReport,
24
+ Plugin,
25
+ PluginInfo,
26
+ Plugins,
27
+ health,
28
+ plugins,
29
+ )
30
+ from laplacekit.core import (
31
+ Batch,
32
+ CapabilityError,
33
+ LaplacePosterior,
34
+ StructureError,
35
+ load,
36
+ per_block,
37
+ predict_outputs,
38
+ sample_outputs,
39
+ save,
40
+ )
41
+ from laplacekit.curvature import (
42
+ DenseGGN,
43
+ DenseHessian,
44
+ DiagGGN,
45
+ LowRankGGN,
46
+ )
47
+ from laplacekit.curvlinops import KFAC
48
+ from laplacekit.front import laplace, predict
49
+ from laplacekit.likelihoods import Bernoulli, Categorical, Gaussian
50
+ from laplacekit.predictive import MC, Bridge, Linearized, Probit, WeightSamples
51
+ from laplacekit.tuning import GridSearch, MarginalLikelihood, Minimize, tune
52
+
53
+ if TYPE_CHECKING:
54
+ import laplacekit_diffusers as diffusers # noqa: F401 # loaded by __getattr__
55
+ import laplacekit_gp as gp # noqa: F401 # loaded by __getattr__
56
+ import laplacekit_heteroscedastic as heteroscedastic # noqa: F401 # loaded by __getattr__
57
+ import laplacekit_marglik as marglik # noqa: F401 # loaded by __getattr__
58
+ import laplacekit_reward as reward # noqa: F401 # loaded by __getattr__
59
+ import laplacekit_subnet as subnet # noqa: F401 # loaded by __getattr__
60
+ import laplacekit_transformers as transformers # noqa: F401 # loaded by __getattr__
61
+
62
+ __all__ = [
63
+ "Batch",
64
+ "Bernoulli",
65
+ "Bridge",
66
+ "CapabilityError",
67
+ "Categorical",
68
+ "DenseGGN",
69
+ "DenseHessian",
70
+ "DiagGGN",
71
+ "Gaussian",
72
+ "GridSearch",
73
+ "HealthCheck",
74
+ "HealthReport",
75
+ "KFAC",
76
+ "LaplacePosterior",
77
+ "Linearized",
78
+ "LowRankGGN",
79
+ "MC",
80
+ "MarginalLikelihood",
81
+ "Minimize",
82
+ "Plugin",
83
+ "PluginInfo",
84
+ "Plugins",
85
+ "Probit",
86
+ "StructureError",
87
+ "WeightSamples",
88
+ "core",
89
+ "curvature",
90
+ "data",
91
+ "distributed",
92
+ "function_space",
93
+ "health",
94
+ "laplace",
95
+ "likelihoods",
96
+ "load",
97
+ "objectives",
98
+ "per_block",
99
+ "plugins",
100
+ "predict",
101
+ "predict_outputs",
102
+ "predictive",
103
+ "priors",
104
+ "sample_outputs",
105
+ "save",
106
+ "subsets",
107
+ "testing",
108
+ "tune",
109
+ "tuning",
110
+ ]
111
+
112
+ if TYPE_CHECKING:
113
+ # Type checkers see the lazy plugin aliases as public, so pyright accepts `lk.gp`.
114
+ # At runtime they stay out of `__all__`: `from laplacekit import *` imports no plugin.
115
+ __all__ += [
116
+ "diffusers",
117
+ "gp",
118
+ "heteroscedastic",
119
+ "marglik",
120
+ "reward",
121
+ "subnet",
122
+ "transformers",
123
+ ]
124
+
125
+
126
+ # Plugin packages reached as `lk.<alias>`, imported on first use. The aliases are not in
127
+ # `__all__`: `from laplacekit import *` would then import transformers, or fail without the
128
+ # plugin.
129
+ _ALIASES = {
130
+ "transformers": "laplacekit_transformers",
131
+ "diffusers": "laplacekit_diffusers",
132
+ "subnet": "laplacekit_subnet",
133
+ "heteroscedastic": "laplacekit_heteroscedastic",
134
+ "reward": "laplacekit_reward",
135
+ "gp": "laplacekit_gp",
136
+ "marglik": "laplacekit_marglik",
137
+ }
138
+
139
+
140
+ def __getattr__(name: str) -> ModuleType:
141
+ """`lk.<alias>` imports the plugin package behind it on first use.
142
+
143
+ Args:
144
+ name: The attribute name, such as `"gp"` for `laplacekit-gp`.
145
+
146
+ Returns:
147
+ The plugin package.
148
+
149
+ Raises:
150
+ AttributeError: `name` is not a plugin alias.
151
+ ImportError: The plugin package is not installed. The message gives the
152
+ `pip install "laplacekit[<alias>]"` command.
153
+ ModuleNotFoundError: The plugin is installed but a module it imports is missing.
154
+ """
155
+
156
+ module = _ALIASES.get(name)
157
+
158
+ if module is None:
159
+ raise AttributeError(f"module 'laplacekit' has no attribute {name!r}")
160
+
161
+ try:
162
+ return importlib.import_module(module)
163
+ except ModuleNotFoundError as e:
164
+ if e.name != module:
165
+ raise # the plugin is there but broken: report what is missing
166
+
167
+ raise ImportError(
168
+ f'lk.{name} needs the laplacekit-{name} package: pip install "laplacekit[{name}]"'
169
+ ) from None
laplacekit/_health.py ADDED
@@ -0,0 +1,461 @@
1
+ """`lk.health()` and `lk.plugins()`: the install, the core and each registered plugin.
2
+
3
+ `health`, `HealthCheck`, `HealthReport`, `Plugin`, `PluginInfo`, `Plugins` and `plugins` are public
4
+ through `laplacekit`; this module is private.
5
+
6
+ A plugin registers one `Plugin` record under the entry-point group `laplacekit.plugins`,
7
+ named after its import package:
8
+
9
+ ```toml
10
+ [project.entry-points."laplacekit.plugins"]
11
+ laplacekit_subnet = "laplacekit_subnet:plugin"
12
+ ```
13
+
14
+ Discovery reads the installed metadata. A plugin is imported only when `lk.health()` or
15
+ `lk.plugins()` runs. A plugin without the entry point is not listed.
16
+ """
17
+
18
+ import importlib
19
+ import inspect
20
+ import re
21
+ from collections.abc import Callable, Iterable, Iterator, Mapping
22
+ from dataclasses import dataclass, field
23
+ from importlib import metadata
24
+ from types import MappingProxyType
25
+ from typing import Literal, get_args
26
+
27
+ import torch
28
+ from packaging.specifiers import InvalidSpecifier, SpecifierSet
29
+ from torch import nn
30
+ from torch.torch_version import TorchVersion
31
+
32
+ import laplacekit.core as core
33
+ from laplacekit.core import Batch, ModelFn
34
+ from laplacekit.likelihoods import Gaussian
35
+
36
+ __all__ = ["HealthCheck", "Plugin", "PluginInfo", "Plugins", "HealthReport", "health", "plugins"]
37
+
38
+ type Status = Literal["ok", "warning", "error"]
39
+
40
+ _GROUP = "laplacekit.plugins"
41
+
42
+ TORCH_FLOOR = "2.15"
43
+ CURVLINOPS = "curvlinops-for-pytorch"
44
+ CURVLINOPS_PIN = "3.0.1"
45
+
46
+ _CORE = "laplacekit"
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class HealthCheck:
51
+ """One result of `lk.health()`.
52
+
53
+ Args:
54
+ name: What was checked, such as `"torch"`.
55
+ status: `"ok"`, `"warning"` (works, with something missing) or `"error"`
56
+ (broken).
57
+ detail: What was found, in one line.
58
+
59
+ Raises:
60
+ ValueError: `status` is not `"ok"`, `"warning"` or `"error"`.
61
+ """
62
+
63
+ name: str
64
+ status: Status
65
+ detail: str
66
+
67
+ def __post_init__(self) -> None:
68
+ if self.status not in get_args(Status.__value__):
69
+ raise ValueError(
70
+ f"HealthCheck status must be 'ok', 'warning' or 'error', got {self.status!r}"
71
+ )
72
+
73
+
74
+ @dataclass(frozen=True)
75
+ class HealthReport:
76
+ """What `lk.health()` found, per package. `print` lists the checks.
77
+
78
+ Args:
79
+ packages: The checks of each package, the core (`"laplacekit"`) first. It is
80
+ stored as a read-only mapping.
81
+ """
82
+
83
+ packages: Mapping[str, tuple[HealthCheck, ...]] = field(default_factory=dict)
84
+
85
+ def __post_init__(self) -> None:
86
+ object.__setattr__(self, "packages", MappingProxyType(dict(self.packages)))
87
+
88
+ @property
89
+ def ok(self) -> bool:
90
+ """True when no check is an error. Warnings still count as ok."""
91
+
92
+ return all(c.status != "error" for checks in self.packages.values() for c in checks)
93
+
94
+ def __str__(self) -> str:
95
+ lines: list[str] = []
96
+
97
+ for pkg, checks in self.packages.items():
98
+ if lines:
99
+ lines.append("")
100
+
101
+ lines.append(pkg)
102
+ lines.extend(f"- {c.status.upper()} {c.name}: {c.detail}" for c in checks)
103
+
104
+ return "\n".join(lines)
105
+
106
+
107
+ @dataclass(frozen=True)
108
+ class Plugin:
109
+ """A plugin's record, the target of its `laplacekit.plugins` entry point.
110
+
111
+ The entry point is named after the plugin's import package.
112
+
113
+ Args:
114
+ supports: PEP 440 specifier set of the laplacekit versions the plugin works with,
115
+ such as `">=0.1a0,<0.2"`. Pre-releases count.
116
+ health: Returns the plugin's own checks for `lk.health()`. The default returns
117
+ none. If it raises, or returns anything but `HealthCheck` objects, `lk.health()`
118
+ reports one `error` check in their place.
119
+
120
+ Raises:
121
+ ValueError: `supports` is not a valid PEP 440 specifier set.
122
+ """
123
+
124
+ supports: str
125
+ health: Callable[[], tuple[HealthCheck, ...]] = lambda: ()
126
+
127
+ def __post_init__(self) -> None:
128
+ try:
129
+ SpecifierSet(self.supports)
130
+ except InvalidSpecifier:
131
+ raise ValueError(
132
+ "Plugin supports must be a PEP 440 specifier set such as '>=0.1a0,<0.2', "
133
+ f"got {self.supports!r}"
134
+ ) from None
135
+
136
+
137
+ @dataclass(frozen=True)
138
+ class PluginInfo:
139
+ """One registered plugin: its package metadata, its `supports` range, what it provides.
140
+
141
+ `lk.plugins()` builds these. `print` shows one.
142
+
143
+ Args:
144
+ name: The distribution's name, or the entry name when the entry point has no
145
+ distribution.
146
+ version: The distribution's version (`""` without a distribution).
147
+ summary: The distribution's summary (`""` without one).
148
+ supported: Whether the installed laplacekit is in `supports`. False when the
149
+ plugin could not be loaded.
150
+ supports: The record's `supports` range (`""` when the plugin could not be loaded).
151
+ provides: Each name in the plugin module's `__all__`, other than its `Plugin`
152
+ record and `health` function, paired with the first sentence of its docstring
153
+ (`""` without one).
154
+ error: Why the plugin could not be loaded; `provides` is then empty. `None` when
155
+ it loaded.
156
+ """
157
+
158
+ name: str
159
+ version: str
160
+ summary: str
161
+ supported: bool
162
+ supports: str
163
+ provides: tuple[tuple[str, str], ...] = ()
164
+ error: str | None = None
165
+
166
+ def __str__(self) -> str:
167
+ lines = [f"{self.name} {self.version} {self.summary}".rstrip()]
168
+
169
+ if self.error is not None:
170
+ lines.append(f" error: {self.error}")
171
+ elif not self.supported:
172
+ lines.append(f" not supported: needs laplacekit {self.supports}")
173
+
174
+ lines.extend(f" {name}: {doc}" if doc else f" {name}" for name, doc in self.provides)
175
+
176
+ return "\n".join(lines)
177
+
178
+
179
+ @dataclass(frozen=True)
180
+ class Plugins:
181
+ """The registered plugins. `print` lists them.
182
+
183
+ It iterates, indexes and has a length like a tuple of `PluginInfo`.
184
+
185
+ Args:
186
+ plugins: One `PluginInfo` per plugin, sorted by distribution name.
187
+ """
188
+
189
+ plugins: tuple[PluginInfo, ...] = ()
190
+
191
+ def __iter__(self) -> Iterator[PluginInfo]:
192
+ return iter(self.plugins)
193
+
194
+ def __len__(self) -> int:
195
+ return len(self.plugins)
196
+
197
+ def __getitem__(self, i: int, /) -> PluginInfo:
198
+ return self.plugins[i]
199
+
200
+ def __str__(self) -> str:
201
+ return "\n\n".join(str(p) for p in self.plugins)
202
+
203
+
204
+ def _torch() -> HealthCheck:
205
+ version = TorchVersion(torch.__version__)
206
+
207
+ if version < TORCH_FLOOR:
208
+ return HealthCheck("torch", "error", f"{version} is older than the required {TORCH_FLOOR}")
209
+
210
+ return HealthCheck("torch", "ok", f"{version} (>= {TORCH_FLOOR})")
211
+
212
+
213
+ def _curvlinops() -> HealthCheck:
214
+ try:
215
+ version = metadata.version(CURVLINOPS)
216
+ except metadata.PackageNotFoundError:
217
+ return HealthCheck(CURVLINOPS, "error", f"not installed; KFAC needs =={CURVLINOPS_PIN}")
218
+
219
+ if version != CURVLINOPS_PIN:
220
+ return HealthCheck(
221
+ CURVLINOPS,
222
+ "error",
223
+ f"{version} installed, but the KFAC adapter is pinned to =={CURVLINOPS_PIN}",
224
+ )
225
+
226
+ return HealthCheck(CURVLINOPS, "ok", version)
227
+
228
+
229
+ def _autograd() -> HealthCheck:
230
+ """Probe a 2-layer MLP on the CPU."""
231
+
232
+ with torch.random.fork_rng(devices=[]): # leaves the caller's RNG state alone
233
+ torch.manual_seed(0)
234
+ module = nn.Sequential(nn.Linear(3, 4), nn.Tanh(), nn.Linear(4, 2))
235
+ x = torch.randn(2, 3)
236
+ y = torch.randn(2, 2)
237
+
238
+ caps = core.probe(ModelFn.from_module(module), Gaussian(sigma=1.0), Batch(x, y))
239
+
240
+ found = {"vjp": caps.vjp, "jvp": caps.jvp, "vmap": caps.vmap, "vjp_twice": caps.vjp_twice}
241
+ missing = [t for t, ok in found.items() if not ok]
242
+
243
+ if missing:
244
+ why = "; ".join(f"{t}: {caps.failures.get(t, 'failed')}" for t in missing)
245
+ return HealthCheck("autograd", "error", f"the probe of a 2-layer MLP failed: {why}")
246
+
247
+ return HealthCheck("autograd", "ok", f"{', '.join(found)} work on a 2-layer CPU MLP")
248
+
249
+
250
+ def _float64() -> HealthCheck:
251
+ x = torch.ones(2, 2, dtype=torch.float64)
252
+ torch.linalg.cholesky(x + torch.eye(2, dtype=torch.float64))
253
+
254
+ return HealthCheck("float64", "ok", "tensors and a Cholesky factor in float64 work")
255
+
256
+
257
+ _CORE_CHECKS: tuple[tuple[str, Callable[[], HealthCheck]], ...] = (
258
+ ("torch", _torch),
259
+ (CURVLINOPS, _curvlinops),
260
+ ("autograd", _autograd),
261
+ ("float64", _float64),
262
+ )
263
+
264
+
265
+ def _core() -> tuple[HealthCheck, ...]:
266
+ """Run each core check. One that raises becomes an `error` check under its name."""
267
+
268
+ checks: list[HealthCheck] = []
269
+
270
+ for name, check in _CORE_CHECKS:
271
+ try:
272
+ checks.append(check())
273
+ except Exception as e:
274
+ checks.append(HealthCheck(name, "error", f"{type(e).__name__}: {e}"))
275
+
276
+ return tuple(checks)
277
+
278
+
279
+ def _run(load: Callable[[], Callable[[], Iterable[object]]]) -> tuple[HealthCheck, ...]:
280
+ """Load and call one plugin's `health`. Any exception becomes one `error` check."""
281
+
282
+ try:
283
+ checks = tuple(load()())
284
+ except Exception as e:
285
+ return (HealthCheck("health", "error", f"{type(e).__name__}: {e}"),)
286
+
287
+ good = tuple(c for c in checks if isinstance(c, HealthCheck))
288
+
289
+ if len(good) < len(checks):
290
+ wrong = ", ".join(
291
+ sorted({type(c).__name__ for c in checks if not isinstance(c, HealthCheck)})
292
+ )
293
+ return (
294
+ HealthCheck(
295
+ "health", "error", f"health() must return HealthCheck objects, got {wrong}"
296
+ ),
297
+ )
298
+
299
+ return good
300
+
301
+
302
+ def _dist_name(ep: metadata.EntryPoint) -> str:
303
+ return ep.dist.name if ep.dist is not None else ep.name
304
+
305
+
306
+ def _load(ep: metadata.EntryPoint) -> Plugin:
307
+ """Import the entry point's target. Anything but a `Plugin` raises `TypeError`."""
308
+
309
+ target = ep.load()
310
+
311
+ if not isinstance(target, Plugin):
312
+ raise TypeError(
313
+ f"entry point {ep.name!r} ({ep.value}) must name an lk.Plugin, "
314
+ f"got {type(target).__name__}"
315
+ )
316
+
317
+ return target
318
+
319
+
320
+ def _supported(plugin: Plugin, version: str) -> bool:
321
+ return SpecifierSet(plugin.supports).contains(version, prereleases=True)
322
+
323
+
324
+ def _supports(ep: metadata.EntryPoint, plugin: Plugin) -> HealthCheck:
325
+ version = metadata.version(_CORE)
326
+
327
+ if not _supported(plugin, version):
328
+ detail = f"{_dist_name(ep)} supports {plugin.supports}, installed laplacekit {version}"
329
+ return HealthCheck("supports", "error", detail)
330
+
331
+ return HealthCheck("supports", "ok", f"laplacekit {version} is in {plugin.supports}")
332
+
333
+
334
+ def _plugin(ep: metadata.EntryPoint) -> tuple[HealthCheck, ...]:
335
+ """The `supports` check, then the plugin's own. A record that fails to load is one error."""
336
+
337
+ try:
338
+ plugin = _load(ep)
339
+ except Exception as e:
340
+ return (HealthCheck("plugin", "error", f"{type(e).__name__}: {e}"),)
341
+
342
+ return (_supports(ep, plugin), *_run(lambda: plugin.health))
343
+
344
+
345
+ def _first_line(obj: object) -> str:
346
+ """The first sentence of the docstring, joined across wrapped lines."""
347
+
348
+ # Any other value would show the docstring of its type.
349
+ if not (inspect.isclass(obj) or inspect.isroutine(obj) or inspect.ismodule(obj)):
350
+ return ""
351
+
352
+ doc = inspect.getdoc(obj)
353
+
354
+ if not doc:
355
+ return ""
356
+
357
+ paragraph = " ".join(doc.split("\n\n")[0].split())
358
+
359
+ return re.split(r"(?<=[.!?])\s", paragraph, maxsplit=1)[0]
360
+
361
+
362
+ def _provides(ep: metadata.EntryPoint, plugin: Plugin) -> tuple[tuple[str, str], ...]:
363
+ module = importlib.import_module(ep.module)
364
+ names: Iterable[str] = vars(module).get("__all__", ())
365
+ found: list[tuple[str, str]] = []
366
+
367
+ for name in names:
368
+ obj = getattr(module, name)
369
+
370
+ if obj is plugin or obj is plugin.health:
371
+ continue
372
+
373
+ found.append((name, _first_line(obj)))
374
+
375
+ return tuple(found)
376
+
377
+
378
+ def _info(ep: metadata.EntryPoint) -> PluginInfo:
379
+ dist = ep.dist
380
+ version = dist.version if dist is not None else ""
381
+ summary = (dist.metadata.get("Summary") or "") if dist is not None else ""
382
+
383
+ try:
384
+ plugin = _load(ep)
385
+ provides = _provides(ep, plugin)
386
+ except Exception as e:
387
+ error = f"{type(e).__name__}: {e}"
388
+ return PluginInfo(_dist_name(ep), version, summary, False, "", error=error)
389
+
390
+ supported = _supported(plugin, metadata.version(_CORE))
391
+
392
+ return PluginInfo(_dist_name(ep), version, summary, supported, plugin.supports, provides)
393
+
394
+
395
+ def plugins() -> Plugins:
396
+ """List the plugins registered under `laplacekit.plugins`, by distribution name.
397
+
398
+ Each plugin is imported. One that fails to import, or whose entry point names something
399
+ other than a `Plugin`, is listed with its `error`.
400
+
401
+ Returns:
402
+ A `Plugins`, one `PluginInfo` per entry point, sorted by distribution name.
403
+ """
404
+
405
+ found = (_info(ep) for ep in metadata.entry_points(group=_GROUP))
406
+
407
+ return Plugins(tuple(sorted(found, key=lambda p: p.name)))
408
+
409
+
410
+ def health() -> HealthReport:
411
+ """HealthCheck the install: the core, then each plugin registered under `laplacekit.plugins`.
412
+
413
+ Core checks: the torch version floor, the exact Curvlinops pin, a probe of a 2-layer
414
+ CPU MLP (vjp, jvp, vmap, vjp_twice) and float64 support. Each plugin gets a `supports`
415
+ check (is the installed laplacekit in its range?), then its own checks. A check or a
416
+ plugin `health` that raises becomes one `error` check naming the exception, and so does
417
+ a plugin that fails to load. Plugins are listed by entry name. An entry name registered
418
+ more than once is one `error` check naming each registration, and none of them runs.
419
+ The entry name `"laplacekit"` is reserved: registering it adds one `error` check to
420
+ the core's checks, and the plugin does not run.
421
+
422
+ Returns:
423
+ A `HealthReport` with the core's checks under `"laplacekit"` first, then each plugin's
424
+ checks under its entry name.
425
+ """
426
+
427
+ packages: dict[str, tuple[HealthCheck, ...]] = {_CORE: _core()}
428
+ by_name: dict[str, list[metadata.EntryPoint]] = {}
429
+
430
+ for ep in metadata.entry_points(group=_GROUP):
431
+ by_name.setdefault(ep.name, []).append(ep)
432
+
433
+ for name in sorted(by_name):
434
+ eps = by_name[name]
435
+
436
+ if name == _CORE: # a plugin can't replace the core's checks
437
+ packages[_CORE] += (_duplicate(name, eps),)
438
+ elif len(eps) > 1:
439
+ packages[name] = (_duplicate(name, eps),)
440
+ else:
441
+ packages[name] = _plugin(eps[0])
442
+
443
+ return HealthReport(packages)
444
+
445
+
446
+ def _duplicate(name: str, eps: list[metadata.EntryPoint]) -> HealthCheck:
447
+ def where(ep: metadata.EntryPoint) -> str:
448
+ dist = ep.dist.name if ep.dist is not None else "an unknown distribution"
449
+
450
+ return f"{ep.value} (from {dist})"
451
+
452
+ regs = ", ".join(where(ep) for ep in eps)
453
+
454
+ if name == _CORE:
455
+ return HealthCheck(
456
+ "health", "error", f"entry name {name!r} is reserved for the core: {regs}"
457
+ )
458
+
459
+ return HealthCheck(
460
+ "health", "error", f"entry name {name!r} is registered {len(eps)} times: {regs}"
461
+ )