Version bump, update deps + readme (#115)

Summary:
- peg to (currently non-existing) pytorch version 1.1
- peg to gpytorch 0.3.2
- Update setup.py with classifiers / urls
- Overhaul README, add badges, examples, etc
Pull Request resolved: #115

Reviewed By: danielrjiang

Differential Revision: D15160094

Pulled By: Balandat

fbshipit-source-id: 858e77d5ba812121de8e5a3e3648505f7e2d5bf8

Author: Balandat

.conda/meta.yaml

@@ -15,8 +15,8 @@ requirements:
   host:
     - python>=3.6
   run:
-    - pytorch-nightly
-    - gpytorch
+    - pytorch>=1.1
+    - gpytorch>=0.3.2
     - scipy
 
 test:

CHANGELOG.md

@@ -1 +1,7 @@
-No release yet.
+# Changelog
+
+The release log for BoTorch.
+
+## [0.1.0] - April 30, 2019
+
+First public beta release.

README.md

@@ -2,17 +2,18 @@
   <img width="300" src="./botorch_logo_lockup.svg" alt="BoTorch Logo" />
 </a>
 
-[![Build Status](
-  https://travis-ci.com/pytorch/botorch.svg?token=esFvpzSw7sLSsfe1PAr1&branch=master
-)](https://travis-ci.com/pytorch/botorch)
+[![CircleCI](https://circleci.com/gh/pytorch/botorch.svg?style=shield&circle-token=19c388387063692b6d33eecc243c8990a43ae655)](https://circleci.com/gh/pytorch/botorch)
+[![Conda](https://img.shields.io/conda/v/pytorch/botorch.svg)](https://anaconda.org/pytorch/botorch)
+[![PyPI](https://img.shields.io/pypi/v/botorch.svg)](https://pypi.org/project/botorch)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)
 
 
 BoTorch is a library for Bayesian Optimization built on PyTorch.
 
-*BoTorch is currently in alpha and under active development - be warned*!
+*BoTorch is currently in beta and under active development!*
 
 
-### Why BoTorch
+#### Why BoTorch ?
 BoTorch
 * Provides a modular and easily extensible interface for composing Bayesian
   optimization primitives, including probabilistic models, acquisition functions,
@@ -30,30 +31,43 @@ BoTorch
   Processes (GPs) deep kernel learning, deep GPs, and approximate inference.
 
 
-### Target Audience
+#### Target Audience
 
 The primary audience for hands-on use of BoTorch are researchers and
 sophisticated practitioners in Bayesian Optimization and AI.
-
 We recommend using BoTorch as a low-level API for implementing new algorithms
-for [Ax](https://github.com/facebook/Ax). Ax has been designed to be
-an easy-to-use platform for end-users, which at the same time is flexible enough
-for Bayesian Optimization researchers to plug into for handling of feature
-transformations, (meta-)data management, storage, etc.
-
+for [Ax](https://ax.dev). Ax has been designed to be an easy-to-use platform
+for end-users, which at the same time is flexible enough for Bayesian
+Optimization researchers to plug into for handling of feature transformations,
+(meta-)data management, storage, etc.
 We recommend that end-users who are not actively doing research on Bayesian
 Optimization simply use Ax.
 
 
 ## Installation
 
-#### Installation Requirements
-
+**Installation Requirements**
 - Python >= 3.6
-- PyTorch nightly (**TODO:** peg to PyTorch 1.1 once released)
-- gpytorch >= 0.3.1 (**TODO:** peg to GPyTorch 0.3.2 once released)
+- PyTorch >= 1.1
+- gpytorch >= 0.3.2
 - scipy
 
+
+#### Installing BoTorch
+
+
+##### Installing the latest release
+
+The latest release of BoTorch is easily installed either via
+[Anaconda](https://www.anaconda.com/distribution/#download-section) (recommended):
+```bash
+conda install botorch -c pytorch
+```
+or via `pip`:
+```bash
+pip install botorch
+```
+
 **Important note for MacOS users:**
 * You will want to make sure your PyTorch build is linked against MKL (the
   non-optimized version of BoTorch can be up to an order of magnitude slower in
@@ -64,52 +78,75 @@ Optimization simply use Ax.
   consult the PyTorch installation instructions above.
 
 
-#### Installing BoTorch
+##### Installing from latest master
 
-The latest release of BoTorch is easily installed using either pip or conda:
-```bash
-pip install botorch
-```
-
-**TODO: Conda install**
-
-
-If you'd like to try our bleeding edge features (and don't mind running into an
-occasional bug here or there), you can install the latest master from GitHub
-(this will also require installing the current GPyTorch master)::
+If you'd like to try our bleeding edge features (and don't mind potentially
+running into the occasional bug here or there), you can install the latest
+master directly from GitHub (this will also require installing the current GPyTorch master):
 ```bash
 pip install git+https://github.com/cornellius-gp/gpytorch.git
 pip install git+https://github.com/pytorch/botorch.git
 ```
 
+**Manual / Dev install**
 
-#### Installing BoTorch from the private repo **TODO: REMOVE**
-
-BoTorch is easily installed using pip:
-```bash
-pip install git+ssh://[email protected]/pytorch/botorch.git
-```
-
-*Note:* You must use **ssh** here since the repo is private - for this to work,
-make sure your ssh public key is registered with GitHub, and is usable by ssh.
-
-Alternatively, you can do a manual install. To do a basic install, run:
+Alternatively, you can do a manual install. For a basic install, run:
 ```bash
+git clone https://github.com/pytorch/botorch.git
 cd botorch
 pip install -e .
 ```
 
-To customize the installation, you can also run the following instead:
+To customize the installation, you can also run the following variants of the
+above:
 * `pip install -e .[dev]`: Also installs all tools necessary for development
-  (testing, linting, docs building).
-* `pip install -e .[tutorial]`: Also installs jupyter for running the tutorial
-  notebooks.
+  (testing, linting, docs building; see [Contributing](#contributing) below).
+* `pip install -e .[tutorials]`: Also installs all packages necessary for running the tutorial notebooks.
+
+
+## Getting Started
+
+Here's a quick run down of the main components of a Bayesian optimization loop.
+For more details see our [Documentation](https://botorch.org/docs) and the
+[Tutorials](https://botorch.org/tutorials).
+
+1. Fit a Gaussian Process model to data
+  ```python
+  import torch
+  from botorch.models import SingleTaskGP
+  from botorch.fit import fit_gpytorch_model
+  from gpytorch.mlls import ExactMarginalLogLikelihood
+
+  train_X = torch.rand(10, 2)
+  Y = 1 - torch.norm(train_X - 0.5, dim=-1) + 0.1 * torch.rand(10)
+  train_Y = (Y - Y.mean()) / Y.std()
+
+  gp = SingleTaskGP(train_X, train_Y)
+  mll = ExactMarginalLogLikelihood(gp.likelihood, gp)
+  fit_gpytorch_model(mll)
+  ```
+
+2. Construct an acquisition function
+  ```python
+  from botorch.acquisition import UpperConfidenceBound
+
+  UCB = UpperConfidenceBound(gp, beta=0.1)
+  ```
+
+3. Optimize the acquisition function
+  ```python
+  from botorch.optim import joint_optimize
 
+  bounds = torch.stack([torch.zeros(2), torch.ones(2)])
+  candidate = joint_optimize(
+      UCB, bounds=bounds, q=1, num_restarts=5, raw_samples=20,
+  )
+  ```
 
 
 ## Contributing
 See the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.
 
 
 ## License
-BoTorch is MIT licensed, as found in the LICENSE file.
+BoTorch is MIT licensed, as found in the [LICENSE](LICENSE.md) file.

botorch/__init__.py

@@ -7,7 +7,7 @@
 from .utils import manual_seed
 
 
-__version__ = "0.1.0a3"
+__version__ = "0.1.0"
 
 
 __all__ = [

environment.yml

@@ -3,6 +3,6 @@ channels:
   - pytorch
   - gpytorch
 dependencies:
-  - pytorch-nightly
-  - gpytorch
+  - pytorch>=1.1
+  - gpytorch>=0.3.2
   - scipy

setup.py

@@ -10,47 +10,27 @@
 REQUIRED_MAJOR = 3
 REQUIRED_MINOR = 6
 
-fatals = []
-
-
 # Check for python version
 if sys.version_info < (REQUIRED_MAJOR, REQUIRED_MINOR):
-    fatals.append(
-        (
-            "Your version of python ({major}.{minor}) is too old. You need "
-            "python >= {required_major}.{required_minor}."
-        ).format(
-            major=sys.version_info.major,
-            minor=sys.version_info.minor,
-            required_minor=REQUIRED_MINOR,
-            required_major=REQUIRED_MAJOR,
-        )
-    )
-
-
-def missing(package_name):
-    """Formatting helper for errors."""
-    fatals.append(
-        "The '{}' package is missing. Please install it before "
-        "running the setup script.".format(package_name)
-    )
-
-
-# error out if setup dependencies not met
-if fatals:
-    sys.exit(
-        "You need to fix the following issues before you can install botorch:\n - "
-        + "\n - ".join(fatals)
+    error = (
+        "Your version of python ({major}.{minor}) is too old. You need "
+        "python >= {required_major}.{required_minor}."
+    ).format(
+        major=sys.version_info.major,
+        minor=sys.version_info.minor,
+        required_minor=REQUIRED_MINOR,
+        required_major=REQUIRED_MAJOR,
     )
+    sys.exit(error)
 
 
 TEST_REQUIRES = ["pytest", "pytest-cov"]
 
 DEV_REQUIRES = TEST_REQUIRES + ["black", "flake8", "sphinx", "sphinx-autodoc-typehints"]
 
-TUTORIAL_REQUIRES = ["jupyter", "matplotlib", "torchvision"]
+TUTORIALS_REQUIRES = ["jupyter", "matplotlib", "cma", "torchvision"]
 
-# get version string from setup.py
+# get version string from module
 with open(os.path.join(os.path.dirname(__file__), "botorch/__init__.py"), "r") as f:
     version = re.search(r"__version__ = ['\"]([^'\"]*)['\"]", f.read(), re.M).group(1)
 
@@ -60,18 +40,27 @@ def missing(package_name):
     description="Bayesian Optimization in PyTorch",
     author="Facebook, Inc.",
     license="MIT",
-    url="https://github.com/pytorch/botorch",
-    keywords=["Bayesian Optimization", "pytorch", "Gaussian Process"],
+    url="https://botorch.org",
+    project_urls={
+        "Documentation": "https://botorch.org",
+        "Source": "https://github.com/pytorch/botorch",
+        "conda": "https://anaconda.org/pytorch/botorch",
+    },
+    keywords=["Bayesian optimization", "PyTorch"],
     classifiers=[
-        "Development Status :: 3 - Alpha",
-        "Programming Language :: Python :: 3",
+        "Development Status :: 4 - Beta",
+        "Programming Language :: Python :: 3 :: Only",
+        "License :: OSI Approved :: MIT License",
+        "Topic :: Scientific/Engineering",
+        "Intended Audience :: Science/Research",
+        "Intended Audience :: Developers",
     ],
     python_requires=">=3.6",
-    install_requires=["torch>=1.0.1", "gpytorch>=0.3.2", "scipy"],
+    install_requires=["torch>=1.1", "gpytorch>=0.3.2", "scipy"],
     packages=find_packages(),
     extras_require={
         "dev": DEV_REQUIRES,
         "test": TEST_REQUIRES,
-        "tutorial": TUTORIAL_REQUIRES,
+        "tutorials": TUTORIALS_REQUIRES,
     },
 )