Olfaction¶

Olfaction is the sense of smell. Olfactory experience is simulated by calculating odor intensities at the locations of the antennae and maxillary palps. More precisely, this is accomplished by adding position sensors to the relevant body segments and calculating the distance between these sensors and the odor sources. Intensities are then emulated through a diffusion relationship.

To enable this calculation, the BaseArena has the following methods. The user does not have to specifically implement them if an odor is not enabled.

BaseArena.get_olfaction(sensor_pos: ndarray) → ndarray

Get the odor intensity readings from the environment.

Parameters:

sensor_posnp.ndarray: The Cartesian coordinates of the antennae of the fly as a (n, 3) NumPy array where n is the number of sensors (usually n=4: 2 antennae + 2 maxillary palps), and the second dimension gives the corrdinates in (x, y, z).

Returns:

np.ndarray: The odor intensity readings from the environment as a (k, n) NumPy array where k is the dimension of the odor signal and n is the number of odor sensors (usally n=4: 2 antennae + 2 maxillary palps).

BaseArena.odor_dimensions

The dimension of the odor signal. This can be used to emulate multiple monomolecular chemical concentrations or multiple composite ordor intensities.

Returns:

int: The dimension of the odor space.

A useful implementation to refer to is the built-in OdorArena:

class flygym.mujoco.arena.OdorArena(size: Tuple[float, float] = (300, 300), friction: Tuple[float, float, float] = (1, 0.005, 0.0001), num_sensors: int = 4, odor_source: ndarray = np.array([[10, 0, 0]]), peak_intensity: ndarray = np.array([[1]]), diffuse_func: Callable = lambda x: ..., marker_colors: List[Tuple[float, float, float, float]] | None = None, marker_size: float = 0.25)

Bases: BaseArena

Flat terrain with an odor source.

Parameters:

sizeTuple[float, float], optional: The size of the arena in mm, by default (300, 300).
frictionTuple[float, float, float], optional: The sliding, torsional, and rolling friction coefficients of the ground, by default (1, 0.005, 0.0001).
num_sensorsint, optional: The number of odor sensors, by default 4: 2 antennae + 2 maxillary palps.
odor_sourcenp.ndarray, optional: The position of the odor source in (x, y, z) coordinates. The shape of the array is (n_sources, 3).
peak_intensitynp.ndarray, optional: The peak intensity of the odor source. The shape of the array is (n_sources, n_dimensions). Note that the odor intensity can be multidimensional.
diffuse_funcCallable, optional: The function that, given a distance from the odor source, returns the relative intensity of the odor. By default, this is a inverse square relationship.
marker_colorsList[Tuple[float, float, float, float]], optional: A list of n_sources RGBA values (each as a tuple) indicating the colors of the markers indicating the positions of the odor sources. The RGBA values should be given in the range [0, 1]. By default, the matplotlib color cycle is used.
marker_sizefloat, optional: The size of the odor source markers, by default 0.25.

Attributes:

root_elementmjcf.RootElement: The root MJCF element of the arena.
frictionTuple[float, float, float]: The sliding, torsional, and rolling friction coefficients of the ground, by default (1, 0.005, 0.0001)
num_sensorsint: The number of odor sensors, by default 4: 2 antennae + 2 maxillary palps.
odor_sourcenp.ndarray: The position of the odor source in (x, y, z) coordinates. The shape of the array is (n_sources, 3).
peak_intensitynp.ndarray: The peak intensity of the odor source. The shape of the array is (n_sources, n_dimensions). Note that the odor intensity can be multidimensional.
num_odor_sourcesint: Number of odor sources.
odor_dimensionsint: The dimension of the odor signal.
diffuse_funcCallable: The function that, given a distance from the odor source, returns the relative intensity of the odor. By default, this is a inverse square relationship.
birdeye_camdm_control.mujoco.Camera: MuJoCo camera that gives a birdeye view of the arena.
birdeye_cam_zoomdm_control.mujoco.Camera: MuJoCo camera that gives a birdeye view of the arena, zoomed in toward the fly.

friction = (100.0, 0.005, 0.0001)

get_olfaction(antennae_pos: ndarray) → ndarray

Notes

w = 4: number of sensors (2x antennae + 2x max. palps) 3: spatial dimensionality k: data dimensionality n: number of odor sources

Input - odor source position: [n, 3] Input - sensor positions: [w, 3] Input - peak intensity: [n, k] Input - difusion function: f(dist)

Reshape sources to S = [n, k*, w*, 3] (* means repeated) Reshape sensor position to A = [n*, k*, w, 3] (* means repeated) Subtract, getting an Delta = [n, k, w, 3] array of rel difference Calculate Euclidean disctance: D = [n, k, w]

Apply pre-integrated difusion function: S = f(D) -> [n, k, w] Reshape peak intensities to P = [n, k, w*] Apply scaling: I = P * S -> [n, k, w] element wise

Output - Sum over the first axis: [k, w]

get_spawn_position(rel_pos: ndarray, rel_angle: ndarray) → Tuple[ndarray, ndarray]

Given a relative entity spawn position and orientation (as if it was a simple flat terrain), return the abjusted position and orientation. This is useful for environments that have complex terrain (eg. with obstacles) where the entity’s spawn position needs to be shifted accordingly.

For example, if the arena has flat terrain, this method can simply return rel_pos, rel_angle unchanged (as is the case by default). If there is are featues on the ground that are 0.1 mm in height, then this method should return rel_pos + [0, 0, 0.1], rel_angle.

Parameters:

rel_posnp.ndarray: (x, y, z) position of the entity in mm as supplied by the user (before any transformation).
rel_anglenp.ndarray: Euler angle (rotation along x, y, z in radian) of the fly’s orientation as supplied by the user (before any transformation).
*args: User defined arguments and keyword arguments.
**kwargs: User defined arguments and keyword arguments.

Returns:

np.ndarray: Adjusted (x, y, z) position of the entity.
np.ndarray: Adjusted euler angle (rotation along x, y, z in raidan) of the fly’s oreintation.

property odor_dimensions: int

The dimension of the odor signal. This can be used to emulate multiple monomolecular chemical concentrations or multiple composite ordor intensities.

Returns:

int: The dimension of the odor space.

post_visual_render_hook(physics: dm_control.mjcf.Physics, *args, **kwargs) → None: Make necessary changes (eg. make certain visualization markers opaque) after rendering the visual inputs. By default, this does nothing.

pre_visual_render_hook(physics: dm_control.mjcf.Physics, *args, **kwargs) → None: Make necessary changes (eg. make certain visualization markers transparent) before rendering the visual inputs. By default, this does nothing.

spawn_entity(entity: Any, rel_pos: ndarray, rel_angle: ndarray) → None

Add the fly to the arena.

Parameters:

entitymjcf.RootElement: The entity to be added to the arena (this should be the fly).
rel_posnp.ndarray: (x, y, z) position of the entity.
rel_anglenp.ndarray: euler angle representation (rot around x, y, z) of the entity’s orientation if it were spawned on a simple flat terrain.

step(dt: float, physics: dm_control.mjcf.Physics, *args, **kwargs) → None

Advance the arena by one step. This is useful for interactive environments (eg. moving object). Typically, this method is called from the core simulation class (eg. NeuroMechFly).

Parameters:

dtfloat: The time step in seconds since the last update. Typically, this is the same as the time step of the physics simulation (provided that this method is called by the core simulation every time the simulation steps).
physicsmjcf.Physics: The physics object of the simulation. This is typically provided by the core simulation class (eg. NeuroMechFly.physics) when the core simulation calls this method.
*args: User defined arguments and keyword arguments.
**kwargs: User defined arguments and keyword arguments.