From 084f0f5b82e36d2429c6731ec09fba62cae96083 Mon Sep 17 00:00:00 2001 From: Mustapha-Yinka Yusuf Date: Mon, 24 Aug 2026 19:33:24 +0100 Subject: [PATCH 1/2] Fix mkdocs autoref links to use reference-style syntax (#107) --- smart_control/dataset/dataset.py | 6 +-- smart_control/dataset/partition.py | 42 +++++++++---------- .../simulator/building_radiation_utils.py | 2 +- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/smart_control/dataset/dataset.py b/smart_control/dataset/dataset.py index 435f7ed1..2a4742be 100644 --- a/smart_control/dataset/dataset.py +++ b/smart_control/dataset/dataset.py @@ -78,7 +78,7 @@ def download(self, timeout=60): """Downloads the building's dataset from Google Cloud Storage. Only downloads and unzips the dataset if it doesn't already exist at the - expected [`building_dirpath`](./#smart_control.dataset.dataset.BuildingDataset.building_dirpath) + expected [`building_dirpath`][smart_control.dataset.dataset.BuildingDataset.building_dirpath] location. Otherwise it will load the existing local data. Download speed is fairly quick, but unzipping takes a few moments. @@ -119,7 +119,7 @@ def floorplan(self) -> np.ndarray: + 1: wall / boundary + 2: outside / external space - Use the [`display_floorplan`](./#smart_control.dataset.dataset.BuildingDataset.display_floorplan) + Use the [`display_floorplan`][smart_control.dataset.dataset.BuildingDataset.display_floorplan] method to view an image of the floorplan. """ return np.load(self.floorplan_filepath) @@ -149,7 +149,7 @@ def display_floorplan( show (bool): Whether or not to show the image. save (bool): Whether or not to save the image (as a .png file). image_filepath (str): An optional custom filepath to use when saving the - image. Only applies if `save=True`. By default, saves to the [`floorplan_image_filepath`](./#smart_control.dataset.dataset.BuildingDataset.floorplan_image_filepath) + image. Only applies if `save=True`. By default, saves to the [`floorplan_image_filepath`][smart_control.dataset.dataset.BuildingDataset.floorplan_image_filepath] """ plt.imshow(self.floorplan, interpolation="nearest", cmap=cmap) if show: diff --git a/smart_control/dataset/partition.py b/smart_control/dataset/partition.py index ebfee3fc..0f358ba0 100644 --- a/smart_control/dataset/partition.py +++ b/smart_control/dataset/partition.py @@ -84,7 +84,7 @@ def metadata_filepath(self): @cached_property def metadata(self) -> dict: - """Metadata describing the partition [`data`](./#smart_control.dataset.partition.BuildingDatasetPartition.data). + """Metadata describing the partition [`data`][smart_control.dataset.partition.BuildingDatasetPartition.data]. Returns: A dictionary containing the following keys: @@ -146,9 +146,9 @@ def action_ids_map(self) -> dict: """A mapping of unique action identifiers. Returns: - A dictionary where the keys are the [`action_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_ids) + A dictionary where the keys are the [`action_ids`][smart_control.dataset.partition.BuildingDatasetPartition.action_ids] and the values are unique integers referencing column indices in the - [`action_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix) + [`action_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix] For example: @@ -167,9 +167,9 @@ def observation_ids_map(self) -> dict: """A mapping of unique observation identifiers. Returns: - A dictionary where the keys are the [`observation_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_ids) + A dictionary where the keys are the [`observation_ids`][smart_control.dataset.partition.BuildingDatasetPartition.observation_ids] and the values are unique integers referencing column indices in the - [`observation_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix). + [`observation_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix]. For example: @@ -190,8 +190,8 @@ def reward_info_ids_map(self) -> dict: See: `RewardInfo` in "smart_control/proto/smart_control_reward.proto". Returns: - A dictionary where the keys are the [`reward_info_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids) - and the values are unique integers referencing column indices in the [`reward_info_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix). + A dictionary where the keys are the [`reward_info_ids`][smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids] + and the values are unique integers referencing column indices in the [`reward_info_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix]. For example: @@ -212,8 +212,8 @@ def reward_ids_map(self) -> dict: See: `RewardResponse` in "smart_control/proto/smart_control_reward.proto". Returns: - A dictionary where the keys are the [`reward_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_ids) - and the values are unique integers referencing column indices in the [`reward_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix). + A dictionary where the keys are the [`reward_ids`][smart_control.dataset.partition.BuildingDatasetPartition.reward_ids] + and the values are unique integers referencing column indices in the [`reward_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix]. """ return { "agent_reward_value": 0, @@ -344,9 +344,9 @@ def actions_df(self) -> pd.DataFrame: """A time-series dataframe of numeric action values, constructed from the following components: - + Columns are the [`action_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_ids) - + Row indices are the [`action_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_timestamps) - + Cell values are from the [`action_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix) + + Columns are the [`action_ids`][smart_control.dataset.partition.BuildingDatasetPartition.action_ids] + + Row indices are the [`action_timestamps`][smart_control.dataset.partition.BuildingDatasetPartition.action_timestamps] + + Cell values are from the [`action_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.action_value_matrix] Returns: A `pandas.DataFrame`. Here is an example of the structure: @@ -373,9 +373,9 @@ def observations_df(self) -> pd.DataFrame: """A time-series dataframe of numeric observation values, constructed from the following components: - + Columns are the [`observation_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_ids) - + Row indices are the [`observation_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_timestamps) - + Cell values are from the [`observation_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix) + + Columns are the [`observation_ids`][smart_control.dataset.partition.BuildingDatasetPartition.observation_ids] + + Row indices are the [`observation_timestamps`][smart_control.dataset.partition.BuildingDatasetPartition.observation_timestamps] + + Cell values are from the [`observation_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.observation_value_matrix] Returns: A `pandas.DataFrame`. Here is an example of the structure: @@ -402,9 +402,9 @@ def rewards_df(self) -> pd.DataFrame: """A time-series dataframe of numeric reward values, constructed from the following components: - + Columns are the [`reward_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_ids) - + Row indices are the [`reward_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_timestamps) - + Cell values are from the [`reward_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix) + + Columns are the [`reward_ids`][smart_control.dataset.partition.BuildingDatasetPartition.reward_ids] + + Row indices are the [`reward_timestamps`][smart_control.dataset.partition.BuildingDatasetPartition.reward_timestamps] + + Cell values are from the [`reward_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix] Returns: A `pandas.DataFrame`. Here is an example of the structure: @@ -430,9 +430,9 @@ def reward_infos_df(self) -> pd.DataFrame: """A time-series dataframe of numeric reward info values, constructed from the following components: - + Columns are the [`reward_info_ids`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids) - + Row indices are the [`reward_info_timestamps`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_timestamps) - + Cell values are from the [`reward_info_value_matrix`](./#smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix) + + Columns are the [`reward_info_ids`][smart_control.dataset.partition.BuildingDatasetPartition.reward_info_ids] + + Row indices are the [`reward_info_timestamps`][smart_control.dataset.partition.BuildingDatasetPartition.reward_info_timestamps] + + Cell values are from the [`reward_info_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.reward_info_value_matrix] Returns: A `pandas.DataFrame`. Here is an example of the structure: diff --git a/smart_control/simulator/building_radiation_utils.py b/smart_control/simulator/building_radiation_utils.py index 180ef1e5..5f714c69 100644 --- a/smart_control/simulator/building_radiation_utils.py +++ b/smart_control/simulator/building_radiation_utils.py @@ -82,7 +82,7 @@ def calculate_ifa_inv(F: np.ndarray, A_inv: np.ndarray) -> np.ndarray: $$IFA_{inv} = (I - F) \tilde{A}^{-1}$$ - See [`net_radiative_heatflux_function_of_T`](./#smart_control.simulator.building_radiation_utils.net_radiative_heatflux_function_of_T) for more details. + See [`net_radiative_heatflux_function_of_T`][smart_control.simulator.building_radiation_utils.net_radiative_heatflux_function_of_T] for more details. Args: F (np.ndarray): The view factor matrix. From 92eb44f033a5634436a80100c8de14155992f7c8 Mon Sep 17 00:00:00 2001 From: Mustapha-Yinka Yusuf Date: Fri, 28 Aug 2026 23:01:29 +0100 Subject: [PATCH 2/2] Fix line-too-long lint errors and typo case in autoref anchor --- smart_control/dataset/dataset.py | 8 ++++++ smart_control/dataset/partition.py | 25 +++++++++++++------ .../simulator/building_radiation_utils.py | 14 ++++++++++- 3 files changed, 38 insertions(+), 9 deletions(-) diff --git a/smart_control/dataset/dataset.py b/smart_control/dataset/dataset.py index 2a4742be..3565782e 100644 --- a/smart_control/dataset/dataset.py +++ b/smart_control/dataset/dataset.py @@ -68,12 +68,15 @@ def zip_filepath(self): return os.path.join(DATA_DIR, self.zip_filename) @property + # pylint: disable=line-too-long def building_dirpath(self): """The local directory containing the building's dataset, after it has been extracted from the local zip file. """ + # pylint: enable=line-too-long return os.path.join(DATA_DIR, self.dataset_id) + # pylint: disable=line-too-long def download(self, timeout=60): """Downloads the building's dataset from Google Cloud Storage. @@ -83,6 +86,7 @@ def download(self, timeout=60): Download speed is fairly quick, but unzipping takes a few moments. """ + # pylint: enable=line-too-long if os.path.isdir(self.building_dirpath): print("Using previously-downloaded data...") print(os.path.abspath(self.building_dirpath)) @@ -110,6 +114,7 @@ def floorplan_filepath(self): return os.path.join(self.tabular_dirpath, "floorplan.npy") @cached_property + # pylint: disable=line-too-long def floorplan(self) -> np.ndarray: """The building's floorplan, as a numpy array. @@ -122,6 +127,7 @@ def floorplan(self) -> np.ndarray: Use the [`display_floorplan`][smart_control.dataset.dataset.BuildingDataset.display_floorplan] method to view an image of the floorplan. """ + # pylint: enable=line-too-long return np.load(self.floorplan_filepath) @property @@ -130,6 +136,7 @@ def floorplan_image_filepath(self): floorplan_image_filename = f"{self.dataset_id}_floorplan.png" return os.path.join(DOCS_DIR, "assets", "images", floorplan_image_filename) + # pylint: disable=line-too-long def display_floorplan( self, cmap="binary", @@ -151,6 +158,7 @@ def display_floorplan( image_filepath (str): An optional custom filepath to use when saving the image. Only applies if `save=True`. By default, saves to the [`floorplan_image_filepath`][smart_control.dataset.dataset.BuildingDataset.floorplan_image_filepath] """ + # pylint: enable=line-too-long plt.imshow(self.floorplan, interpolation="nearest", cmap=cmap) if show: plt.show() diff --git a/smart_control/dataset/partition.py b/smart_control/dataset/partition.py index 0f358ba0..f2bce198 100644 --- a/smart_control/dataset/partition.py +++ b/smart_control/dataset/partition.py @@ -77,12 +77,12 @@ def data(self) -> np.lib.npyio.NpzFile: See corresponding documentation below for more information about each. """ return np.load(self.data_filepath) - @property def metadata_filepath(self): return os.path.join(self.partition_dirpath, "metadata.pickle") @cached_property + # pylint: disable=line-too-long def metadata(self) -> dict: """Metadata describing the partition [`data`][smart_control.dataset.partition.BuildingDatasetPartition.data]. @@ -100,6 +100,7 @@ def metadata(self) -> dict: Each of these keys has a corresponding public method for convenience. See corresponding documentation below for more information about each. """ + # pylint: enable=line-too-long metadata = pickle.load(open(self.metadata_filepath, "rb")) # renaming keys: metadata = { @@ -136,12 +137,12 @@ def reward_value_matrix(self) -> np.ndarray: def reward_info_value_matrix(self) -> np.ndarray: """Time series reward information data.""" return self.data["reward_info_value_matrix"] - # # METADATA PROPERTIES # @cached_property + # pylint: disable=line-too-long def action_ids_map(self) -> dict: """A mapping of unique action identifiers. @@ -152,17 +153,19 @@ def action_ids_map(self) -> dict: For example: - ```py +```py { '12945159110931775488@supply_air_temperature_setpoint': 0, '13761436543392677888@supply_water_temperature_setpoint': 1, '14409954889734029312@supply_air_temperature_setpoint': 2 } - ``` +``` """ + # pylint: enable=line-too-long return self.metadata["action_ids_map"] @cached_property + # pylint: disable=line-too-long def observation_ids_map(self) -> dict: """A mapping of unique observation identifiers. @@ -173,17 +176,19 @@ def observation_ids_map(self) -> dict: For example: - ```py +```py { '202194278473007104@building_air_static_pressure_setpoint', 0, ... '2640423556868160@zone_air_temperature_sensor': 1197 } - ``` +``` """ + # pylint: enable=line-too-long return self.metadata["observation_ids_map"] @cached_property + # pylint: disable=line-too-long def reward_info_ids_map(self) -> dict: """A mapping of unique reward info identifiers. @@ -195,17 +200,19 @@ def reward_info_ids_map(self) -> dict: For example: - ```py +```py { 'rooms/9028552126@heating_setpoint_temperature': 0 ... '14409954889734029312@air_conditioning_electrical_energy_rate': 3251 } - ``` +``` """ + # pylint: enable=line-too-long return self.metadata["reward_info_ids_map"] @cached_property + # pylint: disable=line-too-long def reward_ids_map(self) -> dict: """A mapping of unique reward identifiers. @@ -215,6 +222,7 @@ def reward_ids_map(self) -> dict: A dictionary where the keys are the [`reward_ids`][smart_control.dataset.partition.BuildingDatasetPartition.reward_ids] and the values are unique integers referencing column indices in the [`reward_value_matrix`][smart_control.dataset.partition.BuildingDatasetPartition.reward_value_matrix]. """ + # pylint: enable=line-too-long return { "agent_reward_value": 0, "productivity_reward": 1, @@ -235,6 +243,7 @@ def reward_ids_map(self) -> dict: "normalized_carbon_emission": 16, } + @cached_property def action_ids(self) -> list[str]: """A list of unique action identifiers. diff --git a/smart_control/simulator/building_radiation_utils.py b/smart_control/simulator/building_radiation_utils.py index 5f714c69..626f3daa 100644 --- a/smart_control/simulator/building_radiation_utils.py +++ b/smart_control/simulator/building_radiation_utils.py @@ -76,13 +76,19 @@ def calculate_a_tilde_inv(epsilon: np.ndarray, F: np.ndarray) -> np.ndarray: return np.linalg.solve(a_tilde, np.eye(n)) +# pylint: disable=line-too-long +# pylint: disable=line-too-long +# pylint: disable=line-too-long +# pylint: disable=line-too-long +# pylint: disable=line-too-long +# pylint: disable=line-too-long def calculate_ifa_inv(F: np.ndarray, A_inv: np.ndarray) -> np.ndarray: r""" Calculates the $IFA_{inv}$ matrix. $$IFA_{inv} = (I - F) \tilde{A}^{-1}$$ - See [`net_radiative_heatflux_function_of_T`][smart_control.simulator.building_radiation_utils.net_radiative_heatflux_function_of_T] for more details. + See [`net_radiative_heatflux_function_of_T`][smart_control.simulator.building_radiation_utils.net_radiative_heatflux_function_of_t] for more details. Args: F (np.ndarray): The view factor matrix. @@ -91,6 +97,12 @@ def calculate_ifa_inv(F: np.ndarray, A_inv: np.ndarray) -> np.ndarray: Returns: IFA_inv : The IFA inverse matrix. """ + # pylint: enable=line-too-long + # pylint: enable=line-too-long + # pylint: enable=line-too-long + # pylint: enable=line-too-long + # pylint: enable=line-too-long + # pylint: enable=line-too-long n = F.shape[0]