new readme (#690)

* new readme

* why oh why

* nicer workflow names

* updated getting started

* addressed Uri's comments

* added paper reference

* codecov

.github/workflows/deploy.yaml

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+name: Release documentation build
+
 on:
   workflow_dispatch:
   push:

.github/workflows/develop-checks.yaml

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+name: Develop checks
+
 on:
   workflow_dispatch:
   push:

.github/workflows/develop-deploy.yaml

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+name: Develop documentation build
+
 on:
   workflow_dispatch:
   push:

.github/workflows/quality-checks.yaml

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+name: Quality checks
+
 on:
   workflow_dispatch:
   pull_request:

CONTRIBUTING.md

@@ -2,14 +2,15 @@
 
 ### Who are we?
 
-*Administrators* (Artem Artemev, Uri Granta, Henry Moss, Hrvoje Stojic) look after the GitHub repository itself.
+*Administrators* (Uri Granta, Sebastian Ober, Hrvoje Stojic) look after the GitHub repository itself.
 
-*Maintainers* (Artem Artemev, Uri Granta, Henry Moss, Victor Picheny, Hrvoje Stojic) steer the project, keep the community thriving, and manage contributions.
+*Maintainers* (Uri Granta, Henry Moss, Sebastian Ober, Victor Picheny, Hrvoje Stojic) steer the project, keep the community thriving, and manage contributions.
 
 *Contributors* (you?) submit issues, make pull requests, answer questions on Slack, and more.
 
 Community is important to us, and we want everyone to feel welcome and be able to contribute to their fullest. Our [code of conduct](CODE_OF_CONDUCT.md) gives an overview of what that means.
 
+
 ### Reporting a bug
 
 Finding and fixing bugs helps us provide robust functionality to all users. You can either submit a bug report or, if you know how to fix the bug yourself, you can submit a bug fix. We gladly welcome either, but a fix is likely to be released sooner, simply because others may not have time to quickly implement a fix themselves. If you're interested in implementing it, but would like help in doing so, ask in Trieste channels of Secondmind Labs' [community Slack workspace](https://join.slack.com/t/secondmind-labs/shared_invite/zt-ph07nuie-gMlkle__tjvXBay4FNSLkw).
@@ -18,6 +19,7 @@ We use GitHub issues for bug reports. You can use the [issue template](https://g
 
 If you'd like to submit a bug fix, the [pull request templates](https://github.com/secondmind-labs/trieste/compare) are a good place to start. We recommend you discuss your changes with the community before you begin working on them, so that questions and suggestions can be made early on.
 
+
 ### Requesting a feature
 
 Trieste is built on features added and improved by the community. You can submit a feature request either as an issue or, if you can implement the change yourself, as a pull request. We gladly welcome either, but a pull request is likely to be released sooner, simply because others may not have time to quickly implement it themselves. If you're interested in implementing it, but would like help in doing so, ask in Trieste channels of Secondmind Labs' [community Slack workspace](https://join.slack.com/t/secondmind-labs/shared_invite/zt-ph07nuie-gMlkle__tjvXBay4FNSLkw).
@@ -26,6 +28,7 @@ We use GitHub issues for feature requests. You can use the [issue template](http
 
 If you'd like to submit a pull request, the [pull request templates](https://github.com/secondmind-labs/trieste/compare) are a good place to start. We recommend you discuss your changes with the community before you begin working on them, so that questions and suggestions can be made early on.
 
+
 ### Pull request guidelines
 
 - Limit the pull request to the smallest useful feature or enhancement, or the smallest change required to fix a bug. This makes it easier for reviewers to understand why each change was made, and makes reviews quicker.
@@ -42,12 +45,14 @@ If you'd like to submit a pull request, the [pull request templates](https://git
   import all modules (or their contents) in their parent package \_\_init\_\_.py file.
 - In commit messages, be descriptive but to the point. Comments such as "further fixes" obscure the more useful information.
 
+
 ### Documentation
 
 Trieste has two primary sources of documentation: the notebooks and the API reference.
 
 For the API reference, we document Python code inline, using [reST markup](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). See [here](docs/README.md) for details on the documentation build. All parts of the public API need docstrings (indeed anything without docstrings won't appear in the built documentation). Similarly, don't add docstrings to private functionality, else it will appear in the documentation website. Use code comments sparingly, as they incur a maintenance cost and tend to drift out of sync with the corresponding code.
 
+
 ### Quality checks
 
 We use [tox](https://tox.readthedocs.io) to run reproducible quality checks. This guide assumes you have this installed.
@@ -106,6 +111,7 @@ You can then use `task` to run various common tasks:
 
 [GitHub actions](https://docs.github.com/en/actions) will automatically run the quality checks against pull requests to the develop branch, by calling into tox. The GitHub repository is set up such that these need to pass in order to merge.
 
+
 ### Updating dependencies
 
 To update the Python dependencies used in any part of the project, update setup.py and/or any relevant requirements.txt files. Then, in the repository root, and with all virtual environments deactivated, run
@@ -114,6 +120,7 @@ $ ./generate_constraints.sh
 ```
 This will update the constraints.txt files (but not your virtual environment).
 
+
 # License
 
 [Apache License 2.0](LICENSE)

README.md

@@ -1,12 +1,79 @@
 # Trieste
 
-A Bayesian optimization toolbox built on [TensorFlow](https://www.tensorflow.org/). Trieste supports Python 3.7 onwards and uses [semantic versioning](https://semver.org/).
+[![PyPI](https://img.shields.io/pypi/v/trieste.svg)](https://pypi.org/project/trieste)
+[![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE)
+[![Quality checks](https://github.com/secondmind-labs/trieste/actions/workflows/develop-checks.yaml/badge.svg)](https://github.com/secondmind-labs/trieste/actions?query=workflows%3Adevelop-checks)
+[![Docs](https://github.com/secondmind-labs/trieste/actions/workflows/deploy.yaml/badge.svg)](https://github.com/secondmind-labs/trieste/actions/workflows/deploy.yaml)
+[![Codecov](https://img.shields.io/codecov/c/github/secondmind-labs/trieste/coverage.svg?branch=develop)](https://codecov.io/c/github/secondmind-labs/trieste?branch=develop)
+[![Slack Status](https://img.shields.io/badge/slack-trieste-green.svg?logo=Slack)](https://join.slack.com/t/secondmind-labs/shared_invite/zt-ph07nuie-gMlkle__tjvXBay4FNSLkw)
 
-We welcome contributions. See [the guidelines](CONTRIBUTING.md) to get started.
 
-### Installation
+[Documentation (develop)](https://secondmind-labs.github.io/trieste/develop/index.html) |
+[Documentation (release)](https://secondmind-labs.github.io/trieste) |
+[Tutorials](https://secondmind-labs.github.io/trieste/1.0.0/tutorials.html) |
+[API reference](https://secondmind-labs.github.io/trieste/1.0.0/autoapi/trieste/index.html) |
 
-To install trieste, run
+
+## What does Trieste do?
+
+Trieste (pronounced tree-est) is a Bayesian optimization toolbox built on [TensorFlow](https://www.tensorflow.org/). Trieste is named after the bathyscaphe [Trieste](https://en.wikipedia.org/wiki/Trieste_%28bathyscaphe%29), the first vehicle to take a crew to Challenger Deep in the Mariana Trench, the lowest point on the Earth’s surface: the literal global minimum.
+
+**Why Trieste?**  
+- Highly modular design and easily customizable. Extend it with your custom model or acquisition functions. Ideal for practitioners that want to use it in their systems or for researchers wishing to implement their latest ideas.
+- Seamless integration with TensorFlow. Leveraging fully its auto differentiation - no more writing of gradients for your acquisition functions!, and scalability capabilities via its support for highly parallelized modern hardware (e.g. GPUs).
+- General purpose toolbox. Advanced algorithms covering all corners of Bayesian optimization and Active learning - batch, asynchronous, constraints, multi-fidelity, multi-objective - you name it, Trieste has it. 
+- Versatile model support out-of-the-box. From gold-standard Gaussian processes (GPs; [GPflow](https://github.com/GPflow/GPflow)) to alternatives like sparse variational GPs, Deep GPs ([GPflux](https://github.com/secondmind-labs/GPflux)) or Deep Ensembles ([Keras](https://keras.io/)), that scale much better with the number of function evaluations.
+- Real-world oriented. Our Ask-Tell interface allows users to apply Bayesian optimization across a range of non-standard real-world settings where control over black-box function is partial. Built on TensorFlow and with comprehensive testing Trieste is production-ready.
+
+
+## Getting started
+
+Here's a quick overview of the main components of a Bayesian optimization loop. For more details, see our [Documentation](https://secondmind-labs.github.io/trieste) where we have multiple [Tutorials](https://secondmind-labs.github.io/trieste/1.0.0/tutorials.html) covering both the basic functionalities of the toolbox, as well as more advanced usage.
+
+Let's set up a synthetic black-box objective function we wish to minimize, for example, a popular Branin optimization function, and generate some initial data
+```python
+from trieste.objectives import Branin, mk_observer
+
+observer = mk_observer(Branin.objective)
+
+initial_query_points = Branin.search_space.sample(5)
+initial_data = observer(initial_query_points)
+```
+
+First step is to crate a probabilistic model, for example a Gaussian Process
+```python
+from trieste.models import build_gpr, GaussianProcessRegression
+
+gpflow_model = build_gpr(initial_data, Branin.search_space)
+model = GaussianProcessRegression(gpflow_model)
+```
+
+Next ingredient is to choose an acquisition rule and acquisition function
+```python
+from trieste.acquisition import EfficientGlobalOptimization, ExpectedImprovement
+
+acquisition_rule = EfficientGlobalOptimization(ExpectedImprovement())
+```
+
+Finally, we optimize the acquisition function using our model for a number of steps and we check the obtained minimum
+```python
+from trieste.bayesian_optimizer import BayesianOptimizer
+
+bo = BayesianOptimizer(observer, search_space)
+num_steps = 15
+result = bo.optimize(num_steps, initial_data, model)
+query_point, observation, arg_min_idx = result.try_get_optimal_point()
+```
+
+
+## Installation
+
+Trieste supports Python 3.7+ and TensorFlow 2.5+, and uses [semantic versioning](https://semver.org/).
+
+
+### For users
+
+To install the latest (stable) release of the toolbox from [PyPI](https://pypi.org/), use `pip`:
 ```bash
 $ pip install trieste
 ```
@@ -16,7 +83,19 @@ $ pip install .
 ```
 in the repository root.
 
-### Documentation
+
+### For contributors
+
+To install this project in editable mode, run the commands below from the root directory of the `trieste` repository.
+```bash
+git clone https://github.com/secondmind-labs/trieste.git
+cd trieste
+pip install -e .
+```
+For installation to be able to run quality checks, as well as other details, see [the guidelines for contributors](CONTRIBUTING.md).
+
+
+### Tutorials
 
 Trieste has a [documentation site](https://secondmind-labs.github.io/trieste) with tutorials on how to use the library, and an API reference. You can also run the tutorials interactively. They can be found in the notebooks directory, and are written as Python scripts for running with Jupytext. To run them, first install trieste from sources as above, then install additional dependencies with
 ```bash
@@ -27,11 +106,39 @@ Finally, run the notebooks with
 $ jupyter-notebook notebooks
 ```
 
+## The Trieste Community
+
 ### Getting help
 
-- To submit a pull request, file a bug report, or make a feature request, see the [contribution guidelines](CONTRIBUTING.md).
-- For more open-ended questions, or for anything else, join the discussions on Trieste channels in Secondmind Labs' community [Slack workspace](https://join.slack.com/t/secondmind-labs/shared_invite/zt-ph07nuie-gMlkle__tjvXBay4FNSLkw).
+**Bugs, feature requests, pain points, annoying design quirks, etc:**
+Please use [GitHub issues](https://github.com/secondmind-labs/trieste/issues/) to flag up bugs/issues/pain points, suggest new features, and discuss anything else related to the use of Trieste that in some sense involves changing the Trieste code itself. We positively welcome comments or concerns about usability, and suggestions for changes at any level of design. We aim to respond to issues promptly, but if you believe we may have forgotten about an issue, please feel free to add another comment to remind us.
+
+
+### Slack workspace
+
+We have a public [Secondmind Labs slack workspace](https://secondmind-labs.slack.com/). Please use this [invite link](https://join.slack.com/t/secondmind-labs/shared_invite/zt-ph07nuie-gMlkle__tjvXBay4FNSLkw) and join the #trieste channel, whether you'd just like to ask short informal questions or want to be involved in the discussion and future development of Trieste.
+
+
+### Contributing
+
+All constructive input is very much welcome. For detailed information, see [the guidelines for contributors](CONTRIBUTING.md).
+
+
+## Citing Trieste
+
+To cite Trieste, please reference our [arXiv](https://arxiv.org/) paper where we review the framework and describe the design. Sample Bibtex is given below:
+
+```
+@misc{trieste2023,
+  author = {Picheny, Victor and Berkeley, Joel and Moss, Henry B. and Stojic, Hrvoje and Granta, Uri and Ober, Sebastian W. and Artemev, Artem and Ghani, Khurram and Goodall, Alexander and Paleyes, Andrei and Vakili, Sattar and Pascual-Diaz, Sergio and Markou, Stratis and Qing, Jixiang and Loka, Nasrulloh R. B. S and Couckuyt, Ivo},
+  title = {Trieste: Efficiently Exploring The Depths of Black-box Functions with TensorFlow},
+  publisher = {arXiv},
+  year = {2023},
+  doi = {10.48550/ARXIV.2302.08436},
+  url = {https://arxiv.org/abs/2302.08436}
+}
+```
 
-# License
+## License
 
 [Apache License 2.0](LICENSE)