[HPO] Documentations update with sphinx

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/build/doctrees/nbsphinx/contents/getting_started.ipynb

@@ -0,0 +1,220 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "demographic-bulletin",
+   "metadata": {},
+   "source": [
+    "# Getting Started with hpopt"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "81460b40",
+   "metadata": {},
+   "source": [
+    "This is quick start for hpoopt. You can learn how to use hpopt standalone with your own traninig module."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "duplicate-plane",
+   "metadata": {},
+   "source": [
+    "## 1. Installation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2d6ef719",
+   "metadata": {},
+   "source": [
+    "\n",
+    "You only need to run following code to install hpopt.\n",
+    "\n",
+    "``` bash\n",
+    "git clone https://github.com/openvinotoolkit/hyper_parameter_optimization\n",
+    "pip install -v -e ./hyper_parameter_optimization\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "22ebd406",
+   "metadata": {},
+   "source": [
+    "## 2. Run HPO"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aca6bb13",
+   "metadata": {},
+   "source": [
+    "First of all, you need to import hpopt to run HPO."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "4be4967c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hpopt"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c1ce246b",
+   "metadata": {},
+   "source": [
+    "Then, make you own models. In this code, I implement very simple black-box function which has two hyper parameters 'a' and 'b'."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "430cd36c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "\n",
+    "import random\n",
+    "\n",
+    "def my_model(a, b, iter):\n",
+    "    return a**2 + (b - 10)**2 + iter * 0.1 + random.random() * 0.1\n",
+    "\n",
+    "def my_trainer(config):\n",
+    "    for iter in range(config[\"iterations\"]):\n",
+    "        score = my_model(**config[\"params\"], iter=iter)\n",
+    "        if hpopt.report(config=config, score=score) == hpopt.Status.STOP:\n",
+    "            break"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b354b760",
+   "metadata": {},
+   "source": [
+    "You should define hyper parameter search space to run HPO. Hyper parameter search space is dictionary which has hyper parameter name as key and search space sampling option as value.\n",
+    "Please refer [](./apis.md) for more details."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "e7b54790",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# make hyper parameter space\n",
+    "search_space = {\"a\": hpopt.search_space(\"uniform\", [-5, 10]),\n",
+    "              \"b\": hpopt.search_space(\"uniform\", [0, 15])}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f1acf21f",
+   "metadata": {},
+   "source": [
+    "Let's initiate hpopt class with hyper parameter search space we made. In this case, we run simple bayesian optimization(SMBO)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "ahead-visibility",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "my_hpo = hpopt.create(save_path='./tmp/my_hpo', # where HPO progress is saved\n",
+    "                      search_alg=\"bayes_opt\", # HPO algorithm\n",
+    "                      search_space=search_space,\n",
+    "                      early_stop=\"median_stop\", # early stopping method\n",
+    "                      num_init_trials=5, num_trials=10, max_iterations=2,\n",
+    "                      resume=False,\n",
+    "                      num_full_iterations=2, # train iteration\n",
+    "                      full_dataset_size=1) # train dataset size. In this case, you can ignore it."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "61fcc5f8",
+   "metadata": {},
+   "source": [
+    "Finally, we can run HPO and print output."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "e54d2cf6",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "|  #  |         a           |         b           |        score        |\n",
+      "|   1 |   9.629164679496109 |   9.152868582262837 |   93.56057080971651 |\n",
+      "|   2 |   9.503930895864768 |  10.477054966570938 |    90.6920277461489 |\n",
+      "|   3 |  6.5275823645277775 |   14.59670633381528 |   63.90848097562949 |\n",
+      "|   4 |  2.8808311670306797 |   9.058790892076829 |    9.29099328793063 |\n",
+      "|   5 |    7.95029121913541 |  13.178755341124605 |   73.50752311230228 |\n",
+      "|   6 |                10.0 |                 0.0 |  200.10740027553825 |\n",
+      "|   7 |   6.025026543316109 |                 0.0 |   136.4928912794813 |\n",
+      "|   8 |                10.0 |  1.6328830252328062 |  170.14644018670234 |\n",
+      "|   9 |                -5.0 |                 0.0 |  125.12112966688557 |\n",
+      "|  10 |   9.571587105736812 |0.004128397224773539 |  191.68849629266415 |\n",
+      "best hp:  {'a': 10.0, 'b': 0.0}\n"
+     ]
+    }
+   ],
+   "source": [
+    "while True:\n",
+    "    config = my_hpo.get_next_sample()\n",
+    "\n",
+    "    if config is None:\n",
+    "        break\n",
+    "\n",
+    "    my_trainer(config)\n",
+    "\n",
+    "best_config = my_hpo.get_best_config()\n",
+    "\n",
+    "my_hpo.print_results()\n",
+    "\n",
+    "print(\"best hp: \", best_config)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fa943338",
+   "metadata": {},
+   "source": [
+    "As you can see, hpopt found best hyper parameters for black box function."
+   ]
+  }
+ ],
+ "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.8.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/make_venv.sh

@@ -0,0 +1,4 @@
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+sudo apt-get install pandoc

docs/requirements.txt

@@ -0,0 +1,81 @@
+alabaster==0.7.12
+attrs==21.4.0
+Babel==2.10.2
+bayesian-optimization==1.2.0
+beautifulsoup4==4.11.1
+bleach==5.0.0
+certifi==2022.6.15
+charset-normalizer==2.0.12
+commonmark==0.9.1
+defusedxml==0.7.1
+docutils==0.17.1
+entrypoints==0.4
+fastjsonschema==2.15.3
+idna==3.3
+imagesize==1.3.0
+importlib-metadata==4.11.4
+importlib-resources==5.8.0
+Jinja2==3.1.2
+joblib==1.1.0
+jsonschema==4.6.0
+jupyter-client==7.3.4
+jupyter-core==4.10.0
+jupyterlab-pygments==0.2.2
+Markdown==3.3.7
+markdown-it-py==2.1.0
+MarkupSafe==2.1.1
+mdit-py-plugins==0.3.0
+mdurl==0.1.1
+mistune==0.8.4
+myst-parser==0.18.0
+nbclient==0.6.4
+nbconvert==6.5.0
+nbformat==5.4.0
+nbsphinx==0.8.9
+nest-asyncio==1.5.5
+numpy==1.22.4
+packaging==21.3
+pandoc==2.2
+pandocfilters==1.5.0
+Pillow==9.1.1
+plumbum==1.7.2
+ply==3.11
+pydash==5.1.0
+Pygments==2.12.0
+pymdown-extensions==9.5
+pyparsing==3.0.9
+pyrsistent==0.18.1
+python-dateutil==2.8.2
+pytz==2022.1
+PyYAML==6.0
+pyzmq==23.1.0
+recommonmark==0.7.1
+requests==2.28.0
+scikit-learn==1.1.1
+scipy==1.8.1
+six==1.16.0
+snowballstemmer==2.2.0
+soupsieve==2.3.2.post1
+Sphinx==5.0.1
+sphinx-markdown-parser==0.2.4
+sphinx-markdown-tables==0.0.15
+sphinx-rtd-theme==1.0.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+threadpoolctl==3.1.0
+tinycss2==1.1.1
+torch==1.11.0
+torchvision==0.12.0
+tornado==6.1
+traitlets==5.2.2.post1
+typing-extensions==4.2.0
+unify==0.5
+untokenize==0.1.1
+urllib3==1.26.9
+webencodings==0.5.1
+yapf==0.32.0
+zipp==3.8.0