.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "recipes/006_benchmarks_basic.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_recipes_006_benchmarks_basic.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_recipes_006_benchmarks_basic.py:


.. _benchmarks_basic:

How to Implement Your Benchmark Problems with OptunaHub (Basic)
===============================================================

OptunaHub provides the ``optunahub.benchmarks`` module for implementing benchmark problems.
In this tutorial, we will explain how to implement your own benchmark problems using ``optunahub.benchmarks``.

.. GENERATED FROM PYTHON SOURCE LINES 12-13

First of all, import `optuna` and other required modules.

.. GENERATED FROM PYTHON SOURCE LINES 13-19

.. code-block:: Python

    from __future__ import annotations

    import optuna
    from optunahub.benchmarks import BaseProblem









.. GENERATED FROM PYTHON SOURCE LINES 20-28

Next, define your own problem class by inheriting ``BaseProblem`` class.
Here, let's implement a simple 2-dimensional sphere function.

You need to implement the following methods defined in the ``BaseProblem`` class.:

- ``search_space``: This method returns the dictionary of search space of the problem. Each dictionary element consists of the parameter name and distribution (see `optuna.distributions <https://optuna.readthedocs.io/en/stable/reference/distributions.html>`__).
- ``directions``: This method returns the directions (minimize or maximize) of the problem. The return type is the list of `optuna.study.direction <https://optuna.readthedocs.io/en/stable/reference/generated/optuna.study.StudyDirection.html>`__.
- ``evaluate``: This method evaluates the objective function given a dictionary of input parameters.

.. GENERATED FROM PYTHON SOURCE LINES 28-44

.. code-block:: Python

    class Sphere2D(BaseProblem):
        @property
        def search_space(self) -> dict[str, optuna.distributions.BaseDistribution]:
            return {
                "x0": optuna.distributions.FloatDistribution(low=-5, high=5),
                "x1": optuna.distributions.FloatDistribution(low=-5, high=5),
            }

        @property
        def directions(self) -> list[optuna.study.StudyDirection]:
            return [optuna.study.StudyDirection.MINIMIZE]

        def evaluate(self, params: dict[str, float]) -> float:
            return params["x0"] ** 2 + params["x1"] ** 2









.. GENERATED FROM PYTHON SOURCE LINES 45-46

Since ``BaseProblem`` provides the default implementation of ``__call__(self, trial: optuna.Trial)`` that calls the ``evaluate`` method internally, the problem instance can be directly used as an objective function for ``study.optimize``.

.. GENERATED FROM PYTHON SOURCE LINES 46-51

.. code-block:: Python

    sphere2d = Sphere2D()
    study = optuna.create_study(directions=sphere2d.directions)
    study.optimize(sphere2d, n_trials=20)









.. GENERATED FROM PYTHON SOURCE LINES 52-54

The constructor of the problem class can be customized to introduce additional attributes.
To give an illustration, we show an example with a dynamic dimensional sphere function.

.. GENERATED FROM PYTHON SOURCE LINES 54-77

.. code-block:: Python

    class SphereND(BaseProblem):
        def __init__(self, dim: int) -> None:
            self.dim = dim

        @property
        def search_space(self) -> dict[str, optuna.distributions.BaseDistribution]:
            return {
                f"x{i}": optuna.distributions.FloatDistribution(low=-5, high=5)
                for i in range(self.dim)
            }

        @property
        def directions(self) -> list[optuna.study.StudyDirection]:
            return [optuna.study.StudyDirection.MINIMIZE]

        def evaluate(self, params: dict[str, float]) -> float:
            return sum(params[f"x{i}"] ** 2 for i in range(self.dim))


    sphere3d = SphereND(dim=3)
    study = optuna.create_study(directions=sphere3d.directions)
    study.optimize(sphere3d, n_trials=20)








.. GENERATED FROM PYTHON SOURCE LINES 78-82

After implementing your own benchmark problem, you can register it with OptunaHub.
See :doc:`002_registration` for how to register your benchmark problem with OptunaHub.

In :ref:`benchmarks_advanced`, we explain how to implement more complex benchmark problems such as a problem with dynamic search space.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.136 seconds)


.. _sphx_glr_download_recipes_006_benchmarks_basic.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 006_benchmarks_basic.ipynb <006_benchmarks_basic.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 006_benchmarks_basic.py <006_benchmarks_basic.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 006_benchmarks_basic.zip <006_benchmarks_basic.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_