spotoptim 3.1.0__tar.gz → 3.2.0__tar.gz

{spotoptim-3.1.0 → spotoptim-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: spotoptim
-Version: 3.1.0
+Version: 3.2.0
 Summary: Sequential Parameter Optimization Toolbox
 Author: bartzbeielstein
 Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>
@@ -36,6 +36,7 @@ Requires-Dist: requests>=2.32.3 ; extra == 'remote'
 Requires-Dist: statsmodels>=0.14.6 ; extra == 'stats'
 Requires-Dist: torch>=2.9.1 ; extra == 'torch'
 Requires-Dist: tensorboard>=2.20.0 ; extra == 'torch'
+Requires-Dist: torchmetrics>=1.8.2 ; extra == 'torch'
 Requires-Dist: matplotlib>=3.10.7 ; extra == 'viz'
 Requires-Dist: seaborn>=0.13.2 ; extra == 'viz'
 Requires-Python: >=3.13

{spotoptim-3.1.0 → spotoptim-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spotoptim"
-version = "3.1.0"
+version = "3.2.0"
 description = "Sequential Parameter Optimization Toolbox"
 readme = "README.md"
 license = { text = "AGPL-3.0-or-later" }
@@ -44,6 +44,7 @@ dev = [
 torch = [
     "torch>=2.9.1",
     "tensorboard>=2.20.0",
+    "torchmetrics>=1.8.2",
 ]
 viz = [
     "matplotlib>=3.10.7",

{spotoptim-3.1.0 → spotoptim-3.2.0}/src/spotoptim/data/__init__.py

@@ -19,6 +19,8 @@ __all__ = [
     "ManyToOneDataset",
     "PadSequenceManyToMany",
     "PadSequenceManyToOne",
+    "load_sequence_data",
+    "load_pooled_sequence_data",
 ]
 
 _lazy_map = {
@@ -28,6 +30,11 @@ _lazy_map = {
     "ManyToOneDataset": ("spotoptim.data.manydataset", "ManyToOneDataset"),
     "PadSequenceManyToMany": ("spotoptim.data.manydataset", "PadSequenceManyToMany"),
     "PadSequenceManyToOne": ("spotoptim.data.manydataset", "PadSequenceManyToOne"),
+    "load_sequence_data": ("spotoptim.data.manydataset", "load_sequence_data"),
+    "load_pooled_sequence_data": (
+        "spotoptim.data.manydataset",
+        "load_pooled_sequence_data",
+    ),
 }
 
 

{spotoptim-3.1.0 → spotoptim-3.2.0}/src/spotoptim/data/manydataset.py

@@ -13,12 +13,12 @@ classes provided here.
 Requires the ``torch`` optional extra (``pip install 'spotoptim[torch]'``).
 """
 
-from typing import List, Optional, Union
+from typing import List, Optional, Tuple, Union
 
 import pandas as pd
 import torch
 from torch.nn.utils.rnn import pad_sequence
-from torch.utils.data import Dataset
+from torch.utils.data import ConcatDataset, Dataset
 
 
 class ManyToManyDataset(Dataset):
@@ -234,3 +234,142 @@ class PadSequenceManyToOne:
         lengths = torch.tensor([len(x) for x in batch_x])
 
         return padded_batch_x, lengths, torch.tensor(batch_y)
+
+
+def load_sequence_data(
+    data: pd.DataFrame,
+    target: str,
+    group_by: str,
+    drop: Optional[Union[str, List[str]]] = None,
+    input_features: Optional[List[str]] = None,
+    feature_scaling=None,
+    target_scaling=None,
+    dataset_type: str = "many_to_many",
+) -> Tuple[Dataset, pd.DataFrame]:
+    """Group a DataFrame into a variable-length sequence dataset.
+
+    Splits ``data`` by the values of ``group_by`` (e.g. one compressor speed
+    line per group) and wraps the groups in a `ManyToManyDataset` or
+    `ManyToOneDataset`. Ported from the schu25a study's ``load_data`` helper
+    (``src/rnn/utils.py``); the experiment-specific column defaults were
+    removed.
+
+    Args:
+        data (pd.DataFrame): Input data; one row per time step.
+        target (str): The target column name.
+        group_by (str): Column whose values define the sequences.
+        drop (Optional[Union[str, List[str]]]): Column(s) to drop from the
+            groups before extracting features. Defaults to None.
+        input_features (Optional[List[str]]): Columns scaled by
+            ``feature_scaling``. Only used when ``feature_scaling`` is given;
+            the dataset features are always all columns except ``drop`` and
+            ``target``. Defaults to None.
+        feature_scaling: Optional sklearn-style scaler; applied in place to
+            ``data[input_features]`` via ``fit_transform``. Defaults to None.
+        target_scaling: Optional sklearn-style scaler; applied in place to
+            ``data[target]`` via ``fit_transform``. Defaults to None.
+        dataset_type (str, optional): Dataset flavor. Options:
+            - "many_to_many": one target value per time step.
+            - "many_to_one": one scalar target per sequence.
+            Defaults to "many_to_many".
+
+    Returns:
+        tuple: ``(dataset, data)`` — the sequence dataset and the (possibly
+            scaled) DataFrame.
+
+    Raises:
+        ValueError: If ``dataset_type`` is not "many_to_many" or "many_to_one".
+
+    Examples:
+        ```{python}
+        import pandas as pd
+        from spotoptim.data.manydataset import load_sequence_data
+
+        df = pd.DataFrame({
+            "line": [1, 1, 1, 2, 2],
+            "x": [0.1, 0.2, 0.3, 0.4, 0.5],
+            "y": [1.0, 2.0, 3.0, 4.0, 5.0],
+        })
+        ds, df = load_sequence_data(df, target="y", group_by="line", drop="line")
+        print(len(ds), ds[0][0].shape)
+        ```
+    """
+    if feature_scaling is not None:
+        data[input_features] = feature_scaling.fit_transform(data[input_features])
+
+    if target_scaling is not None:
+        data[target] = target_scaling.fit_transform(data[target])
+
+    groups = [group for _, group in data.groupby(group_by)]
+
+    if dataset_type == "many_to_many":
+        return ManyToManyDataset(groups, target=target, drop=drop), data
+    elif dataset_type == "many_to_one":
+        return ManyToOneDataset(groups, target=target, drop=drop), data
+    raise ValueError(
+        f"dataset_type {dataset_type!r} not supported. "
+        "Options: 'many_to_many', 'many_to_one'."
+    )
+
+
+def load_pooled_sequence_data(
+    data_list: List[pd.DataFrame],
+    target: str,
+    group_by: str,
+    drop: Optional[Union[str, List[str]]] = None,
+    input_features: Optional[List[str]] = None,
+    feature_scaling=None,
+    target_scaling=None,
+    dataset_type: str = "many_to_many",
+) -> ConcatDataset:
+    """Pool several DataFrames into one concatenated sequence dataset.
+
+    Applies `load_sequence_data` to every DataFrame (e.g. one compressor map
+    each) and concatenates the resulting sequence datasets — the pooled
+    training set of the schu25a "global training" workflow (ported from
+    ``load_pretrain_data`` in ``src/rnn/utils.py``).
+
+    Args:
+        data_list (List[pd.DataFrame]): Input DataFrames; one per map.
+        target (str): The target column name.
+        group_by (str): Column whose values define the sequences.
+        drop (Optional[Union[str, List[str]]]): Column(s) to drop from the
+            groups before extracting features. Defaults to None.
+        input_features (Optional[List[str]]): Columns scaled by
+            ``feature_scaling``; see `load_sequence_data`. Defaults to None.
+        feature_scaling: Optional sklearn-style scaler, applied per DataFrame.
+            Defaults to None.
+        target_scaling: Optional sklearn-style scaler, applied per DataFrame.
+            Defaults to None.
+        dataset_type (str, optional): "many_to_many" or "many_to_one".
+            Defaults to "many_to_many".
+
+    Returns:
+        ConcatDataset: The concatenation of the per-DataFrame sequence datasets.
+
+    Examples:
+        ```{python}
+        import pandas as pd
+        from spotoptim.data.manydataset import load_pooled_sequence_data
+
+        df1 = pd.DataFrame({"line": [1, 1, 2], "x": [0.1, 0.2, 0.3], "y": [1.0, 2.0, 3.0]})
+        df2 = pd.DataFrame({"line": [1, 1], "x": [0.4, 0.5], "y": [4.0, 5.0]})
+        pooled = load_pooled_sequence_data([df1, df2], target="y", group_by="line", drop="line")
+        print(len(pooled))
+        ```
+    """
+    ds_ls = []
+    for data in data_list:
+        ds, _ = load_sequence_data(
+            data,
+            target=target,
+            group_by=group_by,
+            drop=drop,
+            input_features=input_features,
+            feature_scaling=feature_scaling,
+            target_scaling=target_scaling,
+            dataset_type=dataset_type,
+        )
+        ds_ls.append(ds)
+
+    return ConcatDataset(ds_ls)

{spotoptim-3.1.0 → spotoptim-3.2.0}/src/spotoptim/nn/__init__.py

@@ -11,6 +11,8 @@ __all__ = [
     "ManyToManyRNNRegressor",
     "get_activation",
     "optimizer_handler",
+    "train_sequences",
+    "evaluate_sequences",
 ]
 
 _lazy_map = {
@@ -23,6 +25,8 @@ _lazy_map = {
     ),
     "get_activation": ("spotoptim.nn.many_to_many_rnn", "get_activation"),
     "optimizer_handler": ("spotoptim.nn.optimizer", "optimizer_handler"),
+    "train_sequences": ("spotoptim.nn.training", "train_sequences"),
+    "evaluate_sequences": ("spotoptim.nn.training", "evaluate_sequences"),
 }
 
 

spotoptim-3.2.0/src/spotoptim/nn/training.py

@@ -0,0 +1,234 @@
+# SPDX-FileCopyrightText: 2026 bartzbeielstein
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Plain training and evaluation loops for variable-length sequence models.
+
+Ported op-for-op from the ``train``/``evaluate_many`` helpers of the schu25a
+compressor-map study (``src/rnn/train.py``), so that runs seeded with
+`spotoptim.utils.seed.seed_everything` reproduce the original results
+bit-identically on the same device. The models are called as
+``model(x, lengths)`` on padded batches (e.g.
+`spotoptim.nn.many_to_many_rnn.ManyToManyRNN` with batches collated by
+`spotoptim.data.manydataset.PadSequenceManyToMany`); losses and metrics are
+computed on the squeezed padded tensors, exactly as in the original. The
+original's unused ``seed`` parameters were dropped.
+
+Requires the ``torch`` optional extra (``pip install 'spotoptim[torch]'``),
+which includes ``torchmetrics``.
+"""
+
+from typing import List, Literal, Optional, Tuple, Union, overload
+
+import numpy as np
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from torchmetrics.regression import MeanAbsolutePercentageError, MeanSquaredError
+
+
+def train_sequences(
+    model: nn.Module,
+    train_loader: DataLoader,
+    optimizer: torch.optim.Optimizer,
+    criterion: nn.Module,
+    val_loader: Optional[DataLoader] = None,
+    epochs: int = 10,
+    device: str = "cpu",
+    verbose: bool = True,
+) -> Union[Tuple[nn.Module, List[float]], Tuple[nn.Module, List[float], List[float]]]:
+    """Train a sequence model with a plain epoch loop.
+
+    One optimizer step per batch; the loss is computed between
+    ``model(x, lengths).squeeze()`` and the (padded) target batch. The
+    recorded training loss is the batch-mean loss per epoch.
+
+    Args:
+        model (nn.Module): Model called as ``model(x, lengths)``.
+        train_loader (DataLoader): Loader yielding ``(x, lengths, y)`` batches,
+            e.g. collated by `PadSequenceManyToMany`.
+        optimizer (torch.optim.Optimizer): Optimizer over ``model.parameters()``.
+        criterion (nn.Module): Loss module, e.g. ``nn.MSELoss()``.
+        val_loader (Optional[DataLoader]): Optional validation loader; when
+            given, the mean per-batch RMSE from `evaluate_sequences` is
+            recorded after every epoch. Defaults to None.
+        epochs (int, optional): Number of epochs. Defaults to 10.
+        device (str, optional): Training device. Defaults to "cpu".
+        verbose (bool, optional): Print per-epoch losses. Defaults to True.
+
+    Returns:
+        tuple: ``(model, train_loss_ls)`` without a validation loader, or
+            ``(model, train_loss_ls, val_loss_ls)`` with one.
+
+    Examples:
+        ```{python}
+        import pandas as pd
+        import torch
+        import torch.nn as nn
+        from torch.utils.data import DataLoader
+        from spotoptim.data.manydataset import ManyToManyDataset, PadSequenceManyToMany
+        from spotoptim.nn.many_to_many_rnn import ManyToManyRNN
+        from spotoptim.nn.training import train_sequences
+        from spotoptim.utils.seed import seed_everything
+
+        seed_everything(42)
+        frames = [
+            pd.DataFrame({"x": [0.1, 0.2, 0.3], "y": [1.0, 2.0, 3.0]}),
+            pd.DataFrame({"x": [0.4, 0.5], "y": [4.0, 5.0]}),
+        ]
+        ds = ManyToManyDataset(frames, target="y")
+        dl = DataLoader(ds, batch_size=2, shuffle=False, collate_fn=PadSequenceManyToMany())
+        model = ManyToManyRNN(input_size=1, rnn_units=8, fc_units=8)
+        optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
+        model, losses = train_sequences(
+            model, dl, optimizer, nn.MSELoss(), epochs=2, verbose=False
+        )
+        print(len(losses))
+        ```
+    """
+    model.train()
+    model.to(device)
+
+    train_loss_ls = []
+    val_loss_ls = []
+
+    for epoch in range(epochs):
+        model.train()
+        train_loss = 0.0
+        for batch_x, lengths, batch_y in train_loader:
+            batch_x = batch_x.to(device)
+            batch_y = batch_y.to(device)
+
+            optimizer.zero_grad()
+            outputs = model(batch_x, lengths)
+            outputs = outputs.squeeze()
+
+            loss = criterion(outputs, batch_y)
+            loss.backward()
+
+            optimizer.step()
+            train_loss += loss.item()
+
+        train_loss /= len(train_loader)
+        train_loss_ls.append(train_loss)
+
+        if val_loader is not None:
+            _, _, _, mape, rmse = evaluate_sequences(model, val_loader, device=device)
+            val_loss_ls.append(float(np.mean(np.array(rmse))))
+        else:
+            mape = None
+            rmse = None
+
+        if verbose:
+            print(f"Epoch: {epoch + 1}/{epochs}, Train Loss: {train_loss:.4f}", end="")
+            if mape is not None:
+                print(
+                    f", Validation: MAPE: {np.mean(np.array(mape)):.4f}, "
+                    f"RMSE: {np.mean(np.array(rmse)):.4f}"
+                )
+            else:
+                print()
+
+    if val_loader is not None:
+        return model, train_loss_ls, val_loss_ls
+    return model, train_loss_ls
+
+
+@overload
+def evaluate_sequences(
+    model: nn.Module,
+    val_loader: DataLoader,
+    device: str = "cpu",
+    metrics_only: Literal[False] = False,
+) -> Tuple[list, list, list, List[float], List[float]]: ...
+
+
+@overload
+def evaluate_sequences(
+    model: nn.Module,
+    val_loader: DataLoader,
+    device: str = "cpu",
+    *,
+    metrics_only: Literal[True],
+) -> Tuple[float, float]: ...
+
+
+def evaluate_sequences(
+    model: nn.Module,
+    val_loader: DataLoader,
+    device: str = "cpu",
+    metrics_only: bool = False,
+) -> Union[Tuple[float, float], Tuple[list, list, list, List[float], List[float]]]:
+    """Evaluate a sequence model with per-batch MAPE and RMSE.
+
+    Metrics are the torchmetrics ``MeanAbsolutePercentageError`` and
+    ``MeanSquaredError(squared=False)`` between ``model(x, lengths).squeeze()``
+    and the squeezed target batch, as in the schu25a original. Inputs,
+    predictions, and targets are additionally returned as nested Python lists
+    for plotting.
+
+    Args:
+        model (nn.Module): Model called as ``model(x, lengths)``.
+        val_loader (DataLoader): Loader yielding ``(x, lengths, y)`` batches.
+            Batches are converted to NumPy, so ``device`` should be "cpu"
+            unless ``metrics_only=True``.
+        device (str, optional): Evaluation device. Defaults to "cpu".
+        metrics_only (bool, optional): Return only ``(mean_mape, mean_rmse)``.
+            Defaults to False.
+
+    Returns:
+        tuple: ``(x_ls, y_hat_ls, y_ls, mape_loss_ls, rmse_loss_ls)`` with one
+            entry per batch, or ``(mean_mape, mean_rmse)`` if ``metrics_only``.
+
+    Examples:
+        ```{python}
+        import pandas as pd
+        import torch
+        from torch.utils.data import DataLoader
+        from spotoptim.data.manydataset import ManyToManyDataset, PadSequenceManyToMany
+        from spotoptim.nn.many_to_many_rnn import ManyToManyRNN
+        from spotoptim.nn.training import evaluate_sequences
+        from spotoptim.utils.seed import seed_everything
+
+        seed_everything(42)
+        frames = [pd.DataFrame({"x": [0.1, 0.2, 0.3], "y": [1.0, 2.0, 3.0]})]
+        ds = ManyToManyDataset(frames, target="y")
+        dl = DataLoader(ds, batch_size=1, shuffle=False, collate_fn=PadSequenceManyToMany())
+        model = ManyToManyRNN(input_size=1, rnn_units=8, fc_units=8)
+        x, y_hat, y, mape, rmse = evaluate_sequences(model, dl)
+        print(len(y_hat), len(mape), len(rmse))
+        ```
+    """
+    mean_abs_percentage_error = MeanAbsolutePercentageError().to(device)
+    rmse_loss = MeanSquaredError(squared=False).to(device)
+
+    model.eval()
+    model.to(device)
+
+    x_ls = []
+    y_hat_ls = []
+    y_ls = []
+    mape_loss_ls = []
+    rmse_loss_ls = []
+
+    with torch.no_grad():
+        for batch_x, lengths, batch_y in val_loader:
+            batch_x = batch_x.to(device)
+            batch_y = batch_y.to(device)
+
+            y_hat = model(batch_x, lengths)
+            y_hat = y_hat.squeeze()
+
+            mape = mean_abs_percentage_error(y_hat, batch_y.squeeze())
+            rmse = rmse_loss(y_hat, batch_y.squeeze())
+
+            mape_loss_ls.append(mape.item())
+            rmse_loss_ls.append(rmse.item())
+
+            x_ls.append(batch_x.squeeze().detach().numpy().tolist())
+            y_hat_ls.append(y_hat.squeeze().detach().numpy().tolist())
+            y_ls.append(batch_y.squeeze().detach().numpy().tolist())
+
+    if metrics_only:
+        return float(np.mean(mape_loss_ls)), float(np.mean(rmse_loss_ls))
+    return x_ls, y_hat_ls, y_ls, mape_loss_ls, rmse_loss_ls

{spotoptim-3.1.0 → spotoptim-3.2.0}/src/spotoptim/utils/__init__.py

@@ -27,6 +27,7 @@ __all__ = [
     "get_loading_scores",
     "plot_loading_scores",
     "TorchStandardScaler",
+    "seed_everything",
 ]
 
 _lazy_map = {
@@ -44,6 +45,8 @@ _lazy_map = {
     "plot_loading_scores": ("spotoptim.utils.pca", "plot_loading_scores"),
     # scaler (pulls torch)
     "TorchStandardScaler": ("spotoptim.utils.scaler", "TorchStandardScaler"),
+    # seed (pulls torch)
+    "seed_everything": ("spotoptim.utils.seed", "seed_everything"),
 }
 
 

spotoptim-3.2.0/src/spotoptim/utils/seed.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 bartzbeielstein
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Global seeding for fully reproducible torch experiments.
+
+Ported from the ``seed_everything`` helper of the schu25a compressor-map
+study (``src/rnn/utils.py``): seeds Python, NumPy, and torch (CPU, CUDA, and
+MPS) and switches cuDNN to deterministic mode, so that repeated runs on the
+same device produce bit-identical results.
+
+Requires the ``torch`` optional extra (``pip install 'spotoptim[torch]'``).
+"""
+
+import os
+import random
+
+import numpy as np
+import torch
+
+
+def seed_everything(seed: int) -> None:
+    """Seed every random number generator relevant to a torch experiment.
+
+    Seeds Python's ``random``, ``PYTHONHASHSEED``, NumPy, and torch (CPU and
+    CUDA unconditionally, MPS when available), and sets
+    ``torch.backends.cudnn.deterministic = True`` and
+    ``torch.backends.cudnn.benchmark = False``.
+
+    Args:
+        seed (int): The seed value.
+
+    Note:
+        - cuDNN determinism and benchmark flags are process-global side
+          effects; they may slow down convolutional workloads.
+        - Unlike the schu25a original, the MPS generator is only seeded when
+          the MPS backend is available, so the function also works on
+          CPU-only Linux hosts.
+
+    Examples:
+        ```{python}
+        import torch
+        from spotoptim.utils.seed import seed_everything
+
+        seed_everything(42)
+        a = torch.rand(3)
+        seed_everything(42)
+        b = torch.rand(3)
+        print(torch.equal(a, b))
+        ```
+    """
+    random.seed(seed)
+    os.environ["PYTHONHASHSEED"] = str(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed(seed)
+    if torch.backends.mps.is_available():
+        torch.mps.manual_seed(seed)
+    torch.backends.cudnn.deterministic = True
+    torch.backends.cudnn.benchmark = False