Make DEHB installable with pip

dehb/__init__.py

@@ -1,3 +1,5 @@
 from .optimizers import DE, AsyncDE
 from .optimizers import DEHB
 from .utils import SHBracketManager
+
+from dehb.__version__ import __version__  # noqa: F401

dehb/__version__.py

@@ -0,0 +1 @@
+__version__ = '0.0.1dev'

examples/00_interfacing_DEHB.ipynb

@@ -172,7 +172,7 @@
      "data": {
       "text/plain": [
        "Configuration:\n",
-       "  x0, Value: 6.3793522646424785"
+       "  x0, Value: 3.716302229868112"
       ]
      },
      "execution_count": 5,
@@ -257,6 +257,15 @@
     "# but can be tuned as desired"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "?dehb.run"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -267,15 +276,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
       "Configuration:\n",
-      "  x0, Value: 4.647994905980703\n",
+      "  x0, Value: 4.060258498267547\n",
       "\n"
      ]
     }
@@ -294,21 +303,21 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2021-03-22 17:53:27.292 | INFO     | dehb.optimizers.dehb:reset:102 - \n",
+      "2021-10-22 14:45:56.117 | INFO     | dehb.optimizers.dehb:reset:107 - \n",
       "\n",
-      "RESET at 03/22/21 17:53:27 CET\n",
+      "RESET at 10/22/21 14:45:56 CEST\n",
       "\n",
       "\n",
       "(Configuration:\n",
-      "  x0, Value: 3.5500062657482494\n",
-      ", 0.04514887709783266)\n"
+      "  x0, Value: 3.724555206841792\n",
+      ", 0.0938589687572785)\n"
      ]
     }
    ],
@@ -329,21 +338,21 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2021-03-22 17:53:29.658 | INFO     | dehb.optimizers.dehb:reset:102 - \n",
+      "2021-10-22 14:45:58.567 | INFO     | dehb.optimizers.dehb:reset:107 - \n",
       "\n",
-      "RESET at 03/22/21 17:53:29 CET\n",
+      "RESET at 10/22/21 14:45:58 CEST\n",
       "\n",
       "\n",
       "(Configuration:\n",
-      "  x0, Value: 6.898789003516494\n",
-      ", 0.0068207743261361475)\n"
+      "  x0, Value: 4.341818535733585\n",
+      ", 3.653636256717441e-05)\n"
      ]
     }
    ],
@@ -367,16 +376,16 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
       "(Configuration:\n",
-      "  x0, Value: 6.695906943430258\n",
-      ", 0.015266398519239388)\n"
+      "  x0, Value: 4.610766436763522\n",
+      ", 0.007774399252232556)\n"
      ]
     }
    ],
@@ -399,15 +408,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 13,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
       "Configuration:\n",
-      "  x0, Value: 6.695906943430258\n",
+      "  x0, Value: 4.610766436763522\n",
       "\n"
      ]
     }
@@ -418,16 +427,16 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "0.015266398519239388 0.015266398519239388\n",
+      "0.007774399252232556 0.007774399252232556\n",
       "Configuration:\n",
-      "  x0, Value: 6.695906943430258\n",
+      "  x0, Value: 4.610766436763522\n",
       "\n"
      ]
     }

setup.py

@@ -0,0 +1,48 @@
+# -*- encoding: utf-8 -*-
+import setuptools
+
+
+def read_file(file_name):
+    with open(file_name, encoding='utf-8') as fh:
+        text = fh.read()
+    return text
+
+
+setuptools.setup(
+    name='dehb',
+    author_email='{awad, mallik, fh}@cs.uni-freiburg.de',
+    description='Evolutionary Hyberband for Scalable, Robust and Efficient Hyperparameter Optimization',
+    long_description=read_file('README.md'),
+    long_description_content_type='text/markdown',
+    license='Apache-2.0',
+    url='https://www.automl.org/automl/',
+    project_urls={
+        'Documentation': 'https://github.com/automl/dehb',
+        'Source Code': 'https://github.com/automl/dehb'
+    },
+    version=read_file('dehb/__version__.py').split()[-1].strip('\''),
+    packages=setuptools.find_packages(exclude=[
+        '*.tests', '*.tests.*', 'tests.*', 'tests'],
+    ),
+    python_requires='>3.5, <=3.9',
+    install_requires=read_file('./requirements.txt').split('\n'),
+    test_suite='pytest',
+    platforms=['Linux'],
+    classifiers=[
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: 3.8',
+        'Development Status :: 3 - Alpha',
+        'Natural Language :: English',
+        'Environment :: Console',
+        'Intended Audience :: Developers',
+        'Intended Audience :: Education',
+        'Intended Audience :: Science/Research',
+        'License :: OSI Approved :: Apache Software License',
+        'Operating System :: POSIX :: Linux',
+        'Topic :: Scientific/Engineering :: Artificial Intelligence',
+        'Topic :: Scientific/Engineering',
+        'Topic :: Software Development',
+    ]
+)

utils/README.md

@@ -0,0 +1,41 @@
+### Scripts to setup a Dask cluster on Meta SLURM
+
+There are 2 distinct ways in which DEHB can be run in a distributed manner.
+* Letting the DEHB process create its [own Dask cluster](../README.md#running-dehb-in-a-parallel-setting) during runtime that lives and dies with the DEHB process 
+* Setting up a Dask cluster that runs independently and multiple DEHB processes can connect and share the cluster
+
+The scripts and instructions below account for the latter case, specifically for **SLURM**:
+
+To create a Dask cluster with 10 workers and uses CPUs:
+```bash
+python utils/generate_slurm_jobs.py --worker_p [cpu_node] --scheduler_p [cpu_node] --nworkers 10 \
+    --scheduler_path ./scheduler --scheduler_file scheduler_cpu.json --output_path temp --setup_file ./setup.sh
+# generates 2 shell scripts
+```
+```bash
+sbatch temp/scheduler.sh
+# sleep 2s or wait till scheduler is allocated (not mandatory)
+sbatch temp/workers.sh
+```
+
+Alternatively, to enable GPU usage by the workers,
+```bash
+python utils/generate_slurm_jobs.py --worker_p [cpu_node] --scheduler_p [cpu_node] --nworkers 10 \
+    --scheduler_path ./scheduler --scheduler_file scheduler_gpu.json --output_path temp \
+    --setup_file ./setup.sh --gpu
+# generates 2 shell scripts
+sbatch temp/scheduler.sh
+# sleep 2s or wait till scheduler is allocated (not mandatory)
+sbatch temp/workers.sh
+```
+
+The above sequence of commands will have a Dask cluster running and waiting for jobs. 
+One or more DEHB processes can share this pool of 10 workers.
+For example, running a DEHB optimization by specifiying `scheduler_file` makes that DEHB process, 
+connect to the Dask cluster runnning.
+```bash
+python examples/03_pytorch_mnist_hpo.py --min_budget 1 --max_budget 9 --verbose \
+    --scheduler_file scheduler/scheduler_gpu.json --runtime 200 --seed 123
+```
+The decoupled Dask cluster remains alive even after the DEHB optimization is over. 
+It can be reused by other DEHB runs or processes.