Param

Param#

class caskade.Param(name: str, value: ArrayLike | float | int | None = None, shape: tuple[int, ...] | None = None, cyclic: bool = False, valid: tuple[ArrayLike | float | int | None] | None = None, units: str | None = None, dynamic: bool | None = None, group: int = 0, batch_shape: tuple[int] | None = None, dtype: Any | None = None, device: Any | None = None, **kwargs)[source]#

Bases: Node

Node to represent a parameter in the graph.

The Param object is used to represent a parameter in the graph. During runtime this will represent a value which can be used in various calculations. The Param object can be set to a constant value (static); None meaning the value is to be provided at runtime (dynamic); another Param object meaning it will take on that value at runtime (pointer); or a function of other Param objects to be computed at runtime (also pointer, see user guides). These options allow users to flexibly set the behavior of the simulator.

Examples

Example making some Param objects:

p1 = Param("test", (1.0, 2.0)) # constant value, length 2 vector
p2 =Param("p2", None, (2,2)) # dynamic 2x2 matrix value
p3 = Param("p3", p1) # pointer to another parameter
p4 = Param("p4", lambda p: p.children["other"].value * 2) # arbitrary function of another parameter
p5 = Param("p5", valid=(0.0,2*pi), units="radians", cyclic=True) # parameter with metadata
Parameters:

  • name ((str)) – The name of the parameter.

  • value ((Optional[Union[ArrayLike, float, int]], optional)) – The value of the parameter. Defaults to None meaning dynamic.

  • shape ((Optional[tuple[int, ...]], optional)) – The shape of the parameter. Defaults to () meaning scalar.

  • cyclic ((bool, optional)) – Whether the parameter is cyclic, imposing periodic boundary conditions. Such as a rotation from 0 to 2pi. Defaults to False.

  • valid ((Optional[tuple[Union[ArrayLike, float, int, None]]], optional)) – The valid range of the parameter. Defaults to None meaning all of -inf to inf is valid.

  • units ((Optional[str], optional)) – The units of the parameter. Defaults to None.

  • dynamic ((bool, optional)) – Force param to be dynamic if True. If a value is provided and param is dynamic then it has a default value at call time.

  • (bool (batched) – If True, the param is assumed batched and the shape may now take the form (*B, *D) where *D is the shape of the value.

  • optional) – If True, the param is assumed batched and the shape may now take the form (*B, *D) where *D is the shape of the value.

  • dtype ((Optional[Any], optional)) – The data type of the parameter. Defaults to None meaning the data type will be inferred from the value.

  • device ((Optional[Any], optional)) – The device of the parameter. Defaults to None meaning the device will be inferred from the value.

property batch_shape: tuple[int, ...]#

The batch dimensions of the parameter value.

Batch dimensions are the leading dimensions of the value that precede the event shape. If an explicit batch shape was set it is returned directly; otherwise it is inferred from the value.

Returns:

The batch shape, or () if the parameter is not batched.

Return type:

tuple of int

property batched: bool#

Whether this parameter carries batch dimensions.

Returns:

True if batch_shape is non-empty.

Return type:

bool

property cyclic: bool#

Whether the parameter has cyclic (periodic) boundary conditions.

When True, values wrap around the valid range (e.g. an angle from 0 to 2π).

Returns:

True if the parameter is cyclic.

Return type:

bool

property device: str | None#

The device on which the parameter value resides.

If no explicit device was set, the device is inferred from the current value.

Returns:

The device, or None if unknown.

Return type:

device or None

property dtype: str | None#

The data type of the parameter value.

If no explicit dtype was set, the dtype is inferred from the current value.

Returns:

The data type, or None if unknown.

Return type:

dtype or None

property dynamic: bool#

Whether this parameter is dynamic.

Returns:

True if the parameter’s value is provided at runtime.

Return type:

bool

property group: int#

The group index of this parameter.

Parameters that share the same group index are collected together into a single params object when calling a simulator’s @forward method, as well as when using get_values or set_values.

Returns:

The group index (default 0).

Return type:

int

is_valid(value=None) → bool[source]#

Check whether a value lies within the allowed range.

Parameters:

value (ArrayLike or None, optional) – The value to check. If None (default), the parameter’s current value is used.

Returns:

True if the value is within the valid range or if no constraints are set. False otherwise; a warning is also emitted.

Return type:

bool

property node_str: str#

Returns a string representation of the node for graph visualization.

property node_type#

The current type of this parameter node.

Returns:

One of "static", "dynamic", or "pointer".

Return type:

str

property npvalue: ndarray#

The current value converted to a NumPy array.

Returns:

The value as a NumPy ndarray.

Return type:

numpy.ndarray

property pointer: bool#

Whether this parameter is a pointer.

Returns:

True if the parameter points to another Param or a callable that is evaluated at runtime.

Return type:

bool

property shape: tuple[int, ...]#

The event (non-batch) shape of the parameter value.

Wildcard dimensions (None) in the declared shape are resolved using the current value. If no shape was declared, the shape of the current value is returned directly.

Returns:

The resolved shape of the parameter.

Return type:

tuple of int

property static: bool#

Whether this parameter is static.

Returns:

True if the parameter holds a fixed value that does not change at runtime.

Return type:

bool

to(device=None, dtype=None) → Param[source]#

Moves and/or casts the values of the parameter.

Parameters:

  • device ((optional)) – The device to move the values to. Defaults to None.

  • dtype ((optional)) – The desired data type. Defaults to None.

to_dynamic(value=<object object>)[source]#

Change this parameter to a dynamic parameter.

If a value is provided, it is stored as the default dynamic value. When called without arguments the existing value (if any) is kept.

Parameters:

value (ArrayLike, float, int, None, or sentinel, optional) – The default value for the dynamic parameter. Must not be a Param or callable. By default the current value is retained.

Raises:
to_pointer(value, link=())[source]#

Change this parameter to a pointer parameter.

The parameter’s value will be computed at runtime by dereferencing another Param or by calling a user-supplied function.

Parameters:

  • value (Param or callable) – A Param whose value will be mirrored, or a callable f(param) -> ArrayLike evaluated at runtime.

  • link (Node or tuple of Node, optional) – Additional nodes to link into the graph when creating the pointer. Defaults to an empty tuple.

Raises:
to_static(value=<object object>)[source]#

Change this parameter to a static parameter.

If a value is provided, it is stored as the fixed static value. When called without arguments the existing value (if any) is kept.

Parameters:

value (ArrayLike, float, int, None, or sentinel, optional) – The constant value for the static parameter. Must not be a Param or callable. By default the current value is retained.

Raises:
property valid: tuple[ArrayLike | None, ArrayLike | None]#

The valid range of the parameter value.

Returns:

(lower_bound, upper_bound). Either bound may be None indicating no constraint on that side.

Return type:

tuple of (ArrayLike or None, ArrayLike or None)

property value: ArrayLike | None#

The current value of the parameter.

For static and dynamic parameters the stored value is returned. For pointer parameters the linked callable is evaluated. During an active simulation the result is cached.

Returns:

The parameter value, or None if no value has been set.

Return type:

ArrayLike or None