ochre_gym.spaces.obs_spaces

OchreObservationSpaceBaseConfig

ochre_gym.spaces.obs_spaces.OchreObservationSpaceBaseConfig

Bases: ABC

Base class for OCHRE observation space configuration. Also provides two hooks for customizing the observation space and customizing the observations from OCHRE.

A reduced set of OCHRE observations is defined in parameter OCHRE_GYM_REDUCED_KEYS:

'Temperature - Indoor (C)',  # Envelope
'Temperature - Outdoor (C)',  # Envelope
'Total Electric Power (kW)',  # Dwelling
'Total Gas Power (therms/hour)', # Dwelling
'HVAC Heating Electric Power (kW)', # HVAC Heating
'HVAC Heating Gas Power (therms/hour)', # HVAC Heating
'HVAC Cooling Electric Power (kW)', # HVAC Cooling,
'Water Heating Gas Power (therms/hour)', # Water Heating
'Water Heating Electric Power (kW)', # Water Heating,
'EV Electric Power', # EV
'PV Electric Power', # PV
'Battery Electric Power', # Battery,
'Gas Generator Electric Power', # Gas Generator
'Gas Generator Gas Power', # Gas Generator

__init__(observation_args: Dict, vectorize_observations: bool, use_all_ochre_observations: bool, override_ochre_observations_with_keys: Optional[List[str]])

Initialize the OCHRE observation space configuration.

Parameters:

Name	Type	Description	Default
observation_args	Dict	A dictionary of keyword arguments.	required
vectorize_observations	bool	Whether to vectorize observations.	required
use_all_ochre_observations	bool	Whether to use all OCHRE observations or not.	required
override_ochre_observations_with_keys	Optional[List[str]]	A list of keys to override the OCHRE observations with. If None, then use all OCHRE observations.	required

customize_observation_space_hook(observations: Dict) -> Dict abstractmethod

A hook to specify a custom observation space for OCHRE Gym. If vectorizing observations, performed beforehand. By default, does nothing. Override this in subclass.

Parameters:

Name	Type	Description	Default
observations	Dict	A dictionary of observations.	required

Returns:

Name	Type	Description
observations	Dict	A dictionary of observations.

customize_observations_from_ochre_hook(observations: Dict, ochre_control_result: Dict, args: Dict) -> Dict abstractmethod

A hook enabling a user to augment a given observation based on the OCHRE control result and extra info.

Parameters:

Name	Type	Description	Default
observations	Dict	A dictionary of observations.	required
ochre_control_result	Dict	A dictionary of control results from OCHRE.	required
args	Dict	A dictionary of extra info to help create the desired observation.	required

Returns:

Name	Type	Description
observations	Dict	The customized dictionary of observations.

TimeAndEnergyPriceObservationSpaceConfig

ochre_gym.spaces.obs_spaces.TimeAndEnergyPriceObservationSpaceConfig

Bases: OchreObservationSpaceBaseConfig

A custom configuration for the observation space that adds time and energy price, which are not included in the OCHRE observations by default.

__init__(observation_args, vectorize_observations, use_all_ochre_observations, override_ochre_observations_with_keys)

Initialize the observation space configuration.

Expects that the observation_args dictionary has a 'reward_args' key with a 'dr_type' sub-key. If 'dr_type' is 'RTP', then the observation space will include a vector of energy prices. If 'dr_type' is 'PC', then the observation space will include a vector of power limits.

Expects that the observation_args dictionary has a 'lookahead_steps' key with a value of the number of steps to look ahead. If 'lookahead_steps' is None, then the observation space will include a single energy price or power limit value.

Parameters:

Name	Type	Description	Default
observation_args	Dict	A dictionary of keyword arguments.	required
vectorize_observations	bool	Whether to vectorize observations.	required
use_all_ochre_observations	bool	Whether to use all OCHRE observations or a default reduced set.	required
override_ochre_observations_with_keys	Optional[List[str]]	A list of keys to override the OCHRE observations with. If None, then use all OCHRE observations.	required

customize_observation_space_hook(observations: Dict) -> Dict

Customize the observation space by adding time and energy price observations.

Parameters:

Name	Type	Description	Default
observations	Dict	A dictionary of observations to customize.	required

Returns:

Name	Type	Description
observations	Dict	The customized dictionary of observations.

customize_observations_from_ochre_hook(observations: Dict, ochre_control_result: Dict, args: Dict) -> Dict

Add time and energy price observations from the OCHRE control result.

Parameters:

Name	Type	Description	Default
observations	Dict	A dictionary of observations.	required
ochre_control_result	Dict	A dictionary of control results from OCHRE.	required
args	Dict	A dictionary of extra info to help create the desired observation.	required

Returns:

Name	Type	Description
observations	Dict	The customized dictionary of observations.

MetadataObservationSpaceConfig

ochre_gym.spaces.obs_spaces.MetadataObservationSpaceConfig

Bases: TimeAndEnergyPriceObservationSpaceConfig

A configuration for the observation space that:

• Adds time and energy price observations
• Adds metadata:
  • Has Attic (binary)
  • Has Garage (binary)
  • Square Footage (float)
  • Number of Bedrooms (int)

__init__(observation_args, vectorize_observations, use_all_ochre_observations, override_ochre_observations_with_keys)

Initialize the OCHRE observation space configuration.

Parameters:

Name	Type	Description	Default
observation_args	Dict	A dictionary of keyword arguments.	required
vectorize_observations	bool	Whether to vectorize observations.	required
use_all_ochre_observations	bool	Whether to use all OCHRE observations or not.	required
override_ochre_observations_with_keys	Optional[List[str]]	A list of keys to override the OCHRE observations with. If None, then use all OCHRE observations.	required

customize_observation_space_hook(observations: Dict) -> Dict

Customize the observation space by adding metadata observations.

Parameters:

Name	Type	Description	Default
observations	Dict	A dictionary of observations to customize.	required

Returns:

Name	Type	Description
observations	Dict	The customized dictionary of observations.

customize_observations_from_ochre_hook(observations, control_result, args)

Customize the observations from OCHRE by adding metadata observations.

Parameters:

Name	Type	Description	Default
observations	Dict	A dictionary of observations.	required

Returns:

Name	Type	Description
observations	Dict	The customized dictionary of observations.

OchreObservationSpace

ochre_gym.spaces.obs_spaces.OchreObservationSpace

A class for creating an OCHRE Gym observation space and managing it. Expects an OchreObservationSpaceBaseConfig object to be passed in the constructor that specifies how to configure the observation space. Users should subclass the OchreObservationSpaceBaseConfig class to create their own custom observation if desired.

Keys in the observation space are ordered alphabetically.

__init__(observation_space_config: OchreObservationSpaceBaseConfig, dwelling: Dwelling, dwelling_metadata: Dict)

Initialize the OchreObservationSpace.

Parameters:

Name	Type	Description	Default
observation_space_config	OchreObservationSpaceBaseConfig	A configuration object for the observation space.	required
dwelling	Dwelling	An OCHRE dwelling object.	required
dwelling_metadata	Dict	A dictionary of dwelling metadata.	required

get_obs_space_from_ochre() -> Tuple[Union[spaces.Dict, spaces.Box], List[str]]

Obtain observation space using an OCHRE dwelling simulation.

Either returns a composite (Dict) or flattened (vector) observation space. This is decided by the observation_space_config.vectorize_observations parameter.

Returns:

Name	Type	Description
observation_space	Union[spaces.Dict, spaces.Box]	The observation space.
observation_keys	List[str]	The observation keys. Sets the class parameter self.observation_keys.

ochre_control_result_to_observation(control_result: Dict, observation_args: Dict) -> Union[np.ndarray, Dict[str, np.ndarray]]

Convert an OCHRE control result to an observation.

Parameters:

Name	Type	Description	Default
control_result	Dict	A dictionary of control results from OCHRE.	required
observation_args	Dict	A dictionary of keyword arguments.	required

Returns:

Type	Description
Union[np.ndarray, Dict[str, np.ndarray]]	A numpy array or a dictionary of observations.

unflatten_observation(vector_observation: np.array) -> OrderedDict

Given a vector observation, unflatten into a dict.

Parameters:

Name	Type	Description	Default
vector_observation	np.array	A vector observation.	required

Returns:

Name	Type	Description
dict_obs	OrderedDict	A dictionary of observations.