core package

Submodules

core.foodweb module

class core.foodweb.FoodWeb(filepath)

Bases: object

A class to represent and query an ecological food web based on a JSON file.

__init__(filepath)

Initialize the FoodWeb by loading data from a JSON file.

Parameters: filepath (str): Path to the JSON file containing organisms and predation data.

get_prey(predator)

Get the list of prey species for a given predator.

Parameters: predator (str): Name of the predator species.

Returns: list: List of prey species names.

get_predators(species)

Get the list of predators for a given species.

Parameters: species (str): Name of the species to check for predators.

Returns: list: List of predator species names.

is_prey(predator, prey)

Check if a species is prey to a given predator.

Parameters: predator (str): Name of the predator. prey (str): Name of the prey.

Returns: bool: True if prey is in the predator’s prey list, False otherwise.

is_predator(prey, predator)

Check if a species is a predator to a given prey.

Parameters: prey (str): Name of the prey. predator (str): Name of the predator.

Returns: bool: True if predator preys on the given species, False otherwise.

all_species()

Get a list of all species in the food web.

Returns: list: List of species names.

get_type(species)

Get the type (e.g. producer, consumer) of a species.

Parameters: species (str): Name of the species.

Returns: str: Type of the species, or ‘Unknown’ if not specified.

get_trophic_level(species)

Get the trophic level of a species.

Parameters: species (str): Name of the species.

Returns: str: Trophic level of the species, or ‘unknown’ if not specified.

get_color(species)

Get the display color associated with a species.

Parameters: species (str): Name of the species.

Returns: str: Hex color code, or ‘#000000’ (black) if not specified.

get_decomposition_rate(species)

Get the decomposition rate of a species.

Parameters: species (str): Name of the species.

Returns: int: Decomposition rate, or 20 if not specified.

core.organism module

class core.organism.Organism(species_name, x, y, energy=100, max_energy=120)

Bases: object

Base class representing a general organism in the ecosystem simulation.

species

The name of the species.

Type:

str

x

X-coordinate on the grid.

Type:

int

y

Y-coordinate on the grid.

Type:

int

energy

Current energy level of the organism.

Type:

int

max_energy

Maximum energy the organism can have.

Type:

int

alive

Indicates whether the organism is alive.

Type:

bool

__init__(species_name, x, y, energy=100, max_energy=120)

Initializes an Organism instance with a species name, coordinates, and energy levels.

Parameters:

• species_name (str) – The species name.

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

• energy (int, optional) – Starting energy. Defaults to 100.

• max_energy (int, optional) – Maximum energy. Defaults to 120.

step(grid_size)

Simulates one time step for the organism, reducing its energy. If energy reaches zero or below, the organism dies.

Parameters:

grid_size (int) – Size of the simulation grid (unused here).

class core.organism.Producer(species_name, x, y)

Bases: Organism

Represents plant-like entities in the ecosystem that do not move.

is_edible

Whether the producer can be consumed by other organisms.

Type:

bool

__init__(species_name, x, y)

Initializes a Producer at a given location with default energy.

Parameters:

• species_name (str) – The species name.

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

step(grid_size)

Defines the behavior of the producer in each time step. Producers do not perform actions, so this is a no-op.

Parameters:

grid_size (int) – Size of the simulation grid (unused).

class core.organism.Consumer(species_name, x, y, trophic_level='primary', speed=1)

Bases: Organism

Represents mobile, decision-making animal entities in the ecosystem.

trophic_level

The trophic level (e.g., ‘primary’, ‘secondary’).

Type:

str

speed

Maximum number of grid cells the consumer can move per step.

Type:

int

__init__(species_name, x, y, trophic_level='primary', speed=1)

Initializes a Consumer with position, energy, and behavior attributes.

Parameters:

• species_name (str) – The species name.

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

• trophic_level (str, optional) – Trophic level. Defaults to ‘primary’.

• speed (int, optional) – Movement speed. Defaults to 1.

move(grid_size)

Moves the consumer randomly within the bounds of the grid.

Parameters:

grid_size (int) – Size of the simulation grid.

step(grid_size, others, foodweb, behavior, terrain=None)

Executes one simulation step where the consumer may perform: - fleeing from threats - chasing prey - attempting to eat - moving randomly

Parameters:

• grid_size (int) – Size of the grid.

• others (list) – Other organisms in the environment.

• foodweb (FoodWeb) – Object representing food chain relationships.

• behavior (module) – Module containing decision-making logic.

• terrain (optional) – Grid terrain, possibly affecting movement.

core.terrain module

class core.terrain.Terrain(grid_size)

Bases: object

Represents the terrain grid used in the ecosystem simulation, including terrain types and their effects.

grid_size

The size of the square simulation grid.

Type:

int

map

A mapping of (x, y) positions to terrain types.

Type:

defaultdict

shelter_occupants

Tracks the occupancy of shelters by organisms.

Type:

dict

water_counters

Tracks energy boosts from water for individual organisms.

Type:

defaultdict

__init__(grid_size)

Initializes the terrain grid with default terrain type “plain”.

Parameters:

grid_size (int) – Size of the simulation grid.

load_from_config(config_path)

Loads terrain layout from a configuration file. Supports ‘random’ or ‘manual’ terrain placement.

Parameters:

config_path (str) – Path to the JSON configuration file.

generate_water()

Generates water patches randomly across the terrain.

generate_trees()

Randomly places individual trees throughout the grid.

generate_hills()

Generates small clusters of ‘hill’ terrain types.

generate_shelters()

Randomly places multiple ‘shelter’ locations on the terrain.

get_type(x, y)

Returns the terrain type at a given coordinate.

Parameters:

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

Returns:

Terrain type at the specified location.

Return type:

str

is_blocked(x, y)

Checks if a tile is blocked due to a tree.

Parameters:

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

Returns:

True if tile contains a tree.

Return type:

bool

is_shelter(x, y)

Checks if a tile is a shelter.

Parameters:

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

Returns:

True if tile is a shelter.

Return type:

bool

is_in_shelter(x, y)

Alias for is_shelter() for compatibility.

Returns:

True if the position is a shelter.

Return type:

bool

is_hill(x, y)

Checks if a tile is a hill.

Parameters:

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

Returns:

True if tile is a hill.

Return type:

bool

is_water(x, y)

Checks if a tile is water.

Parameters:

• x (int) – X-coordinate.

• y (int) – Y-coordinate.

Returns:

True if tile is water.

Return type:

bool

apply_terrain_effects(org, step_counter)

Applies terrain-based effects to an organism, such as energy gain near water.

Parameters:

• org (Organism) – The organism affected.

• step_counter (int) – Current simulation step counter.

update_shelters(organisms)

Updates organism interactions with shelter tiles. Carnivores are pushed out, while herbivores gain temporary protection or die if they stay too long.

Parameters:

organisms (list) – List of organisms to update.

can_enter_shelter(org)

Checks if a given organism is allowed to enter the current shelter tile.

Parameters:

org (Organism) – The organism to check.

Returns:

True if organism is a primary consumer in a shelter.

Return type:

bool

Module contents