Merge pull request #80 from jmejia8/develop

Preparing Metaheuristics v3.3.0

.github/workflows/CI.yml

@@ -4,7 +4,8 @@ on:
     branches:
       - 'master'
   pull_request:
-    types: [opened, reopened]
+
+jobs:
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
@@ -13,7 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - 1.5
+          - 1.7
         os:
           - ubuntu-latest
         arch:

.github/workflows/documentation-github-actions.yml

@@ -14,7 +14,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1.5'
+          version: '1.7'
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy

Project.toml

@@ -1,7 +1,7 @@
 name = "Metaheuristics"
 uuid = "bcdb8e00-2c21-11e9-3065-2b553b22f898"
 authors = ["Jesus Mejia <[email protected]>"]
-version = "3.2.16"
+version = "3.3.0"
 
 [deps]
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
@@ -10,16 +10,20 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
+SearchSpaces = "eb7571c6-2196-4f03-99b8-52a5a35b3163"
 SnoopPrecompile = "66db9d55-30c0-4569-8b51-7e840670fc0c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 Distances = "^0.10.7"
 JMcDM = "^0.7.1"
+Reexport = "^1"
 Requires = "1"
+SearchSpaces = "^0.2"
 SnoopPrecompile = "1"
-julia = "^1.5"
+julia = "^1.7"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"

README.md

@@ -16,7 +16,7 @@ High-performance metaheuristics for global optimization.
 
 ## Installation
 
-Open the Julia REPL (v1.1 or later) and press `]` to open the Pkg prompt. To add this package, use the add command:
+Open the Julia REPL and press `]` to open the Pkg prompt. To add this package, use the add command:
 
 ```
 pkg> add Metaheuristics
@@ -105,15 +105,16 @@ Code the objective function:
 f(x) = 10length(x) + sum( x.^2 - 10cos.(2π*x)  )
 ```
 
-Instantiate the bounds, note that `bounds` should be a $2\times 10$ `Matrix` where
-the first row corresponds to the lower bounds whilst the second row corresponds to the
-upper bounds.
+Instantiate the bounds:
 
 ```julia
 D = 10
-bounds = [-5ones(D) 5ones(D)]'
+bounds = boxconstraints(lb = -5ones(D), ub = 5ones(D))
 ```
 
+Also, `bounds` can be a $2\times 10$ `Matrix` where the first row corresponds to the
+lower bounds whilst the second row corresponds to the upper bounds.
+
 Approximate the optimum using the function `optimize`.
 
 ```julia

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 
 [compat]
 Documenter = "0.27.15"

docs/make.jl

@@ -9,7 +9,8 @@ makedocs(
                                   prettyurls = get(ENV, "CI", nothing) == "true",
                                   assets = ["assets/favicon.ico", "assets/extra_styles.css"],
                                   analytics = "UA-184071594-1",
-                                  collapselevel = 2,
+                                  collapselevel = 1,
+                                  ansicolor=true,
                                  ),
          sitename="Metaheuristics.jl",
          authors = "Jesús Mejía",
@@ -19,6 +20,7 @@ makedocs(
                                   "tutorials/simple-tutorial.md",
                                   "tutorials/create-metaheuristic.md",
                                   "tutorials/parallelization.md",
+                                  "tutorials/n-queens.md",
                                  ],
                   "Examples" =>  "examples.md",
                   "Algorithms" => "algorithms.md",
@@ -27,6 +29,7 @@ makedocs(
                   "Multi-Criteria Decision Making" => "mcdm.md",
                   "Visualization" => "visualization.md",
                   "API References" => "api.md",
+                  "FAQ" => "faq.md",
                   "Contributing" => "contributing.md",
                   "References" => "references.md",
                  ]

docs/src/api.md

@@ -198,6 +198,10 @@ GenerationalReplacement
 ElitistReplacement
 ```
 
+```@docs
+RankAndCrowding
+```
+
 ## Population
 
 

docs/src/assets/extra_styles.css

@@ -4,3 +4,39 @@ dl dd div:target {
     border-radius: 10px;
 }
 
+html.theme--documenter-dark #documenter .docs-main,
+#documenter .docs-main{
+    max-width: 45rem;
+}
+
+
+pre {
+    border-radius: 7px;
+}
+
+article.docstring {
+    border:none;
+    box-shadow: 1px 1px 9px -2px rgba(0,0,0,0.7);
+    -webkit-box-shadow: 1px 1px 9px -2px rgba(0,0,0,0.7);
+    -moz-box-shadow: 1px 1px 9px -2px rgba(0,0,0,0.7);
+    margin-bottom: 2em;
+}
+
+code.nohighlight.ansi {
+    transition: opacity .5s ease-out;
+    opacity: 0.5;
+}
+
+.documenter-example-output code.nohighlight.ansi{
+    opacity: 0.8;
+}
+
+
+pre:hover > code.nohighlight.ansi {
+    opacity: 9;
+}
+
+.content pre {
+  border: 1px solid #e6e6e6;
+}
+

docs/src/examples.md

@@ -6,29 +6,66 @@ examples for using the implemented `Metaheuristics`.
 ## Single-Objective Optimization
 
 
-```@repl
+Firstly import this package
+
+```@example SingleObjective
 using Metaheuristics
+```
+Now, let us define the objective function to be minimized:
 
-f(x) = 10length(x) + sum( x.^2 - 10cos.(2π*x) ) # objective function
+```@example SingleObjective
+f(x) = 10length(x) + sum( x.^2 - 10cos.(2π*x) )
+```
 
-bounds = [-5ones(10) 5ones(10)]' # limits/bounds
+The search space (a.k.a. box-constraints) can be defined as follows:
 
-information = Information(f_optimum = 0.0); # information on the minimization problem
+```@example SingleObjective
+bounds = boxconstraints(lb = -5ones(10), ub = 5ones(10))
+```
 
-options = Options(f_calls_limit = 9000*10, f_tol = 1e-5); # generic settings
+!!! compat "boxconstraints in a Matrix format."
+    You can also define the bounds using `bounds = [-5ones(10) 5ones(10)]'`; however this
+    is not longer recommended.
 
-algorithm = ECA(information = information, options = options) # metaheuristic used to optimize
+It is possible to provide some information on the minimization problem.
+Let's provide the true optimum to stop the optimizer when a tolerance `f_tol` is satisfied.
 
-result = optimize(f, bounds, algorithm) # start the minimization process
+```@example SingleObjective
+information = Information(f_optimum = 0.0)
+```
 
+Generic options or settings (e.g. budget limitation, tolerances, etc) can be provided as follows:
+
+```@example SingleObjective
+options = Options(f_calls_limit = 9000*10, f_tol = 1e-5, seed=1)
+```
+
+Now, we can provide the Information and Options to the optimizer (ECA in this example).
+
+```@example SingleObjective
+algorithm = ECA(information = information, options = options)
+```
 
+Now, the optimization is performed as follows:
+
+```@example SingleObjective
+result = optimize(f, bounds, algorithm)
+```
+
+The minimum and minimizer:
+
+```@example SingleObjective
 minimum(result)
+```
+
+```@example SingleObjective
 minimizer(result)
+```
 
 
-result = optimize(f, bounds, algorithm) # note that second run is faster
+!!! compat "Second run is faster"
+    As you may know, the second run can be faster:
 
-```
 
 ## Constrained Optimization
 
@@ -81,6 +118,7 @@ you need to provide constraints if they exist, otherwise put `gx = [0.0]; hx = [
 to indicate an unconstrained multiobjective problem.
 
 ```@repl
+using UnicodePlots # to visualize in console (optional)
 using Metaheuristics
 
 function f(x)
@@ -244,7 +282,7 @@ algorithm performance or test new mechanisms. This example illustrates how to do
 Let's assume that we want to modify the stop criteria for `ECA`. See [Contributing](@ref) 
 for more details.
 
-```@repl
+```julia
 using Metaheuristics
 import LinearAlgebra: norm
 

docs/src/faq.md

@@ -0,0 +1,10 @@
+# FAQ
+
+Answers to Frequently Asked Questions:
+
+## How to solve combinatorial problems?
+
+This package was initially developed for numerical optimization, but recent updates
+can handle combinatorial problems. The Genetic Algorithm framework ([`GA`](@ref)) can be used.
+
+

docs/src/index.md

@@ -1,6 +1,6 @@
 # Metaheuristics - an Intuitive Package for Global Optimization
 
-**Author: Jesus Mejía (@jmejia8)**
+**Author: Jesús-Adolfo Mejía-de-Dios (@jmejia8)**
 
 High-performance algorithms for optimization coded purely in a high-performance language.
 
@@ -26,13 +26,13 @@ global optimization.
 
 Open the Julia (Julia 1.1 or Later) REPL and press `]` to open the Pkg prompt. To add this package, use the add command:
 
-```
+```julia-repl
 pkg> add Metaheuristics
 ```
 
 Or, equivalently, via the `Pkg` API:
 
-```julia
+```julia-repl
 julia> import Pkg; Pkg.add("Metaheuristics")
 ```
 
@@ -53,36 +53,45 @@ dimension number, assume $D=10$.
 
 Firstly, import the Metaheuristics package:
 
-```julia
+```@example julia
 using Metaheuristics
 ```
 
 Code the objective function:
-```julia
+
+```@example julia
 f(x) = 10length(x) + sum( x.^2 - 10cos.(2π*x)  )
+nothing # hide
 ```
 
-Instantiate the bounds, note that `bounds` should be a $2\times 10$ `Matrix` where
-the first row corresponds to the lower bounds whilst the second row corresponds to the
-upper bounds.
+Instantiate the bounds:
 
-```julia
+```@example julia
 D = 10
-bounds = [-5ones(D) 5ones(D)]'
+bounds = boxconstraints(lb = -5ones(D), ub = 5ones(D))
+nothing # hide
 ```
 
+Also, `bounds` can be a $2\times 10$ `Matrix` where the first row corresponds to the
+lower bounds whilst the second row corresponds to the upper bounds.
+
 Approximate the optimum using the function `optimize`.
 
-```julia
+```@example julia
+import Random: seed! # hide
+seed!(50) # hide
 result = optimize(f, bounds)
 ```
 
 Optimize returns a `State` datatype which contains some information about the approximation.
 For instance, you may use mainly two functions to obtain such an approximation.
 
-```julia
-@show minimum(result)
-@show minimizer(result)
+```@example julia
+minimum(result)
+```
+
+```@example julia
+minimizer(result)
 ```