Skip to content

Commit

Permalink
additional documentation & examples
Browse files Browse the repository at this point in the history
  • Loading branch information
KRM7 authored Aug 18, 2023
1 parent 811f00c commit 4a8faec
Show file tree
Hide file tree
Showing 36 changed files with 1,615 additions and 127 deletions.
14 changes: 8 additions & 6 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

on:
push:
branches: [master, dev]
branches: [master]

jobs:
update-docs:
Expand All @@ -17,17 +17,18 @@ jobs:

- name: git-config
run: |
git config user.name ${{ github.repository_owner }}
git config user.email ${{ github.repository_owner }}@users.noreply.github.com
git config --global user.name ${{ github.repository_owner }}
git config --global user.email ${{ github.repository_owner }}@users.noreply.github.com
- name: update-api-docs
uses: actions/checkout@v3
with:
ref: gh-pages
fetch-depth: 0
- run: |
git rebase origin/master
sudo ./docs/api/generate_api_docs.sh
mv docs/api/sphinx-out/* docs/
sudo bash ./docs/api/generate_api_docs.sh
sudo rsync -a docs/api/sphinx-out/ docs/
git commit --all --amend --no-edit
git push --force-with-lease
Expand All @@ -40,5 +41,6 @@ jobs:
rm -f wiki/*.md
cp docs/*.md wiki/
cd wiki
git commit --all --amend --no-edit
git add .
git commit --amend --no-edit
git push --force-with-lease
35 changes: 21 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@

# Genetic Algorithms in C++

[![linux](https://github.com/KRM7/genetic-algorithms/actions/workflows/linux.yml/badge.svg?branch=dev)](https://github.com/KRM7/genetic-algorithms/actions/workflows/linux.yml)
[![windows](https://github.com/KRM7/genetic-algorithms/actions/workflows/windows.yml/badge.svg?branch=dev)](https://github.com/KRM7/genetic-algorithms/actions/workflows/windows.yml)
[![sanitizers](https://github.com/KRM7/genetic-algorithms/actions/workflows/sanitizers.yml/badge.svg?branch=dev)](https://github.com/KRM7/genetic-algorithms/actions/workflows/sanitizers.yml)
[![code analysis](https://github.com/KRM7/genetic-algorithms/actions/workflows/analysis.yml/badge.svg?branch=dev)](https://github.com/KRM7/genetic-algorithms/actions/workflows/analysis.yml)

[![linux](https://github.com/KRM7/genetic-algorithms/actions/workflows/linux.yml/badge.svg?branch=master)](https://github.com/KRM7/genetic-algorithms/actions/workflows/linux.yml)
[![windows](https://github.com/KRM7/genetic-algorithms/actions/workflows/windows.yml/badge.svg?branch=master)](https://github.com/KRM7/genetic-algorithms/actions/workflows/windows.yml)
[![sanitizers](https://github.com/KRM7/genetic-algorithms/actions/workflows/sanitizers.yml/badge.svg?branch=master)](https://github.com/KRM7/genetic-algorithms/actions/workflows/sanitizers.yml)
[![code analysis](https://github.com/KRM7/genetic-algorithms/actions/workflows/analysis.yml/badge.svg?branch=master)](https://github.com/KRM7/genetic-algorithms/actions/workflows/analysis.yml)
[![docs](https://github.com/KRM7/gapp/actions/workflows/docs.yml/badge.svg?branch=master)](https://github.com/KRM7/gapp/actions/workflows/docs.yml)

## Overview

Expand Down Expand Up @@ -86,22 +86,29 @@ target_link_libraries(YourTarget PRIVATE gapp::gapp)
```


## Examples
## Documentation

The [examples](./examples) directory contains several examples for using the library.
The API documentation is available [here](https://krm7.github.io/gapp/).

* [Minimal example](./examples/1_minimal_example.cpp)
* [Single-objective optimization](./examples/2_basic_single_objective.cpp)
* [Multi-objective optimization](./examples/3_basic_multi_objective.cpp)
Additional documentation for the library can be found in the [docs](./docs) directory:

* [Introduction](./docs/introduction.md)
* [Fitness functions](./docs/fitness-functions.md)
* [Encodings](./docs/encodings.md)
* [Algorithms](./docs/algorithms.md)
* [Genetic operators](./docs/genetic-operators.md)
* [Stop conditions](./docs/stop-conditions.md)
* [Metrics](./docs/metrics.md)
* [Miscellaneous](./docs/miscellaneous.md)

## Documentation

The API documentation is available [here](https://krm7.github.io/gapp/).
## Examples

Additional documentation for the library can be found in the [docs](./docs) directory.
The [examples](./examples) directory contains several examples for using the library.

* [Introduction](./docs/introduction.md)
* [Minimal example](./examples/1_minimal_example.cpp)
* [Single-objective optimization](./examples/2_basic_single_objective.cpp)
* [Multi-objective optimization](./examples/3_basic_multi_objective.cpp)

-------------------------------------------------------------------------------------------------

Expand Down
149 changes: 149 additions & 0 deletions docs/algorithms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@

1. [Introduction](introduction.md)
2. [Fitness functions](fitness-functions.md)
3. [Encodings](encodings.md)
4. **Algorithms**
5. [Genetic operators](genetic-operators.md)
6. [Stop conditions](stop-conditions.md)
7. [Metrics](metrics.md)
8. [Miscellaneous](miscellaneous.md)

------------------------------------------------------------------------------------------------

# Algorithms

The algorithms are used in the library to define different genetic algorithm
variants. They consist of the selection and population replacement methods,
which define the overall evolution process in combination with the genetic
operators.

The algorithms in the library belong to 2 categories: single-, and
multi-objective algorithms. These can only be used for single- and
multi-objective optimization problems respectively. It is possible
to implement general algorithms that work for any type of problem, but the
library currently doesn't have such an algorithm.

There are 3 algorithms provided by the library:

- SingleObjective (single-objective)
- NSGA-II (multi-objective)
- NSGA-III (multi-objective)

All of these algorithms are in the `gapp::algorithm` namespace.

## Selecting the algorithm

By default, if no algorithm is specified for the GA, one will automatically
be selected based on the number of objectives of the fitness function being used.
This means that the default algorithm used by the GA will always be compatible
with the fitness functions regardless of the number of objectives.

```cpp
BinaryGA ga;
ga.solve(f); // run using the default algorithm
```

It is also possible to select a different algorithm to be used by the GA.
This can be done either in the constructor or by using the `algorithm` method:

```cpp
BinaryGA ga;
ga.algorithm(algorithm::NSGA3{});
ga.solve(f);
```

The only thing that should be kept in mind when selecting the algorithm this
way is that it needs to be compatible with the fitness function used.
The single-objective algorithms can only be used for single-objective fitness
functions, and the multi-objective algorithms can only be used with multi-objective
fitness functions.

If an algorithm was explicitly specified, it can be cleared by passing a `nullptr`
to the `algorithm` setter. This will result in the default algorithm being used,
as in the case where no algorithm was explicitly set.

```cpp
ga.algorithm(nullptr);
ga.solve(f); // uses the default algorithm
```

## The single-objective algorithm

The `SingleObjective` algorithm is not a concrete algorithm implementation
like the NSGA-II and NSGA-III algorithms are. It is simply a wrapper that
combines a selection and a population replacement method. These methods
can be selected independently of eachother in the `SingleObjective` algorithm.

The library implements several selection and population replacement methods
that can be used. These are in the `gapp::selection` and `gapp::replacement`
namespaces respectively.

```cpp
BinaryGA ga;
ga.algorithm(algorithm::SingleObjective{}); // use the default selection and replacement methods
ga.solve(f);

// use tournament selection, and elitism for the population replacement methods
ga.algorithm(algorithm::SingleObjective{ selection::Tournament{}, replacement::Elitism{ 5 } });
ga.solve(f);
```
## Custom algorithms
In addition to the algorithms provided by the library, it is also possible to
use user-defined algorithms in the GAs. These must be implemented as a class
that is derived from `algorithm::Algorithm`. The class technically only has to implement
the `selectImpl` and `nextPopulationImpl` methods, but more complex, and efficient
algorithm implementations will have to implement several additional methods.
```cpp
class MyAlgorithm : public algorithm::Algorithm
{
public:
// ...
};
```

## Custom selection and replacement methods (single-objective)

For the `SingleObjective` algorithms, it's possible to define additional selection
and replacement methods separately without having to define a completely new
algorithm.

Simple selection and population replacement methods can be defined using a lambda
or some other callable type. As an example, a simple tournament selection method
could be implemented this way:

```cpp
algorithm::SingleObjective algorithm;
algorithm.selection_method([](const GaInfo& context, const FitnessMatrix& fmat)
{
size_t first = rng::randomIdx(fmat);
size_t second = rng::randomIdx(fmat);

return (fmat[first][0] >= fmat[second][0]) ? first : second;
});
```

More complex operators can be implemented as classes derived from `selection::Selection`
and `replacement::Replacement` respectively. The implementation of the simple
tournament selection shown above could also be implemented this way:

```cpp
class MyTournamentSelection : public selection::Selection
{
public:
size_t selectImpl(const GaInfo& context, const FitnessMatrix& fmat) const override
{
size_t first = rng::randomIdx(fmat);
size_t second = rng::randomIdx(fmat);

return (fmat[first][0] >= fmat[second][0]) ? first : second;
}
};
```

Note that a more general version of the tournament selection operator
is already implemented in the library, called `selection::Tournament`.

------------------------------------------------------------------------------------------------
2 changes: 1 addition & 1 deletion docs/api/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

html_theme = "sphinx_book_theme"
html_theme_options = {
"repository_url": "https://github.com/KRM7/genetic-algorithms",
"repository_url": "https://github.com/KRM7/gapp",
"use_repository_button": True,
"use_fullscreen_button": False,
"use_download_button": False,
Expand Down
Loading

0 comments on commit 4a8faec

Please sign in to comment.