nervecode 0.1.0__py3-none-any.whl

nervecode/utils/seed.py

@@ -0,0 +1,161 @@
+"""Seeding helpers to make runs reproducible across local and CI.
+
+These utilities intentionally keep a small surface and no hard dependency on
+NumPy. If NumPy is available, its global RNG is also seeded and restored.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import os
+import random
+import types
+import typing
+
+
+def _maybe_import_numpy() -> typing.Any | None:
+    """Return NumPy module if available, else None."""
+    try:
+        return importlib.import_module("numpy")
+    except Exception:  # pragma: no cover - optional dependency
+        return None
+
+
+def _maybe_import_torch() -> typing.Any | None:
+    """Return a torch-like module if available with required attributes, else None."""
+    try:
+        t = importlib.import_module("torch")
+    except Exception:  # pragma: no cover - torch missing
+        return None
+    required = all(hasattr(t, name) for name in ("manual_seed", "get_rng_state", "set_rng_state"))
+    return t if required else None
+
+
+def seed_from_env(
+    env_var: str = "NERVECODE_SEED",
+    default: int = 1234,
+    *,
+    set_env_if_missing: bool = False,
+) -> int:
+    """Return an integer seed sourced from an environment variable.
+
+    - If ``env_var`` is set and parseable as an int, return its value.
+    - Otherwise, return ``default``. If ``set_env_if_missing`` is True, also set
+      ``os.environ[env_var]`` to the default value for downstream tools.
+    """
+    raw = os.environ.get(env_var)
+    if raw is not None:
+        try:
+            return int(raw)
+        except ValueError:  # Fall back to default on malformed input
+            pass
+    if set_env_if_missing:
+        os.environ[env_var] = str(default)
+    return default
+
+
+def seed_everything(seed: int, *, deterministic: bool = True) -> None:
+    """Seed Python, optional NumPy, and PyTorch RNGs.
+
+    Also toggles PyTorch deterministic settings when ``deterministic`` is True to
+    minimize nondeterministic kernels. On CUDA setups, call this as early as
+    possible in process startup for best effect.
+    """
+    # Hash-based ops reproducibility (effective at interpreter start;
+    # set anyway for child processes invoked by test runners)
+    os.environ["PYTHONHASHSEED"] = str(seed)
+
+    random.seed(seed)
+
+    np = _maybe_import_numpy()
+    if np is not None:  # pragma: no branch - trivial branch
+        np.random.seed(seed)
+
+    t = _maybe_import_torch()
+    if t is not None:
+        t.manual_seed(seed)
+        if hasattr(t, "cuda") and t.cuda.is_available():  # pragma: no cover
+            t.cuda.manual_seed_all(seed)
+
+    # Configure PyTorch deterministic behavior as far as feasible.
+    t = _maybe_import_torch()
+    if t is not None and hasattr(t, "use_deterministic_algorithms"):
+        # warn_only=True avoids raising on ops without deterministic kernels
+        with contextlib.suppress(Exception):  # pragma: no cover - older/newer API differences
+            t.use_deterministic_algorithms(bool(deterministic), warn_only=True)
+
+    # cuDNN knobs (safe on CPU-only builds; no-ops)
+    # cuDNN knobs (safe on CPU-only builds; no-ops)
+    try:
+        cudnn = importlib.import_module("torch.backends.cudnn")
+    except Exception:  # pragma: no cover - backend not available
+        cudnn = None
+    if cudnn is not None:  # pragma: no branch
+        cudnn_mod: typing.Any = cudnn
+        try:
+            cudnn_mod.deterministic = bool(deterministic)
+            cudnn_mod.benchmark = not bool(deterministic)
+        except Exception:  # pragma: no cover - attributes may be missing
+            pass
+
+
+class temp_seed(contextlib.AbstractContextManager[None]):
+    """Temporarily set RNG seeds and restore previous states on exit.
+
+    This context manager saves Python's ``random`` state, optional NumPy's global
+    RNG state, and PyTorch CPU/CUDA RNG states. It then calls ``seed_everything``
+    with the provided seed and restores the saved states when leaving the context.
+    """
+
+    def __init__(self, seed: int, *, deterministic: bool = True) -> None:
+        self._seed = int(seed)
+        self._deterministic = bool(deterministic)
+
+        self._py_state: tuple[typing.Any, ...] | None = None
+        self._np_state: typing.Any | None = None
+        self._torch_cpu_state: typing.Any | None = None
+        self._torch_cuda_states: typing.Any | None = None
+
+    def __enter__(self) -> None:
+        # Save current states
+        self._py_state = random.getstate()
+        np = _maybe_import_numpy()
+        if np is not None:  # pragma: no branch
+            self._np_state = np.random.get_state()
+        t = _maybe_import_torch()
+        if t is not None:
+            self._torch_cpu_state = t.get_rng_state()
+            if hasattr(t, "cuda") and t.cuda.is_available():  # pragma: no cover
+                self._torch_cuda_states = t.cuda.get_rng_state_all()
+        # Apply temporary seed
+        seed_everything(self._seed, deterministic=self._deterministic)
+        return None
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        # Restore saved states
+        if self._py_state is not None:
+            random.setstate(self._py_state)
+        np = _maybe_import_numpy()
+        if np is not None and self._np_state is not None:  # pragma: no branch
+            np.random.set_state(self._np_state)
+        t = _maybe_import_torch()
+        if t is not None and self._torch_cpu_state is not None:
+            t.set_rng_state(self._torch_cpu_state)
+            if (
+                hasattr(t, "cuda") and self._torch_cuda_states is not None and t.cuda.is_available()
+            ):  # pragma: no cover
+                t.cuda.set_rng_state_all(self._torch_cuda_states)
+        return None
+
+
+__all__ = [
+    "seed_everything",
+    "seed_from_env",
+    "temp_seed",
+]

nervecode-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: nervecode
+Version: 0.1.0
+Summary: Intrinsic surprise scoring for PyTorch via statistical coding.
+Project-URL: Homepage, https://gitlab.com/domezsolt/nervecode
+Project-URL: Repository, https://gitlab.com/domezsolt/nervecode
+Author: Zsolt Döme
+License: MIT License
+        
+        Copyright (c) 2026 Nervecode Maintainers
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+License-File: LICENSE
+Keywords: coding,ml,pytorch,research,surprise
+Requires-Python: >=3.10
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: logging
+Requires-Dist: loguru>=0.7; extra == 'logging'
+Requires-Dist: rich>=13; extra == 'logging'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Requires-Dist: seaborn>=0.13; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# Nervecode Docs
+
+This directory will contain documentation for the Nervecode project.
+
+## Developer Setup
+
+- Install dev tools (in your virtualenv): `pip install -e .[dev]`
+- Install git hooks: `pre-commit install`
+- Run on all files once: `pre-commit run --all-files`
+
+Included hooks:
+- Formatting: `ruff-format`
+- Linting and import sorting: `ruff` (with `--fix`)
+- Type-checking: `mypy`
+
+## Tests
+
+- Unit tests: `pytest tests/unit` (fast correctness checks)
+- Integration tests: `pytest tests/integration` (heavier, cross-module)
+- Smoke tests: `pytest tests/smoke` (repo wiring and API surface)
+
+### Deterministic runs
+
+- Tests auto-seed RNGs per test using `NERVECODE_SEED` (default: `1234`).
+- You can control reproducibility in your own scripts via:
+  ```python
+  from nervecode.utils.seed import seed_everything, seed_from_env
+  seed_everything(seed_from_env())
+  ```
+
+## Performance Notes
+
+- Overhead estimates and guidance for pooled Conv2d coding: see `docs/overhead.md`.
+- Scaling and tradeoffs for layer selection and coding dimension: see `docs/scaling.md`.

nervecode-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+nervecode/__init__.py,sha256=xPUsGwV4JD71a5lClC6TqiOzEVWkTdwh8RRtaz53kNE,17734
+nervecode/_version.py,sha256=MtrcXrZW_diNtg4lJtIVD5xrp0F8fhI_Q-Y-TLVm3ws,280
+nervecode/core/__init__.py,sha256=MG6Q-13HOQ8HeN6CsisffNqUOsnCDywiUFHKzgJHFVQ,497
+nervecode/core/assignment.py,sha256=wS8_I9Exb63dg1VAm6OP8QgUhDxRT2hWr_aHhp81z54,7080
+nervecode/core/codebook.py,sha256=M6KaE71w5lQE3QdgCzwnRa6_trLebrDppnYQFP1ih6Y,7327
+nervecode/core/shapes.py,sha256=wBjGh_Gk4Xt6nITsYJS0wf-v-WR7YFSkzI-lhUk2OL0,3612
+nervecode/core/temperature.py,sha256=kBL99jxRFjZe_oiCL-NzveTVCxHoDBmX8JfvtHjePIY,7930
+nervecode/core/trace.py,sha256=EyTlthcaCDDKamtLhcC35sESHt8LauUKZ2exquAmwkE,6936
+nervecode/core/types.py,sha256=YJylBQiqICQCjU4Y_DfmVbvIl8yCXtLa_Dcedmne7cM,4805
+nervecode/integration/__init__.py,sha256=eDP_VIlczERiMmIxaggtzvsDsbamI5WZWIlG-R0VJJM,243
+nervecode/layers/__init__.py,sha256=DRYdTi2uSlp9m1wq8-Zbphm6c0PgwDaIsZWsCHdRPeM,374
+nervecode/layers/base.py,sha256=9QOqCpa926EdotVhRp6apLZyrBApGDtlik_d4TVf4tg,12161
+nervecode/layers/conv.py,sha256=ROKyq1bMbjwmltRwHN5oMh3ljnO_CsIs4rPU9c-QteI,7095
+nervecode/layers/linear.py,sha256=YXX-0iNQ0r05ExD4JPkR3R2FJZsqPHJtfDB5SFwKLsQ,7383
+nervecode/layers/reducers.py,sha256=7PN2ZO2hsJr5aXQye3d03nvM0fXY40uYd5TCMYwg53A,2879
+nervecode/layers/wrap.py,sha256=UEhkFLw8U54ZLl0BjrfsZiMH1_7nlQQLAcWhhbEIHb0,7928
+nervecode/scoring/__init__.py,sha256=ULUQbzb51OpakpLC_o8Ra6DC6CflmuxM-t3GmI0IWuU,583
+nervecode/scoring/aggregator.py,sha256=cSv8vfpgRWfWExJIQ6bPqHbjMu_uCJCnNnW2Gd8Cb8Y,13297
+nervecode/scoring/calibrator.py,sha256=-Wm6te9XzpTYX0uLV_qBgEHSfcM403Ilw_4gmaWiRlg,16326
+nervecode/scoring/types.py,sha256=EmK0NO0muvjb5Ah272-g_y6Iuzc7WkCoZMolbSrvbxM,1087
+nervecode/training/__init__.py,sha256=_YW_FlGgsTHNFaKm7frK9XemV7a-XWoeBcRSrePzadI,580
+nervecode/training/diagnostics.py,sha256=0Peh4pOTnPSvJ4_UNXHKVPwf_dunOpq_vg7EjcCijRc,6606
+nervecode/training/loss.py,sha256=rxreNiBu9LlxlHHdXhcH207o68VSGZRuBqQ6-xwTFwU,7278
+nervecode/training/updaters.py,sha256=pSzbvjAacN8wTWXUboBRKrlgjoX4rX-3KquMAB7D1s4,7072
+nervecode/utils/__init__.py,sha256=KUAQvrOQuAaTlPRmy3UuebKSO7FJZd5dF65s0fsfKRw,309
+nervecode/utils/overhead.py,sha256=3hr3JwNKkDphPMOAs1Vkrq7CTRxR6X_qwfUx5nUDlxI,6606
+nervecode/utils/seed.py,sha256=VMj2Vtr8OYEz0Gc0PJWdxow4He6Wv8tEoq9MgGb0mZk,5867
+nervecode-0.1.0.dist-info/METADATA,sha256=oM2aV6Vsau0cjAq6XRzxilZ7c943q7zAocikHVbiPaQ,3294
+nervecode-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nervecode-0.1.0.dist-info/licenses/LICENSE,sha256=WP83ux1S7U3IyieW0mPA_Q1mpbJHK5ipX3_bniUAgYM,1079
+nervecode-0.1.0.dist-info/RECORD,,

nervecode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nervecode-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Nervecode Maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+