zeroth-learn 0.1.0__tar.gz

zeroth_learn-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: zeroth-learn
+Version: 0.1.0
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: cycler

zeroth_learn-0.1.0/README.md

@@ -0,0 +1,244 @@
+# Zeroth-Learn
+
+**A research library for zeroth-order optimization (gradient-free) in machine learning, with applications to quantum computing.**
+
+*Research project — Nicolas, X24*
+
+---
+
+## Context & Motivation
+
+This project originated from a fundamental question in quantum machine learning:
+
+> **How do you train parameterized quantum circuits when backpropagation is impossible?**
+
+Quantum circuits are too complex to differentiate we treat it as a black box, thus we need to find alternatives to backpropagation, SPSA is an excellent candidate.
+
+**SPSA (Simultaneous Perturbation Stochastic Approximation)** solves this by estimating gradients from only O(1) evaluations per iteration.
+
+Before deploying on quantum simulators, I built this library to:
+1. Understand the theoretical foundations of zeroth-order optimization
+2. Validate SPSA stability on classical benchmarks (MNIST)
+3. Validate my results with backpropagation models.
+
+---
+
+## Technical Implementation
+
+### Architecture Decisions
+
+**Problem**: Standard deep learning frameworks (PyTorch, JAX) are tightly coupled to automatic differentiation. I needed an architecture where gradient computation is a **swappable abstraction**.
+
+**Solution**: Clean separation of concerns using abstract base classes:
+```
+Model (training loop orchestration)
+  ├── NeuralNetwork (forward pass interface)
+  │     ├── NeuralNetworkBackpropagation (layer-based, stores activations)
+  │     └── NeuralNetworkPerturbation (parameter-vector based, no activation storage)
+  └── Optimizer (gradient computation + update rule)
+        ├── OptimizerBackprop (analytical gradients via chain rule)
+        └── OptimizerPerturbation (estimated gradients via function evaluations)
+```
+
+**Key insight**: By treating gradients as an *estimated quantity* rather than an *exact derivative*, both methods become instances of the same abstraction.
+
+---
+
+## Quick Start
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/nicolasmalet/Zeroth-Learn.git
+    cd Zeroth-Learn
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+3.  **Run a benchmark experiment:**
+    To train a linear MLP on MNIST using SPSA with 50 perturbations:
+    ```bash
+    python -m lab.mnist 
+    ```
+---
+
+### SPSA Implementation Details
+
+The core challenge: **evaluate multiple perturbed models in parallel without Python loops**.
+
+#### Naive Approach (slow):
+```python
+for perturbation in perturbations:
+    theta_perturbed = theta + perturbation
+    loss_perturbed[i] = evaluate_model(theta_perturbed)
+```
+**Cost**: O(T) sequential forward passes for T perturbations.
+
+#### Vectorized Approach (implemented):
+```python
+# Shape: (T, n_params)
+pThetas = theta[None, :] + perturbations  
+
+# Reshape to (T, n_layers) weight matrices
+Ws, Bs = params.from_pThetas(pThetas)  
+
+# Broadcast input across all T models simultaneously
+# X: (input_dim, batch) -> (T, input_dim, batch)
+for W, B, f in zip(Ws, Bs, fs):
+    X = f(W @ X + B)  # Matrix multiplication broadcasts automatically
+```
+**Result**: All T forward passes execute in a single vectorized NumPy operation.
+
+---
+
+### Mathematical Rigor
+
+#### Gradient Estimation
+The SPSA gradient estimator:
+
+$$\nabla L(\theta) \approx \frac{1}{T \cdot \delta} \sum_{i=1}^{T} \left( L(\theta + \delta \Delta_i) - L(\theta) \right) \Delta_i$$
+
+where $\Delta_i \sim \text{Rademacher}(\pm 1)$ are random perturbation directions.
+
+**Implementation** (using Einstein summation for efficiency):
+```python
+# L_diff: (T, batch_size), Ps: (T, n_params)
+grad = np.einsum('ij,ik->k', L_diff, self.Ps) / (batch_size * T * delta)
+```
+
+#### Numerical Stability Considerations
+- **Softmax**: Shifted by max to prevent overflow: `exp(x - max(x))`
+- **CrossEntropy**: Added epsilon (1e-8) to prevent log(0)
+- **Xavier initialization**: Weights sampled from $U(-\sqrt{6/(n_{in}+n_{out})}, +\sqrt{6/(n_{in}+n_{out})})$
+
+---
+
+## Experimental Validation
+
+### Research Question
+*What are the optimal conditions (architecture depth, learning rate, perturbation count) for SPSA to compete with backpropagation?*
+
+### Methodology
+
+**Phase 1: Hyperparameter Sensitivity Analysis**
+- Grid search over learning rates × architectures
+- Identified stability thresholds (divergence boundaries)
+
+<img alt="Learning Rate Analysis" src="assets/plots/lr_adam.png" height="300">
+
+**Finding**: Adam requires lr ~ 0.001 for networks with 10K to 100K parameters to avoid gradient explosion in SPSA.
+
+---
+
+**Phase 2: Scalability Limits**
+- Trained 6 models from 7K to 1.3M parameters (here are the first three)
+- Measured convergence speed vs parameter count
+
+<img alt="Architecture Scaling" src="assets/plots/small_sizes.png" height="300"/>
+
+**Finding**: Models with 100K parameters are sufficient to get 97% accuracy
+
+---
+
+**Phase 3: Sample Efficiency**
+- Varied perturbation count T ∈ {10, 30, 100}
+- Measured gradient variance vs. computational cost
+
+<img alt="Perturbation Analysis" src="assets/plots/nb_perturbations.png" height="300"/>
+
+**Finding**: As gradient approximation variance reduction follows $\sigma \propto 1/\sqrt{T}$, we get marginal returns beyond T=30.
+
+**Practical implication**: For quantum circuits, 30 evaluations/step is feasible on current hardware.
+
+---
+
+## Software Engineering Practices
+
+### Type Safety & Configuration Management
+- **Frozen dataclasses** for all configs → immutable
+- **Config serialization** → full experiment reproducibility (saved as JSON)
+
+### Modular Design
+- **Catalog pattern** for hyperparameters (see `config.py`):
+```python
+@dataclass(frozen=True)
+class OptimizerCatalog:
+    FirstOrderAdam = FirstOrderAdamConfig(lr=0.001, ...)
+    ZerothOrderAdam = ZerothOrderAdamConfig(lr=0.001, ...)
+```
+  Enables experiment generation via `itertools.product`.
+
+### Experiment Reproducibility
+- Automatic result saving (loss curves, results dataframe, hyperparameter logs)
+- Plot styling configured globally (publication-ready figures)
+
+---
+
+## Software Design Principles
+
+- **Separation of Concerns**: Gradient computation (Optimizer) is decoupled from forward pass (NeuralNetwork)
+- **Config-Driven**: All hyperparameters defined as immutable dataclasses → reproducibility
+- **Polymorphism**: Models can swap between backprop and SPSA without code changes
+---
+
+## Skills Demonstrated
+
+**Deep Learning Fundamentals**: Implemented backprop from scratch (no PyTorch/TensorFlow)  
+**Numerical Optimization**: SPSA, Adam, gradient estimation theory  
+**Scientific Computing**: Vectorized NumPy, broadcasting, numerical stability  
+**Software Architecture**: Abstract base classes, config management  
+**Research Methodology**: Systematic experimentation, reproducible results  
+**Mathematical Rigor**: Gradient derivations, loss functions  
+
+---
+
+## Next Steps
+
+### Quantum Simulation (In Progress)
+- Implement `QuantumCircuitSimulator` class using Dynamics
+- Test SPSA on parameterized quantum circuits
+- Validate that convergence behavior matches classical benchmarks
+
+---
+
+## Technical Stack
+
+**Language**: Python  
+**Core Libraries**: NumPy (vectorization), Pandas (results), Matplotlib (visualization)  
+**Design Patterns**: Strategy (Optimizer), Abstract Factory (Config instantiation), Template Method (Model training loop)
+
+---
+
+## Project Structure
+```
+zeroth/
+│
+│── first-order/                # Analytical gradient methods
+│   ├── layer.py                # Forward/backward pass logic
+│   └── optimizers.py           # SGD, Adam implementations
+│── zeroth-order/               # Zeroth-order methods
+│   ├── gradient_estimator.py   # Gradient estimation strategies
+│   ├── parameter_manager.py    # Parameter vector management
+│   └── optimizers.py           # SPSA + Adam/SGD variants
+│── abstract/                   # Shared abstractions
+│   ├── neural_network.py       # Abstract base class
+│   └── optimizer.py            # Optimizer interface
+└── experiment.py               # Experiment orchestration
+
+lab/
+│
+├── experiments.py              # Pre-configured experiments
+├── models.py                   # Model definitions
+└── config.py                   # Hyperparameter catalogs
+```
+
+---
+
+## Contact
+
+**Nicolas Malet**  
+X24 — École Polytechnique  
+nicolas.malet@polytechnique.edu  
+[GitHub](https://github.com/nicolasmalet) | [LinkedIn](https://www.linkedin.com/in/nicolas-malet-pro)

zeroth_learn-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zeroth-learn"
+version = "0.1.0"
+dependencies = [
+    "numpy",
+    "pandas",
+    "matplotlib",
+    "cycler"
+]
+
+[tool.setuptools]
+packages = ["zeroth"]

zeroth_learn-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zeroth_learn-0.1.0/zeroth/__init__.py

@@ -0,0 +1,5 @@
+from zeroth.model import (Model, ModelConfig, ZerothOrderModel, FirstOrderModel,
+                          ZerothOrderModelConfig, FirstOrderModelConfig)
+from zeroth.experiment import Experiment, ExperimentConfig, VariationConfig
+
+from zeroth.data import Data

zeroth_learn-0.1.0/zeroth/experiment.py

@@ -0,0 +1,134 @@
+from zeroth.utils.dataclasses_utils import config_serializer, generate_param_map, get_name, set_value_by_path
+from zeroth.model import ModelConfig, Model
+from zeroth.plot_losses import plot_losses
+from zeroth.data import Data
+
+from dataclasses import dataclass, replace
+from typing import Callable
+
+import pandas as pd
+import itertools
+import json
+import os
+
+
+
+
+@dataclass(frozen=True)
+class VariationConfig:
+    param: str
+    values: list
+
+
+@dataclass(frozen=True)
+class ExperimentConfig:
+    name: str
+    title: str
+    base_model: ModelConfig
+    variations: list[VariationConfig]
+    create_data: Callable
+    plot_dimension : int
+
+    def instantiate(self):
+        return Experiment(self)
+
+
+class Experiment:
+    """Manages the full lifecycle of a deep learning experiment.
+
+    It handles data loading, model instantiation, training loops, and results visualization.
+
+    Attributes:
+        name (str): Name of the experiment
+        title (str): Title of the graphs
+        models (list[Model]): List of models to train/compare
+        data (Data): The dataset wrapper.
+    """
+
+    def __init__(self, config: ExperimentConfig):
+        self.config = config
+        self.name: str = config.name
+        self.title: str = config.title
+        self.base_model_config: ModelConfig = config.base_model
+        self.models: list[Model] = generate_models(config.base_model, config.variations)
+        self.data: Data = config.create_data()
+        self.plot_dimension: int = config.plot_dimension
+
+        self.save_dir = os.path.join("results", self.name)
+
+    def launch(self, do_train, do_test, nb_print_train, do_plot_train, do_save):
+        """
+        Executes the experiment pipeline.
+
+        Args:
+            do_train (bool): Whether to run the training loop.
+            do_test (bool): Whether to run evaluation on test set.
+            nb_print_train (int): Number of logs to print during training.
+            do_plot_train (bool): If True, plots loss curves after training.
+            do_save (bool): if True, saves the plots and dataframes
+        """
+        print(f"### Launching Experiment : {self.name} ###")
+        if do_train:
+            self.train(nb_print=nb_print_train, do_plot=do_plot_train, do_save=do_save)
+        if do_test:
+            self.test()
+        if do_save:
+            self.save_df()
+
+    def train(self, nb_print: int, do_plot: bool, do_save: bool):
+        for model in self.models:
+            model.train(self.data, nb_print)
+
+        if do_plot:
+            plot_path = None
+            if do_save:
+                os.makedirs(self.save_dir, exist_ok=True)
+                plot_path = os.path.join(self.save_dir, "training_losses.png")
+
+            plot_losses(dimension=self.plot_dimension, models=self.models, title=self.title, save_path=plot_path)
+
+    def test(self):
+        for model in self.models:
+            model.test(self.data)
+
+    def save_df(self):
+        """
+        saves the models parameters and their args
+        """
+        os.makedirs(self.save_dir, exist_ok=True)
+        print(f"    Saving results to: {self.save_dir}")
+
+        data = [model.id | {"test_loss": model.test_loss, "test_accuracy": model.test_accuracy}
+                for model in self.models]
+
+        df = pd.DataFrame(data)
+        df.to_csv(os.path.join(self.save_dir, "models_accuracy.csv"), index_label="iteration")
+
+        config_path = os.path.join(self.save_dir, "config.json")
+        with open(config_path, "w") as f:
+            json.dump(self.config, f, default=config_serializer, indent=4)
+
+
+def generate_models(base_model: ModelConfig, variations: list[VariationConfig]) -> list[Model]:
+
+    models = []
+
+    names = [v.param for v in variations]
+    values = [v.values for v in variations]
+
+    # key: param  value: path
+    PARAM_MAP = generate_param_map(base_model)
+
+    for combination in itertools.product(*values):
+        id_ = {}
+        for key, val in zip(names, combination):
+            id_[key] = get_name(val)
+        current_model = base_model
+        for param_key, value in zip(names, combination):
+            path = PARAM_MAP[param_key]
+            current_model = set_value_by_path(current_model, path, value)
+
+        current_model = replace(current_model, id=id_)
+        models.append(current_model.instantiate())
+
+    return models

zeroth_learn-0.1.0/zeroth/losses.py

@@ -0,0 +1,121 @@
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class Loss(ABC):
+    @staticmethod
+    @abstractmethod
+    def compute_loss(Y_pred: np.ndarray, Y_true: np.ndarray) -> float:
+        """
+        :param Y_pred: shape (out, batch)
+        :param Y_true: shape (out, batch)
+        :return: avg loss shape: float
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def compute_batch_losses(Y_pred: np.ndarray, Y_true: np.ndarray) -> np.ndarray:
+        """
+        :param Y_pred: shape (out, batch)
+        :param Y_true: shape (out, batch)
+        :return: batch loss shape (batch, )
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def compute_perturbed_losses(pY_pred: np.ndarray, Y_true: np.ndarray) -> np.ndarray:
+        """
+        :param pY_pred: (T, out, batch)
+        :param Y_true: (out, batch)
+        :return: perturbed loss (nb_params, T)
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def compute_gradient_wrt_preactivation(last_layer, Y_pred: np.ndarray, Y_true: np.ndarray) -> np.ndarray:
+        """
+        :param last_layer: last_layer of the network
+        :param Y_pred: shape (out, batch)
+        :param Y_true: shape (out, batch)
+        :return: batch loss shape (batch, )
+        """
+        pass
+
+    @abstractmethod
+    def compute_losses_for_zeroth_order(self, pY_pred: np.ndarray, Y_true: np.ndarray) -> tuple[float, np.ndarray]:
+        pass
+
+
+    @abstractmethod
+    def compute_losses_for_first_order(self, last_layer, Y_pred: np.ndarray, Y_true: np.ndarray):
+        pass
+
+
+class MSE(Loss):
+    name = "MSE"
+
+    @staticmethod
+    def compute_loss(Y_pred, Y_true) -> float:
+        return np.mean((Y_pred - Y_true) ** 2, axis=(0, 1))
+
+    @staticmethod
+    def compute_batch_losses(Y_pred, Y_true):
+        return np.mean((Y_pred - Y_true) ** 2, axis=0)
+
+    @staticmethod
+    def compute_perturbed_losses(pY_pred, Y_true):
+        return np.mean((pY_pred - Y_true) ** 2, axis=1)
+
+    @staticmethod
+    def compute_gradient_wrt_activation(Y_pred, Y_true):
+        return 2 * np.mean(Y_pred - Y_true, axis=0)
+
+    @staticmethod
+    def compute_gradient_wrt_preactivation(last_layer, Y_pred, Y_true):
+        dL_dA = 2 * (Y_pred - Y_true) / Y_true.size
+        dL_dZ = dL_dA * last_layer.df(last_layer.Z)
+        return dL_dZ
+
+    def compute_losses_for_zeroth_order(self, pY_pred, Y_true):
+        return (self.compute_loss(pY_pred[0], Y_true),
+                self.compute_perturbed_losses(pY_pred, Y_true))
+
+    def compute_losses_for_first_order(self, last_layer, Y_pred, Y_true):
+        return self.compute_loss(Y_pred, Y_true), self.compute_gradient_wrt_preactivation(last_layer, Y_pred, Y_true)
+
+
+class CrossEntropy(Loss):
+    name = "CrossEntropy"
+
+    @staticmethod
+    def compute_loss(Y_pred: np.ndarray, Y_true: np.ndarray) -> float:
+        idx = np.arange(Y_pred.shape[1])
+        return - np.mean(np.log(1e-8 + Y_pred[Y_true, idx]))
+
+    @staticmethod
+    def compute_batch_losses(Y_pred: np.ndarray, Y_true: np.ndarray):
+        idx = np.arange(Y_pred.shape[1])
+        return - np.log(1e-8 + Y_pred[Y_true, idx])
+
+    @staticmethod
+    def compute_perturbed_losses(pY_pred: np.ndarray, Y_true: np.ndarray):
+        idx = np.arange(pY_pred.shape[2])
+        return - np.mean(np.log(1e-8 + pY_pred[:, Y_true, idx]), axis=1)
+
+    @staticmethod
+    def compute_gradient_wrt_preactivation(last_layer, Y_pred: np.ndarray, Y_true: np.ndarray):
+        dZ = Y_pred.copy()
+        batch_size = Y_pred.shape[1]
+        dZ[Y_true[0], np.arange(batch_size)] -= 1.0
+        return dZ
+
+    def compute_losses_for_zeroth_order(self, pY_pred: np.ndarray, Y_true: np.ndarray):
+        avg_loss = self.compute_loss(pY_pred[0], Y_true)
+        p_loss = self.compute_perturbed_losses(pY_pred, Y_true)
+        return avg_loss, p_loss
+
+    def compute_losses_for_first_order(self, last_layer, Y_pred: np.ndarray, Y_true: np.ndarray) -> tuple[float, np.ndarray]:
+        return self.compute_loss(Y_pred, Y_true), self.compute_gradient_wrt_preactivation(last_layer, Y_pred, Y_true)

zeroth_learn-0.1.0/zeroth/model.py

@@ -0,0 +1,144 @@
+from dataclasses import dataclass
+from matplotlib.axes import Axes
+from typing import Callable
+from abc import ABC
+
+import pandas as pd
+import numpy as np
+
+from zeroth.zeroth_order import ZerothOrderNeuralNetwork, ZerothOrderOptimizerConfig, GradientEstimatorConfig, \
+    GradientEstimator
+from zeroth.first_order import FirstOrderNeuralNetwork, FirstOrderOptimizerConfig
+from zeroth.abstract import BlackBox, NeuralNetworkConfig, Optimizer
+from zeroth.losses import Loss
+from zeroth.data import Data
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    """
+    name (str): Name of the model (used for display and saving).
+    loss (Loss): The loss class.
+    metric (Callable): Function (Y_pred, Y_true) -> score (e.g., accuracy).
+    batch_size (int): Number of samples per gradient update.
+    plot_results (Callable): Function to visualize test results.
+    nb_epochs (int): Number of passes through the entire dataset.
+    """
+    name: str
+    id: dict
+    loss: Loss
+    metric: Callable
+    batch_size: int
+    nb_epochs: int
+
+    def instantiate(self):
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class FirstOrderModelConfig(ModelConfig):
+    neural_network_config: NeuralNetworkConfig
+    optimizer_config: FirstOrderOptimizerConfig
+
+    def instantiate(self):
+        return FirstOrderModel(self)
+
+
+@dataclass(frozen=True)
+class ZerothOrderModelConfig(ModelConfig):
+    neural_network_config: NeuralNetworkConfig
+    optimizer_config: ZerothOrderOptimizerConfig
+    gradient_estimator_config: GradientEstimatorConfig
+
+    def instantiate(self):
+        return ZerothOrderModel(self)
+
+
+class Model(ABC):
+    """
+    Base class orchestrating the training and testing loop.
+
+    This class abstracts the abstract logic for training
+    regardless of the underlying engine (Backpropagation or zeroth_order).
+    """
+
+    def __init__(self, config: ModelConfig):
+
+        self.name: str = config.name
+        self.id: dict = config.id
+        self.loss: Loss = config.loss
+        self.metric: Callable = config.metric
+        self.batch_size: int = config.batch_size
+        self.nb_epochs: int = config.nb_epochs
+        self.neural_network: BlackBox | None = None
+        self.optimizer: Optimizer | None = None
+
+        self.train_loss: np.ndarray = np.array([])
+        self.test_loss: float | None = None
+        self.test_accuracy: float | None = None
+
+    def train(self, data: Data, nb_print: int = 0):
+        """Runs the training loop over the dataset.
+
+        Args:
+            data (Data): The dataset object containing train/test sets.
+            nb_print (int): Number of progress updates to print per epoch.
+
+        Returns:
+            np.ndarray: Array of loss values recorded at each step (for plotting).
+        """
+
+        nb_batches = data.nb_data // self.batch_size
+
+        self.train_loss = np.zeros(self.nb_epochs * nb_batches, dtype=np.float64)
+
+        print_indexes = np.linspace(0, nb_batches - 1, nb_print).astype(int)
+        print(f"    Training {self.id} Model")
+        for epoch_idx in range(self.nb_epochs):
+            print(f"        epoch n°{epoch_idx + 1} out of {self.nb_epochs}")
+            data.prepare_data(self.batch_size)
+            for batch_idx in range(nb_batches):
+                X_train, Y_train = data.X_train[batch_idx], data.Y_train[batch_idx]
+                avg_loss = self.optimizer.do_descent(self.neural_network, self.loss, X_train, Y_train)
+                self.train_loss[epoch_idx * nb_batches + batch_idx] = avg_loss
+
+                if batch_idx in print_indexes:
+                    print(f"            batch n°{batch_idx + 1} out of {nb_batches}, "
+                          f"loss : {np.round(self.train_loss[epoch_idx * nb_batches + batch_idx], 3)}")
+            self.test(data)
+
+    def plot_loss(self, ax: Axes, label: str, smooth_span: int = 50):
+        ax.plot(self.train_loss, alpha=0.25, linewidth=1.0)
+        smooth = self.smooth_curve(self.train_loss, smooth_span)
+        ax.plot(smooth, label=label, linewidth=2.5)
+
+    @staticmethod
+    def smooth_curve(loss: np.ndarray, smooth_span: int) -> np.ndarray:
+        return np.exp(pd.Series(np.log(loss)).ewm(span=smooth_span, adjust=True).mean())
+
+    def test(self, data):
+        X_test, Y_true = data.X_test, data.Y_test  # (in, batch), (out, batch)
+        Y_pred = self.neural_network.forward(X_test)  # (out, batch)
+
+        self.test_accuracy = self.metric(Y_pred, Y_true)
+        self.test_loss = self.loss.compute_loss(Y_pred, Y_true)
+
+        print(f"    {self.id} accuracy : {self.test_accuracy}, loss : {self.test_loss}")
+
+
+class FirstOrderModel(Model):
+    def __init__(self, config: FirstOrderModelConfig):
+        super().__init__(config)
+
+        self.neural_network = FirstOrderNeuralNetwork(config.neural_network_config)
+        self.optimizer = config.optimizer_config.instantiate()
+
+
+class ZerothOrderModel(Model):
+    def __init__(self, config: ZerothOrderModelConfig):
+        super().__init__(config)
+
+        self.neural_network: ZerothOrderNeuralNetwork = ZerothOrderNeuralNetwork(config.neural_network_config)
+        nb_params = self.neural_network.params.nb_params
+        self.gradient_estimator: GradientEstimator = config.gradient_estimator_config.instantiate(nb_params)
+        self.optimizer: Optimizer = config.optimizer_config.instantiate(self.gradient_estimator)

zeroth_learn-0.1.0/zeroth/plot_losses.py

@@ -0,0 +1,190 @@
+from zeroth.model import Model
+
+from matplotlib.axes import Axes
+from cycler import cycler
+
+import matplotlib.pyplot as plt
+
+def set_style():
+    plt.rcParams.update({
+        "font.family": "serif",
+        "font.serif": ["Times New Roman", "Times", "DejaVu Serif"],
+        "font.size": 10,
+        "axes.labelsize": 10,
+        "axes.titlesize": 11,
+        "axes.linewidth": 0.8,
+        "axes.spines.top": False,
+        "axes.spines.right": False,
+        "xtick.labelsize": 9,
+        "ytick.labelsize": 9,
+        "xtick.direction": "out",
+        "ytick.direction": "out",
+        "xtick.major.size": 3,
+        "ytick.major.size": 3,
+        "lines.linewidth": 2.2,
+        "legend.fontsize": 9,
+        "legend.frameon": False,
+        "grid.color": "0.85",
+        "grid.linewidth": 0.6,
+        "grid.linestyle": "-",
+        "savefig.dpi": 300,
+        "savefig.bbox": "tight",
+    })
+    plt.rcParams["axes.prop_cycle"] = cycler(color=[
+        "#4477AA", "#EE6677", "#228833",
+        "#CCBB44", "#66CCEE", "#AA3377"
+    ])
+
+
+def format_ax(ax: Axes):
+    ax.set_axisbelow(True)
+    ax.set_yscale('log')
+    ax.grid(True, which="major", axis="y")
+    ax.grid(False, axis="x")
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+
+
+def plot_0d(models: list[Model], title: str, smooth_span: int = 50):
+    """
+    Plots a single graph overlaying multiple models that share the same hyperparameters.
+    """
+    fig, ax = plt.subplots(figsize=(5.5, 3.5))
+
+    for model in models:
+        others = [f"{k}={v}" for k, v in model.id.items()]
+        label = ", ".join(others)
+        model.plot_loss(ax, label, smooth_span)
+
+        format_ax(ax)
+
+    plt.subplots_adjust(left=0.1, right=0.95, top=0.9, bottom=0.2)
+    fig.suptitle(title, fontweight='bold', fontsize=12)
+    ax.set_xlabel("Training steps")
+    ax.set_ylabel("Training loss")
+    format_ax(ax)
+
+    handles, labels = ax.get_legend_handles_labels()
+
+    if handles:
+        fig.legend(handles, labels, loc='lower center', ncol=len(handles),
+                   bbox_to_anchor=(0.5, 0), frameon=False, fontsize=9)
+
+
+def plot_1d(models: list[Model], title: str, key: str, smooth_span: int = 50):
+    """
+    Plots a row of subplots, varying one hyperparameter (key) across columns.
+    """
+
+    cols = list(dict.fromkeys([m.id[key] for m in models]))
+    n_models = len(cols)
+    fig, axs = plt.subplots(1, n_models, figsize=(4.5 * n_models, 3.5), sharey=True)
+
+    for i, val in enumerate(cols):
+        ax = axs[i]
+        cell_models = [m for m in models if m.id[key] == val]
+
+        for model in cell_models:
+            others = [f"{k}={v}" for k, v in model.id.items()
+                      if k != key]
+            label = ", ".join(others)
+            model.plot_loss(ax, label, smooth_span)
+
+        format_ax(ax)
+
+        ax.set_title(f"{key} = {val}")
+
+
+    fig.text(0.5, 0.1, "Training steps", ha='center', fontsize=10)
+    fig.text(0.01, 0.5, "Training loss", va='center', rotation='vertical', fontsize=10)
+
+    plt.subplots_adjust(left=0.05, right=0.96, top=0.85, bottom=0.2, wspace=0.10, hspace=0.18)
+    fig.suptitle(title, fontweight='bold', fontsize=12)
+
+    handles, labels = axs[0].get_legend_handles_labels()
+
+    if handles:
+        fig.legend(handles, labels, loc='lower center', ncol=len(handles),
+                   bbox_to_anchor=(0.5, 0), frameon=False, fontsize=9)
+
+
+def plot_2d_grid(models: list[Model], title: str, row_key: str, col_key: str, smooth_span: int = 50):
+    """
+    Plots a grid of subplots varying two hyperparameters: one across rows, one across columns.
+
+    Args:
+        models (list): List of model objects.
+        title (str): The title of the plot.
+        row_key (str): The hyperparameter key changing across rows.
+        col_key (str): The hyperparameter key changing across columns.
+        smooth_span (int): The span for the EWM average.
+    """
+    rows = list(dict.fromkeys([m.id[row_key] for m in models]))
+    cols = list(dict.fromkeys([m.id[col_key] for m in models]))
+
+    fig, axs = plt.subplots(len(rows), len(cols),
+                            figsize=(4.5 * len(cols), 3.5 * len(rows)),
+                            sharex=True, sharey=True, squeeze=False)
+
+    for i, r_val in enumerate(rows):
+        for j, c_val in enumerate(cols):
+            ax = axs[i, j]
+            cell_models = [m for m in models if m.id[row_key] == r_val and m.id[col_key] == c_val]
+
+            for model in cell_models:
+                others = [f"{k}={v}" for k, v in model.id.items() if k not in [row_key, col_key]]
+                label = ", ".join(others)
+                model.plot_loss(ax, label, smooth_span)
+
+            format_ax(ax)
+
+
+            if i == 0:
+                ax.set_title(f"{col_key} = {c_val}")
+
+            if j == len(cols) - 1:
+                ax.text(1.02, 0.5, f"{row_key} = {r_val}",
+                        transform=ax.transAxes, rotation=-90,
+                        va="center", ha="left")
+
+    plt.subplots_adjust(left=0.06, right=0.96, top=0.90, bottom=0.12, wspace=0.10, hspace=0.18)
+    fig.suptitle(title, fontsize=14, fontweight='bold', y=0.98)
+
+    handles, labels = axs[0, 0].get_legend_handles_labels()
+    if handles:
+        fig.legend(handles, labels, loc='lower center', ncol=len(handles),
+                   bbox_to_anchor=(0.5, 0.02), frameon=False, fontsize=9)
+
+    fig.text(0.5, 0.07, "Training steps", ha='center', fontsize=10)
+    fig.text(0.02, 0.5, "Training loss", va='center', rotation='vertical', fontsize=10)
+
+
+
+def plot_losses(dimension: int, models: list, title: str, save_path: str = None, smooth_span: int = 100):
+    """
+    Main entry point for plotting. Automatically detects if the plot should be 0D, 1D, or 2D
+    based on the number of variation parameters.
+
+    Args:
+        dimension (int): dimension of the plot
+        models (list): List of model objects.
+        title (str): The title of the plot.
+        save_path (str, optional): File path to save the figure (e.g., 'plot.png').
+        smooth_span (int): EWM span for smoothing. Defaults to 50.
+    """
+    set_style()
+
+    keys = list(models[0].id.keys())
+
+    if dimension == 0:
+        plot_0d(models, title, smooth_span)
+    elif dimension == 1:
+        plot_1d(models, title, keys[0], smooth_span)
+    else:
+        plot_2d_grid(models, title, keys[0], keys[1], smooth_span)
+
+    if save_path:
+        plt.savefig(save_path, dpi=300, bbox_inches="tight")
+        print(f"Plot saved to {save_path}")
+
+    plt.show()

zeroth_learn-0.1.0/zeroth_learn.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: zeroth-learn
+Version: 0.1.0
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: cycler

zeroth_learn-0.1.0/zeroth_learn.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+zeroth/__init__.py
+zeroth/experiment.py
+zeroth/losses.py
+zeroth/model.py
+zeroth/plot_losses.py
+zeroth_learn.egg-info/PKG-INFO
+zeroth_learn.egg-info/SOURCES.txt
+zeroth_learn.egg-info/dependency_links.txt
+zeroth_learn.egg-info/requires.txt
+zeroth_learn.egg-info/top_level.txt

zeroth_learn-0.1.0/zeroth_learn.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zeroth_learn-0.1.0/zeroth_learn.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+pandas
+matplotlib
+cycler

zeroth_learn-0.1.0/zeroth_learn.egg-info/top_level.txt

@@ -0,0 +1 @@
+zeroth