{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\nSaving/Resuming Study with RDB Backend\n==========================================\n\nAn RDB backend enables persistent experiments (i.e., to save and resume a study) as well as access to history of studies.\nIn addition, we can run multi-node optimization tasks with this feature, which is described in `sphx_glr_tutorial_004_distributed.py`.\n\nIn this section, let's try simple examples running on a local environment with SQLite DB.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>You can also utilize other RDB backends, e.g., PostgreSQL or MySQL, by setting the storage argument to the DB's URL.\n    Please refer to `SQLAlchemy's document <https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls>`_ for how to set up the URL.</p></div>\n\n\nNew Study\n---------\n\nWe can create a persistent study by calling :func:`~optuna.study.create_study` function as follows.\nAn SQLite file ``example.db`` is automatically initialized with a new study record.\n\n.. code-block:: python\n\n    import optuna\n    study_name = 'example-study'  # Unique identifier of the study.\n    study = optuna.create_study(study_name=study_name, storage='sqlite:///example.db')\n\nTo run a study, call :func:`~optuna.study.Study.optimize` method passing an objective function.\n\n.. code-block:: python\n\n    def objective(trial):\n        x = trial.suggest_uniform('x', -10, 10)\n        return (x - 2) ** 2\n\n    study.optimize(objective, n_trials=3)\n\nResume Study\n------------\n\nTo resume a study, instantiate a :class:`~optuna.study.Study` object passing the study name ``example-study`` and the DB URL ``sqlite:///example.db``.\n\n.. code-block:: python\n\n    study = optuna.create_study(study_name='example-study', storage='sqlite:///example.db', load_if_exists=True)\n    study.optimize(objective, n_trials=3)\n\nExperimental History\n--------------------\n\nWe can access histories of studies and trials via the :class:`~optuna.study.Study` class.\nFor example, we can get all trials of ``example-study`` as:\n\n.. code-block:: python\n\n    import optuna\n    study = optuna.create_study(study_name='example-study', storage='sqlite:///example.db', load_if_exists=True)\n    df = study.trials_dataframe(attrs=('number', 'value', 'params', 'state'))\n\nThe method :func:`~optuna.study.Study.trials_dataframe` returns a pandas dataframe like:\n\n.. code-block:: python\n\n    print(df)\n\nOut:\n\n.. code-block:: console\n\n            number       value  params_x     state\n         0       0   25.301959 -3.030105  COMPLETE\n         1       1    1.406223  0.814157  COMPLETE\n         2       2   44.010366 -4.634031  COMPLETE\n         3       3   55.872181  9.474770  COMPLETE\n         4       4  113.039223 -8.631991  COMPLETE\n         5       5   57.319570  9.570969  COMPLETE\n\nA :class:`~optuna.study.Study` object also provides properties such as :attr:`~optuna.study.Study.trials`, :attr:`~optuna.study.Study.best_value`, :attr:`~optuna.study.Study.best_params` (see also `sphx_glr_tutorial_001_first.py`).\n\n.. code-block:: python\n\n    study.best_params  # Get best parameters for the objective function.\n    study.best_value  # Get best objective value.\n    study.best_trial  # Get best trial's information.\n    study.trials  # Get all trials' information.\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.7"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}