larvaworld.lib.param.custom =========================== .. py:module:: larvaworld.lib.param.custom Classes ------- .. autoapisummary:: larvaworld.lib.param.custom.StringRobust larvaworld.lib.param.custom.PositiveNumber larvaworld.lib.param.custom.PositiveInteger larvaworld.lib.param.custom.Phase larvaworld.lib.param.custom.RangeRobust larvaworld.lib.param.custom.RangeInf larvaworld.lib.param.custom.PositiveRange larvaworld.lib.param.custom.PhaseRange larvaworld.lib.param.custom.OptionalPositiveNumber larvaworld.lib.param.custom.OptionalPositiveInteger larvaworld.lib.param.custom.RandomizedPhase larvaworld.lib.param.custom.RandomizedColor larvaworld.lib.param.custom.OptionalPositiveRange larvaworld.lib.param.custom.OptionalPhaseRange larvaworld.lib.param.custom.OptionalSelector larvaworld.lib.param.custom.IntegerTuple larvaworld.lib.param.custom.IntegerRange larvaworld.lib.param.custom.PositiveIntegerTuple larvaworld.lib.param.custom.IntegerRangeOrdered larvaworld.lib.param.custom.PositiveIntegerRange larvaworld.lib.param.custom.PositiveIntegerRangeOrdered larvaworld.lib.param.custom.NegativeIntegerRangeOrdered larvaworld.lib.param.custom.OptionalPositiveIntegerRangeOrdered larvaworld.lib.param.custom.OptionalNegativeIntegerRangeOrdered larvaworld.lib.param.custom.NumericTuple2DRobust larvaworld.lib.param.custom.IntegerTuple2DRobust larvaworld.lib.param.custom.ListXYcoordinates larvaworld.lib.param.custom.XYLine larvaworld.lib.param.custom.ItemListParam larvaworld.lib.param.custom.ClassDict larvaworld.lib.param.custom.ClassAttr larvaworld.lib.param.custom.ModeSelector larvaworld.lib.param.custom.DataFrameIndexed larvaworld.lib.param.custom.StepDataFrame larvaworld.lib.param.custom.EndpointDataFrame Module Contents --------------- .. py:class:: StringRobust(default='', **kwargs) Bases: :py:obj:`param.String` Robust string parameter that converts any input to string. Extends param.String to automatically convert non-string inputs to string representation during initialization. Args: default: Default value (converted to str if not None) **kwargs: Additional keyword arguments passed to param.String Example: >>> str_param = StringRobust(default=123) >>> str_param.default # "123" .. py:class:: PositiveNumber(default=0.0, softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, bounds=None, step=0.1, **kwargs) Bases: :py:obj:`param.Number` Numeric parameter constrained to positive values. Extends param.Number with automatic positive bounds enforcement. Useful for physical quantities that must be non-negative (distances, frequencies, counts). Args: default: Default value (must be >= 0.0) softmin: Soft lower bound for UI sliders (default: 0.0) softmax: Soft upper bound for UI sliders (default: None) hardmin: Hard lower bound (default: 0.0, enforced) hardmax: Hard upper bound (default: None) bounds: Explicit bounds tuple (overrides hardmin/hardmax if provided) step: Step size for UI increments (default: 0.1) **kwargs: Additional keyword arguments passed to param.Number Example: >>> velocity = PositiveNumber(default=1.5, softmax=5.0, step=0.1) .. py:class:: PositiveInteger(default=0, softmin=0, softmax=None, hardmin=0, hardmax=None, step=1, **kwargs) Bases: :py:obj:`param.Integer` Integer parameter constrained to positive values. Extends param.Integer with automatic positive bounds enforcement. Useful for counts, indices, and discrete quantities that must be non-negative. Args: default: Default integer value (must be >= 0) softmin: Soft lower bound for UI sliders (default: 0) softmax: Soft upper bound for UI sliders (default: None) hardmin: Hard lower bound (default: 0, enforced) hardmax: Hard upper bound (default: None) step: Step size for UI increments (default: 1) **kwargs: Additional keyword arguments passed to param.Integer Example: >>> num_agents = PositiveInteger(default=10, softmax=100, step=5) .. py:class:: Phase(default=0.0, softmin=0.0, softmax=2 * np.pi, hardmin=0.0, hardmax=2 * np.pi, step=0.1, **kwargs) Bases: :py:obj:`param.Number` Phase angle parameter constrained to [0, 2π] range. Extends param.Number for representing phase angles in radians, automatically bounded to the valid phase range [0, 2π]. Args: default: Default phase value in radians (0.0 to 2π) softmin: Soft lower bound (default: 0.0) softmax: Soft upper bound (default: 2π) hardmin: Hard lower bound (default: 0.0, enforced) hardmax: Hard upper bound (default: 2π, enforced) step: Step size for UI increments (default: 0.1 radians) **kwargs: Additional keyword arguments passed to param.Number Example: >>> initial_phase = Phase(default=np.pi/2, step=0.05) .. py:class:: RangeRobust(default=(0.0, 0.0), step=0.1, **kwargs) Bases: :py:obj:`param.Range` Robust range parameter accepting both tuples and lists. Extends param.Range to automatically convert list inputs to tuples, providing more flexible range specification in configurations. Args: default: Default range as tuple or list (default: (0.0, 0.0)) step: Step size for UI increments (default: 0.1) **kwargs: Additional keyword arguments passed to param.Range Example: >>> velocity_range = RangeRobust(default=[0.5, 2.0], step=0.1) >>> velocity_range.default # (0.5, 2.0) - converted to tuple .. py:class:: RangeInf(default=(0.0, 0.0), step=0.1, **kwargs) Bases: :py:obj:`RangeRobust` Range parameter allowing None values within tuple bounds. Extends RangeRobust to support unbounded ranges by accepting None for either lower or upper bound, enabling half-open intervals. Example: >>> unbounded_upper = RangeInf(default=(0.0, None)) # [0, ∞) >>> unbounded_lower = RangeInf(default=(None, 10.0)) # (-∞, 10] .. py:class:: PositiveRange(default=(0.0, 0.0), softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, **kwargs) Bases: :py:obj:`RangeRobust` Range parameter constrained to positive number tuples. Extends RangeRobust with automatic positive bounds enforcement for both lower and upper range values. Args: default: Default range tuple (both values >= 0.0) softmin: Soft lower bound (default: 0.0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0.0, enforced) hardmax: Hard upper bound (default: None) **kwargs: Additional keyword arguments passed to RangeRobust Example: >>> speed_range = PositiveRange(default=(0.5, 2.0), softmax=5.0) .. py:class:: PhaseRange(default=(0.0, 0.0), softmin=0.0, softmax=2 * np.pi, hardmin=0.0, hardmax=2 * np.pi, **kwargs) Bases: :py:obj:`RangeRobust` Phase angle range parameter constrained to [0, 2π]. Extends RangeRobust for representing phase angle ranges in radians, both bounds automatically constrained to [0, 2π]. Args: default: Default phase range tuple (both values 0.0 to 2π) softmin: Soft lower bound (default: 0.0) softmax: Soft upper bound (default: 2π) hardmin: Hard lower bound (default: 0.0, enforced) hardmax: Hard upper bound (default: 2π, enforced) **kwargs: Additional keyword arguments passed to RangeRobust Example: >>> phase_bounds = PhaseRange(default=(0.0, np.pi), step=0.1) .. py:class:: OptionalPositiveNumber(default=None, softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, step=0.1, **kwargs) Bases: :py:obj:`param.Number` Optional numeric parameter constrained to positive values or None. Extends param.Number with positive bounds and explicit None support, useful for optional physical quantities that when specified must be positive. Args: default: Default value (None or >= 0.0, default: None) softmin: Soft lower bound (default: 0.0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0.0, enforced when not None) hardmax: Hard upper bound (default: None) step: Step size for UI increments (default: 0.1) **kwargs: Additional keyword arguments passed to param.Number Example: >>> max_duration = OptionalPositiveNumber(default=None, softmax=1000.0) .. py:class:: OptionalPositiveInteger(default=None, softmin=0, softmax=None, hardmin=0, hardmax=None, step=1, **kwargs) Bases: :py:obj:`param.Integer` Optional integer parameter constrained to positive values or None. Extends param.Integer with positive bounds and explicit None support, useful for optional counts or indices that when specified must be positive. Args: default: Default value (None or >= 0, default: None) softmin: Soft lower bound (default: 0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0, enforced when not None) hardmax: Hard upper bound (default: None) step: Step size for UI increments (default: 1) **kwargs: Additional keyword arguments passed to param.Integer Example: >>> max_iterations = OptionalPositiveInteger(default=None, softmax=1000) .. py:class:: RandomizedPhase(default=None, **kwargs) Bases: :py:obj:`Phase` Phase parameter with automatic random initialization. Extends Phase to randomly initialize from uniform [0, 2π] distribution when default is None or np.nan, useful for randomized initial conditions. Args: default: Initial phase (if None/nan, randomly sampled from [0, 2π]) **kwargs: Additional keyword arguments passed to Phase Example: >>> random_phase = RandomizedPhase(default=None) # Random each time .. py:class:: RandomizedColor(default=None, instantiate=True, allow_None=True, per_instance=True, **kwargs) Bases: :py:obj:`param.Color` Color parameter with automatic random initialization. Extends param.Color to randomly select from named colors when default is None/nan/empty, useful for auto-coloring agents or objects. Args: default: Initial color (if None/nan/"", randomly selected from named colors) instantiate: Create unique instances per parameter (default: True) allow_None: Allow None values (default: True) per_instance: Different values per class instance (default: True) **kwargs: Additional keyword arguments passed to param.Color Example: >>> agent_color = RandomizedColor(default=None) # Random named color .. py:class:: OptionalPositiveRange(default=None, softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, **kwargs) Bases: :py:obj:`RangeInf` Optional range parameter constrained to positive tuples or None. Extends RangeInf with positive bounds and None support for entire range, useful for optional bounded intervals that must be positive when specified. Args: default: Default range (None or tuple with values >= 0.0) softmin: Soft lower bound (default: 0.0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0.0, enforced) hardmax: Hard upper bound (default: None) **kwargs: Additional keyword arguments passed to RangeInf Example: >>> optional_range = OptionalPositiveRange(default=None, softmax=10.0) .. py:class:: OptionalPhaseRange(default=None, softmin=0.0, softmax=2 * np.pi, hardmin=0.0, hardmax=2 * np.pi, **kwargs) Bases: :py:obj:`RangeRobust` Optional phase range parameter constrained to [0, 2π] or None. Extends RangeRobust for optional phase angle ranges, with both bounds constrained to [0, 2π] when range is specified. Args: default: Default phase range (None or tuple with values 0.0 to 2π) softmin: Soft lower bound (default: 0.0) softmax: Soft upper bound (default: 2π) hardmin: Hard lower bound (default: 0.0, enforced) hardmax: Hard upper bound (default: 2π, enforced) **kwargs: Additional keyword arguments passed to RangeRobust Example: >>> phase_range = OptionalPhaseRange(default=(0.0, np.pi)) .. py:class:: OptionalSelector(objects, default=None, **kwargs) Bases: :py:obj:`param.Selector` Selector parameter with automatic None support. Extends param.Selector to allow None as default value even when None is not in the objects list, useful for optional selections. Args: objects: List of valid selectable objects default: Default selected object (None allowed even if not in objects) **kwargs: Additional keyword arguments passed to param.Selector Example: >>> mode_select = OptionalSelector(objects=['A', 'B', 'C'], default=None) .. py:class:: IntegerTuple(default=(0, 0), *, length=None, doc=None, label=None, precedence=None, instantiate=False, constant=False, readonly=False, pickle_default_value=True, allow_None=False, per_instance=True, allow_refs=False, nested_refs=False) Bases: :py:obj:`param.NumericTuple` Numeric tuple parameter constrained to integer values. Extends param.NumericTuple to enforce that all tuple elements are integers, rejecting float or other numeric types. Example: >>> int_coords = IntegerTuple(default=(10, 20, 30), length=3) .. py:class:: IntegerRange(default=(0, 0), step=1, **kwargs) Bases: :py:obj:`RangeRobust` Range parameter constrained to integer tuple values. Extends RangeRobust to enforce both range bounds are integers, useful for discrete intervals and index ranges. Args: default: Default integer range tuple (default: (0, 0)) step: Step size for UI increments (default: 1) **kwargs: Additional keyword arguments passed to RangeRobust Example: >>> age_range = IntegerRange(default=(0, 100), step=5) .. py:class:: PositiveIntegerTuple(default=(0, 0), softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs) Bases: :py:obj:`IntegerTuple` Integer tuple parameter constrained to non-negative values. Extends IntegerTuple with automatic positive bounds enforcement for every tuple element. Args: default: Default integer tuple (all values >= 0) softmin: Soft lower bound (default: 0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0, enforced) hardmax: Hard upper bound (default: None) **kwargs: Additional keyword arguments passed to IntegerTuple Example: >>> grid_dims = PositiveIntegerTuple(default=(51, 51), length=2, softmax=500) .. py:attribute:: softmin :value: 0 .. py:attribute:: softmax :value: None .. py:attribute:: hardmin :value: 0 .. py:attribute:: hardmax :value: None .. py:class:: IntegerRangeOrdered(default=(0, 0), step=1, **kwargs) Bases: :py:obj:`IntegerRange` Ordered integer range parameter enforcing lower <= upper. Extends IntegerRange with validation to ensure first value is less than or equal to second value in tuple. Example: >>> ordered_range = IntegerRangeOrdered(default=(5, 15)) # OK >>> ordered_range = IntegerRangeOrdered(default=(15, 5)) # Raises ValueError .. py:class:: PositiveIntegerRange(default=(0, 0), softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs) Bases: :py:obj:`IntegerRange` Integer range parameter constrained to positive values. Extends IntegerRange with automatic positive bounds enforcement for both range endpoints. Args: default: Default integer range (both values >= 0) softmin: Soft lower bound (default: 0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0, enforced) hardmax: Hard upper bound (default: None) **kwargs: Additional keyword arguments passed to IntegerRange Example: >>> count_range = PositiveIntegerRange(default=(10, 50), softmax=100) .. py:class:: PositiveIntegerRangeOrdered(default=(0, 1), softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs) Bases: :py:obj:`IntegerRangeOrdered` Ordered positive integer range parameter. Combines IntegerRangeOrdered with positive bounds, ensuring both ordering (lower <= upper) and positivity constraints. Args: default: Default ordered integer range (both >= 0, first <= second) softmin: Soft lower bound (default: 0) softmax: Soft upper bound (default: None) hardmin: Hard lower bound (default: 0, enforced) hardmax: Hard upper bound (default: None) **kwargs: Additional keyword arguments passed to IntegerRangeOrdered Example: >>> id_range = PositiveIntegerRangeOrdered(default=(5, 20), softmax=100) .. py:class:: NegativeIntegerRangeOrdered(default=(-1, 0), softmin=None, softmax=0, hardmin=None, hardmax=0, **kwargs) Bases: :py:obj:`IntegerRangeOrdered` Ordered negative integer range parameter. Combines IntegerRangeOrdered with negative/zero upper bound, ensuring both ordering and non-positive constraints (useful for negative indices). Args: default: Default ordered integer range (both <= 0, first <= second) softmin: Soft lower bound (default: None) softmax: Soft upper bound (default: 0) hardmin: Hard lower bound (default: None) hardmax: Hard upper bound (default: 0, enforced) **kwargs: Additional keyword arguments passed to IntegerRangeOrdered Example: >>> negative_range = NegativeIntegerRangeOrdered(default=(-10, -1)) .. py:class:: OptionalPositiveIntegerRangeOrdered(default=None, softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs) Bases: :py:obj:`PositiveIntegerRangeOrdered` Optional ordered positive integer range parameter. Accepts either an ordered positive integer tuple or ``None``. .. py:class:: OptionalNegativeIntegerRangeOrdered(default=None, softmin=None, softmax=0, hardmin=None, hardmax=0, **kwargs) Bases: :py:obj:`NegativeIntegerRangeOrdered` Optional ordered negative integer range parameter. Accepts either an ordered negative integer tuple or ``None``. .. py:class:: NumericTuple2DRobust(default=(0.0, 0.0), **kwargs) Bases: :py:obj:`param.NumericTuple` 2D numeric tuple parameter accepting both tuples and lists. Extends param.NumericTuple with automatic list-to-tuple conversion and fixed length=2, useful for XY coordinates and 2D vectors. Args: default: Default 2D point as tuple or list (default: (0.0, 0.0)) **kwargs: Additional keyword arguments passed to param.NumericTuple Example: >>> position = NumericTuple2DRobust(default=[10.5, 20.3]) >>> position.default # (10.5, 20.3) - converted to tuple .. py:class:: IntegerTuple2DRobust(default=(0, 0), **kwargs) Bases: :py:obj:`IntegerTuple` 2D integer tuple parameter accepting both tuples and lists. Extends IntegerTuple with automatic list-to-tuple conversion and fixed length=2, useful for pixel coordinates and grid indices. Args: default: Default 2D integer point as tuple or list (default: (0, 0)) **kwargs: Additional keyword arguments passed to IntegerTuple Example: >>> pixel_pos = IntegerTuple2DRobust(default=[100, 200]) >>> pixel_pos.default # (100, 200) - converted to tuple .. py:class:: ListXYcoordinates(default=[], minlen=0, maxlen=None, **kwargs) Bases: :py:obj:`param.List` List parameter for XY coordinate tuples. Extends param.List with tuple item_type and length bounds, useful for polylines, paths, and multi-point geometries. Args: default: Default list of XY tuples (default: []) minlen: Minimum list length (default: 0) maxlen: Maximum list length (default: None) **kwargs: Additional keyword arguments passed to param.List Example: >>> path = ListXYcoordinates(default=[(0,0), (10,5), (20,10)], minlen=2) .. py:class:: XYLine(minlen=0, **kwargs) Bases: :py:obj:`ListXYcoordinates` XY coordinate list parameter for line geometries. Extends ListXYcoordinates as specialized alias for line/polyline definitions in spatial configurations. Args: minlen: Minimum number of points (default: 0) **kwargs: Additional keyword arguments passed to ListXYcoordinates Example: >>> boundary = XYLine(default=[(0,0), (100,0), (100,100), (0,100)]) .. py:class:: ItemListParam(default=util.ItemList(), size=(0, None), **params) Bases: :py:obj:`param.List` Parameter for managed lists with ItemList functionality. Extends param.List to enable list management functionality provided by the lib.util.ItemList class, which inherits from a custom SuperList class as well as from agentpy.AgentSequence for agent-based modeling. Attributes: size: Tuple (min, max) specifying valid list length bounds bounds: Inherited bounds attribute item_type: Type constraint for list items class_: Class constraint for list items Args: default: Default ItemList instance (default: empty ItemList()) size: Length bounds tuple (min, max) where None = unbounded **params: Additional keyword arguments passed to param.List Example: >>> agents = ItemListParam(default=util.ItemList(), size=(1, 100)) .. py:attribute:: size :value: (0, None) .. py:class:: ClassDict(default=util.AttrDict(), item_type=None, **params) Bases: :py:obj:`param.ClassSelector` Dictionary parameter with class-constrained values. Extends param.ClassSelector for AttrDict values where all dict items must be instances of a specified type, useful for typed configuration dicts. Attributes: item_type: Required type for all dictionary values (None = no constraint) class_: Fixed to util.AttrDict is_instance: Inherited from ClassSelector Args: default: Default AttrDict instance (default: empty AttrDict()) item_type: Required type for dict values (default: None = unconstrained) **params: Additional keyword arguments passed to param.ClassSelector Example: >>> configs = ClassDict(default=util.AttrDict(), item_type=NestedConf) .. py:attribute:: item_type :value: None .. py:class:: ClassAttr(class_, **kwargs) Bases: :py:obj:`param.ClassSelector` Class instance parameter with automatic initialization. Extends param.ClassSelector to automatically instantiate class from dict configs, supporting both instance and config dict as defaults. Args: class_: Target class or tuple of classes for validation **kwargs: Default value (as instance or config dict) plus ClassSelector args Example: >>> brain_param = ClassAttr(class_=Brain, default={'olfactor': {...}}) >>> brain_param.default # Brain instance created from dict .. py:class:: ModeSelector(classDict=util.AttrDict(), classID=None, class_=None, **kwargs) Bases: :py:obj:`ClassAttr` Mode selector parameter for choosing among class variants. Extends ClassAttr to select class from a dict of options by ID key, useful for behavior mode selection (e.g., 'RL' vs 'MB' memory types). Attributes: classDict: Dictionary mapping mode IDs to class types classID: Currently selected mode ID Args: classDict: Dict mapping mode names to classes (default: empty AttrDict()) classID: Initial mode selection (default: None) class_: Explicit class override (overrides classDict[classID] if provided) **kwargs: Additional keyword arguments passed to ClassAttr Example: >>> memory_mode = ModeSelector( ... classDict={'RL': RLmemory, 'MB': MBmemory}, ... classID='RL' ... ) .. py:attribute:: classDict .. py:attribute:: classID :value: None .. py:class:: DataFrameIndexed(levels=None, **params) Bases: :py:obj:`param.DataFrame` DataFrame parameter with index level validation. Extends param.DataFrame to enforce specific index level names, useful for structured datasets with required multi-index levels. Attributes: levels: Required index level names (None = no validation) rows: Inherited row constraint columns: Inherited column constraint ordered: Inherited ordering constraint Args: levels: List of required index level names (default: None) **params: Additional keyword arguments passed to param.DataFrame Example: >>> trajectory_df = DataFrameIndexed( ... levels=['AgentID', 'Step'], ... columns=['x', 'y', 'orientation'] ... ) .. py:attribute:: levels :value: None .. py:class:: StepDataFrame(**params) Bases: :py:obj:`DataFrameIndexed` DataFrame parameter for step-by-step timeseries data. Extends DataFrameIndexed with fixed index levels ['Step', 'AgentID'], used for trajectory and timeseries datasets across simulation steps. Each row represents one agent's state at one timestep. Args: **params: Additional keyword arguments passed to DataFrameIndexed (e.g., columns=['x', 'y', 'v', 'a']) Example: >>> step_data = StepDataFrame(columns=['x', 'y', 'v', 'a']) >>> # Expected index: MultiIndex(['Step', 'AgentID']) .. py:class:: EndpointDataFrame(**params) Bases: :py:obj:`DataFrameIndexed` DataFrame parameter for endpoint/summary data per agent. Extends DataFrameIndexed with fixed index level ['AgentID'], used for final metrics and endpoint statistics aggregated per agent. Each row represents one agent's complete trajectory summary. Args: **params: Additional keyword arguments passed to DataFrameIndexed (e.g., columns=['cum_d', 'cum_dur', 'max_v']) Example: >>> endpoint_data = EndpointDataFrame(columns=['cum_d', 'cum_dur', 'max_v']) >>> # Expected index: Index(['AgentID'])