Merge pull request #5 from Talendar/r0.1.0

Resolve #1, improve docs and add new examples

README.md

@@ -7,23 +7,28 @@
 [![PyPI](https://img.shields.io/pypi/v/nevopy)](https://pypi.org/project/nevopy/)
 [![Documentation](https://img.shields.io/badge/api-reference-blue.svg)](https://nevopy.readthedocs.io/en/latest/index.html)
 
-*NEvoPy* is an open source neuroevolution framework for Python. It allows 
-researchers and enthusiasts to quickly tackle machine learning problems 
-through the use of neuroevolutionary algorithms. In addition to being highly 
-optimized for distributed computing, *NEvoPy* is also compatible with
-TensorFlow.
+*NEvoPy* is an open source neuroevolution framework for Python. It provides a
+simple and intuitive API for researchers and enthusiasts in general to quickly
+tackle machine learning problems using neuroevolutionary algorithms. *NEvoPy* is
+optimized for distributed computing and has compatibility with TensorFlow.
 
-Neuroevolution is a form of artificial intelligence that uses evolutionary
-algorithms to generate artificial neural networks (ANNs). It is a vast and 
-expanding field of research that holds many promises for the future. Currently,
-*NEvoPy* implements the NEAT (NeuroEvolution of Augmenting Topologies) algorithm
-and a custom fixed-topology deep-neuroevolutionary algorithm, but much more is
-coming.
+Currently, the neuroevolutionary algorithms implemented by *NEvoPy* are:
 
-Here is a sample neural network generated by the NEAT algorithm to learn the XOR
-logic function:
+  * **NEAT** (NeuroEvolution of Augmenting Topologies), a powerful method by
+    Kenneth O. Stanley for evolving neural networks through complexification;
+  * the standard fixed-topology approach to neuroevolution, with support to
+    TensorFlow and deep neural networks.
 
-<img src="https://github.com/Talendar/nevopy/blob/master/docs/imgs/sample_network.png?raw=true" width="700" alt="Sample neural network">
+Note, though, that there's much more to come!
+
+In addition to providing high-performance implementations of powerful
+neuroevolutionary algorithms, such as NEAT, *NEvoPy* also provides tools to help
+you more easily implement your own algorithms.
+
+Neuroevolution, a form of artificial intelligence that uses evolutionary
+algorithms to generate artificial neural networks (ANNs), is one of the most
+interesting and unexplored fields of machine learning. It is a vast and
+expanding area of research that holds many promises for the future.
 
 <h2> Installing </h2>
 
@@ -35,11 +40,28 @@ $ pip install nevopy
 
 <h2> Getting started </h2>
 
-To get started with *NEvoPy*, please check out the examples available
+To get started with *NEvoPy*,
+[this](https://nevopy.readthedocs.io/en/latest/nevopy_overview.html) quick
+guide is especially useful. You should also check out some examples available
 [here](https://github.com/Talendar/nevopy/tree/master/examples).
+The XOR example is particularly instructive.
+
+The project's documentation is available on *Read the Docs*. You can access it
+through this [link](https://nevopy.readthedocs.io/en/latest/index.html).
 
-The project's documentation is available
-[here](https://nevopy.readthedocs.io/en/latest/index.html).
+<p>
+  <img align="center" 
+       src="https://github.com/Talendar/nevopy/blob/r0.1.0/docs/imgs/flappy_bird.gif?raw=true" 
+       height="250"/>
+  &nbsp;&nbsp;&nbsp;
+  <img align="center" 
+       src="https://github.com/Talendar/nevopy/blob/r0.1.0/docs/imgs/lunar_lander.gif?raw=true" 
+       height="250"/>
+  &nbsp;&nbsp;&nbsp;
+  <img align="center" 
+       src="https://github.com/Talendar/nevopy/blob/r0.1.0/docs/imgs/cart_pole.gif?raw=true" 
+       height="250"/>
+</p>
 
 <h2> Citing </h2>
 

RELEASE.md

@@ -1 +1,30 @@
-# Release 1.0.0
+## Release 0.1.0
+
+### Breaking Changes
+
+* `ne.fixed_topology.FixedTopologyPopulation` has been deprecated. The new class
+  `ne.genetic_algorithm.GeneticPopulation` should be
+  used in its place.
+* `ne.fixed_topology.FixedTopologyConfig` has been  deprecated. The new class
+  `ne.genetic_algorithm.GeneticAlgorithmConfig` should used in its place.  
+
+### Bug Fixes and Other Changes
+
+* Added new type of population: `ne.genetic_algorithm.GeneticPopulation`. It
+  implements a generalizable genetic algorithm that can be used as a base for a
+  wide range of neuroevolutionary algorithms. This resolves
+  [#1](https://github.com/Talendar/nevopy/issues/1).
+* Added `deprecation.py` to `utils`. It implements the `@deprecated` decorator,
+  that can be used to mark a function, method or class as being deprecated.
+* Fixed a bug in `GymEnvFitness` that was causing an incorrect interpretation of
+  the output values of fixed-topology genomes using TensorFlow layers.
+* Made some fixes and additions to the project's docstrings.
+* Added a new example in which *NEvoPy* is used to create an AI to play the
+  *Flappy Bird* game.
+* The other examples were reformatted and comments explaining the code were
+  added to them.
+
+
+## Release 0.0.2
+
+Initial public release of the *NEvoPy* framework.

docs/autodoc.py

@@ -4,8 +4,8 @@
 
 commands = [
 	"sphinx-apidoc -f -o ./ ../nevopy",
-    "make clean",
-    "make html"
+	"make clean",
+	"make html"
 ]
 
 

docs/callbacks.rst

@@ -1,4 +1,90 @@
+=========
 Callbacks
 =========
 
-todo
+------------
+Introduction
+------------
+
+A callback is a powerful tool to customize the behaviour of a population of
+genomes during the neuroevolutionary process. Examples include
+:class:`.FitnessEarlyStopping` to stop the evolution when a certain fitness has
+been achieved by the population, or :class:`.BestGenomeCheckpoint` to
+periodically save the best genome of a population during evolution. For a list
+with all the pre-implemented callbacks, take a look at :mod:`.callbacks`.
+
+In this quick guide you'll learn what a `NEvoPy` callback is, what it can do,
+and how you can build your own.
+
+---------------------------
+`NEvoPy` callbacks overview
+---------------------------
+
+In `NEvoPy`, all callbacks subclass the :class:`.Callback` class and override a
+set of methods called at various stages of the evolutionary process. Callbacks
+are useful to get a view on internal states and statistics of a population and
+its genomes, as well as for modifying the behavior of the evolutionary algorithm
+being used.
+
+You can pass a list of callbacks (as the keyword argument ``callbacks``) to
+the :meth:`evolve() <.BasePopulation.evolve()>` method of your population.
+
+
+-------------------------------
+An overview of callback methods
+-------------------------------
+
+A callback implements one or more of the following methods (check each method's
+documentation for a list of accepted parameters):
+
+    * :meth:`on_generation_start <.Callback.on_generation_start>`: called at the
+      beginning of each new generation.
+    * :meth:`on_fitness_calculated <.Callback.on_fitness_calculated>`: called
+      right after the fitness values of the population's genomes are calculated.
+    * :meth:`on_mass_extinction_counter_updated
+      <.Callback.on_mass_extinction_counter_updated>`: called right after the
+      mass extinction counter is updated. The mass extinction counter counts how
+      many generations have passed since the fitness of the population's best
+      genomes improved.
+    * :meth:`on_mass_extinction_start <.Callback.on_mass_extinction_start>`:
+      called at the beginning of a mass extinction event. A mass extinction
+      event occurs when the population's fitness haven't improved for a
+      predefined number of generations. It results in the replacement of all the
+      population's genomes (except for the fittest genome) for new randomly
+      generated genomes.
+    * :meth:`on_reproduction_start <.Callback.on_reproduction_start>`: called
+      at the beginning of the reproductive process.
+    * :meth:`on_speciation_start <.Callback.on_speciation_start>`: called at
+      the beginning of the speciation process. If the neuroevolutionary
+      algorithm doesn't use speciation, this method isn't called at all.
+    * :meth:`on_generation_end <.Callback.on_generation_end>`: called at the
+      end of each generation.
+    * :meth:`on_evolution_end <.Callback.on_evolution_end>`: called when the
+      evolutionary process ends.
+
+
+--------------------------
+Writing your own callbacks
+--------------------------
+
+To build your own callback, simply create a new class that has
+:class:`.Callback` as its parent class:
+
+    .. code-block:: python
+
+        class MyCallback(Callback):
+            def on_generation_start(self,
+                                    current_generation,
+                                    max_generations):
+                print("This is printed at the start of every generation!")
+                print(f"Starting generation {current_generation} of "
+                      f"{max_generations}.")
+
+Then, just create a new instance of your callback and pass it to the
+:meth:`evolve() <.BasePopulation.evolve()>` of your population:
+
+    .. code-block:: python
+
+        population.evolve(generations=100,
+                          fitness_function=my_func,
+                          callbacks=[MyCallback()])

docs/conf.py

@@ -49,7 +49,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "modules.rst"]
 
 
 # -- Options for HTML output -------------------------------------------------

docs/index.rst

@@ -1,17 +1,29 @@
+==================================
 Welcome to NEvoPy's documentation!
 ==================================
 
-`NEvoPy` is an open source neuroevolution framework for Python. It allows
-researchers and enthusiasts to quickly tackle machine learning problems through
-the use of neuroevolutionary algorithms. In addition to being highly optimized
-for distributed computing, `NEvoPy` is also compatible with TensorFlow.
+`NEvoPy` is an open source neuroevolution framework for Python. It provides a
+simple and intuitive API for researchers and enthusiasts in general to quickly
+tackle machine learning problems using neuroevolutionary algorithms. `NEvoPy` is
+optimized for distributed computing and has compatibility with TensorFlow.
+
+Currently, the neuroevolutionary algorithms implemented by `NEvoPy` are:
+
+    * **NEAT** (NeuroEvolution of Augmenting Topologies), a powerful method by
+      Kenneth O. Stanley for evolving neural networks through complexification;
+    * the standard fixed-topology approach to neuroevolution, with support to
+      TensorFlow and deep neural networks.
+
+Note, though, that there's much more to come!
+
+In addition to providing high-performance implementations of powerful
+neuroevolutionary algorithms, such as NEAT, `NEvoPy` also provides tools to help
+you more easily implement your own algorithms.
 
-Neuroevolution is a form of artificial intelligence that uses evolutionary
-algorithms to generate artificial neural networks (ANNs). It is a vast and
-expanding field of research that holds many promises for the future. Currently,
-`NEvoPy` implements the NEAT (NeuroEvolution of Augmenting Topologies) algorithm
-and a custom fixed-topology deep-neuroevolutionary algorithm, but much more is
-coming.
+Neuroevolution, a form of artificial intelligence that uses evolutionary
+algorithms to generate artificial neural networks (ANNs), is one of the most
+interesting and unexplored fields of machine learning. It is a vast and
+expanding area of research that holds many promises for the future.
 
 If you encounter any confusing, incomplete or incorrect information in this
 project, please open an issue in our `GitHub project
@@ -24,8 +36,6 @@ project, please open an issue in our `GitHub project
    nevopy_overview
    installation
    examples
-   genomes_and_populations
-   neuroevolutionary_algorithms
    callbacks
    processing
    Modules and Subpackages<nevopy>

docs/installation.rst

@@ -1,10 +1,50 @@
+============
 Installation
 ============
 
-Install NEvoPy from PyPI using pip
-----------------------------------
-todo
+------------------------------------
+Install `NEvoPy` from PyPI using pip
+------------------------------------
+
+To install the latest stable release of `NEvoPy` from `PyPI`, just run the
+following command:
+
+.. code::
+
+   $ pip install nevopy
+
+In case you want to install `NEvoPy` with all the its most recent changes
+(might be unstable), you can directly install it from GitHub with `pip`:
+
+.. code::
+
+   $ pip install git+https://github.com/Talendar/nevopy
+
+
+-----------------------------------------------------------
+Install `NEvoPy` by cloning the project's GitHub repository
+-----------------------------------------------------------
+
+To install `NEvoPy` directly from its source code, first clone our GitHub
+repository by running the command:
+
+.. code::
+
+   $ git clone https://github.com/Talendar/nevopy
+
+Then change directories to the `nevopy` folder and install the package using
+`pip`:
+
+.. code::
+
+   $ cd nevopy
+   $ pip install .
+
+
+Alternatively, you can install `NEvoPy` by executing the `setup.py` script (not
+recommended):
+
+.. code::
 
-Install NEvoPy from source using setup.py
------------------------------------------
-todo
+   $ cd nevopy
+   $ python3 setup.py install

docs/nevopy.genetic_algorithm.rst

@@ -0,0 +1,29 @@
+nevopy.genetic\_algorithm package
+=================================
+
+Submodules
+----------
+
+nevopy.genetic\_algorithm.config module
+---------------------------------------
+
+.. automodule:: nevopy.genetic_algorithm.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nevopy.genetic\_algorithm.population module
+-------------------------------------------
+
+.. automodule:: nevopy.genetic_algorithm.population
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: nevopy.genetic_algorithm
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/nevopy.rst

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    nevopy.fixed_topology
+   nevopy.genetic_algorithm
    nevopy.neat
    nevopy.processing
    nevopy.utils

docs/nevopy.utils.rst

@@ -4,6 +4,14 @@ nevopy.utils package
 Submodules
 ----------
 
+nevopy.utils.deprecation module
+-------------------------------
+
+.. automodule:: nevopy.utils.deprecation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 nevopy.utils.gym\_utils module
 ------------------------------