{"id":26517060,"url":"https://github.com/borjaest/gevopy","last_synced_at":"2026-03-06T07:31:39.446Z","repository":{"id":62889799,"uuid":"563383169","full_name":"BorjaEst/gevopy","owner":"BorjaEst","description":"Genetics for Evolutionary Algorithms in Python","archived":false,"fork":false,"pushed_at":"2023-05-24T12:12:01.000Z","size":175,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-20T10:07:04.259Z","etag":null,"topics":["evolutionary-algorithms","genetic-algorithm","hyperparameter-optimization","numpy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BorjaEst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-08T13:56:25.000Z","updated_at":"2023-01-27T13:59:23.000Z","dependencies_parsed_at":"2023-02-10T00:00:42.773Z","dependency_job_id":null,"html_url":"https://github.com/BorjaEst/gevopy","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BorjaEst%2Fgevopy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BorjaEst%2Fgevopy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BorjaEst%2Fgevopy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BorjaEst%2Fgevopy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BorjaEst","download_url":"https://codeload.github.com/BorjaEst/gevopy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244759961,"owners_count":20505716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["evolutionary-algorithms","genetic-algorithm","hyperparameter-optimization","numpy"],"created_at":"2025-03-21T08:17:57.019Z","updated_at":"2026-03-06T07:31:39.377Z","avatar_url":"https://github.com/BorjaEst.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"left\"\u003e\n\u003cimg src=\"README_files/gevopy-logo2.png\" width=\"600\"\u003e\n\u003c/h1\u003e\u003cbr\u003e\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)\n\nAwesome Genetics for Evolutionary Algorithms library created by Borja Esteban.\n\n## Install it from PyPI\n```bash\n$ pip install gevopy\n```\n\n\n## Usage\nThis 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\nNow the following sections will introduce a fast initialization to the package.\nDo not hesitate to extend your knowledge by using all the additional provided\nexamples at the folder [examples](./examples).\n\n\n### Genotypes\nDefine your Genotypes following the `dataclass` principles from `pydantic` by\nusing the base model `GenotypeModel`. All dataclass attributes are accepted in \naddition to an special type `Chromosome` provided in the module `genetics`.\nTo start use the already defined chromosome subclasses such `Haploid` and\n`Diploid` depending on the complexity of your genetic model.\n\n\n```python\nfrom gevopy import genetics, random\nfrom gevopy.genetics import Field\n\nclass 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)]\n```\n\n\n\n\n    [{'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}]\n\n\n\n\u003e Note Genotype attrubutes *id*, *experiment*, *created*, *parents*,\n*generation*, *score* and *clone* are attributes used by the library.\nOverwriting of this attributes might lead to unexpected behaviors.\n\n### Fitness\nCreate your fitness using the parent class `fitness.FitnessModel` and defining\nthe class method `score`. The fitness to use on the experiment will be an \ninstance of the defined class. You can use the init arguments `cache` and\n`scheduler` (from Dask) to optimize how the evaluation flow is executed.\n\n\n```python\nfrom gevopy import fitness\n\nclass 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\nMyFitness(cache=True, scheduler=\"threads\")\n```\n\n\n\n\n    \u003c__main__.MyFitness at 0x7f19e0744f40\u003e\n\n\n\n\u003e You can additionally define `setup` as method to execute once at the begining\nof each generation before phenotypes are evaluated.\n\n\u003e The only accepted values for scheduler are `synchronous`, `threads` and `processes`.\nBy default `threads` is used.\n\n### Algorithm\nThe algorithm is the core of your experiment. It defines the rules of the\nevolution process. You can create your own algorithm or use the already\nexisting 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\nAdditionally, each algorithm template might contain additional arguments such a\n`survival_rate` or `similarity`. Make sure you read and understand each of the \narguments and steps.\n\n\n```python\nfrom gevopy.tools import crossover, mutation, selection\nfrom gevopy import algorithms\n\nclass 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\nMyAlgorithm()\n```\n\n\n\n\n    MyAlgorithm(selection1=\u003cgevopy.tools.selection.Tournaments object at 0x7f19906ca680\u003e, mutation=\u003cgevopy.tools.mutation.SinglePoint object at 0x7f19906ca710\u003e, selection2=\u003cgevopy.tools.selection.Uniform object at 0x7f19906ca770\u003e, crossover=\u003cgevopy.tools.crossover.Uniform object at 0x7f19906c8ee0\u003e, survival_rate=0.4)\n\n\n\n\u003e The modules `tools.crossover`, `tools.mutation` and `tools.selection` contain\ntemplates and utilities to simplify your algorithm definition.\n\n### Experiment\nThe experiment is the final expression of your evolutionary algorithm.\nit provides the methods to evolve and store phenotypes. Once an experiment\nis instantiated, use the method `run` to force the evolution of the population\nuntil a desired state.\n\nThe results of the experiment can be collected from the method output, calling\n`best` method or adding a [Neo4j]() connection as `database` input when\ninstantiating the experiment to store all phenotypes during the execution.\n\n\n```python\nimport gevopy as ea\n\nexperiment = ea.Experiment()\nwith experiment.session() as session:\n    session.add_phenotypes([MyGenotype() for _ in range(20)])\n    session.algorithm = MyAlgorithm(survival_rate=0.2)\n    session.fitness = MyFitness(cache=True, scheduler=\"synchronous\")\n    statistics = session.run(max_generation=20, max_score=10)\n\nexperiment.close()\nstatistics\n```\n\n    Evolutionary algorithm execution report:\n      Executed generations: 12\n      Best phenotype: 7b13630f-d07c-4ff6-8be1-df6d6ceb06ca\n      Best score: 10\n\n\n\u003eThe method `run` forces the evolution of the experiment which is updated on\neach cycle. After the method is completed, you can force again te evolution\nprocess using higher inputs for `max_generations` or `max_score`.\n\n## Development\nFork the repository, pick one of the issues at the [issues](https://github.com/BorjaEst/gevopy/issues)\nand create a [Pull request](https://github.com/BorjaEst/gevopy/pulls).\n\n\n## FAQ and Notes\n\n### Why Graph Database?\nStoring relationships at the record level makes sense in genotype \nrelationships as it provides index-free adjacency.\nGraph traversal operations such 'genealogy tree' or certain matches can\nbe performed with no index lookups leading to much better performance.\n\n### Why pydantic instead of dataclass?\nPydantic supports validation of fields during and after the\ninitialization process and makes parsing easier. \nParsing is a relevant step if you are planing to save your\nphenotypes into the connected database.\n\n### Limitations\nCollections containing collections can not be stored in properties.\nProperty values can only be of primitive types or arrays in Neo4J Cypher queries.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborjaest%2Fgevopy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborjaest%2Fgevopy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborjaest%2Fgevopy/lists"}