Models

smart_control.models.base_building

Base class that extends functionality outside of the building.

The base class should be extended by the simulation and actual buildings.

BaseBuilding

Base class for a controllable building for reinforcement learning.

current_timestamp abstractmethod property

current_timestamp: Timestamp

Lists the current local time of the building.

devices abstractmethod property

devices: Sequence[DeviceInfo]

Lists the devices that can be queried and/or controlled.

num_occupants abstractmethod property

num_occupants: int

Returns the number of occupants in building.

reward_info abstractmethod property

reward_info: RewardInfo

Returns a message with data to compute the instantaneous reward.

time_step_sec abstractmethod property

time_step_sec: float

Returns the amount of time between time steps.

zones abstractmethod property

zones: Sequence[ZoneInfo]

Lists the zones in the building managed by the RL agent.

is_comfort_mode abstractmethod

is_comfort_mode(current_time: Timestamp) -> bool

Returns True if building is in comfort mode.

render abstractmethod

render(path: str) -> None

Renders the current state of the building.

request_action abstractmethod

request_action(
    action_request: ActionRequest,
) -> smart_control_building_pb2.ActionResponse

Issues a command to the building to change one or more setpoints.

request_observations abstractmethod

request_observations(
    observation_request: ObservationRequest,
) -> smart_control_building_pb2.ObservationResponse

Queries the building for its current state.

request_observations_within_time_interval abstractmethod

request_observations_within_time_interval(
    observation_request: ObservationRequest,
    start_timestamp: Timestamp,
    end_timestamp: Timestamp,
) -> Sequence[smart_control_building_pb2.ObservationResponse]

Queries the building for observations between start and end times.

reset abstractmethod

reset() -> None

Resets the building, throwing an RuntimeError if this is impossible.

wait_time abstractmethod

wait_time() -> None

Returns after a certain amount of time.

smart_control.models.base_energy_cost

Base class for energy cost and carbon, for use in reward function.

BaseEnergyCost

Class that returns a cost for energy consumed over a time interval.

carbon abstractmethod

carbon(start_time: Timestamp, end_time: Timestamp, energy_rate: float) -> float

Returns the mass of carbon emitted from the energy consumption.

The energy-to-carbon emission is source specific. Assuming a constant rate of energy consumption (W) of the time interval bounded by start_time and end_time, we can estimate total energy use (J). The type of source will convert energy into carbon mass (kg).

Parameters:

Name	Type	Description	Default
start_time	Timestamp	starting local time for the energy use.	required
end_time	Timestamp	ending local time for the energy use.	required
energy_rate	float	constant-rate power in Watts consumed over the interval.	required

Returns: carbon mass (kg) emitted

cost abstractmethod

cost(start_time: Timestamp, end_time: Timestamp, energy_rate: float) -> float

Computes cost in USD for energy consumed from start_time to end_time.

Fundamentally, energy cost is computed as: energy_consumed [J] = energy_rate [W] * (end_time - start_time) [s] energy_cost = energy_consumed [J] * energy_price [USD/J]

Most utilities use different units for their pricing, such as kWh, Btu/hr, cubic feet per minute, etc., so implementations will have to perform all necessary conversions internally.

Parameters:

Name	Type	Description	Default
start_time	Timestamp	starting local time for the energy use.	required
end_time	Timestamp	ending local time for the energy use.	required
energy_rate	float	constant-rate power in Watts consumed over the interval.	required

Returns: cost in USD of the energy consumed over the interval.

smart_control.models.base_normalizer

Defines observation and action normalizer base classes.

BaseActionNormalizer

Translates native agent action values into normalized setpoint values.

setpoint_max abstractmethod property

setpoint_max: float

Returns the maximum setpoint value.

setpoint_min abstractmethod property

setpoint_min: float

Returns the minimum setpoint value.

agent_value abstractmethod

agent_value(setpoint_value: float) -> float

Returns the normalized setpoint_value as an agent action.

Parameters:

Name	Type	Description	Default
setpoint_value	float	Value in native units.	required

get_array_spec abstractmethod

get_array_spec(name=None) -> specs.ArraySpec

Returns array_spec for the action.

This informs the agent how many values to output, which will get transformed into a single value for the setpoint.

Parameters:

Name	Type	Description	Default
name		Name to pass to the ArraySpec	None

setpoint_value abstractmethod

setpoint_value(agent_action: ndarray) -> float

Returns value to apply to building given agent action values.

Parameters:

Name	Type	Description	Default
agent_action	ndarray	Values returned directly from agent, compatible with array_spec.	required

BaseObservationNormalizer

Normalizer base class for Observations.

denormalize abstractmethod

denormalize(
    normalized: ObservationResponse,
) -> smart_control_building_pb2.ObservationResponse

De-normalizes an Observation response.

normalize abstractmethod

normalize(
    native: ObservationResponse,
) -> smart_control_building_pb2.ObservationResponse

Normalizes an Observation response.

smart_control.models.base_occupancy

Defines an occupancy model that returns the average number of occupants.

Occupancy refers to the average number of people in a zone within a specified period of time. Concrete classes can either simulate the occupancy or estimate the occupancy from Calendar or motion sensors in the buildings.

The occupancy signal is an input to the agent's reward function.

BaseOccupancy

Provides the RL agent information about how many people are in a zone.

average_zone_occupancy abstractmethod

average_zone_occupancy(
    zone_id: str, start_time: Timestamp, end_time: Timestamp
) -> float

Returns the occupancy within start_time, end_time for the zone.

If the zone is not found, implementations should raise a ValueError.

Parameters:

Name	Type	Description	Default
zone_id	str	specific zone identifier for the building.	required
start_time	Timestamp	local time w/ TZ for the beginning of the interval.	required
end_time	Timestamp	local time w/ TZ for the end of the interval.	required

Returns:

Type	Description
float	average number of people in the zone for the interval.

smart_control.models.base_reward_function

Base class for smart buildings reward function.

BaseRewardFunction

Base class that converts the building energy information into a reward.

compute_reward abstractmethod

compute_reward(
    reward_info: RewardInfo,
) -> smart_control_reward_pb2.RewardResponse

Returns the real-valued reward for the current state of the building.