Full Documentation¶
Subpackages¶
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)[source]¶ 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)[source]¶ 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={})[source]¶ Bases:
object
A basic organism structure for all species.
-
act
(population_dict, world, position_hash_table=None)[source]¶ 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)[source]¶ Makes a new Organism object identical to the current one.
Parameters: organism (Organism) – Organism to copy. Returns: new_organism – Copied organism. Return type: Organism
-
die
(cause, in_place=False, original=None)[source]¶ 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:
-
drink
(population_dict, world, position_hash_table=None)[source]¶ 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)[source]¶ 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)[source]¶ 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
-
is_at_death
(cause)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ Steps through one time step without acting for this organism.
Returns: Note that this returns an Organism object, not a list. Return type: organism
-
update_parameter
(parameter, value, method='set', in_place=False, original=None)[source]¶ 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:
-
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)[source]¶ 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=[])[source]¶ 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)[source]¶ 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)[source]¶ 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={})[source]¶ 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:
blossom.parse_intent module¶
-
blossom.parse_intent.
parse
(intent_list, population_dict)[source]¶ 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)[source]¶ Bases:
object
Create the universe of the simulation.
-
initialize
()[source]¶ 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.
-
blossom.world module¶
blossom.world_generator module¶
Module contents¶
blossom is a package for simulating evolution