Performant evolutionary algorithms for Python.
Project description
🧬 Ruck
Performant evolutionary algorithms for Python
Visit the docs for more info, or browse the releases.
Contributions are welcome!
Goals
Ruck aims to fill the following criteria:
- Provide high quality, readable implementations of algorithms.
- Be easily extensible and debuggable.
- Performant while maintaining its simplicity.
Citing Ruck
Please use the following citation if you use Ruck in your research:
@Misc{Michlo2021Ruck,
author = {Nathan Juraj Michlo},
title = {Ruck - Performant evolutionary algorithms for Python},
howpublished = {Github},
year = {2021},
url = {https://github.com/nmichlo/ruck}
}
Overview
Ruck takes inspiration from PyTorch Lightning's module system. The population creation,
offspring, evaluation and selection steps are all contained within a single module inheriting
from EaModule
. While the training logic and components are separated into its own class.
Members
of a Population
(A list of Members) are intended to be read-only. Modifications should not
be made to members, instead new members should be created with the modified values. This enables us to
easily implement efficient multi-threading, see below!
The trainer automatically constructs HallOfFame
and LogBook
objects which keep track of your
population and offspring. EaModule
provides defaults for get_stats_groups
that can be overridden
if you wish to customize the tracked statistics.
Minimal OneMax Example
import random
import numpy as np
from ruck import *
class OneMaxMinimalModule(EaModule):
"""
Minimal onemax example
- The goal is to flip all the bits of a boolean array to True
- Offspring are generated as bit flipped versions of the previous population
- Selection tournament is performed between the previous population and the offspring
"""
# evaluate unevaluated members according to their values
def evaluate_values(self, values):
return [v.sum() for v in values]
# generate 300 random members of size 100 with 50% bits flipped
def gen_starting_values(self):
return [np.random.random(100) < 0.5 for _ in range(300)]
# randomly flip 5% of the bits of each each member in the population
# the previous population members should never be modified
def generate_offspring(self, population):
return [Member(m.value ^ (np.random.random(m.value.shape) < 0.05)) for m in population]
# selection tournament between population and offspring
def select_population(self, population, offspring):
combined = population + offspring
return [max(random.sample(combined, k=3), key=lambda m: m.fitness) for _ in range(len(population))]
if __name__ == '__main__':
# create and train the population
module = OneMaxMinimalModule()
pop, logbook, halloffame = Trainer(generations=100, progress=True).fit(module)
print('initial stats:', logbook[0])
print('final stats:', logbook[-1])
print('best member:', halloffame.members[0])
Advanced OneMax Example
Ruck provides various helper functions and implementations of evolutionary algorithms for convenience. The following example makes use of these additional features so that components and behaviour can easily be swapped out.
The three basic evolutionary algorithms provided are based around deap's
default algorithms from deap.algorithms
: eaSimple
, eaMuPlusLambda
, and eaMuCommaLambda
. These
algorithms can be accessed from ruck.functional
which has the alias R
: R.factory_simple_ea
,
R.factory_mu_plus_lambda
and R.factory_mu_comma_lambda
.
Code Example
"""
OneMax serial example based on:
https://github.com/DEAP/deap/blob/master/examples/ga/onemax_numpy.py
"""
import functools
import numpy as np
from ruck import *
class OneMaxModule(EaModule):
def __init__(
self,
population_size: int = 300,
member_size: int = 100,
p_mate: float = 0.5,
p_mutate: float = 0.5,
):
# save the arguments to the .hparams property. values are taken from the
# local scope so modifications can be captured if the call to this is delayed.
self.save_hyperparameters()
# implement the required functions for `EaModule`
self.generate_offspring, self.select_population = R.factory_simple_ea(
mate_fn=R.mate_crossover_1d,
mutate_fn=functools.partial(R.mutate_flip_bit_groups, p=0.05),
select_fn=functools.partial(R.select_tournament, k=3),
p_mate=self.hparams.p_mate,
p_mutate=self.hparams.p_mutate,
)
def evaluate_values(self, values):
return map(np.sum, values)
def gen_starting_values(self) -> Population:
return [
np.random.random(self.hparams.member_size) < 0.5
for i in range(self.hparams.population_size)
]
if __name__ == '__main__':
# create and train the population
module = OneMaxModule(population_size=300, member_size=100)
pop, logbook, halloffame = Trainer(generations=40, progress=True).fit(module)
print('initial stats:', logbook[0])
print('final stats:', logbook[-1])
print('best member:', halloffame.members[0])
Multithreading OneMax Example (Ray)
If we need to scale up the computational requirements, for example requiring increased member and population sizes, the above serial implementations will soon run into performance problems.
The basic Ruck implementations of various evolutionary algorithms are designed around a map
function that can be swapped out to add multi-threading support. We can easily do this using
ray and we even provide various helper functions that
enhance ray support.
-
We begin by placing member's values into shared memory using ray's read-only object store and the
ray.put
function. These ObjectRef's values point to the originalnp.ndarray
values. When retrieved withray.get
they obtain the original arrays using an efficient zero-copy procedure. This is advantageous over something like Python's multiprocessing module which uses expensive pickle operations to pass data around. -
The second step is to swap out the aforementioned
map
function in the previous example to a multiprocessing equivalent. We provide theray_map
function that can be used instead, which automatically wraps functions usingray.remote
, and provides additional benefits when usingObjectRef
s. -
Finally we need to update our
mate
andmutate
functions to handleObjectRef
s, we provide a convenient wrapper to automatically callray.get
on function arguments andray.out
on function results so that you can re-use your existing code.
Code Example
"""
OneMax parallel example using ray's object store.
8 bytes * 1_000_000 * 128 members ~= 128 MB of memory to store this population.
This is quite a bit of processing that needs to happen! But using ray
and its object store we can do this efficiently!
"""
from functools import partial
import numpy as np
import ray
from ruck import *
from ruck.util import *
class OneMaxRayModule(EaModule):
def __init__(
self,
population_size: int = 300,
member_size: int = 100,
p_mate: float = 0.5,
p_mutate: float = 0.5,
):
self.save_hyperparameters()
# implement the required functions for `EaModule`
# - decorate the functions with `ray_refs_wrapper` which
# automatically `ray.get` arguments and `ray.put` returned results
self.generate_offspring, self.select_population = R.factory_simple_ea(
mate_fn=ray_refs_wrapper(R.mate_crossover_1d, iter_results=True),
mutate_fn=ray_refs_wrapper(partial(R.mutate_flip_bit_groups, p=0.05)),
select_fn=partial(R.select_tournament, k=3), # OK to compute locally, because we only look at the fitness
p_mate=self.hparams.p_mate,
p_mutate=self.hparams.p_mutate,
map_fn=ray_map, # specify the map function to enable multiprocessing
)
def evaluate_values(self, values):
# values is a list of `ray.ObjectRef`s not `np.ndarray`s
# ray_map automatically converts np.sum to a `ray.remote` function which
# automatically handles `ray.get`ing of `ray.ObjectRef`s passed as arguments
return ray_map(np.sum, values)
def gen_starting_values(self):
# generate objects and place in ray's object store
return [
ray.put(np.random.random(self.hparams.member_size) < 0.5)
for i in range(self.hparams.population_size)
]
if __name__ == '__main__':
# initialize ray to use the specified system resources
ray.init()
# create and train the population
module = OneMaxRayModule(population_size=128, member_size=1_000_000)
pop, logbook, halloffame = Trainer(generations=100, progress=True).fit(module)
print('initial stats:', logbook[0])
print('final stats:', logbook[-1])
print('best member:', halloffame.members[0])
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ruck-0.0.1.dev1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 93bcce4af87aa6b551fb7361ce63cc5eebc19047a2bc7f690419a9f449aa67c5 |
|
MD5 | 2bbf42dc9adf61df150a57fdc3d6e241 |
|
BLAKE2b-256 | c9c29ec3448b4e5b886427d7367bf111eafb10a25daf2bfa8f7d910dea4619b9 |