Skip to content

Commit

Permalink
Merge pull request #24 from BorjaEst/dev
Browse files Browse the repository at this point in the history 
improve README with image and jupyter notebook
  • Loading branch information
@BorjaEst
BorjaEst authored Mar 4, 2023
2 parents 14c48b6 + c0db324 commit 1e1d3ac
Show file tree
Hide file tree
Showing 6 changed files with 565 additions and 143 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,3 +130,6 @@ dmypy.json

# Whiteboard files
whiteboard.py

# Gimp files
*.xcf
350 changes: 350 additions & 0 deletions README.ipynb
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,350 @@
{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"<h1 align=\"left\">\n",
"<img src=\"README_files/gevopy-logo2.png\" width=\"600\">\n",
"</h1><br>\n",
"\n",
"![qc.sec](https://github.com/BorjaEst/gevopy/actions/workflows/qc-sec.yml/badge.svg)\n",
"![qc.sty](https://github.com/BorjaEst/gevopy/actions/workflows/qc-sty.yml/badge.svg)\n",
"![qc.uni](https://github.com/BorjaEst/gevopy/actions/workflows/qc-uni.yml/badge.svg)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"Awesome Genetics for Evolutionary Algorithms library created by Borja Esteban."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## Install it from PyPI\n",
"```bash\n",
"$ pip install gevopy\n",
"```\n"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## Usage\n",
"This package is designed in order to create your own evolution scripts based on the following concepts:\n",
" - **Chromosomes**: Genetic instructions for phenotypes.\n",
" - **Genotype**: Genetic design to instantiate phenotypes.\n",
" - **Phenotypes**: Genotype instances which perform a task.\n",
" - **Fitness**: Provide the methods to evaluate phenotypes.\n",
" - **Algorithm**: Evolution procedure for phenotypes.\n",
" - **Experiment**: Evolution session with phenotypes.\n",
"\n",
"Now the following sections will introduce a fast initialization to the package.\n",
"Do not hesitate to extend your knowledge by using all the additional provided\n",
"examples at the folder [examples](./examples).\n"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"### Genotypes\n",
"Define your Genotypes following the `dataclass` principles from `pydantic` by\n",
"using the base model `GenotypeModel`. All dataclass attributes are accepted in \n",
"addition to an special type `Chromosome` provided in the module `genetics`.\n",
"To start use the already defined chromosome subclasses such `Haploid` and\n",
"`Diploid` depending on the complexity of your genetic model."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"[{'id': UUID('8b77fc1d-befe-4ad3-924c-1774223b7b60'),\n",
" 'experiment': None,\n",
" 'created': datetime.datetime(2023, 3, 4, 15, 24, 49, 325435),\n",
" 'parents': [],\n",
" 'generation': 1,\n",
" 'score': None,\n",
" 'chromosome_1': Haploid([0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0], dtype=uint8),\n",
" 'chromosome_2': Haploid([1, 0, 1, 1, 1, 0, 0, 1, 0, 1], dtype=uint8),\n",
" 'simple_attribute': 1.0},\n",
" {'id': UUID('a4460974-a45a-4ed2-8937-55ea211bb520'),\n",
" 'experiment': None,\n",
" 'created': datetime.datetime(2023, 3, 4, 15, 24, 49, 325564),\n",
" 'parents': [],\n",
" 'generation': 1,\n",
" 'score': None,\n",
" 'chromosome_1': Haploid([1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0], dtype=uint8),\n",
" 'chromosome_2': Haploid([1, 0, 1, 1, 1, 0, 0, 1, 0, 1], dtype=uint8),\n",
" 'simple_attribute': 1.0}]"
]
},
"execution_count": 1,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from gevopy import genetics, random\n",
"from gevopy.genetics import Field\n",
"\n",
"class MyGenotype(genetics.GenotypeModel):\n",
" chromosome_1: genetics.Haploid = Field(default_factory=lambda: random.haploid(12))\n",
" chromosome_2: genetics.Haploid = Field(default_factory=lambda: random.haploid(10))\n",
" simple_attribute: float = 1.0\n",
"\n",
"[MyGenotype() for _ in range(2)]"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"> Note Genotype attrubutes *id*, *experiment*, *created*, *parents*,\n",
"*generation*, *score* and *clone* are attributes used by the library.\n",
"Overwriting of this attributes might lead to unexpected behaviors."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"### Fitness\n",
"Create your fitness using the parent class `fitness.FitnessModel` and defining\n",
"the class method `score`. The fitness to use on the experiment will be an \n",
"instance of the defined class. You can use the init arguments `cache` and\n",
"`scheduler` (from Dask) to optimize how the evaluation flow is executed."
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"<__main__.MyFitness at 0x7f19e0744f40>"
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from gevopy import fitness\n",
"\n",
"class MyFitness(fitness.FitnessModel):\n",
" def score(self, phenotype):\n",
" x1 = phenotype.chromosome_1.count(1)\n",
" x2 = phenotype.chromosome_2.count(0)\n",
" return x1 - x2\n",
"\n",
"MyFitness(cache=True, scheduler=\"threads\")"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"> You can additionally define `setup` as method to execute once at the begining\n",
"of each generation before phenotypes are evaluated.\n",
"\n",
"> The only accepted values for scheduler are `synchronous`, `threads` and `processes`.\n",
"By default `threads` is used."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"### Algorithm\n",
"The algorithm is the core of your experiment. It defines the rules of the\n",
"evolution process. You can create your own algorithm or use the already\n",
"existing templates. Algorithms are generally composed by 4 components:\n",
" - **Selection**: Callable which provides the first list of candidates.\n",
" - **Mating**: Callable which provides the second list of candidates.\n",
" - **Crossover**: Callable to generate offspring from candidates.\n",
" - **Mutation**: Callable to mutate phenotype's chromosomes.\n",
"\n",
"Additionally, each algorithm template might contain additional arguments such a\n",
"`survival_rate` or `similarity`. Make sure you read and understand each of the \n",
"arguments and steps."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"MyAlgorithm(selection1=<gevopy.tools.selection.Tournaments object at 0x7f19906ca680>, mutation=<gevopy.tools.mutation.SinglePoint object at 0x7f19906ca710>, selection2=<gevopy.tools.selection.Uniform object at 0x7f19906ca770>, crossover=<gevopy.tools.crossover.Uniform object at 0x7f19906c8ee0>, survival_rate=0.4)"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from gevopy.tools import crossover, mutation, selection\n",
"from gevopy import algorithms\n",
"\n",
"class MyAlgorithm(algorithms.Standard):\n",
" selection1 = selection.Tournaments(tournsize=3)\n",
" selection2 = selection.Uniform()\n",
" crossover = crossover.Uniform(indpb=0.01)\n",
" mutation = mutation.SinglePoint(mutpb=0.2)\n",
"\n",
"MyAlgorithm()"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"> The modules `tools.crossover`, `tools.mutation` and `tools.selection` contain\n",
"templates and utilities to simplify your algorithm definition."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"### Experiment\n",
"The experiment is the final expression of your evolutionary algorithm.\n",
"it provides the methods to evolve and store phenotypes. Once an experiment\n",
"is instantiated, use the method `run` to force the evolution of the population\n",
"until a desired state.\n",
"\n",
"The results of the experiment can be collected from the method output, calling\n",
"`best` method or adding a [Neo4j]() connection as `database` input when\n",
"instantiating the experiment to store all phenotypes during the execution."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"Evolutionary algorithm execution report:\n",
" Executed generations: 12\n",
" Best phenotype: 7b13630f-d07c-4ff6-8be1-df6d6ceb06ca\n",
" Best score: 10"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import gevopy as ea\n",
"\n",
"experiment = ea.Experiment(\n",
" fitness=MyFitness(cache=True, scheduler=\"synchronous\"),\n",
" algorithm=MyAlgorithm(survival_rate=0.2),\n",
")\n",
"\n",
"with experiment.session() as session:\n",
" session.add_phenotypes([MyGenotype() for _ in range(20)])\n",
" statistics = session.run(max_generation=20, max_score=10)\n",
"\n",
"experiment.close()\n",
"statistics"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
">The method `run` forces the evolution of the experiment which is updated on\n",
"each cycle. After the method is completed, you can force again te evolution\n",
"process using higher inputs for `max_generations` or `max_score`."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## Development\n",
"Fork the repository, pick one of the issues at the [issues](https://github.com/BorjaEst/gevopy/issues)\n",
"and create a [Pull request](https://github.com/BorjaEst/gevopy/pulls).\n"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"## FAQ and Notes\n",
"\n",
"### Why Graph Database?\n",
"Storing relationships at the record level makes sense in genotype \n",
"relationships as it provides index-free adjacency.\n",
"Graph traversal operations such 'genealogy tree' or certain matches can\n",
"be performed with no index lookups leading to much better performance.\n",
"\n",
"### Why pydantic instead of dataclass?\n",
"Pydantic supports validation of fields during and after the\n",
"initialization process and makes parsing easier. \n",
"Parsing is a relevant step if you are planing to save your\n",
"phenotypes into the connected database.\n",
"\n",
"### Limitations\n",
"Collections containing collections can not be stored in properties.\n",
"Property values can only be of primitive types or arrays in Neo4J Cypher queries."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.10"
},
"orig_nbformat": 4
},
"nbformat": 4,
"nbformat_minor": 2
}
Loading

0 comments on commit 1e1d3ac

Please sign in to comment.