Actor

Actor

An exogenous energy consumer or producer based on a Signal.

Actors represent non-dispatchable energy devices whose power output is determined externally like solar panels, wind turbines, or (compute) loads.

Parameters:

Name	Type	Description	Default
name	str	The name of the actor.	required
signal	Signal	The Signal that determines the power consumption/production. Can be a StaticSignal for constant power, a Trace for time series data, or any custom signal (e.g., based on real-time monitoring).	required
consumer	bool	If True, the signal value is negated (Vessim convention: consumption is negative, production is positive). Defaults to False.	False
step_size	Optional[int]	The step size of the actor in seconds. If None, the step size of the microgrid is used.	None

Source code in vessim/actor.py

class Actor:
    """An exogenous energy consumer or producer based on a `Signal`.

    Actors represent non-dispatchable energy devices whose power output is
    determined externally like solar panels, wind turbines, or (compute) loads.

    Args:
        name: The name of the actor.
        signal: The `Signal` that determines the power consumption/production. Can be
            a `StaticSignal` for constant power, a `Trace` for time series data, or any
            custom signal (e.g., based on real-time monitoring).
        consumer: If True, the signal value is negated (Vessim convention: consumption
            is negative, production is positive). Defaults to False.
        step_size: The step size of the actor in seconds. If None, the step size
            of the microgrid is used.
    """

    def __init__(
        self,
        name: str,
        signal: Signal,
        consumer: bool = False,
        step_size: Optional[int] = None,
    ) -> None:
        self.name = name
        self.step_size = step_size
        self.signal = signal
        self.consumer = consumer

    def power(self, elapsed: timedelta | float) -> float:
        """Current power consumption/production at `elapsed` time since `sim_start`."""
        value = self.signal.at(elapsed)
        return -value if self.consumer else value

    def config(self) -> dict:
        """Static configuration of the actor. Used for experiment config export."""
        return {
            "name": self.name,
            "signal": str(self.signal),
            "consumer": self.consumer,
            "step_size": self.step_size,
        }

    def state(self, elapsed: timedelta | float) -> dict:
        """Dynamic state of the actor at `elapsed` time since `sim_start`.

        This can be extended to include any relevant information about e.g. internal
        states of simulators that may be useful for control (e.g. temperature) or logs.
        """
        return {"power": self.power(elapsed)}

    def finalize(self) -> None:
        """Clean up resources."""
        self.signal.finalize()

power

Current power consumption/production at elapsed time since sim_start.

Source code in vessim/actor.py

def power(self, elapsed: timedelta | float) -> float:
    """Current power consumption/production at `elapsed` time since `sim_start`."""
    value = self.signal.at(elapsed)
    return -value if self.consumer else value

config

Static configuration of the actor. Used for experiment config export.

Source code in vessim/actor.py

def config(self) -> dict:
    """Static configuration of the actor. Used for experiment config export."""
    return {
        "name": self.name,
        "signal": str(self.signal),
        "consumer": self.consumer,
        "step_size": self.step_size,
    }

state

Dynamic state of the actor at elapsed time since sim_start.

This can be extended to include any relevant information about e.g. internal states of simulators that may be useful for control (e.g. temperature) or logs.

Source code in vessim/actor.py

def state(self, elapsed: timedelta | float) -> dict:
    """Dynamic state of the actor at `elapsed` time since `sim_start`.

    This can be extended to include any relevant information about e.g. internal
    states of simulators that may be useful for control (e.g. temperature) or logs.
    """
    return {"power": self.power(elapsed)}

finalize

Clean up resources.

Source code in vessim/actor.py

def finalize(self) -> None:
    """Clean up resources."""
    self.signal.finalize()