Merge pull request #35 from rafaelbailo/main

Improve documentation following JOSS review

Author: rafaelbailo

docs/make.jl

@@ -65,7 +65,7 @@ makedocs(;
     prettyurls = get(ENV, "CI", "false") == "true",
     canonical = "https://PdIPS.github.io/ConsensusBasedX.jl",
     edit_link = "main",
-    assets = String[],
+    assets = ["assets/favicon.ico"],
     footer = "Copyright © 2024 [Dr Rafael Bailo](https://rafaelbailo.com/) and [Purpose-Driven Interacting Particle Systems Group](https://github.com/PdIPS). [MIT License](https://github.com/PdIPS/ConsensusBasedX.jl/blob/main/LICENSE).",
   ),
   source = "parsed",

docs/src/assets/favicon.ico

@@ -9,6 +9,7 @@ For instance, if `D = 2`, you can sample `exp(-αf)` by running:
 out = sample(f, D = 2, extended_output=true)
 out.sample
 ```
+The method must be run with the `extended_output=true` option in order to receive [Extended output](@ref) and access the full particle sample; without it, `sample` returns a single `Vector{Float64}` of length `D` which contains the candidate to the global minimiser of `f`, just like `minimise`.
 
 !!! note
     You must always provide `D`.

docs/src/assets/logo-square.png

@@ -1,13 +1,18 @@
 # Extended output
 
-By default, the `minimise` routine returns its best guess for the global minimiser of the function `f`. However, it is possible to access the extended output by passing the `extended_output = true` option.
+By default, the `minimise` and `sample` routines return their best guess for the global minimiser of the function `f`. However, it is possible to access the extended output by passing the `extended_output = true` option.
 
-The extended output is a `NamedTuple` which contains:
-- `minimiser`, the usual output of the `minimise`;
+When calling `minimise`, the extended output is a `NamedTuple` which contains:
+- `minimiser`, a `Vector{Float64}`, the candidate to the global minimiser of `f`;
 - `ensemble_minimiser`, a `Vector` of the `M` minimisers computed by each ensemble. `minimiser` is equal to their mean;
-- `initial_particles`, the initial position of the particles, see Particle initialisationref;
-- `final_particles`, the final position of the particles;
+- `initial_particles`, the initial position of the particles, see [Particle initialisation](@ref);
+- `final_particles`, the final position of the particles.
+
+When calling `sample`, the extended output also includes `sample`, which is an alias for `final_particles`. The final position of the particles is the distribution sample when running with `CBS_mode = :sampling`.
+
+In both cases, certain low-level caches are included as well:
 - `method`, by default a `ConsensusBasedOptimisation` object;
 - `method_cache`, by default a `ConsensusBasedOptimisationCache` object;
 - `particle_dynamic`, by default a `ParticleDynamic` object;
-- `particle_dynamic_cache`, by default a `ParticleDynamicCache` object.
+- `particle_dynamic_cache`, by default a `ParticleDynamicCache` object. 
+These objects are part of the [Low-level interface](@ref).

docs/src/distribution_sampling.md

@@ -6,7 +6,7 @@ For instance, if `D = 2`, you can minimise `f` by running:
 ```julia
 minimise(f, D = 2)
 ```
-By default, `minimise` returns a `Vector{Float64}` of length `D`.
+By default, `minimise` returns a `Vector{Float64}` of length `D` which contains the candidate to the global minimiser of `f`.
 
 !!! note
     You must always provide `D`.
@@ -34,6 +34,16 @@ This is a version of the full-code example above, using `config` instead:
 ConsensusBasedX.jl also defines `optimise` as an alias of `minimise`.
 
 
+## Receiving extended output
+
+It is possible to receive extended output from `minimise` by passing the option `extended_output = true`:
+```julia
+config = (; D = 2, extended_output = true)
+minimise(f, config)
+```
+For more details, see [Extended output](@ref).
+
+
 ## Maximisation
 
 ConsensusBasedX.jl also defines `maximise` for convenience. If you call

docs/src/extended_output.md

@@ -2,7 +2,7 @@
 
 Consensus-based optimisation is often used to tackle minimisation problems where `f(x)` is expensive to evaluate (for instance, parameter estimation in a [partial differential equation](https://en.wikipedia.org/wiki/Partial_differential_equation) model). Therefore, ConsensusBasedX.jl does not use parallelisation by default, as it assumes the implementation of `f` will be parallelised if possible.
 
-However, you can enable parallelisation by passing the option `parallelisation=:EnsembleParallelisation`. With this option, ConsensusBasedX.jl will run each of the `M` particle ensembles in parallel.
+However, you can enable parallelisation by passing the option `parallelisation=:EnsembleParallelisation`. With this option, ConsensusBasedX.jl will run each of the `M` particle ensembles in parallel, using multithreading.
 
 !!! warning
     Parallelisation leads to memory allocations which cannot be avoided, as there is overhead associated with distributing the tasks. If you activate parallelisation, and then run `minimise` in benchmark mode (see [Performance and benchmarking](@ref)), you will detect some allocations, and this is expected.

docs/src/function_minimisation.md

@@ -4,6 +4,9 @@ ConsensusBasedX.jl has been developed with performance in mind. As such, it foll
 
 In order to maintain good performance, it's important that your function `f` also follows these patterns. We recommend the [performance tips](https://docs.julialang.org/en/v1/manual/performance-tips/) section of the Julia documentation. You should benchmark `f`, paying attention to memory allocations.
 
+!!! tip
+    You should use the [BenchmarkTools.jl](https://juliaci.github.io/BenchmarkTools.jl/stable/) package to benchmark `f`.
+
 Once you have benchmarked `f`, you might want to test its performance within ConsensusBasedX.jl. You could run
 ```julia
 config = (; D = 2)

docs/src/parallelisation.md

@@ -33,6 +33,6 @@ You can apply any of these criteria by passing them as keywords to the `minimise
 
 ## Max time
 
-`max_time::Real = Inf` determines the maximal simulation time. If the number of iterations times `Δt` surpasses this value, the minimisation stops. 
+`max_time::Real = Inf` determines the maximal solution time (the corresponding SDE is solved from time `0` until time `max_time`). If the number of iterations times `Δt` surpasses this value, the minimisation stops. 
 
 {{basic_usage/max_time.jl}}

docs/src/performance_benchmarking.md

@@ -29,7 +29,7 @@ See [Stopping criteria](@ref).
 - `energy_tolerance::Real = 1e-8` is the stopping tolerance for the value of `f`.
 - `max_evaluations::Real = Inf` is the maximum number of evaluations of `f`.
 - `max_iterations::Real = 1000` is the maximum number of iterations.
-- `max_time::Real = Inf` is the maximal simulation time.
+- `max_time::Real = Inf` is the maximal  solution time (the corresponding SDE is solved from time `0` until time `max_time`).
 
 ## Advanced options