Merge pull request #136 from knshnb/ensembled-sampler

Add `EnsembledSampler`

package/samplers/ensembled/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kenshin Abe
+
+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.

package/samplers/ensembled/README.md

@@ -0,0 +1,59 @@
+---
+author: Kenshin Abe
+title: Ensembled Sampler
+description: A sampler that ensembles multiple samplers.
+tags: [sampler, ensemble]
+optuna_versions: [3.6.1]
+license: MIT License
+---
+
+<!--
+This is an example of the frontmatters.
+All columns must be string.
+You can omit quotes when value types are not ambiguous.
+For tags, a package placed in
+- package/samplers/ must include the tag "sampler"
+- package/visualilzation/ must include the tag "visualization"
+- package/pruners/ must include the tag "pruner"
+respectively.
+
+---
+author: Optuna team
+title: My Sampler
+description: A description for My Sampler.
+tags: [sampler, 2nd tag for My Sampler, 3rd tag for My Sampler]
+optuna_versions: [3.6.1]
+license: "MIT License"
+---
+-->
+
+## Installation
+
+No additional packages are required.
+
+## Abstract
+
+This package provides a sampler that ensembles multiple samplers.
+You can specify the list of samplers to be ensembled.
+
+## Class or Function Names
+
+- EnsembledSampler
+
+## Example
+
+```python
+import optuna
+import optunahub
+
+mod = optunahub.load_module("samplers/ensembled")
+
+samplers = [
+    optuna.samplers.RandomSampler(),
+    optuna.samplers.TPESampler(),
+    optuna.samplers.CmaEsSampler(),
+]
+sampler = mod.EnsembledSampler(samplers)
+```
+
+See [`example.py`](https://github.com/optuna/optunahub-registry/blob/main/package/samplers/ensembled/example.py) for more details.

package/samplers/ensembled/__init__.py

@@ -0,0 +1,4 @@
+from .sampler import EnsembledSampler
+
+
+__all__ = ["EnsembledSampler"]

package/samplers/ensembled/example.py

@@ -0,0 +1,22 @@
+import optuna
+import optunahub
+
+
+if __name__ == "__main__":
+    samplers = [
+        optuna.samplers.RandomSampler(),
+        optuna.samplers.TPESampler(),
+        optuna.samplers.CmaEsSampler(),
+    ]
+
+    mod = optunahub.load_module("samplers/ensembled")
+    EnsembledSampler = mod.EnsembledSampler
+    study = optuna.create_study(sampler=EnsembledSampler(samplers))
+
+    def objective(trial: optuna.Trial) -> float:
+        x = trial.suggest_float("x", 0, 1)
+        y = trial.suggest_float("y", 0, 1)
+        return x + y
+
+    study.optimize(objective, n_trials=20)
+    print(study.best_params)

package/samplers/ensembled/sampler.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any
+from typing import Sequence
+
+import optuna
+from optuna.distributions import BaseDistribution
+from optuna.samplers import BaseSampler
+from optuna.trial import FrozenTrial
+from optuna.trial import TrialState
+
+
+class EnsembledSampler(BaseSampler):
+    def __init__(self, samplers: list[BaseSampler]) -> None:
+        self._samplers = samplers
+
+    def _get_sampler(self, trial: FrozenTrial) -> BaseSampler:
+        return self._samplers[trial.number % len(self._samplers)]
+
+    def infer_relative_search_space(
+        self, study: optuna.study.Study, trial: FrozenTrial
+    ) -> dict[str, BaseDistribution]:
+        return self._get_sampler(trial).infer_relative_search_space(study, trial)
+
+    def sample_relative(
+        self, study: optuna.Study, trial: FrozenTrial, search_space: dict[str, BaseDistribution]
+    ) -> dict[str, Any]:
+        return self._get_sampler(trial).sample_relative(study, trial, search_space)
+
+    def sample_independent(
+        self,
+        study: optuna.Study,
+        trial: FrozenTrial,
+        param_name: str,
+        param_distribution: BaseDistribution,
+    ) -> Any:
+        return self._get_sampler(trial).sample_independent(
+            study, trial, param_name, param_distribution
+        )
+
+    def after_trial(
+        self,
+        study: optuna.Study,
+        trial: FrozenTrial,
+        state: TrialState,
+        values: Sequence[float] | None,
+    ) -> None:
+        self._get_sampler(trial).after_trial(study, trial, state, values)