larvaworld.lib.param.custom

Classes

`StringRobust`	Robust string parameter that converts any input to string.
`PositiveNumber`	Numeric parameter constrained to positive values.
`PositiveInteger`	Integer parameter constrained to positive values.
`Phase`	Phase angle parameter constrained to [0, 2π] range.
`RangeRobust`	Robust range parameter accepting both tuples and lists.
`RangeInf`	Range parameter allowing None values within tuple bounds.
`PositiveRange`	Range parameter constrained to positive number tuples.
`PhaseRange`	Phase angle range parameter constrained to [0, 2π].
`OptionalPositiveNumber`	Optional numeric parameter constrained to positive values or None.
`OptionalPositiveInteger`	Optional integer parameter constrained to positive values or None.
`RandomizedPhase`	Phase parameter with automatic random initialization.
`RandomizedColor`	Color parameter with automatic random initialization.
`OptionalPositiveRange`	Optional range parameter constrained to positive tuples or None.
`OptionalPhaseRange`	Optional phase range parameter constrained to [0, 2π] or None.
`OptionalSelector`	Selector parameter with automatic None support.
`IntegerTuple`	Numeric tuple parameter constrained to integer values.
`IntegerRange`	Range parameter constrained to integer tuple values.
`PositiveIntegerTuple`	Integer tuple parameter constrained to non-negative values.
`IntegerRangeOrdered`	Ordered integer range parameter enforcing lower <= upper.
`PositiveIntegerRange`	Integer range parameter constrained to positive values.
`PositiveIntegerRangeOrdered`	Ordered positive integer range parameter.
`NegativeIntegerRangeOrdered`	Ordered negative integer range parameter.
`OptionalPositiveIntegerRangeOrdered`	Optional ordered positive integer range parameter.
`OptionalNegativeIntegerRangeOrdered`	Optional ordered negative integer range parameter.
`NumericTuple2DRobust`	2D numeric tuple parameter accepting both tuples and lists.
`IntegerTuple2DRobust`	2D integer tuple parameter accepting both tuples and lists.
`ListXYcoordinates`	List parameter for XY coordinate tuples.
`XYLine`	XY coordinate list parameter for line geometries.
`ItemListParam`	Parameter for managed lists with ItemList functionality.
`ClassDict`	Dictionary parameter with class-constrained values.
`ClassAttr`	Class instance parameter with automatic initialization.
`ModeSelector`	Mode selector parameter for choosing among class variants.
`DataFrameIndexed`	DataFrame parameter with index level validation.
`StepDataFrame`	DataFrame parameter for step-by-step timeseries data.
`EndpointDataFrame`	DataFrame parameter for endpoint/summary data per agent.

Module Contents

class larvaworld.lib.param.custom.StringRobust(default='', **kwargs)

Bases: 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"

class larvaworld.lib.param.custom.PositiveNumber(default=0.0, softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, bounds=None, step=0.1, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.PositiveInteger(default=0, softmin=0, softmax=None, hardmin=0, hardmax=None, step=1, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.Phase(default=0.0, softmin=0.0, softmax=2 * np.pi, hardmin=0.0, hardmax=2 * np.pi, step=0.1, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.RangeRobust(default=(0.0, 0.0), step=0.1, **kwargs)

Bases: 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

class larvaworld.lib.param.custom.RangeInf(default=(0.0, 0.0), step=0.1, **kwargs)

Bases: 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]

class larvaworld.lib.param.custom.PositiveRange(default=(0.0, 0.0), softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.PhaseRange(default=(0.0, 0.0), softmin=0.0, softmax=2 * np.pi, hardmin=0.0, hardmax=2 * np.pi, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.OptionalPositiveNumber(default=None, softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, step=0.1, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.OptionalPositiveInteger(default=None, softmin=0, softmax=None, hardmin=0, hardmax=None, step=1, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.RandomizedPhase(default=None, **kwargs)

Bases: 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

class larvaworld.lib.param.custom.RandomizedColor(default=None, instantiate=True, allow_None=True, per_instance=True, **kwargs)

Bases: 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

class larvaworld.lib.param.custom.OptionalPositiveRange(default=None, softmin=0.0, softmax=None, hardmin=0.0, hardmax=None, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.OptionalPhaseRange(default=None, softmin=0.0, softmax=2 * np.pi, hardmin=0.0, hardmax=2 * np.pi, **kwargs)

Bases: 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))

class larvaworld.lib.param.custom.OptionalSelector(objects, default=None, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.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: 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)

class larvaworld.lib.param.custom.IntegerRange(default=(0, 0), step=1, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.PositiveIntegerTuple(default=(0, 0), softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs)

Bases: 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)

softmin = 0

softmax = None

hardmin = 0

hardmax = None

class larvaworld.lib.param.custom.IntegerRangeOrdered(default=(0, 0), step=1, **kwargs)

Bases: 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

class larvaworld.lib.param.custom.PositiveIntegerRange(default=(0, 0), softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.PositiveIntegerRangeOrdered(default=(0, 1), softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.NegativeIntegerRangeOrdered(default=(-1, 0), softmin=None, softmax=0, hardmin=None, hardmax=0, **kwargs)

Bases: 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))

class larvaworld.lib.param.custom.OptionalPositiveIntegerRangeOrdered(default=None, softmin=0, softmax=None, hardmin=0, hardmax=None, **kwargs)

Bases: PositiveIntegerRangeOrdered

Optional ordered positive integer range parameter.

Accepts either an ordered positive integer tuple or None.

class larvaworld.lib.param.custom.OptionalNegativeIntegerRangeOrdered(default=None, softmin=None, softmax=0, hardmin=None, hardmax=0, **kwargs)

Bases: NegativeIntegerRangeOrdered

Optional ordered negative integer range parameter.

Accepts either an ordered negative integer tuple or None.

class larvaworld.lib.param.custom.NumericTuple2DRobust(default=(0.0, 0.0), **kwargs)

Bases: 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

class larvaworld.lib.param.custom.IntegerTuple2DRobust(default=(0, 0), **kwargs)

Bases: 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

class larvaworld.lib.param.custom.ListXYcoordinates(default=[], minlen=0, maxlen=None, **kwargs)

Bases: 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)

class larvaworld.lib.param.custom.XYLine(minlen=0, **kwargs)

Bases: 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)])

class larvaworld.lib.param.custom.ItemListParam(default=util.ItemList(), size=(0, None), **params)

Bases: 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))

size = (0, None)

class larvaworld.lib.param.custom.ClassDict(default=util.AttrDict(), item_type=None, **params)

Bases: 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)

item_type = None

class larvaworld.lib.param.custom.ClassAttr(class_, **kwargs)

Bases: 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

class larvaworld.lib.param.custom.ModeSelector(classDict=util.AttrDict(), classID=None, class_=None, **kwargs)

Bases: 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'
... )

classDict

classID = None

class larvaworld.lib.param.custom.DataFrameIndexed(levels=None, **params)

Bases: 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']
... )

levels = None

class larvaworld.lib.param.custom.StepDataFrame(**params)

Bases: 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'])

class larvaworld.lib.param.custom.EndpointDataFrame(**params)

Bases: 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'])