diff --git a/README.md b/README.md index 60bd5ce8..bf52a1ce 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,6 @@ You can install optuna-dashboard via [PyPI](https://pypi.org/project/optuna-dash $ pip install optuna-dashboard ``` -Also, you can install following optional dependencies to make optuna-dashboard faster. - -```console -$ pip install optuna-fast-fanova gunicorn -``` - ## Getting Started First, please specify the storage URL to persistent your study using the [RDB backend](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/001_rdb.html). @@ -49,56 +43,7 @@ Listening on http://localhost:8080/ Hit Ctrl-C to quit. ``` -
- -More command line options - -```console -$ optuna-dashboard -h -usage: optuna-dashboard [-h] [--port PORT] [--host HOST] [--version] [--quiet] storage - -Real-time dashboard for Optuna. - -positional arguments: - storage DB URL (e.g. sqlite:///example.db) - -optional arguments: - -h, --help show this help message and exit - --port PORT port number (default: 8080) - --host HOST hostname (default: 127.0.0.1) - --server {wsgiref,gunicorn} - server (default: auto) - --artifact-dir ARTIFACT_DIR - directory to store artifact files - --version, -v show program's version number and exit - --quiet, -q quiet -``` - -
- -
- -Python Interface - -**`run_server(storage: Union[str, BaseStorage], host: str = 'localhost', port: int = 8080) -> None`** - -Start running optuna-dashboard and blocks until the server terminates. -This function uses wsgiref module which is not intended for the production use. - -**`wsgi(storage: Union[str, BaseStorage]) -> WSGIApplication`** - -This function exposes WSGI interface for people who want to run on the -production-class WSGI servers like Gunicorn or uWSGI. - -**`save_note(study_or_trial: Union[Study, Trial], body: str) -> None`** - -Save the note (Markdown format) to the Study or the Trial. - -**`set_objective_names(study: Study, names: list[str]) -> None`** - -Set the names of objectives. - -
+Please check out [our documentation](https://optuna-dashboard.readthedocs.io) for more details. ## Using an official Docker image diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 00000000..324f0b35 --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,204 @@ +Getting Started +=============== + +Installation +------------ + +Prerequisite +~~~~~~~~~~~~ + +Optuna Dashboard supports Python 3.7 or newer. + + +Installing from PyPi +~~~~~~~~~~~~~~~~~~~~ + +You can install optuna-dashboard via `PyPI `_ or `Anaconda Cloud `_. + +.. code-block:: console + + $ pip install optuna-dashboard + +Also, you can install following optional dependencies to make optuna-dashboard faster. + +.. code-block:: console + + $ pip install optuna-fast-fanova gunicorn + +Installing from the source code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since it requires to build TypeScript files, ``pip install git+https://.../optuna-dashboard.git`` does not actually work. +Please clone the git repository and execute following commands to build sdist package: + +.. code-block:: console + + $ git clone git@github.com:optuna/optuna.git + $ cd optuna + +.. code-block:: console + + # Node.js v16 is required to compile TypeScript files. + $ npm install + $ npm run build:prd + $ python setup.py sdist + +Then you can install it like: + +.. code-block:: console + + $ pip install dist/optuna-dashboard-x.y.z.tar.gz + +See `CONTRIBUTING.md `_ for more details. + + +Command-line Interface +---------------------- + +The most common usage of Optuna Dashboard is using the command-line interface. +Assuming that Optuna's optimization history is persisted using ``RDBStorage``, +you can use the command line interface like ``optuna-dashboard ``. + +.. code-block:: python + + import optuna + + def objective(trial): + x = trial.suggest_float("x", -100, 100) + y = trial.suggest_categorical("y", [-1, 0, 1]) + return x**2 + y + + study = optuna.create_study( + storage="sqlite:///db.sqlite3", # Specify the storage URL here. + study_name="quadratic-simple" + ) + study.optimize(objective, n_trials=100) + print(f"Best value: {study.best_value} (params: {study.best_params})") + + +.. code-block:: console + + $ optuna-dashboard sqlite:///db.sqlite3 + Listening on http://localhost:8080/ + Hit Ctrl-C to quit. + +If you are using JournalStorage classes introduced in Optuna v3.1, you can use them like below: + +.. code-block:: console + + # JournalFileStorage + $ optuna-dashboard ./path/to/journal.log + + # JournalRedisStorage + $ optuna-dashboard redis://localhost:6379 + + +Using an official Docker image +------------------------------ + +You can also use `an official Docker image `_ instead of setting up your Python environment. +The Docker image only supports SQLite3, MySQL(PyMySQL), and PostgreSQL(Psycopg2). + +**SQLite3** + +.. code-block:: console + + $ docker run -it --rm -p 8080:8080 -v `pwd`:/app -w /app ghcr.io/optuna/optuna-dashboard sqlite:///db.sqlite3 + + +**MySQL (PyMySQL)** + +.. code-block:: console + + $ docker run -it --rm -p 8080:8080 ghcr.io/optuna/optuna-dashboard mysql+pymysql://username:password@hostname:3306/dbname + +**PostgreSQL (Psycopg2)** + +.. code-block:: console + + $ docker run -it --rm -p 8080:8080 ghcr.io/optuna/optuna-dashboard postgresql+psycopg2://username:password@hostname:5432/dbname + +Python Interface +---------------- + +Python interfaces are also provided for users who want to use other storage implementations (e.g. ``InMemoryStorage``). +You can use :func:`~optuna_dashboard.run_server` function like below: + +.. code-block:: python + + import optuna + from optuna_dashboard import run_server + + def objective(trial): + x = trial.suggest_float("x", -100, 100) + y = trial.suggest_categorical("y", [-1, 0, 1]) + return x**2 + y + + storage = optuna.storages.InMemoryStorage() + study = optuna.create_study(storage=storage) + study.optimize(objective, n_trials=100) + + run_server(storage) + + +Using Gunicorn or uWSGI server +------------------------------ + +Optuna Dashboard uses `wsgiref `_ module, which is in the Python's standard libraries, by default. +However, as described `here `_, ``wsgiref`` is implemented for testing or debugging purpose. +You can switch to other WSGI server implementations by using :func:`~optuna_dashboard.wsgi` function. + +.. code-block:: python + + :caption: wsgi.py + + from optuna.storages import RDBStorage + from optuna_dashboard import wsgi + + storage = RDBStorage("sqlite:///db.sqlite3") + application = wsgi(storage) + +Then please execute following commands to start. + +.. code-block:: console + + $ pip install gunicorn + $ gunicorn --workers 4 wsgi:application + +or + +.. code-block:: console + + $ pip install uwsgi + $ uwsgi --http :8080 --workeers 4 --wsgi-file wsgi.py + + +Google Colaboratory +------------------- + +When you want to check the optimization history on Google Colaboratory, +you can use ``google.colab.output()`` function as follows: + +.. code-block:: python + + import optuna + import threading + from google.colab import output + from optuna_dashboard import run_server + + def objective(trial): + x = trial.suggest_float("x", -100, 100) + return (x - 2) ** 2 + + # Run optimization + storage = optuna.storages.InMemoryStorage() + study = optuna.create_study(storage=storage) + study.optimize(objective, n_trials=100) + + # Start Optuna Dashboard + port = 8081 + thread = threading.Thread(target=run_server, args=(storage,), kwargs={"port": port}) + thread.start() + output.serve_kernel_port_as_window(port, path='/dashboard/') + +Then please open http://localhost:8081/dashboard to browse. diff --git a/docs/index.rst b/docs/index.rst index c12e83c4..71a0a66e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,7 +12,7 @@ Real-time dashboard for `Optuna `_. :maxdepth: 3 :caption: Contents: - installation + getting-started api errors diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index c8fb2ac1..00000000 --- a/docs/installation.rst +++ /dev/null @@ -1,17 +0,0 @@ -Installation -============ - -Optuna Dashboard supports Python 3.7 or newer. - -We recommend to install Optuna via pip: -You can install optuna-dashboard via `PyPI `_ or `Anaconda Cloud `_. - -.. code-block:: console - - $ pip install optuna-dashboard - -Also, you can install following optional dependencies to make optuna-dashboard faster. - -.. code-block:: console - - $ pip install optuna-fast-fanova gunicorn