From d0c536a2721343de66f6236d0015c25dd38b1376 Mon Sep 17 00:00:00 2001 From: Dr Rafael Bailo Date: Tue, 30 Apr 2024 13:15:52 +0100 Subject: [PATCH] Add contribution guidelines --- CONTRIBUTING.md | 34 ++++++++++++++++++++++++ README.md | 6 ++++- docs/src/consensus-based_optimisation.md | 2 +- docs/src/index.md | 8 ++++-- 4 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c810e51 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 23f2fc8..2afdb77 100644 --- a/README.md +++ b/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 diff --git a/docs/src/consensus-based_optimisation.md b/docs/src/consensus-based_optimisation.md index ee70030..7108c4f 100644 --- a/docs/src/consensus-based_optimisation.md +++ b/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); ``` diff --git a/docs/src/index.md b/docs/src/index.md index af0e44e..a91663d 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -8,7 +8,7 @@ CurrentModule = ConsensusBasedX ``` -**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 -``` \ No newline at end of file +``` + +## Bug reports, feature requests, and contributions + +See [the contribution guidelines](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/CONTRIBUTING.md).