larvaworld.lib.param.grouped

Classes

`FramerateOps`	Framerate and timestep configuration parameter group.
`XYops`	XY coordinate tracking configuration parameter group.
`SimTimeOps`	Simulation time configuration parameter group.
`SimSpatialOps`	Simulation spatial operations configuration parameter group.
`SimOps`	Combined simulation operations parameter group.
`RuntimeGeneralOps`	General runtime operations parameter group.
`RuntimeDataOps`	Runtime data directory operations parameter group.
`RuntimeOps`	Combined runtime operations parameter group.
`Filesystem`	Filesystem configuration for raw tracker data import.
`TrackedPointIdx`	Tracked point index configuration parameter group.
`SimMetricOps`	Simulation metrics computation configuration parameter group.
`TrackerOps`	Combined tracker operations parameter group.

Module Contents

class larvaworld.lib.param.grouped.FramerateOps(**kwargs: Any)

Bases: larvaworld.lib.param.nested_parameter_group.NestedConf

Framerate and timestep configuration parameter group.

Manages bidirectional synchronization between framerate (Hz) and timestep (seconds), ensuring dt = 1/fr relationship is maintained.

Attributes:

fr: Framerate in Hz (default: 10 Hz) dt: Timestep in seconds (default: 0.1 s) constant_framerate: Whether framerate is constant (default: True)

Example:

>>> fr_ops = FramerateOps(fr=20)  # dt auto-updates to 0.05
>>> fr_ops.dt = 0.1  # fr auto-updates to 10

fr

dt

constant_framerate

update_framerate() → None

update_timestep() → None

class larvaworld.lib.param.grouped.XYops(**kwargs: Any)

Bases: larvaworld.lib.param.nested_parameter_group.NestedConf

XY coordinate tracking configuration parameter group.

Manages spatial coordinate tracking parameters for larva body shape, including midline points, contour points, and derived quantities (segments, angles, orientations).

Attributes:

XY_unit: Spatial unit (‘m’ or ‘mm’, default: ‘m’) Npoints: Number of midline tracking points (default: 3) Ncontour: Number of contour tracking points (default: 0) Nangles: Computed number of bend angles (Npoints - 2) Nsegs: Computed number of body segments (Npoints - 1)

Example:

>>> xy_ops = XYops(Npoints=11, Ncontour=20, XY_unit='mm')
>>> xy_ops.Nangles  # 9 bend angles
>>> xy_ops.midline_xy  # ['point0_x', 'point0_y', ...]

XY_unit

Npoints

Ncontour

property Nangles: int

property Nsegs: int

property angles: larvaworld.lib.util.SuperList

property midline_points: larvaworld.lib.util.SuperList

property midline_segs: larvaworld.lib.util.SuperList

property midline_seg_xy: larvaworld.lib.util.SuperList

property seg_orientations: larvaworld.lib.util.SuperList

property midline_xy: larvaworld.lib.util.SuperList

property contour_points: larvaworld.lib.util.SuperList

property contour_xy: larvaworld.lib.util.SuperList

property centroid_xy: larvaworld.lib.util.SuperList

property traj_xy: larvaworld.lib.util.SuperList

property all_xy: larvaworld.lib.util.SuperList

get_track_point(idx: int) → str

get_midline_xy_data(s: Any) → numpy.ndarray

get_contour_xy_data(s: Any) → numpy.ndarray

class larvaworld.lib.param.grouped.SimTimeOps(**kwargs: Any)

Bases: FramerateOps

Simulation time configuration parameter group.

Extends FramerateOps with duration and step count, maintaining bidirectional synchronization: Nsteps = duration*60/dt.

Attributes:

duration: Simulation duration in minutes (optional) Nsteps: Number of simulation timesteps (optional) fr: Inherited framerate in Hz dt: Inherited timestep in seconds

Example:

>>> time_ops = SimTimeOps(duration=5.0, dt=0.1)  # Nsteps auto-updates to 3000
>>> time_ops.Nsteps = 6000  # duration auto-updates to 10.0

duration

Nsteps

update_Nsteps() → None

update_duration() → None

class larvaworld.lib.param.grouped.SimSpatialOps(**kwargs: Any)

Bases: larvaworld.lib.param.nested_parameter_group.NestedConf

Simulation spatial operations configuration parameter group.

Manages physics engine settings and collision detection parameters for spatial simulation dynamics.

Attributes:

Box2D: Use Box2D physics engine (default: False) larva_collisions: Allow body overlap (default: True) scaling_factor: Spatial scaling coefficient (always 1.0)

Example:

>>> spatial_ops = SimSpatialOps(Box2D=True, larva_collisions=False)

Box2D

larva_collisions

property scaling_factor: float

class larvaworld.lib.param.grouped.SimOps(**kwargs: Any)

Bases: SimTimeOps, SimSpatialOps

Combined simulation operations parameter group.

Merges temporal (SimTimeOps) and spatial (SimSpatialOps) configuration into unified simulation control parameters.

Example:

>>> sim_ops = SimOps(duration=10.0, dt=0.1, Box2D=True)

class larvaworld.lib.param.grouped.RuntimeGeneralOps(**kwargs: Any)

Bases: larvaworld.lib.param.nested_parameter_group.NestedConf

General runtime operations parameter group.

Controls basic runtime execution modes (offline, multicore, storage).

Attributes:

offline: Offline mode without full environment (default: False) multicore: Use parallel execution (default: False) store_data: Store simulation data (default: True)

Example:

>>> runtime_gen = RuntimeGeneralOps(multicore=True, store_data=False)

offline

multicore

store_data

class larvaworld.lib.param.grouped.RuntimeDataOps(**kwargs: Any)

Bases: larvaworld.lib.param.nested_parameter_group.NestedConf

Runtime data directory operations parameter group.

Manages data and plot directory paths, auto-creating subdirectories when base dir is specified.

Attributes:

id: Simulation run ID (optional) dir: Base storage directory path (optional) data_dir: Auto-created data subdirectory ({dir}/data) plot_dir: Auto-created plots subdirectory ({dir}/plots)

Example:

>>> data_ops = RuntimeDataOps(id='exp001', dir='/path/to/output')
>>> data_ops.data_dir  # '/path/to/output/data' (auto-created)

id

dir

property data_dir: str | None

property plot_dir: str | None

class larvaworld.lib.param.grouped.RuntimeOps(**kwargs: Any)

Bases: RuntimeGeneralOps, RuntimeDataOps

Combined runtime operations parameter group.

Merges general and data runtime operations into unified runtime control.

Example:

>>> runtime = RuntimeOps(show_display=True, store_data=True, save_video=False)

class larvaworld.lib.param.grouped.Filesystem(**kwargs: Any)

Bases: larvaworld.lib.param.nested_parameter_group.NestedConf

Filesystem configuration for raw tracker data import.

Defines file/folder naming conventions, data format, and structure for importing experimental tracker datasets into Larvaworld.

Attributes:

read_sequence: Column sequence in tracker files read_metadata: Metadata files available (default: False) folder_pref: Raw-data folder prefix pattern folder_suff: Raw-data folder suffix pattern file_pref: Raw-data file prefix (default: “”) file_suf: Raw-data file suffix (default: “”) file_sep: File name separator pattern structure: File organization (‘per_larva’ or ‘per_parameter’)

Example:

>>> fs = Filesystem(
...     file_pref='trial_',
...     file_suf='.csv',
...     structure='per_larva'
... )
>>> fs.valid_files_in_folder('/path/to/data')

read_sequence

read_metadata

folder_pref

folder_suff

file_pref

file_suf

file_sep

structure

valid_files_in_folder(dir) → list[str]

class larvaworld.lib.param.grouped.TrackedPointIdx(**kwargs)

Bases: XYops

Tracked point index configuration parameter group.

Extends XYops to specify which midline point serves as larva position reference, with automatic point name synchronization.

Attributes:

point_idx: Midline point index (-1=centroid, 1 to Npoints, default: -1) point: Point name string (auto-synced with point_idx)

Example:

>>> tracked = TrackedPointIdx(Npoints=11, point_idx=5)
>>> tracked.point  # 'point4' (auto-updated)

point_idx

point

update_tracked_point() → None

property point_xy: larvaworld.lib.util.SuperList

class larvaworld.lib.param.grouped.SimMetricOps(**kwargs)

Bases: TrackedPointIdx

Simulation metrics computation configuration parameter group.

Extends TrackedPointIdx with bend angle computation settings, front/rear body vector definitions, and velocity component options.

Attributes:

bend: Bend computation method (‘from_vectors’ or ‘from_angles’) front_vector: Front body segment range (1-indexed, ordered) rear_vector: Rear body segment range (can be negative, ordered) front_body_ratio: Front body fraction for angle-based bend (0-1, default: 0.5) use_component_vel: Use velocity component along forward axis (default: False) Nbend_angles: Computed front bend angles count (property) vector_dict: Body vector definitions dict (property)

Example:

>>> metrics = SimMetricOps(
...     Npoints=11,
...     bend='from_vectors',
...     front_vector=(1, 5),
...     rear_vector=(-5, -1),
...     front_body_ratio=0.6
... )
>>> metrics.vector_dict  # {'front': (4, 0), 'rear': (-6, -2), ...}

bend

front_vector

rear_vector

front_body_ratio

use_component_vel

update_vectors() → None

property Nbend_angles: int

property vector_dict: larvaworld.lib.util.AttrDict

class larvaworld.lib.param.grouped.TrackerOps(**kwargs)

Bases: SimMetricOps, FramerateOps

Combined tracker operations parameter group.

Merges metrics computation (SimMetricOps) and framerate (FramerateOps) into unified tracker configuration for experimental data import.

Example:

>>> tracker_ops = TrackerOps(
...     Npoints=11,
...     fr=10,
...     bend='from_angles'
... )