From 2ddc3bc541b8caf7dffe30da045454611abe689f Mon Sep 17 00:00:00 2001 From: Jonathan Wenger Date: Mon, 17 Aug 2020 18:56:21 +0200 Subject: [PATCH] removed all references to development branch --- CONTRIBUTING.md | 50 ++++++++++++------- README.md | 2 +- docs/source/development/developer_guides.rst | 3 +- docs/source/development/documentation.rst | 11 +++- docs/source/development/example_notebook.rst | 24 ++++++--- docs/source/development/probnum_method.rst | 15 +++--- .../introduction/probabilistic_numerics.rst | 30 ++++++----- docs/source/introduction/quickstart.ipynb | 6 +-- 8 files changed, 92 insertions(+), 49 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53ef0e54d..8b3cf1d8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ Contributions to ProbNum are very welcome. Before getting started make sure to read the following guidelines. All contributions to ProbNum should be made via pull requests (PR) to the -[development branch](https://github.com/probabilistic-numerics/probnum/tree/development) on GitHub. Some suggestions for +[master branch](https://github.com/probabilistic-numerics/probnum/tree/master) on GitHub. Some suggestions for a good PR are: - implements or fixes one functionality; @@ -17,7 +17,9 @@ for detailed instructions. ## Getting Started -Begin by forking the repository on GitHub and cloning your fork to a local machine. Next, create a new branch in your forked repository describing the feature you would like to implement. You can now get started writing code in your new branch. Make sure to keep the following best practices regarding code quality in mind. +Begin by forking the repository on GitHub and cloning your fork to a local machine. Next, create a new branch in your +forked repository describing the feature you would like to implement. You can now get started writing code in your new +branch. Make sure to keep the following best practices regarding code quality in mind. ### Code Quality @@ -35,34 +37,43 @@ For all of the above the existing ProbNum code is a good initial reference point ### Using Tox -Probnum uses [tox](https://tox.readthedocs.io/en/latest/) in its [continuous integration (CI)](#continuous-integration) pipeline to run tests and to build documentation. Under the hood, tox builds virtual environments following the specifications in `./tox.ini` in order to run tests across multiple python versions, while making sure that all the necessary dependencies are installed. Using tox unifies the *local* development process with CI, such that local test results should match the outcomes of Travis's builds more closely. This ensures that your pull request can be merged seemlessly into ProbNum's codebase. +Probnum uses [tox](https://tox.readthedocs.io/en/latest/) in its [continuous integration (CI)](#continuous-integration) +pipeline to run tests and to build documentation. Under the hood, tox builds virtual environments following the +specifications in `./tox.ini` in order to run tests across multiple python versions, while making sure that all the +necessary dependencies are installed. Using tox unifies the *local* development process with CI, such that local test +results should match the outcomes of Travis's builds more closely. This ensures that your pull request can be merged +seamlessly into ProbNum's codebase. Install tox from the Python Package Index (PyPI) via ```bash pip install -U tox ``` -Once tox and the required [external tools](#external-tools) below are installed, you can run tests and build the documentation locally by simply calling +Once tox and the required [external tools](#external-tools) below are installed, you can run tests and build the +documentation locally by simply calling ```bash tox ``` **Word of caution:** -Running `tox` runs all environments as specified in `tox.ini`, thus potentially running tests across many different python versions. -To run the full test suite make sure that you have all specified python versions installed. -Alternatively, you can run a single specific environment through `tox -e `, e.g. `tox -e py36` to run tests with Python 3.6 or `tox -e docs` to just build the documentation. +Running `tox` runs all environments as specified in `tox.ini`, thus potentially running tests across many different +Python versions. To run the full test suite make sure that you have all specified Python versions installed. +Alternatively, you can run a single specific environment through `tox -e `, e.g. `tox -e py36` to run tests with +Python 3.6 or `tox -e docs` to just build the documentation. ### External Tools -Building the documentation locally requires additional packages (e.g. for inheritance diagrams), which can be found in `.travis.yml`. These packages are currently: +Building the documentation locally requires additional packages (e.g. for inheritance diagrams), which can be found in +`.travis.yml`. These packages are currently: - [pandoc](https://pandoc.org/): In Ubuntu, install via `sudo apt install pandoc` - [graphviz](https://graphviz.org/): In Ubuntu, install via `sudo apt install graphviz` ## Testing [![test coverage: latest](https://img.shields.io/codecov/c/gh/probabilistic-numerics/probnum/master?label=Coverage%3A%20latest&logo=codecov)](https://codecov.io/gh/probabilistic-numerics/probnum/branch/master) -[![test coverage: development](https://img.shields.io/codecov/c/gh/probabilistic-numerics/probnum/development?label=Coverage%3A%20dev&logo=codecov)](https://codecov.io/gh/probabilistic-numerics/probnum/branch/development) -We use [unittest](https://docs.python.org/3/library/unittest.html) for testing and aim to cover as much code with tests as possible. Make sure to always add tests for newly implemented code. To run the test suite on your machine you have multiple options: +We use [unittest](https://docs.python.org/3/library/unittest.html) for testing and aim to cover as much code with tests +as possible. Make sure to always add tests for newly implemented code. To run the test suite on your machine you have +multiple options: - **Full test suite with tox:** Run the full suite across different Python versions with @@ -81,20 +92,23 @@ We use [unittest](https://docs.python.org/3/library/unittest.html) for testing a ```bash pytest ``` +Code coverage of the tests is reported via [codecov](https://codecov.io/github/probabilistic-numerics/probnum?branch=master). ## Documentation [![docs: stable](https://img.shields.io/readthedocs/probnum.svg?logo=read%20the%20docs&logoColor=white&label=Docs:%20stable)](https://probnum.readthedocs.io/en/stable/) [![docs: latest](https://img.shields.io/readthedocs/probnum.svg?logo=read%20the%20docs&logoColor=white&label=Docs:%20latest)](https://probnum.readthedocs.io/en/latest/) -[![docs: development](https://img.shields.io/readthedocs/probnum.svg?logo=read%20the%20docs&logoColor=white&label=Docs:%20dev&version=development)](https://probnum.readthedocs.io/en/development/) -ProbNum's documentation is created with [Sphinx](https://www.sphinx-doc.org/en/master/) and automatically built and hosted by [ReadTheDocs](https://readthedocs.org/projects/probnum/) for stable (release), latest (`master` branch) and dev (`development` branch) versions. +ProbNum's documentation is created with [Sphinx](https://www.sphinx-doc.org/en/master/) and automatically built and +hosted by [ReadTheDocs](https://readthedocs.org/projects/probnum/) for stable releases and the latest (`master` branch) +version. You can build the documentation locally via ```bash tox -e docs ``` -This creates a static web page under `./docs/_build/html/` which you can view in your browser by opening `./docs/_build/html/intro.html`. +This creates a static web page under `./docs/_build/html/` which you can view in your browser by opening +`./docs/_build/html/intro.html`. Alternatively, if you want to build the docs in your current environment you can manually execute ```bash @@ -106,9 +120,11 @@ make html ## Continuous Integration [![build status: latest](https://img.shields.io/travis/probabilistic-numerics/probnum/master.svg?logo=travis%20ci&logoColor=white&label=Travis%20CI:%20latest)](https://travis-ci.org/github/probabilistic-numerics/probnum/branches) -[![build status: development](https://img.shields.io/travis/probabilistic-numerics/probnum/development.svg?logo=travis%20ci&logoColor=white&label=Travis%20CI:%20dev)](https://travis-ci.org/github/probabilistic-numerics/probnum/branches) ProbNum uses [Travis CI](https://travis-ci.org/probabilistic-numerics/probnum) for continuous integration. -For every pull request and every commit Travis builds the project and runs the test suite (through `tox`), to make sure that no breaking changes are introduced by mistake. -Code coverage of the tests is reported through [codecov](https://codecov.io/github/probabilistic-numerics/probnum?branch=master). Travis also automatically triggers a build of ProbNum's documentation. Changes to Travis can be made through the `.travis.yml` file, as well as through `tox.ini` since Travis relies on `tox` for both testing and building the documentation. -ProbNum also uses [GitHub Actions](https://docs.github.com/en/actions) to verify that all pushes and pull requests are compliant with the [*Black*](https://github.com/psf/black) code style. +For every pull request and every commit Travis builds the project and runs the test suite (through `tox`), to make sure +that no breaking changes are introduced by mistake. Travis also automatically triggers a +build of ProbNum's documentation. Changes to Travis can be made through the `.travis.yml` file, as well as through +`tox.ini` since Travis relies on `tox` for both testing and building the documentation. ProbNum also uses +[GitHub Actions](https://docs.github.com/en/actions) to verify that all pushes and pull requests are compliant with the +[*Black*](https://github.com/psf/black) code style. diff --git a/README.md b/README.md index 6e678c8d0..49b06743a 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ To get started install ProbNum using `pip`. ```bash pip install probnum ``` -Alternatively, you can install the package from source. +Alternatively, you can install the latest version from source. ```bash pip install git+https://github.com/probabilistic-numerics/probnum.git ``` diff --git a/docs/source/development/developer_guides.rst b/docs/source/development/developer_guides.rst index 1d3be3158..7045c4b9c 100644 --- a/docs/source/development/developer_guides.rst +++ b/docs/source/development/developer_guides.rst @@ -1,7 +1,8 @@ Developer Guides ======================= -Do you want to contribute to ProbNum, but are unsure how? The developer guides below give step-by-step instructions on how to contribute to the codebase via a pull request. +Do you want to contribute to ProbNum, but are unsure how? The developer guides below give step-by-step instructions on +how to contribute to the codebase via a pull request. .. toctree:: :maxdepth: 1 diff --git a/docs/source/development/documentation.rst b/docs/source/development/documentation.rst index 3e62a21e8..b5969d8f8 100644 --- a/docs/source/development/documentation.rst +++ b/docs/source/development/documentation.rst @@ -1,12 +1,19 @@ Adding to the Documentation ============================ -Documentation is an integral part of every collaborative software project. Good documentation not only encourages users of the package to try out different functionalities, but it also makes maintaining and expanding code significantly easier. If you want to improve ProbNum's documentation or learn how to write documentation for your newly implemented functionality, keep reading. +Documentation is an integral part of every collaborative software project. Good documentation not only encourages users +of the package to try out different functionalities, but it also makes maintaining and expanding code significantly +easier. If you want to improve ProbNum's documentation or learn how to write documentation for your newly implemented +functionality, keep reading. Docstrings *********** -The main form of documentation are `docstrings`, multi-line comments beneath a class or function definition with a specific syntax, which detail its functionality. This package uses the `NumPy docstring format `_. As a rule, all functions which are exposed to the user *must* have appropriate docstrings. Below is an example of a docstring for a probabilistic numerical method. +The main form of documentation are `docstrings`, multi-line comments beneath a class or function definition with a +specific syntax, which detail its functionality. This package uses the +`NumPy docstring format `_. As a rule, +all functions which are exposed to the user *must* have appropriate docstrings. Below is an example of a docstring for a +probabilistic numerical method. .. code-block:: python diff --git a/docs/source/development/example_notebook.rst b/docs/source/development/example_notebook.rst index 7732b9080..9e02883e1 100644 --- a/docs/source/development/example_notebook.rst +++ b/docs/source/development/example_notebook.rst @@ -1,14 +1,19 @@ Adding an Example Notebook =========================== -Functionality of ProbNum is explained in detail in the form of Jupyter notebooks in the `tutorials section `_ of the documentation. If you want to add an example showcasing the functionality of ProbNum, follow the instructions below. +Functionality of ProbNum is explained in detail in the form of Jupyter notebooks in the +`tutorials section `_ of the documentation. +If you want to add an example showcasing the functionality of ProbNum, follow the instructions below. Creating the Notebook ********************** -We begin by creating a new Jupyter notebook under :code:`./docs/source/tutorials/`. If you want some guidance on the style, simply copy one of the existing notebooks. If you create your own ensure that the first cell is a markdown cell containing an upper level markdown header (:code:`# Header`) to be converted correctly to HTML. +We begin by creating a new Jupyter notebook under :code:`./docs/source/tutorials/`. If you want some guidance on the +style, simply copy one of the existing notebooks. If you create your own ensure that the first cell is a markdown cell +containing an upper level markdown header (:code:`# Header`) to be converted correctly to HTML. -In order to keep the style of the output consistent, the first code cell of the notebook should contain the following code snippet: +In order to keep the style of the output consistent, the first code cell of the notebook should contain the following +code snippet: .. code-block:: python @@ -26,13 +31,18 @@ In order to keep the style of the output consistent, the first code cell of the r'\usepackage{bm}'] -This snippet defines the style of plots generated by Matplotlib. For example it defines the font and makes sure any output is a vector graphic. If you need to use specific LaTeX packages, e.g. to label your plots, simply add them to the list :code:`plt.rcParams['text.latex.preamble']`. +This snippet defines the style of plots generated by Matplotlib. For example it defines the font and makes sure any +output is a vector graphic. If you need to use specific LaTeX packages, e.g. to label your plots, simply add them to the +list :code:`plt.rcParams['text.latex.preamble']`. Adding the Notebook to the Website *********************************** -Now that you've created your notebook, we have to add it in the right place on the website. Check the existing categories in :code:`./docs/source/tutorials/tutorials.rst` and add your notebook name under the appropriate header. If you want to add a new category, use the following restructuredText snippet to add a new table of contents linking to your notebook: +Now that you've created your notebook, we have to add it in the right place on the website. Check the existing +categories in :code:`./docs/source/tutorials/tutorials.rst` and add your notebook name under the appropriate header. If +you want to add a new category, use the following restructuredText snippet to add a new table of contents linking to +your notebook: .. code-block:: rst @@ -78,6 +88,8 @@ If the notebook compiles successfully, you should see output similar to: build succeeded. -You can now view your results locally by opening the website in :code:`./docs/_build/html`. Make sure you fix any error messages popping up in the build before making a pull request to the :code:`development` branch. Once your pull request has been merged, Travis will automatically build the documentation including your new example notebook. +You can now view your results locally by opening the website in :code:`./docs/_build/html`. Make sure you fix any error +messages popping up in the build before making a pull request to the :code:`master` branch. Once your pull request +has been merged, Travis will automatically build the documentation including your new example notebook. diff --git a/docs/source/development/probnum_method.rst b/docs/source/development/probnum_method.rst index 9795bb6ea..1e67332c1 100644 --- a/docs/source/development/probnum_method.rst +++ b/docs/source/development/probnum_method.rst @@ -1,15 +1,16 @@ Implementing a Probabilistic Numerical Method ============================================= -Probabilistic numerical methods in ProbNum follow the dogma of having random variables as input and random variables as output. Hence their signature should be similar to +Probabilistic numerical methods in ProbNum follow the dogma of having random variables as input and random variables as +output. Hence their signature should be similar to .. code-block:: python randvar_out = probnum_method(problem, randvar_in, **kwargs) -where :code:`problem` defines the numerical problem to solve, :code:`randvar_in` is the input random variable encoding prior -information and :code:`**kwargs` are keyword arguments that influence the behaviour +where :code:`problem` defines the numerical problem to solve, :code:`randvar_in` is the input random variable encoding +prior information and :code:`**kwargs` are keyword arguments that influence the behaviour of the solver (e.g. control termination). If your method has a classic analogue in NumPy or SciPy, make sure the signatures match as closely as possible. This enables PN methods to be used as drop-in replacements for classic numerical routines. @@ -143,8 +144,8 @@ Testing ******** While or even before you add a new PN method, write tests for its functionality. Writing tests before the -code forces you to think about what your numerical method should do independent of its implementation. Some basic tests to consider are listed -below. +code forces you to think about what your numerical method should do independent of its implementation. Some basic tests +to consider are listed below. In- and Output """"""""""""""" @@ -159,5 +160,5 @@ Numerical Conclusion *********** -Once you are done, consider writing an `example notebook `_ showcasing your new -method. Congratulations you just implemented your first probabilistic numerical method in ProbNum! \ No newline at end of file +Once you are done, consider writing an `example notebook `_ +showcasing your new method. Congratulations you just implemented your first probabilistic numerical method in ProbNum! \ No newline at end of file diff --git a/docs/source/introduction/probabilistic_numerics.rst b/docs/source/introduction/probabilistic_numerics.rst index f8cab369f..3b79d1f77 100644 --- a/docs/source/introduction/probabilistic_numerics.rst +++ b/docs/source/introduction/probabilistic_numerics.rst @@ -1,29 +1,35 @@ Probabilistic Numerics ======================= -Mathematical models used to explain and predict -the behaviour of complex systems such as immune cells or the climate -rely heavily on numerical methods. The exponential growth in -available data and computing power has revolutionized the scale of such models. -In practice given finite computational resources, this introduces -*additional uncertainty* arising from not running numerical -methods to convergence and from -observations corrupted by noise. +Mathematical models used to explain and predict the behaviour of complex systems such as immune cells or the climate +rely heavily on numerical methods. The exponential growth in available data and computing power has revolutionized the +scale of such models. In practice given finite computational resources, this introduces *additional uncertainty* arising +from not running numerical methods to convergence and from observations corrupted by noise. In a Nutshell **************** -`Probabilistic numerics (PN) `_ aims to quantify uncertainty arising from intractable or incomplete numerical computation and from stochastic input. This new paradigm which has emerged at the intersection of computer science and numerical analysis treats a *numerical problem* as one of *statistical inference* instead. [#]_ [#]_ +`Probabilistic numerics (PN) `_ aims to quantify uncertainty arising from +intractable or incomplete numerical computation and from stochastic input. This new paradigm which has emerged at the +intersection of computer science and numerical analysis treats a *numerical problem* as one of *statistical inference* +instead. [#]_ [#]_ -The probabilistic viewpoint provides a principled way to encode structural knowledge about a problem. By giving an explicit role to uncertainty from all sources, in particular from the computation itself, PN gives rise to new applications beyond the scope of classical methods. For example, it allows consistent propagation of uncertainty through the entirety of a computational pipeline. +The probabilistic viewpoint provides a principled way to encode structural knowledge about a problem. By giving an +explicit role to uncertainty from all sources, in particular from the computation itself, PN gives rise to new +applications beyond the scope of classical methods. For example, it allows consistent propagation of uncertainty +through the entirety of a computational pipeline. -Typical numerical tasks to which PN may be applied include optimization, quadrature, the solution of ordinary and partial differential equations, and the basic tasks of linear algebra, e.g. solution of linear systems and eigenvalue problems. Note that the PN approach is different from exploiting randomization in numerical methods, in fact many PN methods do not rely on sampling. +Typical numerical tasks to which PN may be applied include optimization, quadrature, the solution of ordinary and +partial differential equations, and the basic tasks of linear algebra, e.g. solution of linear systems and eigenvalue +problems. Note that the PN approach is different from exploiting randomization in numerical methods, in fact many PN +methods do not rely on sampling. Value of a Probabilistic Approach ********************************** -As well as offering an enriched reinterpretation of classical methods, the PN approach has several concrete practical points of value. The probabilistic interpretation of computation +As well as offering an enriched reinterpretation of classical methods, the PN approach has several concrete practical +points of value. The probabilistic interpretation of computation - allows to build customized methods for specific problems with bespoke priors - formalizes the design of adaptive methods using tools from decision theory diff --git a/docs/source/introduction/quickstart.ipynb b/docs/source/introduction/quickstart.ipynb index 06fd87e6a..ced98bdb1 100644 --- a/docs/source/introduction/quickstart.ipynb +++ b/docs/source/introduction/quickstart.ipynb @@ -41,12 +41,12 @@ "```bash\n", "pip install probnum\n", "```\n", - "Alternatively, you can install the package from source.\n", + "Alternatively, you can install the latest version from source.\n", "\n", "```bash\n", "pip install git+https://github.com/probabilistic-numerics/probnum.git\n", "```\n", - "Then in a python session simply import ProbNum." + "Then in a Python session simply import ProbNum." ] }, { @@ -1152,4 +1152,4 @@ }, "nbformat": 4, "nbformat_minor": 4 -} +} \ No newline at end of file