larvaworld.lib.param.grouped ============================ .. py:module:: larvaworld.lib.param.grouped Classes ------- .. autoapisummary:: larvaworld.lib.param.grouped.FramerateOps larvaworld.lib.param.grouped.XYops larvaworld.lib.param.grouped.SimTimeOps larvaworld.lib.param.grouped.SimSpatialOps larvaworld.lib.param.grouped.SimOps larvaworld.lib.param.grouped.RuntimeGeneralOps larvaworld.lib.param.grouped.RuntimeDataOps larvaworld.lib.param.grouped.RuntimeOps larvaworld.lib.param.grouped.Filesystem larvaworld.lib.param.grouped.TrackedPointIdx larvaworld.lib.param.grouped.SimMetricOps larvaworld.lib.param.grouped.TrackerOps Module Contents --------------- .. py:class:: FramerateOps(**kwargs: Any) Bases: :py:obj:`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 .. py:attribute:: fr .. py:attribute:: dt .. py:attribute:: constant_framerate .. py:method:: update_framerate() -> None .. py:method:: update_timestep() -> None .. py:class:: XYops(**kwargs: Any) Bases: :py:obj:`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', ...] .. py:attribute:: XY_unit .. py:attribute:: Npoints .. py:attribute:: Ncontour .. py:property:: Nangles :type: int .. py:property:: Nsegs :type: int .. py:property:: angles :type: larvaworld.lib.util.SuperList .. py:property:: midline_points :type: larvaworld.lib.util.SuperList .. py:property:: midline_segs :type: larvaworld.lib.util.SuperList .. py:property:: midline_seg_xy :type: larvaworld.lib.util.SuperList .. py:property:: seg_orientations :type: larvaworld.lib.util.SuperList .. py:property:: midline_xy :type: larvaworld.lib.util.SuperList .. py:property:: contour_points :type: larvaworld.lib.util.SuperList .. py:property:: contour_xy :type: larvaworld.lib.util.SuperList .. py:property:: centroid_xy :type: larvaworld.lib.util.SuperList .. py:property:: traj_xy :type: larvaworld.lib.util.SuperList .. py:property:: all_xy :type: larvaworld.lib.util.SuperList .. py:method:: get_track_point(idx: int) -> str .. py:method:: get_midline_xy_data(s: Any) -> numpy.ndarray .. py:method:: get_contour_xy_data(s: Any) -> numpy.ndarray .. py:class:: SimTimeOps(**kwargs: Any) Bases: :py:obj:`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 .. py:attribute:: duration .. py:attribute:: Nsteps .. py:method:: update_Nsteps() -> None .. py:method:: update_duration() -> None .. py:class:: SimSpatialOps(**kwargs: Any) Bases: :py:obj:`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) .. py:attribute:: Box2D .. py:attribute:: larva_collisions .. py:property:: scaling_factor :type: float .. py:class:: SimOps(**kwargs: Any) Bases: :py:obj:`SimTimeOps`, :py:obj:`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) .. py:class:: RuntimeGeneralOps(**kwargs: Any) Bases: :py:obj:`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) .. py:attribute:: offline .. py:attribute:: multicore .. py:attribute:: store_data .. py:class:: RuntimeDataOps(**kwargs: Any) Bases: :py:obj:`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) .. py:attribute:: id .. py:attribute:: dir .. py:property:: data_dir :type: Optional[str] .. py:property:: plot_dir :type: Optional[str] .. py:class:: RuntimeOps(**kwargs: Any) Bases: :py:obj:`RuntimeGeneralOps`, :py:obj:`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) .. py:class:: Filesystem(**kwargs: Any) Bases: :py:obj:`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') .. py:attribute:: read_sequence .. py:attribute:: read_metadata .. py:attribute:: folder_pref .. py:attribute:: folder_suff .. py:attribute:: file_pref .. py:attribute:: file_suf .. py:attribute:: file_sep .. py:attribute:: structure .. py:method:: valid_files_in_folder(dir) -> list[str] .. py:class:: TrackedPointIdx(**kwargs) Bases: :py:obj:`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) .. py:attribute:: point_idx .. py:attribute:: point .. py:method:: update_tracked_point() -> None .. py:property:: point_xy :type: larvaworld.lib.util.SuperList .. py:class:: SimMetricOps(**kwargs) Bases: :py:obj:`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), ...} .. py:attribute:: bend .. py:attribute:: front_vector .. py:attribute:: rear_vector .. py:attribute:: front_body_ratio .. py:attribute:: use_component_vel .. py:method:: update_vectors() -> None .. py:property:: Nbend_angles :type: int .. py:property:: vector_dict :type: larvaworld.lib.util.AttrDict .. py:class:: TrackerOps(**kwargs) Bases: :py:obj:`SimMetricOps`, :py:obj:`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' ... )