Merge pull request #29 from rafaelbailo/main

Add contribution guidelines

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to ConsensusBasedX.jl
+
+We are always happy to receive community contributions, thank you in advance for your contribution and for reading through these guidelines! We are open to various inputs, including but not limited to
+- new features;
+- feature requests;
+- bug reports;
+- bug fixes;
+- documentation.
+
+## How to contribute
+
+### Features, bug fixes, and documentation
+
+The preferred workflow is to fork the ConsensusBasedX.jl repository, to commit your changes to the fork, and to create a pull request.
+
+ConsensusBasedX.jl employs unit tests to ensure code quality. Please make sure that your contribution passes all unit tests before creating the pull request.
+
+**To run the tests locally** (preferred): activate the Julia environment in your local clone of the fork, and then run
+```julia
+using Pkg; Pkg.test()
+```
+
+**To run the tests on Github**: you will have to enable [GitHub workflows](https://github.com/PdIPS/CBXpy/blob/main/.github/workflows/Tests.yml) on your fork. Workflows are turned off by default in forks for security reasons. Unit tests are run as part of the *CI* (continuous integration) [GitHub action](https://docs.github.com/en/actions).
+
+### Feature requests and bug reports
+
+If you want to request a new feature or report a bug (e.g. wrong output, unexpected behaviour), please [open an issue here](https://github.com/PdIPS/ConsensusBasedX.jl/issues/new/choose). There are *Feature request* and *Bug report* templates that might be useful.
+
+## Scope of new features
+
+ConsensusBasedX.jl has been designed with flexibility in mind, in order to accomodate the growing number of consensus-based particle methods in one library. We recommend reading the [documentation](https://pdips.github.io/ConsensusBasedX.jl/) carefully before contributing new features. The main criteria for a contribution are:
+- **Novelty**: New features should add functionality that cannot already be accomplished with the existing interface. For example, a good contribution would be the implementation of [constrained minimisation](https://en.wikipedia.org/wiki/Constrained_optimization), whereas a bad contribution would be to define new version of `sample` that is hard-coded to run on [minimisation mode](https://pdips.github.io/ConsensusBasedX.jl/stable/distribution_sampling/#Running-on-minimisation-mode).
+- **Consistency**: We try to keep a unified syntax across ConsensusBasedX.jl (e.g. the methods `minimise` and `sample` use the same syntax and accept many of the same arguments). New features should adhere to this pattern.
+- **Performance**: Optimisation problems are extremely computationally demanding, so it is important to offer good performance. You should read the [performance and benchmarking](https://pdips.github.io/ConsensusBasedX.jl/stable/performance_benchmarking/) section of the documentation and consider including "zero-allocation" unit tests for your implementation, [similar to those included for `minimise`](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/test/interface/minimise.jl). For more information, see the [performance tips](https://docs.julialang.org/en/v1/manual/performance-tips/) page of the Julia documentation.

README.md

@@ -10,7 +10,7 @@
 [![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**ConsensusBasedX.jl** is a gradient-free stochastic optimisation package for Julia, born out of [Consensus.jl](https://github.com/rafaelbailo/Consensus.jl) and [CBXpy](https://github.com/PdIPS/CBXpy). It uses _Consensus-Based Optimisation_ (CBO), a flavour of _Particle Swarm Optimisation_ (PSO) first introduced by [R. Pinnau, C. Totzeck, O. Tse, and S. Martin (2017)][1]. This is a method of global optimisation particularly suited for rough functions, where gradient descent would fail. It is also useful for optimisation in higher dimensions. It also implements _Consensus-Based Sampling_ (CBS), as introduced in [J. A. Carrillo, F. Hoffmann, A. M. Stuart, and U. Vaes (2022)][2].
+**ConsensusBasedX.jl** is a gradient-free stochastic optimisation package for Julia, born out of [Consensus.jl](https://github.com/rafaelbailo/Consensus.jl) and [CBXpy](https://github.com/PdIPS/CBXpy). It uses _Consensus-Based Optimisation_ (CBO), a flavour of _Particle Swarm Optimisation_ (PSO) first introduced by [R. Pinnau, C. Totzeck, O. Tse, and S. Martin (2017)][1]. This is a method of global optimisation particularly suited for rough functions, where gradient descent would fail. It is useful for optimisation in higher dimensions. It also implements _Consensus-Based Sampling_ (CBS), as introduced in [J. A. Carrillo, F. Hoffmann, A. M. Stuart, and U. Vaes (2022)][2].
 
 
 ## How to install and use
@@ -52,6 +52,10 @@ out.sample
 
 For more detailed explanations and full-code examples, see the [documentation](https://PdIPS.github.io/ConsensusBasedX.jl/stable/).
 
+## Bug reports, feature requests, and contributions
+
+See [the contribution guidelines](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/CONTRIBUTING.md).
+
 [1]: http://dx.doi.org/10.1142/S0218202517400061
 [2]: https://onlinelibrary.wiley.com/doi/10.1111/sapm.12470
 

docs/src/consensus-based_optimisation.md

@@ -2,7 +2,7 @@
 
 Consensus-based optimisation (CBO) is an approach to solve the *global minimisation problem*:
 !!! note "Global minimisation problem"
-    Given a (continuous) *objective function* ``f(x)=\mathbb{R}^D \rightarrow \mathbb{R}``, find
+    Given a (continuous) *objective function* ``f(x):\mathbb{R}^D \rightarrow \mathbb{R}``, find
     ```math
     x^* = \operatorname*{argmin}_{x\in\mathbb{R}^D} f(x);
     ```

docs/src/index.md

@@ -8,7 +8,7 @@ CurrentModule = ConsensusBasedX
 <iframe src="https://ghbtns.com/github-btn.html?user=PdIPS&repo=ConsensusBasedX.jl&type=star&count=true&size=large" frameborder="0" scrolling="0" width="170" height="30" title="GitHub"></iframe>
 ```
 
-**ConsensusBasedX.jl** is a gradient-free stochastic optimisation package for Julia, born out of [Consensus.jl](https://github.com/rafaelbailo/Consensus.jl) and [CBXpy](https://github.com/PdIPS/CBXpy). It uses _Consensus-Based Optimisation_ (CBO), a flavour of _Particle Swarm Optimisation_ (PSO) first introduced by [R. Pinnau, C. Totzeck, O. Tse, and S. Martin (2017)](http://dx.doi.org/10.1142/S0218202517400061). This is a method of global optimisation particularly suited for rough functions, where gradient descent would fail. It is also useful for optimisation in higher dimensions. It also implements _Consensus-Based Sampling_ (CBS), as introduced in [J. A. Carrillo, F. Hoffmann, A. M. Stuart, and U. Vaes (2022)](https://onlinelibrary.wiley.com/doi/10.1111/sapm.12470). 
+**ConsensusBasedX.jl** is a gradient-free stochastic optimisation package for Julia, born out of [Consensus.jl](https://github.com/rafaelbailo/Consensus.jl) and [CBXpy](https://github.com/PdIPS/CBXpy). It uses _Consensus-Based Optimisation_ (CBO), a flavour of _Particle Swarm Optimisation_ (PSO) first introduced by [R. Pinnau, C. Totzeck, O. Tse, and S. Martin (2017)](http://dx.doi.org/10.1142/S0218202517400061). This is a method of global optimisation particularly suited for rough functions, where gradient descent would fail. It is useful for optimisation in higher dimensions. It also implements _Consensus-Based Sampling_ (CBS), as introduced in [J. A. Carrillo, F. Hoffmann, A. M. Stuart, and U. Vaes (2022)](https://onlinelibrary.wiley.com/doi/10.1111/sapm.12470). 
 
 [![Static Badge](https://img.shields.io/badge/View%20on%20Github-grey?logo=github)](https://github.com/PdIPS/ConsensusBasedX.jl)
 [![Build Status](https://github.com/PdIPS/ConsensusBasedX.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/PdIPS/ConsensusBasedX.jl/actions/workflows/CI.yml?query=branch%3Amain)
@@ -51,4 +51,8 @@ For instance, if `D = 2`, you can sample `exp(-αf)` by running:
 ```julia
 out = sample(f, D = 2, extended_output=true)
 out.sample
-```
+```
+
+## Bug reports, feature requests, and contributions
+
+See [the contribution guidelines](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/CONTRIBUTING.md).