Skip to content

gds.state

Bases: Tagged

A named component of the system state.

In GDS terms, the full state space X is the product of all entity state spaces. Entities correspond to actors, resources, registries — anything that persists across timesteps.

Source code in packages/gds-framework/gds/state.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class Entity(Tagged):
    """A named component of the system state.

    In GDS terms, the full state space X is the product of all entity
    state spaces. Entities correspond to actors, resources, registries —
    anything that persists across timesteps.
    """

    name: str
    variables: dict[str, StateVariable] = Field(default_factory=dict)
    description: str = ""
    model_config = ConfigDict(frozen=True)

    def validate_state(self, data: dict[str, Any]) -> list[str]:
        """Validate a state snapshot for this entity.

        Returns a list of error strings (empty means valid).
        """
        errors: list[str] = []
        for vname, var in self.variables.items():
            if vname not in data:
                errors.append(f"{self.name}.{vname}: missing")
            elif not var.check_value(data[vname]):
                errors.append(f"{self.name}.{vname}: type/constraint violation")
        return errors

validate_state(data)

Validate a state snapshot for this entity.

Returns a list of error strings (empty means valid).

Source code in packages/gds-framework/gds/state.py 
52
53
54
55
56
57
58
59
60
61
62
63
def validate_state(self, data: dict[str, Any]) -> list[str]:
    """Validate a state snapshot for this entity.

    Returns a list of error strings (empty means valid).
    """
    errors: list[str] = []
    for vname, var in self.variables.items():
        if vname not in data:
            errors.append(f"{self.name}.{vname}: missing")
        elif not var.check_value(data[vname]):
            errors.append(f"{self.name}.{vname}: type/constraint violation")
    return errors

Bases: BaseModel

A single typed variable within an entity's state.

Each variable has a TypeDef (with runtime constraints), a human-readable description, and an optional math symbol.

Source code in packages/gds-framework/gds/state.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
class StateVariable(BaseModel):
    """A single typed variable within an entity's state.

    Each variable has a TypeDef (with runtime constraints),
    a human-readable description, and an optional math symbol.
    """

    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)

    name: str
    typedef: TypeDef
    description: str = ""
    symbol: str = ""

    def check_value(self, value: Any) -> bool:
        """Check if a value satisfies this variable's type definition."""
        return self.typedef.check_value(value)

check_value(value)

Check if a value satisfies this variable's type definition.

Source code in packages/gds-framework/gds/state.py 
34
35
36
def check_value(self, value: Any) -> bool:
    """Check if a value satisfies this variable's type definition."""
    return self.typedef.check_value(value)