Welcome to blossom’s documentation!

blossom is a Python package for producing simulations of evolving organisms.

Table of Contents

Installation

You can use pip to install the latest version of the package automatically:

pip install blossom

Alternately, execute:

git clone git@github.com:blossom-evolution/blossom.git
python setup.py install

Cookbook

Full Documentation

Subpackages

blossom.organism_behavior package

Submodules

blossom.organism_behavior.action module

blossom.organism_behavior.action.move_and_drink(organism, population_dict, world, position_hash_table=None)

Move and drink. Each occurs with probability 1/2.

blossom.organism_behavior.action.move_and_reproduce(organism, population_dict, world, position_hash_table=None)

Move and reproduce. Reproduction occurs with probability 1/8.

blossom.organism_behavior.action.move_only(organism, population_dict, world, position_hash_table=None)

Only move.

blossom.organism_behavior.action.move_reproduce_drink(organism, population_dict, world, position_hash_table=None)

Move, drink, and reproduce. Reproduction occurs with probability 1/8. Drinks with probability 3/8, and moves with probability 1/2.

blossom.organism_behavior.drinking module

blossom.organism_behavior.drinking.constant_drink(organism, population_dict, world, position_hash_table=None)

Intake constant amount of water from world if water is present.

blossom.organism_behavior.movement module

blossom.organism_behavior.movement.simple_random(organism, population_dict, world, position_hash_table=None)

Move in random direction with equal probability. For 2D, organisms walk diagonally.

blossom.organism_behavior.movement.stationary(organism, population_dict, world, position_hash_table=None)

Organism stays still.

blossom.organism_behavior.reproduction module

blossom.organism_behavior.reproduction.pure_replication(organism, population_dict, world, position_hash_table=None)

Replace organism with two organism with similar parameters. Essentially, only differences in parameters are organism id, ancestry, age, and water / food levels.

Module contents

Built-in methods for organism behaviors.

Submodules

blossom.dataset_io module

Load information from a certain dataset, e.g. to resume a simulation, and write world and organism data back to file.

blossom.dataset_io.load_universe(fn)

Load dataset file from JSON.

Parameters:fn (str) – Input filename of saved universe dataset. Returns:

• population_dict (dict) – A dict of Organism objects reconstructed from the saved dataset.
• world (World) – World object reconstructed from the saved dataset.

blossom.dataset_io.save_universe(population_dict, world, fn)

Save population_dict and world to file in JSON format.

Parameters:

• population_dict (dict) – Dict of Organisms to write to file.
• world (World) – World attributes to write to file.
• fn (str) – Output filename of saved universe dataset.

blossom.fields module

blossom.organism module

class blossom.organism.Organism(init_dict={})

Bases: object

A basic organism structure for all species.

act(population_dict, world, position_hash_table=None)

Method that decides and calls an action for the current timestep. Searches through custom methods and built-in movement methods. The action method specifically selects an action to take, from “move”, “reproduce”, “drink”, and “eat”. Then the appropriate instance method from this class is executed to yield the final list of affect organisms.

Parameters:

• population_dict (dict of Organisms) – Dict of organisms, with which this organism may interact.
• world (World) – World, with which this organism may interact.
• position_hash_table (dict) – Dictionary mapping positions to available organisms.

Returns:

affected_organisms – Organism or list of organisms affected by this organism’s action.

Return type:

Organisms, or list of Organisms

classmethod clone(organism)

Makes a new Organism object identical to the current one.

Parameters:organism (Organism) – Organism to copy. Returns:new_organism – Copied organism. Return type:Organism

clone_self()

Clone this organism.

die(cause, in_place=False, original=None)

Method that “kills” organism.

Parameters:

• cause (str) – Cause of this organism’s death.
• in_place (bool) – If True, modifies self, otherwise, copy organism and return new Organism object.

Returns:

dead_organism – New “dead” state of this organism.

Return type:

Organism

drink(population_dict, world, position_hash_table=None)

Method for handling drinking. Searches through custom methods and built-in drinking methods.

Parameters:

• population_dict (dict of Organisms) – Dict of organisms, with which this organism may interact.
• world (World) – World, with which this organism may interact.
• position_hash_table (dict) – Dictionary mapping positions to available organisms.

Returns:

affected_organisms – Organism or list of organisms affected by this organism’s drinking.

Return type:

Organisms, or list of Organisms

eat(population_dict, world, position_hash_table=None)

Method for handling eating. Searches through custom methods and built-in eating methods.

Parameters:

• population_dict (dict of Organisms) – Dict of organisms, with which this organism may interact.
• world (World) – World, with which this organism may interact.
• position_hash_table (dict) – Dictionary mapping positions to available organisms.

Returns:

affected_organisms – Organism or list of organisms affected by this organism’s eating.

Return type:

Organisms, or list of Organisms

get_child(other_parent=None)

Creates an Organism object with similar properties to self, and can add another parent if it exists. Note that this doesn’t assume anything about how much food / water the child is left with, so these should be set with custom / default reproduction methods.

Parameters:other_parent (Organism) – Parent that reproduces with self to produce the child. Returns:child – Generated child. Return type:Organism

get_new_id()

Generates pseudo-random ID for the organism, seeded by the universe.

is_at_death(cause)

Check various conditions for death.

Parameters:cause (str) – Potential cause of this organism’s death. Returns:is_dead – Returns True if organism is dead from the specified cause, False otherwise. Return type:bool

move(population_dict, world, position_hash_table=None)

Method for handling movement. Searches through custom methods and built-in movement methods.

Parameters:

• population_dict (dict of Organisms) – Dict of organisms, with which this organism may interact.
• world (World) – World, with which this organism may interact.
• position_hash_table (dict) – Dictionary mapping positions to available organisms.

Returns:

affected_organisms – Organism or list of organisms affected by this organism’s movement.

Return type:

Organisms, or list of Organisms

reproduce(population_dict, world, position_hash_table=None)

Method for handling reproduction. Searches through custom methods and built-in reproduction methods.

Parameters:

• population_dict (dict of Organisms) – Dict of organisms, with which this organism may interact.
• world (World) – World, with which this organism may interact.
• position_hash_table (dict) – Dictionary mapping positions to available organisms.

Returns:

affected_organisms – Organism or list of organisms affected by this organism’s reproduction. For example, this would include both parent and child organisms.

Return type:

Organisms, or list of Organisms

step(population_dict, world, position_hash_table=None, do_action=True)

Steps through one time step for this organism. Reflects changes based on actions / behaviors and updates to health parameters.

Returns a list of organisms that the action produced (either new or altered organisms).

Parameters:

• population_dict (dict of Organisms) – Dict of organisms, with which this organism may interact.
• world (World) – World, with which this organism may interact.
• position_hash_table (dict) – Dictionary of organisms “hashed” by position.
• do_action (bool) – If True, this organism will act, otherwise, it will not.

Returns:

affected_organisms – List of organisms affected by this organism’s actions or health. This could be an updated version of this organism, especially if the organism dies during the time step, but could also be multiple other organisms affected by actions (i.e. children from reproduction).

Return type:

list of Organisms

step_without_acting()

Steps through one time step without acting for this organism.

Returns:Note that this returns an Organism object, not a list. Return type:organism

to_dict()

Convert Organism to dict.

update_parameter(parameter, value, method='set', in_place=False, original=None)

Update a specific parameter of the organism.

Parameters:

• parameter (string) – Parameter to update.
• value – Value with which to update.
• method (string) – Method types are: ‘set’, ‘add’, ‘subtract’, ‘append’.
• in_place (bool) – If True, modifies self, otherwise, copy organism and return new Organism object.
• original (Organism or None) – Original organism we are changing. If it is the original, clone organism so that we aren’t editing the original.

Returns:

updated_organism – Organism object with updated parameter.

Return type:

Organism

blossom.parameter_io module

Load information from parameter files and construct world and organism objects at the initial timestep.

blossom.parameter_io.create_organisms(species_init_dict, init_world=<world.World object>, position_callback=None)

Make organism list from an species_init_dict either provided directly or scraped from parameter file. All organisms are from a single species.

blossom.parameter_io.load_species(fns=None, init_dicts=[{}], init_world=<world.World object>, custom_module_fns=[])

Load organisms from available species parameter files or dictionaries.

Parameters:

• fns (list of str) – Input filenames of species parameter files. Different species get different species parameter files, from which the individual organisms are initialized.
• init_dicts (list of dict) – Parameter dicts for each species.
• init_world (World) – Initial World instance for this Universe.
• custom_module_fns (list of str) – List of external Python scripts containing custom organism behaviors. blossom will search for methods within each filename included here.

Returns:

population_dict – A dict of Organism objects constructed from the parameter file.

Return type:

dict of Organisms

blossom.parameter_io.load_species_from_dict(init_dicts, init_world, custom_module_fns=None)

Create a list of organisms loaded from Python dicts.

Parameters:

• init_dicts (list of dict) – Input species dictionaries from which the individual organisms are initialized. Each dictionary is for a different species.
• init_world (World) – Initial World instance for this Universe.
• custom_module_fns (list of str) – List of external Python scripts containing custom organism behaviors. blossom will search for methods within each filename included here.

Returns:

population_dict – A dict of Organism objects constructed from the parameter file.

Return type:

dict of Organisms

blossom.parameter_io.load_species_from_param_files(fns, init_world, custom_module_fns=None)

Load all available species parameter files.

Parameters:

• fns (list of str) – Input filenames of species parameter files. Different species get different species parameter files, from which the individual organisms are initialized.
• init_world (World) – Initial World instance for this Universe.
• custom_module_fns (list of str) – List of external Python scripts containing custom organism behaviors. blossom will search for methods within each filename included here.

Returns:

population_dict – A dict of Organism objects constructed from the parameter file.

Return type:

dict of Organisms

blossom.parameter_io.load_world(fn=None, init_dict={})

Load world from either parameter file or dictionary and construct initial World object.

Parameters:

• fn (str) – Input filename of parameter file.
• init_dict (dict) – Dictionary containing world parameters.

Returns:

world – World object constructed from the parameter file.

Return type:

World

blossom.parameter_io.load_world_from_dict(init_dict)

blossom.parameter_io.load_world_from_param_file(fn)

Load world parameter file and construct initial World object.

Parameters:fn (str) – Input filename of parameter file. Returns:world – World object constructed from the parameter file. Return type:World

blossom.parse_intent module

blossom.parse_intent.parse(intent_list, population_dict)

Determine whether the intent list is valid and fix it in the event of conflicts.

Parameters:

• intent_list (list of lists of Organisms) – List of lists of organisms with proposed organism states, after each organism has ‘acted’. Length equals number of organisms in the current time step.
• population_dict (dict of Organisms) – Dict of current organisms

Returns:

• updated_population_dict (dict of Organisms) – Dict of updated organisms, where organism states that conflict between intent_list and population_dict are resolved.
• Conflicts may be cases in which an organism has different states in the
• intent list, perhaps arrising from the actions of other organisms that
• somehow effect its state. This method resolves those conflicts, so that
• there is only one organism with a given organism id present in the final
• output list at all times.

blossom.universe module

class blossom.universe.Universe(dataset_fn=None, world_param_fn=None, species_param_fns=None, world_param_dict={}, species_param_dicts=[{}], custom_module_fns=None, current_time=0, end_time=10, dataset_dir='datasets/', pad_zeros=0, file_extension='.txt', seed=None)

Bases: object

Create the universe of the simulation.

current_info(verbosity=1, expanded=True)

initialize()

Initialize world and organisms in the universe, from either saved datasets or from parameter files (and subsequently writing the initial time step to file).

Returns:

• population_dict (dict) – Dict of organisms at the beginning of the simulation.
• world (World) – World at the beginning of the simulation.

run(verbosity=1, expanded=True)

step()

Steps through one time step, iterating over all organisms and computing new organism states. Saves all organisms and the world to file at the end of each step.

blossom.utils module

Common utilities used throughout blossom

blossom.utils.cast_to_list(x)

Make a list out of the input if the input isn’t a list.

blossom.utils.time_to_string(seconds)

Convert time in seconds to the most reasonable representation.

blossom.world module

class blossom.world.World(init_dict={})

Bases: object

World class for the environment of the simulation.

step()

to_dict()

Convert World to dict.

blossom.world_generator module

blossom.world_generator.constant_2d_list(val, size)

Generate a constant-valued two dimensional array.

blossom.world_generator.constant_list(val, length)

Generate a constant-valued list.

blossom.world_generator.write_environment(water, food, obstacles, environment_fn='environment.json')

Write water, food, and obstacles lists to an environment file.

Module contents

blossom is a package for simulating evolution

Indices and tables

• Index
• Module Index
• Search Page