archimedes.tree.struct¶

archimedes.tree.struct(

cls: T | None = None,

**kwargs,

) → T | Callable¶

Decorator to convert a class into a tree-compatible frozen dataclass.

This decorator creates a structured data class that can be seamlessly used with structree’s tree functions. The class will be registered with the tree system, allowing its instances to be flattened, mapped over, and transformed while preserving its structure.

Parameters:

cls (type, optional) – The class to convert into a tree-compatible dataclass.
**kwargs (dict) – Additional keyword arguments passed to dataclasses.dataclass(). By default, frozen=True is set unless explicitly overridden.

Returns:

decorated_class – The decorated class, now a frozen dataclass registered as tree-compatible.

Return type:

type

Notes

The “frozen” attribute makes the class immutable. The replace() method allows you to create modified copies of the object with new values for specific fields.

Fields are automatically classified as either “data” (dynamic values that change during operations) or “static” (configuration parameters). By default, all fields are treated as data unless marked with field(static=True).

The decorated class:

Is frozen (immutable) by default
Has a replace() method for creating modified copies
Will be properly handled by flatten(), map(), etc.
Can be nested within other tree nodes (structs, dicts, tuples, etc.)

Examples

>>> import structree as st
>>> import numpy as np
>>>
>>> @st.struct
>>> class Vehicle:
...     position: np.ndarray
...     velocity: np.ndarray
...     mass: float = st.field(static=True, default=1000.0)
>>>
>>> car = Vehicle(np.zeros(2), np.array([10.0, 0.0]))
>>> car2 = car.replace(position=np.array([5.0, 0.0]))
>>> scaled = st.map(lambda x: x * 2, car)