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

.. only:: html

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

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

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

.. _sphx_glr_recipes_003_pruner.py:


.. _pruner:

How to Implement Your Pruners with OptunaHub
=========================================================

OptunaHub supports Optuna's pruners as well as samplers and visualization functions.
This recipe shows how to implement and register your own pruner with OptunaHub.

Usually, Optuna provides ``BasePruner`` class to implement your own sampler.
You can implement your own pruner by inheriting this class.
You need to install ``optuna`` to implement your own pruner.

.. code-block:: bash

    $ pip install optuna

.. GENERATED FROM PYTHON SOURCE LINES 21-22

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

.. GENERATED FROM PYTHON SOURCE LINES 22-28

.. code-block:: Python

    from __future__ import annotations

    import optuna
    from optuna.pruners import BasePruner









.. GENERATED FROM PYTHON SOURCE LINES 29-31

Next, define your own pruner class by inheriting ``BasePruner`` class.
In this example, we implement a pruner that stops objective functions based on a given threshold.

.. GENERATED FROM PYTHON SOURCE LINES 31-58

.. code-block:: Python

    class MyPruner(BasePruner):  # type: ignore
        def __init__(self, upper_threshold: float, n_warmup_steps: int) -> None:
            self._upper_threshold = upper_threshold
            self._n_warmup_steps = n_warmup_steps

        # You need to implement `prune` method.
        # This method returns true if it stops objective function, otherwise false.
        # It stops the objective function if the intermediate value exceeds the threshold.
        # Note that first `n_warmup_steps` steps are not pruned.
        def prune(
            self,
            study: optuna.study.Study,
            trial: optuna.trial.FrozenTrial,
        ) -> bool:
            step = trial.last_step
            if step is None:
                return False

            if step < self._n_warmup_steps:
                return False

            if trial.intermediate_values[step] > self._upper_threshold:
                return True

            return False









.. GENERATED FROM PYTHON SOURCE LINES 59-61

In this example, the objective function is a simple quadratic function.
It has 20 variables and the sum of the squares of these variables is returned.

.. GENERATED FROM PYTHON SOURCE LINES 61-74

.. code-block:: Python



    def objective(trial: optuna.trial.Trial) -> float:
        s = 0.0
        for step in range(20):
            x = trial.suggest_float(f"x_{step}", -5, 5)
            s += x**2
            trial.report(s, step)
            if trial.should_prune():
                raise optuna.TrialPruned()
        return s









.. GENERATED FROM PYTHON SOURCE LINES 75-77

This pruner can be used in the same way as other Optuna pruners.
In the following example, we create a study and optimize it using ``MyPruner`` class.

.. GENERATED FROM PYTHON SOURCE LINES 77-81

.. code-block:: Python

    pruner = MyPruner(upper_threshold=100, n_warmup_steps=5)
    study = optuna.create_study(pruner=pruner)
    study.optimize(objective, n_trials=100)








.. GENERATED FROM PYTHON SOURCE LINES 82-85

After implementing your own pruner, you can register it with OptunaHub.
See :doc:`002_registration` for how to register your pruner with OptunaHub.
See `the User-Defined Pruner documentation <https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/006_user_defined_pruner.html>`_ for more information to implement an pruner.


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

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


.. _sphx_glr_download_recipes_003_pruner.py:

.. only:: html

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

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

      :download:`Download Jupyter notebook: 003_pruner.ipynb <003_pruner.ipynb>`

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

      :download:`Download Python source code: 003_pruner.py <003_pruner.py>`

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

      :download:`Download zipped: 003_pruner.zip <003_pruner.zip>`


.. only:: html

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

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