{"id":26947293,"url":"https://github.com/r8vnhill/keen","last_synced_at":"2025-04-02T20:18:57.779Z","repository":{"id":62942425,"uuid":"336524963","full_name":"r8vnhill/keen","owner":"r8vnhill","description":"Keen is a Kotlin genetic algorithms' framework","archived":false,"fork":false,"pushed_at":"2025-03-11T01:53:17.000Z","size":5392,"stargazers_count":18,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-11T02:34:21.329Z","etag":null,"topics":["evolutionary-algorithms","evolutionary-computation","genetic-algorithms","kotlin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r8vnhill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2021-02-06T11:46:48.000Z","updated_at":"2024-07-12T18:06:52.000Z","dependencies_parsed_at":"2023-10-11T19:09:56.810Z","dependency_job_id":"2a544fdf-e2d1-4848-bd8e-a429e5aaf6bf","html_url":"https://github.com/r8vnhill/keen","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r8vnhill%2Fkeen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r8vnhill%2Fkeen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r8vnhill%2Fkeen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r8vnhill%2Fkeen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r8vnhill","download_url":"https://codeload.github.com/r8vnhill/keen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246884760,"owners_count":20849554,"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","evolutionary-computation","genetic-algorithms","kotlin"],"created_at":"2025-04-02T20:18:57.169Z","updated_at":"2025-04-02T20:18:57.769Z","avatar_url":"https://github.com/r8vnhill.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keen | Kotlin Evolutionary Computation Framework\n\n[![Maven Central](https://img.shields.io/maven-central/v/cl.ravenhill/keen-core.svg)](https://search.maven.org/artifact/cl.ravenhill/keen-core)\n[![License](https://img.shields.io/badge/License-BSD_2--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause)\n\n![Keen logo](logos/TransparentBg.png)\n\nKeen is a framework for Kotlin that leverages evolutionary algorithms to solve optimization problems.\nIt harnesses the power and expressiveness of Kotlin to provide an intuitive and efficient interface for researchers,\nscientists, and developers alike.\nWith Keen, you can build and fine-tune complex evolutionary algorithms with just a few lines of code.\n\nWhether you are delving into genetic algorithms for the first time or are an experienced researcher looking for a \nKotlin-native tool, Keen offers a streamlined experience without sacrificing depth or flexibility. Its modular\narchitecture means you can easily extend or modify components, from selection and crossover methods to mutation and \nfitness evaluation.\n\n## Table of Contents\n\n- [Installation](#installation)\n  - [Gradle Kotlin DSL Setup](#gradle-kotlin-dsl-setup)\n    - [Step 1: Specify Versions in `gradle.properties`](#step-1-specify-versions-in-gradleproperties)\n    - [Step 2: Configure Plugin Management in `settings.gradle.kts`](#step-2-configure-plugin-management-in-settingsgradlekts)\n    - [Step 3: Configure Project Plugins, Repositories, and Dependencies](#step-3-configure-project-plugins-repositories-and-dependencies)\n  - [Additional Notes](#additional-notes)\n- [Examples](#examples)\n  - [One Max (Ones Counting) Problem](#one-max-ones-counting-problem)\n    - [Implementation](#implementation)\n    - [Output](#output)\n- [Acknowledgements](#acknowledgements)\n\n## Installation\n\nThis section guides you through the process of setting up the Keen framework and the EvolutionPlotter in your Kotlin \nproject using Gradle Kotlin DSL.\n\n### Gradle Kotlin DSL Setup\n\n#### Step 1: Specify Versions in `gradle.properties`\nFirst, define the versions of Keen and Compose in your `gradle.properties` file. Make sure to replace these with the \nlatest versions available.\n\n```\n# gradle.properties\n# Keen framework version. Replace with the latest version.\nkeen.version=1.1.0\n# Compose version for the EvolutionPlotter. Replace at your discretion.\ncompose.version=1.5.11\n```\n\n#### Step 2: Configure Plugin Management in `settings.gradle.kts`\nThis step is essential only if you plan to use the EvolutionPlotter. Here, you configure the plugin management for the\nCompose plugin.\n\n```kotlin\n// settings.gradle.kts\npluginManagement {\n    repositories {\n        gradlePluginPortal()  // Standard Gradle plugin repository.\n        maven(\"https://maven.pkg.jetbrains.space/public/p/compose/dev\")  // Repository for JetBrains Compose.\n        google()  // Google's Maven repository, sometimes needed for dependencies.\n    }\n\n    plugins {\n        id(\"org.jetbrains.compose\") version extra[\"compose.version\"] as String  // Apply the Compose plugin with the specified version.\n    }\n}\n```\n\n#### Step 3: Configure Project Plugins, Repositories, and Dependencies\nIn your build script, configure the necessary plugins, repositories, and dependencies.\n\n```kotlin\nval keenVersion: String = extra[\"keen.version\"] as String  // Retrieve the Keen version defined earlier.\n\nplugins {\n    /* ... */\n    id(\"org.jetbrains.compose\") // Include this only if using the EvolutionPlotter.\n}\n\nrepositories {\n    mavenCentral()  // Maven Central repository for most dependencies.\n    /* ... */\n}\n\ndependencies {\n    implementation(\"cl.ravenhill:keen-core:$keenVersion\")  // Keen core library dependency.\n    implementation(compose.desktop.currentOs)   // Compose dependency, required for the EvolutionPlotter.\n    /* ... */\n}\n```\n\n### Additional Notes:\n- Ensure that the versions specified in `gradle.properties` are compatible with your project setup.\n- The `pluginManagement` block in `settings.gradle.kts` is crucial for resolving the Compose plugin, especially if \n  you're using features like the EvolutionPlotter.\n- Remember to sync your Gradle project after making changes to these files to apply the configurations.\n\n## Examples\n\nThe following examples only have the explanation of what's the problem to solve.\nYou can find the explanations of the code in the [manual](https://ravenhill.pages.dev/keen/manual) (WIP).\n\n### One Max (Ones Counting) Problem\n\nThe _One Max_ problem is a well known problem widely used to exemplify the genetic algorithms'\ncapabilities.\nThe problem consists of maximizing the number of ones in a bit string.\nThe following example shows how to solve the _One Max_ problem with _Keen_.\n\n#### Implementation\n\n```kotlin\nimport cl.ravenhill.keen.ExperimentalKeen\nimport cl.ravenhill.keen.dsl.booleans\nimport cl.ravenhill.keen.dsl.chromosomeOf\nimport cl.ravenhill.keen.dsl.evolutionEngine\nimport cl.ravenhill.keen.dsl.genotypeOf\nimport cl.ravenhill.keen.genetic.Genotype\nimport cl.ravenhill.keen.genetic.genes.BooleanGene\nimport cl.ravenhill.keen.limits.MaxGenerations\nimport cl.ravenhill.keen.limits.TargetFitness\nimport cl.ravenhill.keen.listeners.plotter.EvolutionPlotter\nimport cl.ravenhill.keen.listeners.summary.EvolutionSummary\nimport cl.ravenhill.keen.operators.alteration.crossover.SinglePointCrossover\nimport cl.ravenhill.keen.operators.alteration.crossover.UniformCrossover\nimport cl.ravenhill.keen.operators.alteration.mutation.BitFlipMutator\nimport cl.ravenhill.keen.operators.selection.RouletteWheelSelector\nimport cl.ravenhill.keen.operators.selection.TournamentSelector\n\nprivate fun count(genotype: Genotype\u003cBoolean, BooleanGene\u003e) = genotype.flatten().count { it }.toDouble()\n\nfun main() {\n  val engine = evolutionEngine(::count, genotypeOf {\n    chromosomeOf {\n      booleans {\n        size = 50\n        trueRate = 0.15\n      }\n    }\n  }) {\n    populationSize = 500\n    parentSelector = RouletteWheelSelector()\n    survivorSelector = TournamentSelector()\n    alterers += listOf(BitFlipMutator(individualRate = 0.5), UniformCrossover(chromosomeRate = 0.6))\n    limits += listOf(MaxGenerations(500), TargetFitness(TARGET_FITNESS))\n    listeners += listOf(EvolutionSummary(), EvolutionPlotter())\n  }\n  engine.evolve()\n  engine.listeners.forEach { it.display() }\n}\n\n```\n\n#### Output\n\n```text\n------------ Evolution Summary ---------------\n|--\u003e Initialization time: 16 ms\n------------- Evaluation Times ----------------\n|--\u003e Average: 0.23076923076923078 ms\n|--\u003e Max: 1 ms\n|--\u003e Min: 0 ms\n-------------- Selection Times ----------------\n|   |--\u003e Offspring Selection\n|   |   |--\u003e Average: 0.6153846153846154 ms\n|   |   |--\u003e Max: 8 ms\n|   |   |--\u003e Min: 0 ms\n|   |--\u003e Survivor Selection\n|   |   |--\u003e Average: 0.0 ms\n|   |   |--\u003e Max: 0 ms\n|   |   |--\u003e Min: 0 ms\n--------------- Alteration Times --------------\n|--\u003e Average: 3.3846153846153846 ms\n|--\u003e Max: 19 ms\n|--\u003e Min: 1 ms\n-------------- Evolution Results --------------\n|--\u003e Total time: 113 ms\n|--\u003e Average generation time: 7.3076923076923075 ms\n|--\u003e Max generation time: 57 ms\n|--\u003e Min generation time: 2 ms\n|--\u003e Generation: 13\n|--\u003e Steady generations: 0\n|--\u003e Fittest: [1111 1111 1111 1111 1111]\n|--\u003e Best fitness: 20.0\n```\n\n![One Max Fitness Plot](docs/onemax.png)\n\n## Acknowledgements\n\nThis project has benefited from the support provided by JetBrains. We're immensely grateful for their backing.\n\n\u003cdiv style=\"text-align: center;\"\u003e\n\u003cimg src=\"https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png\" alt=\"JetBrains Logo (Main) logo.\" width=\"100\"\u003e\n\u003c/div\u003e\n\nA big thank you to [JetBrains](https://jb.gg/OpenSourceSupport) for their open-source support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr8vnhill%2Fkeen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr8vnhill%2Fkeen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr8vnhill%2Fkeen/lists"}