ber-equalization-studio 0.1.2__tar.gz → 0.1.3__tar.gz

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ber-equalization-studio
-Version: 0.1.2
+Version: 0.1.3
 Summary: Research studio for BER equalization experiments in nonlinear optical links.
 Keywords: ber,equalization,optical-communications,photonics,pytorch
 Classifier: Development Status :: 3 - Alpha
@@ -9,6 +9,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.10

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ber-equalization-studio"
-version = "0.1.2"
+version = "0.1.3"
 description = "Research studio for BER equalization experiments in nonlinear optical links."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,6 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Scientific/Engineering :: Physics",
 ]
@@ -52,6 +53,9 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+ber_equalization_studio = ["py.typed", "__init__.pyi"]
+
 [[tool.uv.index]]
 name = "pytorch-cu130"
 url = "https://download.pytorch.org/whl/cu130"

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio/__init__.py

@@ -1,5 +1,13 @@
-"""Convenient research API for BER equalization experiments."""
+"""Notebook-friendly API for BER equalization experiments.
 
+The top-level package exports the objects that are most useful in notebooks:
+`Studio` for running experiments, config dataclasses for reproducible setups,
+model registry helpers, and result table helpers.
+"""
+
+from typing import Any
+
+from ber_equalization_studio.api import RunResult, Studio, StudyResult, run, sweep
 from ber_equalization_studio.config import (
     DataConfig,
     EvaluationConfig,
@@ -9,6 +17,7 @@ from ber_equalization_studio.config import (
     StudioConfig,
     TrainingConfig,
 )
+from ber_equalization_studio.models import available_models, build_model
 
 __all__ = [
     "DataConfig",
@@ -32,27 +41,13 @@ __all__ = [
 ]
 
 
-def __getattr__(name):
+def __getattr__(name: str) -> Any:
     if name in {"ExperimentRunner", "run_experiment"}:
         from ber_equalization_studio.experiment import ExperimentRunner, run_experiment
 
         return {"ExperimentRunner": ExperimentRunner, "run_experiment": run_experiment}[name]
-    if name in {"available_models", "build_model"}:
-        from ber_equalization_studio.models import available_models, build_model
-
-        return {"available_models": available_models, "build_model": build_model}[name]
     if name in {"compare_results", "load_result_table"}:
         from ber_equalization_studio.results import compare_results, load_result_table
 
         return {"compare_results": compare_results, "load_result_table": load_result_table}[name]
-    if name in {"RunResult", "Studio", "StudyResult", "run", "sweep"}:
-        from ber_equalization_studio.api import RunResult, Studio, StudyResult, run, sweep
-
-        return {
-            "RunResult": RunResult,
-            "Studio": Studio,
-            "StudyResult": StudyResult,
-            "run": run,
-            "sweep": sweep,
-        }[name]
     raise AttributeError(name)

ber_equalization_studio-0.1.3/src/ber_equalization_studio/__init__.pyi

@@ -0,0 +1,20 @@
+from ber_equalization_studio.api import RunResult as RunResult
+from ber_equalization_studio.api import Studio as Studio
+from ber_equalization_studio.api import StudyResult as StudyResult
+from ber_equalization_studio.api import run as run
+from ber_equalization_studio.api import sweep as sweep
+from ber_equalization_studio.config import DataConfig as DataConfig
+from ber_equalization_studio.config import EvaluationConfig as EvaluationConfig
+from ber_equalization_studio.config import ExperimentConfig as ExperimentConfig
+from ber_equalization_studio.config import ModelConfig as ModelConfig
+from ber_equalization_studio.config import OutputConfig as OutputConfig
+from ber_equalization_studio.config import StudioConfig as StudioConfig
+from ber_equalization_studio.config import TrainingConfig as TrainingConfig
+from ber_equalization_studio.experiment import ExperimentRunner as ExperimentRunner
+from ber_equalization_studio.experiment import run_experiment as run_experiment
+from ber_equalization_studio.models import available_models as available_models
+from ber_equalization_studio.models import build_model as build_model
+from ber_equalization_studio.results import compare_results as compare_results
+from ber_equalization_studio.results import load_result_table as load_result_table
+
+__all__: list[str]

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio/api.py

@@ -4,7 +4,7 @@ import itertools
 import re
 from dataclasses import fields, replace
 from pathlib import Path
-from typing import Any, Iterable
+from typing import TYPE_CHECKING, Any, Iterable
 
 from ber_equalization_studio.config import (
     DataConfig,
@@ -16,6 +16,9 @@ from ber_equalization_studio.config import (
     TrainingConfig,
 )
 
+if TYPE_CHECKING:
+    import pandas as pd
+
 
 _CONFIG_SECTIONS = {
     "data": DataConfig,
@@ -165,7 +168,12 @@ def _pd():
 
 
 class RunResult:
-    """Notebook-friendly wrapper around a single experiment run."""
+    """Notebook-friendly wrapper around a completed experiment run.
+
+    Use `results` for the metrics table, `best()` to select the best model row,
+    `history()` for raw training curves, and the plotting helpers for inline
+    Plotly figures.
+    """
 
     def __init__(self, payload: dict[str, Any], config: StudioConfig):
         self.payload = payload
@@ -173,14 +181,20 @@ class RunResult:
 
     @property
     def run_dir(self) -> Path:
+        """Directory containing config, metrics, checkpoints, histories, and plots."""
+
         return Path(self.payload["run_dir"])
 
     @property
     def results_csv(self) -> Path:
+        """Path to the CSV table with one row per evaluated model."""
+
         return Path(self.payload["results_csv"])
 
     @property
-    def results(self):
+    def results(self) -> "pd.DataFrame":
+        """Return the run metrics as a pandas DataFrame."""
+
         from ber_equalization_studio.results import flatten_metrics, load_result_table
 
         if self.results_csv.exists():
@@ -189,9 +203,23 @@ class RunResult:
 
     @property
     def histories(self) -> dict[str, dict[str, Any]]:
+        """Training histories keyed by canonical model name."""
+
         return self.payload.get("histories", {})
 
-    def best(self, by: str = "equalized_ber", ascending: bool | None = None) -> pd.Series:
+    def best(self, by: str = "equalized_ber", ascending: bool | None = None) -> "pd.Series":
+        """Return the best result row sorted by a metric column.
+
+        Parameters
+        ----------
+        by:
+            Result column to rank by, for example `equalized_ber`,
+            `improvement_db`, or `samples_per_sec`.
+        ascending:
+            Sort direction. When omitted, lower is better for error metrics and
+            higher is better for improvement, accuracy, and throughput metrics.
+        """
+
         df = self.results
         if by not in df.columns:
             raise KeyError(f"Column not found in results: {by}")
@@ -199,19 +227,28 @@ class RunResult:
             ascending = by not in {"improvement_rel", "improvement_db", "accuracy", "samples_per_sec"}
         return df.sort_values(by, ascending=ascending).iloc[0]
 
-    def compare(self, sort_by: str = "equalized_ber") -> pd.DataFrame:
+    def compare(self, sort_by: str = "equalized_ber") -> "pd.DataFrame":
+        """Return a publication-friendly comparison table for this run."""
+
         from ber_equalization_studio.results import compare_results
 
         return compare_results(self.results_csv, sort_by=sort_by)
 
     def history(self, model: str | None = None) -> dict[str, Any]:
+        """Return the saved training history for one model.
+
+        Pass `model` when the run evaluated more than one model.
+        """
+
         if model is None:
             if len(self.histories) != 1:
                 raise ValueError("Pass model=... when a run contains more than one model.")
             return next(iter(self.histories.values()))
         return self.histories[model]
 
-    def plot_history(self, model: str | None = None, metric: str = "ber"):
+    def plot_history(self, model: str | None = None, metric: str = "ber") -> Any:
+        """Build an inline training-history figure for `ber` or `loss`."""
+
         from ber_equalization_studio.visualization import history_figure
 
         history = self.history(model)
@@ -224,7 +261,9 @@ class RunResult:
         y: str = "equalized_ber",
         color: str | None = None,
         kind: str = "bar",
-    ):
+    ) -> Any:
+        """Build an inline comparison figure from the result table."""
+
         from ber_equalization_studio.visualization import comparison_figure
 
         return comparison_figure(self.results, x=x, y=y, color=color, kind=kind)
@@ -234,14 +273,16 @@ class RunResult:
 
 
 class StudyResult:
-    """Result object for a sequence of runs, usually produced by Studio.sweep()."""
+    """Result object for a sequence of runs produced by `Studio.sweep()`."""
 
     def __init__(self, runs: list[RunResult], parameters: list[dict[str, Any]]):
         self.runs = runs
         self.parameters = parameters
 
     @property
-    def results(self):
+    def results(self) -> "pd.DataFrame":
+        """Concatenate all sweep run result tables and attach sweep parameters."""
+
         pd = _pd()
         frames: list[pd.DataFrame] = []
         for index, run in enumerate(self.runs):
@@ -254,7 +295,9 @@ class StudyResult:
             return pd.DataFrame()
         return pd.concat(frames, ignore_index=True)
 
-    def best(self, by: str = "equalized_ber", ascending: bool | None = None) -> pd.Series:
+    def best(self, by: str = "equalized_ber", ascending: bool | None = None) -> "pd.Series":
+        """Return the best row across all runs in the sweep."""
+
         df = self.results
         if by not in df.columns:
             raise KeyError(f"Column not found in results: {by}")
@@ -267,7 +310,9 @@ class StudyResult:
         x: str = "trainable_params",
         y: str = "equalized_ber",
         color: str | None = "model_type",
-    ):
+    ) -> Any:
+        """Build a scatter plot for accuracy/complexity tradeoff analysis."""
+
         from ber_equalization_studio.visualization import comparison_figure
 
         return comparison_figure(self.results, x=x, y=y, color=color, kind="scatter")
@@ -277,7 +322,14 @@ class StudyResult:
 
 
 class Studio:
-    """High-level research interface for notebooks and scripts."""
+    """High-level research interface for notebooks and scripts.
+
+    `Studio` keeps a reusable base configuration and lets each call override
+    only the fields that matter for the current experiment. Short aliases such
+    as `data_dirs`, `out_dir`, `epochs`, `lr`, `context_k`, and `max_test_files`
+    are accepted in addition to dotted config keys like
+    `training.early_stopping_patience`.
+    """
 
     def __init__(
         self,
@@ -285,13 +337,30 @@ class Studio:
         legacy_path: str | Path | None = None,
         **defaults: Any,
     ):
+        """Create a studio with optional default configuration overrides.
+
+        Parameters
+        ----------
+        base_config:
+            Existing structured config to use as the starting point.
+        legacy_path:
+            Optional path to a custom `ber_equalization.py` backend.
+        **defaults:
+            Default config overrides. Examples: `data_dirs=["../test"]`,
+            `out_dir="notebook_runs"`, `device="cuda"`, `epochs=10`.
+        """
+
         self.base_config = _apply_updates(base_config or StudioConfig(), defaults)
         self.legacy_path = Path(legacy_path) if legacy_path is not None else None
 
     def config(self, **updates: Any) -> StudioConfig:
+        """Return a `StudioConfig` with temporary overrides applied."""
+
         return _apply_updates(self.base_config, updates)
 
-    def models(self) -> pd.DataFrame:
+    def models(self) -> "pd.DataFrame":
+        """List available model names and short architecture descriptions."""
+
         from ber_equalization_studio.models import available_models
 
         rows = [{"model": name, "description": note} for name, note in available_models().items()]
@@ -303,6 +372,20 @@ class Studio:
         models: str | Iterable[str] | None = None,
         **updates: Any,
     ) -> RunResult:
+        """Run one experiment and return a notebook-friendly `RunResult`.
+
+        Parameters
+        ----------
+        name:
+            Experiment folder name inside `out_dir`.
+        models:
+            One model name, a comma-separated string, or an iterable of model
+            names. When omitted, `StudioConfig.experiment.models` is used.
+        **updates:
+            Per-run config overrides such as `epochs=5`, `lr=1e-3`,
+            `context_k=32`, or `evaluation.ber_scale_steps=20`.
+        """
+
         if models is not None:
             updates["models"] = models
         updates["experiment_name"] = name
@@ -319,6 +402,12 @@ class Studio:
         models: str | Iterable[str] | None = None,
         **updates: Any,
     ) -> StudyResult:
+        """Run a Cartesian sweep over config values.
+
+        `grid` maps config aliases or dotted keys to candidate values, for
+        example `{"context_k": [16, 32], "lr": [1e-3, 3e-4]}`.
+        """
+
         runs: list[RunResult] = []
         parameters = _grid_items(grid)
         for index, params in enumerate(parameters, start=1):
@@ -335,6 +424,8 @@ def run(
     legacy_path: str | Path | None = None,
     **updates: Any,
 ) -> RunResult:
+    """Convenience wrapper for `Studio(...).run(...)`."""
+
     return Studio(legacy_path=legacy_path).run(name=name, models=models, **updates)
 
 
@@ -345,4 +436,6 @@ def sweep(
     legacy_path: str | Path | None = None,
     **updates: Any,
 ) -> StudyResult:
+    """Convenience wrapper for `Studio(...).sweep(...)`."""
+
     return Studio(legacy_path=legacy_path).sweep(name=name, grid=grid, models=models, **updates)

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio/config.py

@@ -20,6 +20,13 @@ def _default_device() -> str:
 
 @dataclass(slots=True)
 class DataConfig:
+    """Dataset and windowing settings for BER equalization.
+
+    `data_dirs` is searched for symbol CSV files, `context_k` controls the
+    number of neighboring symbols on each side of the center sample, and
+    `seq_len` is computed as `2 * context_k + 1`.
+    """
+
     data_dirs: list[Path] = field(
         default_factory=lambda: [Path("symbols_new"), Path("Symbols_1m_1ch_PR"), Path(".")]
     )
@@ -39,11 +46,19 @@ class DataConfig:
 
     @property
     def seq_len(self) -> int:
+        """Window length in symbols: `2 * context_k + 1`."""
+
         return 2 * self.context_k + 1
 
 
 @dataclass(slots=True)
 class ModelConfig:
+    """Architecture hyperparameters shared by the model registry.
+
+    The active architecture is selected by `name`. Other fields tune model
+    families such as MLP, temporal CNN/TCN, EfficientKAN, and FastKAN variants.
+    """
+
     name: str = "complex_fastkan"
     hidden_dim: int = 96
     dropout: float = 0.2
@@ -70,6 +85,8 @@ class ModelConfig:
 
 @dataclass(slots=True)
 class TrainingConfig:
+    """Optimizer, loss, scheduling, precision, and early-stopping settings."""
+
     epochs: int = 250
     learning_rate: float = 1e-3
     weight_decay: float = 0.0
@@ -97,6 +114,8 @@ class TrainingConfig:
 
 @dataclass(slots=True)
 class EvaluationConfig:
+    """Evaluation settings for BER, per-file metrics, and timing benchmarks."""
+
     eval_batch_size: int = 65536
     eval_test_during_training: bool = False
     test_ber_every: int = 10
@@ -114,6 +133,8 @@ class EvaluationConfig:
 
 @dataclass(slots=True)
 class OutputConfig:
+    """Output folder, checkpoint, history, and plot settings for a run."""
+
     out_dir: Path = Path("studio_outputs")
     experiment_name: str = "experiment"
     save_checkpoint: bool = True
@@ -126,11 +147,15 @@ class OutputConfig:
 
     @property
     def run_dir(self) -> Path:
+        """Concrete directory for the current experiment."""
+
         return self.out_dir / self.experiment_name
 
 
 @dataclass(slots=True)
 class ExperimentConfig:
+    """Experiment-level model list and metadata."""
+
     models: list[str] = field(default_factory=lambda: ["complex_fastkan"])
     tags: dict[str, str] = field(default_factory=dict)
     notes: str = ""
@@ -138,6 +163,8 @@ class ExperimentConfig:
 
 @dataclass(slots=True)
 class StudioConfig:
+    """Complete structured configuration for one studio run."""
+
     data: DataConfig = field(default_factory=DataConfig)
     model: ModelConfig = field(default_factory=ModelConfig)
     training: TrainingConfig = field(default_factory=TrainingConfig)
@@ -147,12 +174,16 @@ class StudioConfig:
     device: str = field(default_factory=_default_device)
 
     def to_dict(self) -> dict[str, Any]:
+        """Convert the config to JSON-serializable dictionaries."""
+
         raw = asdict(self)
         raw["data"]["data_dirs"] = [str(path) for path in self.data.data_dirs]
         raw["output"]["out_dir"] = str(self.output.out_dir)
         return raw
 
     def with_updates(self, **updates: Any) -> "StudioConfig":
+        """Return a copy with dotted-key updates such as `training.epochs=10`."""
+
         values = self.to_dict()
         for dotted_key, value in updates.items():
             section, key = dotted_key.split(".", 1)

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio/models.py

@@ -45,11 +45,15 @@ MODEL_NOTES: dict[str, str] = {
 
 
 def canonical_model_name(name: str) -> str:
+    """Normalize aliases such as `kan` or `fastkan` to registry names."""
+
     normalized = name.strip().lower()
     return MODEL_ALIASES.get(normalized, normalized)
 
 
 def available_models() -> dict[str, str]:
+    """Return model registry entries as `{model_name: description}`."""
+
     return dict(sorted(MODEL_NOTES.items()))
 
 
@@ -75,10 +79,14 @@ def build_model(
 
 
 def count_parameters(model: "nn.Module") -> int:
+    """Count trainable parameters in a PyTorch module."""
+
     return sum(parameter.numel() for parameter in model.parameters() if parameter.requires_grad)
 
 
 def describe_model(name: str) -> dict[str, Any]:
+    """Return a normalized model name and human-readable description."""
+
     model_name = canonical_model_name(name)
     return {
         "name": model_name,

ber_equalization_studio-0.1.3/src/ber_equalization_studio/py.typed

@@ -0,0 +1 @@
+

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio/results.py

@@ -26,6 +26,8 @@ PREFERRED_COLUMNS = [
 
 
 def flatten_metrics(metrics: dict[str, Any]) -> dict[str, Any]:
+    """Convert nested or tensor-like metrics to CSV-friendly scalar values."""
+
     flat: dict[str, Any] = {}
     for key, value in metrics.items():
         if isinstance(value, (str, int, float, bool)) or value is None:
@@ -38,11 +40,15 @@ def flatten_metrics(metrics: dict[str, Any]) -> dict[str, Any]:
 
 
 def save_json(path: Path, payload: dict[str, Any]) -> None:
+    """Write a JSON file, creating parent directories as needed."""
+
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(json.dumps(payload, indent=2, ensure_ascii=True), encoding="utf-8")
 
 
 def load_result_table(path: Path) -> pd.DataFrame:
+    """Load one result CSV or concatenate result CSVs below a directory."""
+
     if path.is_dir():
         candidates = sorted(path.glob("**/results.csv"))
         if not candidates:
@@ -55,6 +61,8 @@ def load_result_table(path: Path) -> pd.DataFrame:
 
 
 def compare_results(path: Path, sort_by: str = "equalized_ber") -> pd.DataFrame:
+    """Load, sort, and reorder result columns for quick model comparison."""
+
     df = load_result_table(path)
     if sort_by in df.columns:
         ascending = sort_by not in {"improvement_rel", "improvement_db", "accuracy", "samples_per_sec"}
@@ -65,6 +73,8 @@ def compare_results(path: Path, sort_by: str = "equalized_ber") -> pd.DataFrame:
 
 
 def write_result_table(path: Path, rows: list[dict[str, Any]]) -> pd.DataFrame:
+    """Write result rows to CSV and return the ordered DataFrame."""
+
     path.parent.mkdir(parents=True, exist_ok=True)
     df = pd.DataFrame([flatten_metrics(row) for row in rows])
     ordered = [column for column in PREFERRED_COLUMNS if column in df.columns]

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ber-equalization-studio
-Version: 0.1.2
+Version: 0.1.3
 Summary: Research studio for BER equalization experiments in nonlinear optical links.
 Keywords: ber,equalization,optical-communications,photonics,pytorch
 Classifier: Development Status :: 3 - Alpha
@@ -9,6 +9,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.10

{ber_equalization_studio-0.1.2 → ber_equalization_studio-0.1.3}/src/ber_equalization_studio.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 pyproject.toml
 src/ber_equalization_studio/__init__.py
+src/ber_equalization_studio/__init__.pyi
 src/ber_equalization_studio/api.py
 src/ber_equalization_studio/cli.py
 src/ber_equalization_studio/config.py
@@ -8,6 +9,7 @@ src/ber_equalization_studio/data.py
 src/ber_equalization_studio/experiment.py
 src/ber_equalization_studio/legacy.py
 src/ber_equalization_studio/models.py
+src/ber_equalization_studio/py.typed
 src/ber_equalization_studio/results.py
 src/ber_equalization_studio/visualization.py
 src/ber_equalization_studio.egg-info/PKG-INFO