Consensus-based sampling

docs/make.jl

@@ -30,6 +30,7 @@ makedocs(;
     "Home" => "index.md",
     "Basic usage" => [
       "Function minimisation" => "function_minimisation.md"
+      "Distribution sampling" => "distribution_sampling.md"
       "Method parameters" => "method_parameters.md"
       "Stopping criteria" => "stopping_criteria.md"
       "Particle initialisation" => "particle_initialisation.md"

docs/src/distribution_sampling.md

@@ -0,0 +1,43 @@
+# Distribution sampling
+
+ConsensusBasedX.jl also provides consensus-based sampling, [J. A. Carrillo, F. Hoffmann, A. M. Stuart, and U. Vaes (2022)](https://onlinelibrary.wiley.com/doi/10.1111/sapm.12470). The package exports `sample`, which behaves exactly as `minimise` in [Function minimisation](@ref). It assumes you have defined a function `f(x::AbstractVector)` that takes a single vector argumemt `x` of length `D = length(x)`.
+
+For instance, if `D = 2`, you can sample `exp(-f)` by running:
+```julia
+out = sample(f, D = 2, extended_output=true)
+out.sample
+```
+[Full-code example](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/examples/basic_usage/sample_with_keywords.jl).
+
+!!! note
+    You must always provide `D`.
+
+
+## Using a `config` object
+
+For more advanced usage, you will select several options. You can pass these as extra keyword arguments to `sample`, or you can create a `NamedTuple` called `config` and pass that:
+```julia
+config = (; D = 2, extended_output=true)
+out = sample(f, config)
+out.sample
+```
+[Full-code example](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/examples/basic_usage/sample_with_config.jl).
+
+!!! note
+    If you pass a `Dict` instead, it will be converted to a `NamedTuple` automatically.
+
+
+## Running on minimisation mode
+
+Consensus-based sampling can also be used for minimisation. If you want to run it in that mode, pass the option `CBS_mode = :minimise`.
+
+
+## Method reference
+
+```@index
+Pages = ["distribution_sampling.md"]
+```
+
+```@docs
+ConsensusBasedX.sample
+```

docs/src/function_minimisation.md

@@ -49,7 +49,6 @@ Full-code examples are provided for the [keyword](https://github.com/PdIPS/Conse
 
 ## Method reference
 
-
 ```@index
 Pages = ["function_minimisation.md"]
 ```

docs/src/low_level.md

@@ -49,3 +49,20 @@ The full reference is:
 ```@docs
 ConsensusBasedX.ConsensusBasedOptimisationCache
 ```
+
+## `ConsensusBasedSampling`
+
+The `ConsensusBasedSampling` struct (of type `CBXMethod`) defines the details of the *consensus-based sampling method* (function evaluations, covariance matrix...).
+
+```@docs
+ConsensusBasedX.ConsensusBasedSampling
+```
+
+### `ConsensusBasedSamplingCache`
+
+`ConsensusBasedSampling` requires a cache, `ConsensusBasedSamplingCache` (of type `CBXMethodCache`). This can be constructed with [`ConsensusBasedX.construct_method_cache`](@ref).
+
+The full reference is:
+```@docs
+ConsensusBasedX.ConsensusBasedSamplingCache
+```

docs/src/summary_options.md

@@ -38,3 +38,7 @@ See [Stopping criteria](@ref).
 - `extended_output::Bool = false` controls the output, and by default returns only the computed minimiser. `extended_output = true` returns additional information, see [Extended output](@ref).
 - `parallelisation = :NoParallelisation` controls the parallelisation of the `minimise` routine, switched off by default. `parallelisation=:EnsembleParallelisation` enables parallelisation, see  [Parallelisation](@ref).
 - `verbosity::Int = 0` is the verbosity level. `verbosity = 0` produces no output to console. `verbosity = 1` produces some output. 
+
+## Consensus-based sampling options
+
+- `CBS_mode = :sampling` controls the mode of consensus-based sampling. If you want to perform a minimisation, pass `CBS_mode = :minimise` instead.

examples/basic_usage/sample_to_minimise.jl

@@ -0,0 +1,6 @@
+using ConsensusBasedX
+
+f(x) = ConsensusBasedX.Ackley(x, shift = 1)
+
+config = (; D = 2, N = 20, CBS_mode = :minimise)
+sample(f, config)

examples/basic_usage/sample_with_config.jl

@@ -0,0 +1,7 @@
+using ConsensusBasedX
+
+f(x) = ConsensusBasedX.Ackley(x, shift = 1)
+
+config = (; D = 2, N = 20, extended_output = true)
+out = sample(f, config)
+out.sample

examples/basic_usage/sample_with_keywords.jl

@@ -0,0 +1,6 @@
+using ConsensusBasedX
+
+f(x) = ConsensusBasedX.Ackley(x, shift = 1)
+
+out = sample(f, D = 2, N = 20, extended_output = true)
+out.sample

src/CBO/CBO.jl

@@ -7,7 +7,7 @@ Fields:
 
   - `f`, the objective function.
   - `correction<:CBXCorrection`, a correction term.
-  - `α::Float64`, the the exponential weight parameter.
+  - `α::Float64`, the exponential weight parameter.
   - `λ::Float64`, the drift strengh.
   - `σ::Float64`, the noise strengh.
 """

src/CBO/CBO_method.jl

@@ -42,7 +42,7 @@ function compute_CBO_update!(
   particle_dynamic_cache::ParticleDynamicCache,
   m::Int,
 ) where {TF, TCorrection}
-  @expand particle_dynamic_cache D N X dX Δt root2Δt
+  @expand particle_dynamic_cache D N X dX Δt root_2Δt
   @expand method correction λ σ
   @expand method_cache consensus consensus_energy distance energy
 
@@ -59,7 +59,7 @@ function compute_CBO_update!(
         λ *
         (consensus[m][d] - X[m][n][d]) *
         correction(energy[m][n] - consensus_energy[m]) +
-        root2Δt * σ * distance[m][n] * randn()
+        root_2Δt * σ * distance[m][n] * randn()
     end
   end
   return nothing
@@ -72,7 +72,7 @@ function compute_CBO_update!(
   particle_dynamic_cache::ParticleDynamicCache,
   m::Int,
 ) where {TF, TCorrection}
-  @expand particle_dynamic_cache D N X dX Δt root2Δt
+  @expand particle_dynamic_cache D N X dX Δt root_2Δt
   @expand method correction λ σ
   @expand method_cache consensus consensus_energy energy
 
@@ -81,7 +81,7 @@ function compute_CBO_update!(
       dX[m][n][d] =
         (consensus[m][d] - X[m][n][d]) * (
           Δt * λ * correction(energy[m][n] - consensus_energy[m]) +
-          root2Δt * σ * randn()
+          root_2Δt * σ * randn()
         )
     end
   end

src/CBO/is_method_pending.jl

@@ -1,6 +1,6 @@
 function is_method_pending(
-  method::ConsensusBasedOptimisation,
-  method_cache::ConsensusBasedOptimisationCache,
+  method::CBXMethod,
+  method_cache::CBXMethodCache,
   particle_dynamic::ParticleDynamic,
   particle_dynamic_cache::ParticleDynamicCache,
   m::Int,
@@ -39,8 +39,8 @@ function is_method_pending(
 end
 
 function is_method_pending_energy_threshold(
-  method::ConsensusBasedOptimisation,
-  method_cache::ConsensusBasedOptimisationCache,
+  method::CBXMethod,
+  method_cache::CBXMethodCache,
   particle_dynamic::ParticleDynamic,
   particle_dynamic_cache::ParticleDynamicCache,
   m::Int,
@@ -50,8 +50,8 @@ function is_method_pending_energy_threshold(
 end
 
 function is_method_pending_energy_tolerance(
-  method::ConsensusBasedOptimisation,
-  method_cache::ConsensusBasedOptimisationCache,
+  method::CBXMethod,
+  method_cache::CBXMethodCache,
   particle_dynamic::ParticleDynamic,
   particle_dynamic_cache::ParticleDynamicCache,
   m::Int,
@@ -62,8 +62,8 @@ function is_method_pending_energy_tolerance(
 end
 
 function is_method_pending_max_evaluations(
-  method::ConsensusBasedOptimisation,
-  method_cache::ConsensusBasedOptimisationCache,
+  method::CBXMethod,
+  method_cache::CBXMethodCache,
   particle_dynamic::ParticleDynamic,
   particle_dynamic_cache::ParticleDynamicCache,
   m::Int,