{"id":28265137,"url":"https://github.com/tin-cat/evolutive","last_synced_at":"2026-07-18T22:34:31.459Z","repository":{"id":90149919,"uuid":"115509504","full_name":"tin-cat/evolutive","owner":"tin-cat","description":"A library to implement simple evolutive, genetics-based machine learning algorithms","archived":false,"fork":false,"pushed_at":"2021-11-17T05:30:42.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-12T11:35:17.593Z","etag":null,"topics":["artificial-intelligence","artificial-intelligence-algorithms","evolution","evolution-simulation","evolutionary-algorithms"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tin-cat.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-12-27T10:22:24.000Z","updated_at":"2021-11-17T05:30:45.000Z","dependencies_parsed_at":"2024-05-12T01:01:10.465Z","dependency_job_id":null,"html_url":"https://github.com/tin-cat/evolutive","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tin-cat/evolutive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tin-cat%2Fevolutive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tin-cat%2Fevolutive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tin-cat%2Fevolutive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tin-cat%2Fevolutive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tin-cat","download_url":"https://codeload.github.com/tin-cat/evolutive/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tin-cat%2Fevolutive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35633896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["artificial-intelligence","artificial-intelligence-algorithms","evolution","evolution-simulation","evolutionary-algorithms"],"created_at":"2025-05-20T10:13:20.077Z","updated_at":"2026-07-18T22:34:31.446Z","avatar_url":"https://github.com/tin-cat.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evolutive\nA library to learn about evolutive, genetics-based machine learning algorithms and object-oriented programming by [Tin.cat](https://tin.cat).\n\n## The entities\nEvolutive is built upon the following classes that represent the main entities that take part in the mechanism:\n- **Nursery** Performs all the breeding of Specimens, simulating an evolutive process.\n- **Breed** Represents a group of Specimens that have been breed from an original Dna.\n- **Specimen** Represents a unique Specimen with a specific Dna.\n- **Dna** Represents all the differential characteristics of the Specimen it belongs to. It holds Genes.\n- **Gene** Represents one characteristic of a Specimen. It holds a Mutagen.\n- **Mutagen** Represents the external influence that causes Specimens to be different from each other by mutating a gene. Mutagens change Genes in a specific way (an offset) each time the Gene is mutated (mutation occurs each time a Specimen is breeded). The simulated evolutive process tries to keep Mutagens that are known to cause better fitness, and mutates Mutagens that are less fitted.\n\n## The process\n1. **The zero specimen** A first specimen is created that will be used as the starting point for breeding.\n2. **Generation breeding** Generations of specimens are breed one at a time, using the best fitted Specimen from the previous generation as the base Specimen for the next one. For the first generation, the zero specimen is used as the base Specimen.\n3. **Evolution at work** Each Specimen in a generation is a mutation from the generation's base Specimen. If the best fitted Specimen from a given generation is less fitted than the previous generation's, the entire generation is discarded and breed again. This only can happen an specific maximum number of times.\n4. **Mutagen** Mutagens mutate Genes in a specific way. When a Mutagen is altered, the Gene will be mutated in a randomly different way (to generate diversity). An unaltered Mutagen will mutate the Gene in the same way (to keep Mutagens that are believed to produce better fitted Specimens). Mutagens are altered for each new breeded Specimen.\n\n## How to use\nLet's consider the example provided in examples/findSummands.php, where we want to code an evolutive algorithm that finds the two numbers which, when added, give a specific result:\n1. First, create a class for your specimen extended from the provided Evolutive\\Specimen class, like so:\n```php\nclass FindSummandsSpecimen extends Evolutive\\Specimen {\n\tpublic $desiredResult = 10;\n\tprivate $result;\n}\n```\n\u003e In our example, since our purpose is to find two numbers that give a specific result when added, we setup this desired result as the $desiredResult class property. We also add a $result property that will hold this Specimen's specific solution to the problem.\n2. Specify the DNA structure of your Specimens by assigning the baseDna property in the class constructor. Use the Evolutive\\Dna class to do it, and don't forget to call the parent's constructor afterwards, like so:\n```php\nclass FindSummandsSpecimen extends Evolutive\\Specimen {\n\tpublic $desiredResult = 10;\n\tprivate $result;\n\n\tpublic function FindSummandsSpecimen($dna = false) {\n\t\t$this-\u003ebaseDna = new Evolutive\\Dna();\n\t\tparent::Specimen($dna);\n\t}\n}\n```\n3. Setup the Genes for your base Dna passing a hash array of Evolutive\\Gene objects to the Evolutive\\Dna constructor, use the keys of the array to assign each Gene a name:\n```php\nclass FindSummandsSpecimen extends Evolutive\\Specimen {\n\tpublic $desiredResult = 10;\n\tprivate $result;\n\n\tpublic function FindSummandsSpecimen($dna = false) {\n\t\t$this-\u003ebaseDna = new Evolutive\\Dna([\n\t\t\t\"summandA\" =\u003e new Evolutive\\Gene(),\n\t\t\t\"summandB\" =\u003e new Evolutive\\Gene(),\n\t\t]);\n\t\tparent::Specimen($dna);\n\t}\n}\n```\n\u003e In our example, since we want to find two numbers, we consider each number to be a Gene in our Specimen, but this is only one way of approaching this specific problem.\n\n\u003e Note that Genes can take two optional arguments that represent the minimum and maximum numeric value that the specific Gene can take. This might come in handy when you need Gene values to represent a discrete indicators, that is: Genes that can only take a value within certain limits.\n\n4. Each Specimen must have some function that represents its reason of being. In our example, that would be the function that adds up the two summands and stores the result. We must implement that function by creating a run() method in our Specimen:\n```php\nclass FindSummandsSpecimen extends Evolutive\\Specimen {\n\tpublic $desiredResult = 10;\n\tprivate $result;\n\n\tpublic function FindSummandsSpecimen($dna = false) {\n\t\t$this-\u003ebaseDna = new Evolutive\\Dna([\n\t\t\t\"summandA\" =\u003e new Evolutive\\Gene(),\n\t\t\t\"summandB\" =\u003e new Evolutive\\Gene(),\n\t\t]);\n\t\tparent::Specimen($dna);\n\t}\n\n\tpublic function run($parameters) {\n\t\t$this-\u003eresult = $this-\u003egetDna()-\u003egetGene(\"summandA\")-\u003egetValue() + $this-\u003egetDna()-\u003egetGene(\"summandB\")-\u003egetValue();\n\t}\n}\n```\n\u003e The run method can accept an array of parameters to perform its calculations. This parameters are passed when calling Nursery::evolve, although we don't need them for our example.\n5. To finalize our Specimen, we need to implement the getFitness method, which must return a value representing how much fitted is this Specimen, where bigger numbers represent better fitted Specimens. We do this like so:\n```php\nclass FindSummandsSpecimen extends Evolutive\\Specimen {\n\tpublic $desiredResult = 10;\n\tprivate $result;\n\n\tpublic function FindSummandsSpecimen($dna = false) {\n\t\t$this-\u003ebaseDna = new Evolutive\\Dna([\n\t\t\t\"summandA\" =\u003e new Evolutive\\Gene(),\n\t\t\t\"summandB\" =\u003e new Evolutive\\Gene(),\n\t\t]);\n\t\tparent::Specimen($dna);\n\t}\n\n\tpublic function run($parameters) {\n\t\t$this-\u003eresult = $this-\u003egetDna()-\u003egetGene(\"summandA\")-\u003egetValue() + $this-\u003egetDna()-\u003egetGene(\"summandB\")-\u003egetValue();\n\t}\n\n\tpublic function getFitness() {\n\t\tif ($this-\u003edesiredResult \u003e $this-\u003eresult)\n\t\t\t$delta = $this-\u003edesiredResult - $this-\u003eresult;\n\t\telse\n\t\t\t$delta = $this-\u003eresult - $this-\u003edesiredResult;\n\t\treturn $this-\u003edesiredResult - $delta;\n\t}\n}\n```\n\u003e In our case, we could say that a better Specimen is the one that has discovered the best approximation to the desired sum result. Thus, in our getFitness method we return a value that represents how close this Specimen was to the desired result (not the difference between the specimen's result and the desired result, but its inverse, since higher values represent better fitness)\n\u003e The returned fitness values can be in any range and scale, as long as better fitness is represented with higher values.\n6. Lastly, we make use of the Evolutive\\Nursery class to run the evolutive process, like so:\n```php\n$nursery = new Evolutive\\Nursery;\n$specimen = $nursery-\u003eevolve([\n\t\"isDebug\" =\u003e true,\n\t\"specimenClassName\" =\u003e \"FindSummandsSpecimen\",\n\t\"specimensPerGeneration\" =\u003e 10,\n\t\"generations\" =\u003e 1000,\n\t\"maxAttemptsPerGeneration\" =\u003e 10\n]);\n```\n\u003e The returned $specimen will be an evolved Specimen that has hopefully reached a great ability to solve our problem.\n\nWhen calling Evolutive\\Nursery::evolve, these are the parameters:\n- **isDebug** Outputs information about the whole process to the standard output.\n- **specimenClassName** The name of the class of your Specimen.\n- **specimensPerGeneration** The number of Specimens that will be breed for each generation.\n- **generations** The number of generations that will be breed.\n- **maxAttemptsPerGeneration** When a generation is less fitted than the previous one, it will be breed again to try to find a best fitted one this many maximum times.\n\n## Final considerations\nTake into account that evolutive genetic machine-learning algorithms are not suited to find specific results like the two summands of our example, as it will almost always find only approximate results. In that example, even with a really high number of iterations, you'll never reach the certainty of always obtaining a precise result. (A simple try-and-guess recursion algorithm might be far more effective)\n\nIt is up to you to find meaningful or fun applications for this kind of algorithms. What about using a genetic evolutive algorithm to determine whether to buy or sell stocks at a given time?","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftin-cat%2Fevolutive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftin-cat%2Fevolutive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftin-cat%2Fevolutive/lists"}