add missing torch entries in README and documentation

Author: Abhishek

README.md

@@ -114,8 +114,8 @@ pip install hyperactive[all_extras]           # Everything including Optuna
       <sub>GFO algorithms, Optuna samplers, and sklearn search methods through one unified API.</sub>
     </td>
     <td width="33%">
-      <a href="https://hyperactive.readthedocs.io/en/latest/api_reference.html"><b>Stable & Tested</b></a><br>
-      <sub>5+ years of development, comprehensive test coverage, and active maintenance since 2019.</sub>
+      <a href="https://hyperactive.readthedocs.io/en/latest/examples.html"><b>Problems & Experiments</b></a><br>
+      <sub>Toy optimization problems as well as AI/ML benchmarking experiments for evaluation and testing.</sub>
     </td>
   </tr>
 </table>

docs/source/examples/integrations.rst

@@ -33,6 +33,31 @@ For time series forecasting and classification with sktime:
        pip install hyperactive[sktime-integration]
 
 
+PyTorch Lightning Integration
+-----------------------------
+
+For deep learning hyperparameter optimization with PyTorch Lightning:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Use Case
+     - Example
+   * - PyTorch Lightning Experiment
+     - `torch_experiment_example.py <https://github.com/SimonBlanke/Hyperactive/blob/master/examples/integrations/torch_experiment_example.py>`_
+
+.. note::
+
+   PyTorch Lightning integration requires additional dependencies:
+
+   .. code-block:: bash
+
+       pip install hyperactive[all_extras]
+
+   or install ``torch`` and ``lightning`` separately.
+
+
 Installing Extras
 -----------------
 

examples/integrations/README.md

@@ -1,7 +1,7 @@
 # Integrations with AI framework toolboxes
 
 This directory contains examples for estimator level integration with
-common AI toolbox libraries such as `scikit-learn` or `sktime`.
+common AI toolbox libraries such as `scikit-learn`, `sktime`, or `torch`.
 
 ## Quick Start
 
@@ -12,9 +12,10 @@ You can also run any example directly:
 python sklearn_classif_example.py
 python sktime_forecasting_example.py
 python sktime_tsc_example.py
+python torch_experiment_example.py
 ```
 
-Requires `scikit-learn` resp `sktime` installed.
+Requires `scikit-learn` resp `sktime` resp `torch` and `lightning` installed.
 
 ## Available Integrations
 
@@ -23,6 +24,7 @@ Requires `scikit-learn` resp `sktime` installed.
 | `sklearn` classifier or regressor tuner | [OptCV](sklearn_classif_example.py) |
 | `sktime` forecasting tuner | [ForecastingOptCV](sktime_forecasting_example.py) |
 | `sktime` time series classifier tuner | [TSCOptCV](sktime_tsc_example.py) |
+| `torch` experiment tuner | [TorchExperiment](torch_experiment_example.py) |
 
 ## Integration with sklearn
 
@@ -143,3 +145,100 @@ y_pred = tuned_naive.predict(X_test)
 best_params = tuned_naive.best_params_
 best_classifier = tuned_naive.best_estimator_
 ```
+
+## Integration with torch
+
+Any available tuning engine from hyperactive can be used, for example:
+
+* hill climbing - ``from hyperactive.opt import HillClimbing``
+* bayesian optimization - ``from hyperactive.opt.gfo import BayesianOptimizer``
+* optuna parzen-tree search - ``from hyperactive.opt.optuna import TPEOptimizer``
+
+For illustration, we use hill climbing, this can be replaced by any other optimizer.
+
+```python
+# 1. defining the experiment:
+import numpy as np
+import lightning as L
+import torch
+from torch import nn
+from torch.utils.data import DataLoader
+
+from hyperactive.experiment.integrations import TorchExperiment
+from hyperactive.opt.gfo import HillClimbing
+
+class SimpleLightningModule(L.LightningModule):
+    def __init__(self, input_dim=10, hidden_dim=16, lr=1e-3):
+        super().__init__()
+        self.save_hyperparameters()
+        self.model = nn.Sequential(
+            nn.Linear(input_dim, hidden_dim), nn.ReLU(),
+            nn.Linear(hidden_dim, 2),
+        )
+        self.lr = lr
+
+    def forward(self, x):
+        return self.model(x)
+
+    def training_step(self, batch, batch_idx):
+        x, y = batch
+        loss = nn.functional.cross_entropy(self(x), y)
+        self.log("train_loss", loss)
+        return loss
+
+    def validation_step(self, batch, batch_idx):
+        x, y = batch
+        val_loss = nn.functional.cross_entropy(self(x), y)
+        self.log("val_loss", val_loss, on_epoch=True)
+        return val_loss
+
+    def configure_optimizers(self):
+        return torch.optim.Adam(self.parameters(), lr=self.lr)
+
+class RandomDataModule(L.LightningDataModule):
+    def __init__(self, batch_size=32):
+        super().__init__()
+        self.batch_size = batch_size
+
+    def setup(self, stage=None):
+        dataset = torch.utils.data.TensorDataset(
+            torch.randn(200, 10), torch.randint(0, 2, (200,)),
+        )
+        self.train, self.val = torch.utils.data.random_split(
+            dataset, [160, 40]
+        )
+
+    def train_dataloader(self):
+        return DataLoader(self.train, batch_size=self.batch_size)
+
+    def val_dataloader(self):
+        return DataLoader(self.val, batch_size=self.batch_size)
+
+# 2. creating the experiment:
+datamodule = RandomDataModule(batch_size=16)
+datamodule.setup()
+
+experiment = TorchExperiment(
+    datamodule=datamodule,
+    lightning_module=SimpleLightningModule,
+    trainer_kwargs={"max_epochs": 3},
+    objective_metric="val_loss",
+)
+
+# 3. defining search space and running optimization:
+search_space = {
+    "hidden_dim": [16, 32, 64, 128],
+    "lr": np.logspace(-4, -1, 10).tolist(),
+}
+
+optimizer = HillClimbing(
+    search_space=search_space,
+    n_iter=5,
+    experiment=experiment,
+)
+best_params = optimizer.solve()
+
+# 4. obtaining best parameters
+print(f"Best params: {best_params}")
+```
+

examples/integrations/torch_experiment_example.py

@@ -0,0 +1,111 @@
+"""Example: Hyperparameter tuning with TorchExperiment and PyTorch Lightning.
+
+This example demonstrates how to use the TorchExperiment class to
+optimize hyperparameters of a PyTorch Lightning model using Hyperactive.
+"""
+
+import lightning as L
+import numpy as np
+import torch
+from torch import nn
+from torch.utils.data import DataLoader
+
+from hyperactive.experiment.integrations import TorchExperiment
+from hyperactive.opt.gfo import HillClimbing
+
+
+# 1. Define a Lightning Module
+class SimpleLightningModule(L.LightningModule):
+    """Simple classification model for demonstration."""
+
+    def __init__(self, input_dim=10, hidden_dim=16, lr=1e-3):
+        super().__init__()
+        self.save_hyperparameters()
+        self.model = nn.Sequential(
+            nn.Linear(input_dim, hidden_dim),
+            nn.ReLU(),
+            nn.Linear(hidden_dim, 2),
+        )
+        self.lr = lr
+
+    def forward(self, x):
+        """Forward pass."""
+        return self.model(x)
+
+    def training_step(self, batch, batch_idx):
+        """Training step."""
+        x, y = batch
+        y_hat = self(x)
+        loss = nn.functional.cross_entropy(y_hat, y)
+        self.log("train_loss", loss)
+        return loss
+
+    def validation_step(self, batch, batch_idx):
+        """Validate a single batch."""
+        x, y = batch
+        y_hat = self(x)
+        val_loss = nn.functional.cross_entropy(y_hat, y)
+        self.log("val_loss", val_loss, on_epoch=True)
+        return val_loss
+
+    def configure_optimizers(self):
+        """Configure optimizers."""
+        return torch.optim.Adam(self.parameters(), lr=self.lr)
+
+
+# 2. Define a DataModule
+class RandomDataModule(L.LightningDataModule):
+    """Random data module for demonstration."""
+
+    def __init__(self, batch_size=32):
+        super().__init__()
+        self.batch_size = batch_size
+
+    def setup(self, stage=None):
+        """Set up train and validation datasets."""
+        dataset = torch.utils.data.TensorDataset(
+            torch.randn(200, 10),
+            torch.randint(0, 2, (200,)),
+        )
+        self.train, self.val = torch.utils.data.random_split(dataset, [160, 40])
+
+    def train_dataloader(self):
+        """Return training dataloader."""
+        return DataLoader(self.train, batch_size=self.batch_size)
+
+    def val_dataloader(self):
+        """Return validation dataloader."""
+        return DataLoader(self.val, batch_size=self.batch_size)
+
+
+# 3. Create the TorchExperiment
+datamodule = RandomDataModule(batch_size=16)
+datamodule.setup()
+
+experiment = TorchExperiment(
+    datamodule=datamodule,
+    lightning_module=SimpleLightningModule,
+    trainer_kwargs={
+        "max_epochs": 3,
+        "enable_progress_bar": False,
+        "enable_model_summary": False,
+        "logger": False,
+    },
+    objective_metric="val_loss",
+)
+
+# 4. Define search space and optimizer
+search_space = {
+    "hidden_dim": [16, 32, 64, 128],
+    "lr": np.logspace(-4, -1, 10).tolist(),
+}
+
+optimizer = HillClimbing(
+    search_space=search_space,
+    n_iter=5,
+    experiment=experiment,
+)
+
+# 5. Run optimization
+best_params = optimizer.solve()
+print(f"Best params: {best_params}")