simulation package
Submodules
simulation.arena module
- class simulation.arena.Arena(env_variables, rng)[source]
Bases:
objectSimulated environment for fish behavior experiments.
Manages the visual environment including sediment patterns, luminance gradients, and spectral fields of view (Red and UV). It defines the spatial and lighting conditions perceived by agents during simulation.
- Parameters:
env_variables (dict) – Dictionary containing configuration parameters such as ‘arena_width’, ‘arena_height’, ‘arena_light_decay_rate’, and ‘arena_sediment_sigma’.
rng (np.random.Generator) – Random number generator for stochastic sediment pattern generation.
- test_mode
True if the arena is in sensory system testing mode (fixed patterns).
- Type:
bool
- arena_width
Width of the arena in pixels.
- Type:
int
- arena_height
Height of the arena in pixels.
- Type:
int
- bottom_intensity
Base intensity value for the sediment pattern.
- Type:
float
- dark_gain
Intensity multiplier for the dark region of the arena.
- Type:
float
- light_gradient
Width in pixels of the transition zone between dark and light regions.
- Type:
int
- dark_light_ratio
Fraction of arena height that is dark (0.0 to 1.0).
- Type:
float
- sediment_sigma
Gaussian filter sigma for smoothing the stochastic sediment patterns.
- Type:
float
- max_uv_range
Maximum range in pixels for UV field of view based on light decay.
- Type:
int
- max_red_range
Maximum range in pixels for red field of view based on viewing angle.
- Type:
int
- global_sediment_grating
The underlying sediment texture (2D array) before lighting is applied.
- Type:
np.ndarray
- global_luminance_mask
The 2D spatial mask representing light and dark regions.
- Type:
np.ndarray
- illuminated_sediment
The final visual output (sediment * luminance).
- Type:
np.ndarray
- red_FOV
Manager for the red channel spectral field of view.
- Type:
- uv_FOV
Manager for the UV channel spectral field of view.
- Type:
- get_global_luminance()[source]
Create the luminance gradient mask for the arena.
Calculates the transition between dark and light fields based on the dark_light_ratio and light_gradient width.
- Returns:
2D array mask of intensity multipliers.
- Return type:
np.ndarray
- get_global_sediment()[source]
Generate the base sediment pattern for the entire arena.
In test mode, this produces a deterministic vertical grating. In normal mode, it produces smoothed Gaussian noise.
- Returns:
2D array representing the sediment intensity across the arena.
- Return type:
np.ndarray
- get_masked_sediment()[source]
Retrieve the sediment visible within the red field of view.
- Returns:
Sliced and masked image corresponding to the red FOV.
- Return type:
np.ndarray
- class simulation.arena.FieldOfView(max_range, env_width, env_height, light_decay_rate)[source]
Bases:
objectThis class handles the calculation and management of a fish’s visual perception area, including light absorption/scattering effects based on distance. It computes the visible region around a fish’s position and applies distance-based light decay. .. attribute:: local_dim
The dimension of the local field of view (2 * max_range + 1).
- type:
int
- max_visual_distance
The maximum distance the fish can see (rounded).
- Type:
int
- env_width
The width of the environment.
- Type:
int
- env_height
The height of the environment.
- Type:
int
- light_decay_rate
The rate at which light decays with distance.
- Type:
float
- local_scatter
Precomputed light decay mask based on distance.
- Type:
np.ndarray
- full_fov_top
Top boundary of the full FOV in environment coordinates.
- Type:
int
- full_fov_bottom
Bottom boundary of the full FOV in environment coordinates.
- Type:
int
- full_fov_left
Left boundary of the full FOV in environment coordinates.
- Type:
int
- full_fov_right
Right boundary of the full FOV in environment coordinates.
- Type:
int
- local_fov_top
Top boundary in local FOV coordinates.
- Type:
int
- local_fov_bottom
Bottom boundary in local FOV coordinates.
- Type:
int
- local_fov_left
Left boundary in local FOV coordinates.
- Type:
int
- local_fov_right
Right boundary in local FOV coordinates.
- Type:
int
- enclosed_fov_top
Top boundary of FOV enclosed within environment bounds.
- Type:
int
- enclosed_fov_bottom
Bottom boundary of FOV enclosed within environment bounds.
- Type:
int
- enclosed_fov_left
Left boundary of FOV enclosed within environment bounds.
- Type:
int
- enclosed_fov_right
Right boundary of FOV enclosed within environment bounds.
- Type:
int
simulation.constants module
simulation.define_actions module
- class simulation.define_actions.Actions(h5_file_path=None, bouts_to_save=None)[source]
Bases:
object- get_extracted_actions(h5_file_path, bouts_to_save=None)[source]
Extracts the actions from the h5 file and returns a list of dictionaries containing the action name, mean, covariance, whether it is a turn, and whether it is a capture.
simulation.eye module
- class simulation.eye.Eye(verg_angle, retinal_field, is_left, env_variables, max_uv_range, rng)[source]
Bases:
object- add_noise_to_readings(readings)[source]
Add shot noise to photon readings using Poisson distribution. This method simulates the quantum nature of light by sampling from a Poisson distribution, which models the statistical fluctuations inherent in photon detection (shot noise). If shot noise is disabled in environment variables, the readings are returned unchanged. :param readings: The input photon readings or expected photon counts to which noise
will be added.
- Returns:
The noisy photon counts sampled from a Poisson distribution with lambda parameter equal to the input readings. If shot noise is disabled, returns the original readings unchanged.
- Return type:
numpy.ndarray or float
Notes
Shot noise is enabled/disabled via the eyes->shot_noise field in the env_config yaml file. The Poisson sampling uses the instance’s random number generator rng_p to ensure reproducibility.
- read(masked_arena_pixels, eye_x, eye_y, fish_angle, uv_lum_mask, prey_positions, predator_left, predator_right, predator_dist)[source]
Read and process visual input from one simulated fish eye. This method simulates the visual system of a fish by computing photoreceptor readings from UV and red channels at different viewing elevations, applying noise, interpolating the readings, and converting them to discrete photon counts. :param masked_arena_pixels: Masked pixel array of the sediment environment :param eye_x: X-coordinate of the eye position :type eye_x: float :param eye_y: Y-coordinate of the eye position :type eye_y: float :param fish_angle: Current orientation angle of the fish in radians :type fish_angle: float :param uv_lum_mask: UV luminance mask array representing the UV light distribution around the fish :param prey_positions: Array of prey positions for UV object detection :param predator_left: angle of the left edge of the predator :param predator_right: angle of the right edge of the predator :param predator_dist: Distance to predator
- Returns:
- Array of shape (num_interpolated_angles, 3) containing discrete photon
counts clipped to range [0, 255]. Columns represent: - Column 0: UV channel readings - Column 1: Red channel readings at first viewing elevation - Column 2: Red channel readings at second viewing elevation
- Return type:
numpy.ndarray
Notes
UV readings incorporate water scatter effects and optional prey projections
Red readings are computed for multiple viewing elevations
Noise is added to both UV and red readings
Final readings are interpolated to a standard set of observation angles
Photon counts are discretized by flooring and clipping to valid range
simulation.fish module
- class simulation.fish.Fish(env_variables, max_uv_range, rng, actions)[source]
Bases:
objectA class representing a fish agent in a 2D physics-based simulation environment. The Fish class models a fish with physical properties (body, head, mouth, tail), visual perception through two eyes, energy management, and action execution capabilities. It uses the pymunk physics engine for realistic movement and collision detection. .. attribute:: max_uv_range
Maximum range for UV light perception.
- type:
float
- env_variables
Dictionary containing environment configuration parameters.
- Type:
dict
- body
The physics body representing the fish.
- Type:
pymunk.Body
- rng
Random number generator for stochastic actions.
- Type:
numpy.random.Generator
- actions
List of available actions the fish can perform.
- Type:
list
- num_actions
Number of available actions.
- Type:
int
- distance_to_impulse_factor
Conversion factor from distance to physics impulse.
- Type:
float
- mouth
Circular collision shape representing the fish’s mouth.
- Type:
pymunk.Circle
- head
Circular collision shape representing the fish’s head.
- Type:
pymunk.Circle
- tail
Polygonal collision shape representing the fish’s tail.
- Type:
pymunk.Poly
- verg_angle
Vergence angle between the two eyes in radians.
- Type:
float
- retinal_field
Visual field angle for each eye in radians.
- Type:
float
- conv_state
Current convergence state of the eyes.
- Type:
int
- hungry
Hunger level of the fish.
- Type:
float
- prey_consumed
Whether prey was consumed in the current step.
- Type:
bool
- touched_edge
Whether the fish has touched the environment edge.
- Type:
bool
- touched_predator
Whether the fish has touched a predator.
- Type:
bool
- making_capture
Whether the fish is currently performing a capture action.
- Type:
bool
- capture_possible
Whether a capture is currently possible.
- Type:
bool
- prev_action_distance
Distance component of the previous action.
- Type:
float
- prev_action_angle
Angle component of the previous action.
- Type:
float
- prev_action
Index of the previously executed action.
- Type:
int
- energy_level
Current energy level of the fish (0.0 to 1.0).
- Type:
float
- d_scaling_energy_cost
Energy cost scaling factor for distance-based movement.
- Type:
float
- a_scaling_energy_cost
Energy cost scaling factor for angular movement.
- Type:
float
- baseline_energy_use
Baseline energy consumption per time step.
- Type:
float
- action_energy_reward_scaling
Scaling factor for energy-based rewards.
- Type:
float
- touched_edge_this_step
Whether the fish touched the edge in the current step.
- Type:
bool
- deterministic_action
Whether to use deterministic (mean) action values.
- Type:
bool
- - The fish uses a physics simulation with configurable mass, inertia, and damping.
- - Collision types are set for different body parts to enable specific interactions.
- - Energy management includes consumption tracking and rewards based on energy efficiency.
- - The fish can operate in test modes
- Type:
sensory system testing, paralysis
- draw_angle_dist(action)[source]
Draw angle and distance values from a multivariate normal distribution. This method samples from a multivariate normal distribution defined by the given action parameters and returns both the sampled values and the mean values. :param action: A dictionary containing:
‘mean’: array-like of shape (2,) representing the mean values [distance_mean, angle_mean]
‘cov’: array-like of shape (2, 2) representing the covariance matrix
- Returns:
- A 4-tuple containing:
float: Sampled angle value
float: Sampled distance value
float: Mean angle value
float: Mean distance value
- Return type:
tuple
- take_action(action_id)[source]
Execute a specific action for the fish agent in the simulation. This method updates the fish’s position and orientation based on the selected action. It handles different simulation modes including sensory system testing and fish paralysis. :param action_id: The identifier of the action to be executed. Must be within
the range of available actions (0 to num_actions-1).
- Side Effects:
Updates self.prev_action with the current action_id
Updates self.prev_action_distance and self.prev_action_angle
Modifies self.body.angle based on the action or test mode sequence
Applies impulse to self.body if fish is not paralyzed
Sets self.making_capture to True if action is a capture action
- Behavior Modes:
test_sensory_system: Rotates fish body by 0.1 radians, no movement
fish_paralyze: Sets distance and angle changes to 0
normal: Draws angle and distance from action distribution, applies impulse
Notes
If deterministic_action is True, uses mean values instead of sampling
The impulse applied is scaled by distance_to_impulse_factor
- update_energy_level(consumption)[source]
Update the fish’s energy level based on consumption and energy costs. This method calculates the net energy change by considering energy gained from consumption and energy expended through movement and actions. It also computes a reward based on energy expenditure. :param consumption: Amount of energy gained from consuming food or prey. :type consumption: float
- Returns:
- Reward value calculated as negative energy use scaled by
action_energy_reward_scaling.
- Return type:
float
- Side Effects:
Updates self.energy_level based on net energy change (unless fixed energy level mode is enabled via env_variables)
Caps energy_level at 1.0 maximum
Notes
If env_variables[“fish_fixed_energy_level”] is True, energy level remains unchanged
Energy level is capped at 1.0 after update
simulation.geometry module
simulation.setup module
simulation.simfish_env module
- class simulation.simfish_env.BaseEnvironment(env_variables, actions, seed=None)[source]
Bases:
EnvironmentBase class for the Simfish environment.
- get_predator_angles_distance()[source]
Get the angles and distance to the predator for visual processing.
- resolve_visual_input()[source]
Compute the visual input from both eyes of the fish. This method calculates the photon readings from the left and right eyes based on the fish’s current position, orientation, and the environment state. It accounts for prey locations, predator positions, sediment masking, and UV luminance. :returns: A 3D array containing stacked photon readings from the left and right eyes.
Shape is (height, width, 2) where the last dimension represents [left_eye, right_eye] photon values.
- Return type:
np.ndarray
Notes
Eye positions are calculated relative to the fish’s body axis and are translated by ‘eyes_biasx’ parameter
Prey locations include both actual prey bodies and stimulated prey locations from the current timestep
Predator information (angles and distance) is computed if a predator exists
The method uses masked sediment and UV luminance masks from the arena
Prey locations are transformed relative to the fish’s position and shifted by max_uv_range for coordinate alignment