Skip to content

Fix mkdocs autoref links to use reference-style syntax #184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Mustaphayinka wants to merge 2 commits into
base: copybara_push
Choose a base branch
from
+62 −33
Open

Fix mkdocs autoref links to use reference-style syntax #184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
084f0f5
Fix mkdocs autoref links to use reference-style syntax (#107)
Mustaphayinka Aug 24, 2026
92eb44f
Fix line-too-long lint errors and typo case in autoref anchor
Mustaphayinka Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions smart_control/dataset/dataset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,21 +68,25 @@ 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.
"""

@s2t2 s2t2 Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all of these line too long disable comments, I believe we could just do a single comment to the right of the end of the docstring, like:

"""
This is the docstring content....................................
"""  # pylint: disable=line-too-long

could you please try this out for all instances of the comment

# 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.

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.
"""
# pylint: enable=line-too-long
if os.path.isdir(self.building_dirpath):
print("Using previously-downloaded data...")
print(os.path.abspath(self.building_dirpath))
Expand Down Expand Up @@ -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.

Expand All @@ -119,9 +124,10 @@ 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.
"""
# pylint: enable=line-too-long
return np.load(self.floorplan_filepath)

@property
Expand All @@ -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",
Expand All @@ -149,8 +156,9 @@ 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]
"""
# pylint: enable=line-too-long
plt.imshow(self.floorplan, interpolation="nearest", cmap=cmap)
if show:
plt.show()
Expand Down
67 changes: 38 additions & 29 deletions smart_control/dataset/partition.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,14 +77,14 @@ def data(self) -> np.lib.npyio.NpzFile:
See corresponding documentation below for more information about each.
"""
return np.load(self.data_filepath)

@s2t2 s2t2 Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add this new line back please

@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).
"""Metadata describing the partition [`data`][smart_control.dataset.partition.BuildingDatasetPartition.data].

Returns:
A dictionary containing the following keys:
Expand All @@ -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 = {
Expand Down Expand Up @@ -136,85 +137,92 @@ 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"]

@s2t2 s2t2 Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's add this new line back please

#
# METADATA PROPERTIES
#

@cached_property
# pylint: disable=line-too-long
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:

```py
```py

@s2t2 s2t2 Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like for docstring content to be nested inside the docstring (in terms of tabs and spaces), not on the left margin, if we can help it.

{
'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.

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:

```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.

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:

```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.

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].
"""
# pylint: enable=line-too-long
return {
"agent_reward_value": 0,
"productivity_reward": 1,
Expand All @@ -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.
Expand Down Expand Up @@ -344,9 +353,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:
Expand All @@ -373,9 +382,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:
Expand All @@ -402,9 +411,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:
Expand All @@ -430,9 +439,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:
Expand Down
14 changes: 13 additions & 1 deletion smart_control/simulator/building_radiation_utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

@s2t2 s2t2 Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove duplicate comments please

# 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.
Expand All @@ -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

@s2t2 s2t2 Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's remove duplicate comments please. these don't nest

# pylint: enable=line-too-long
# pylint: enable=line-too-long
# pylint: enable=line-too-long
# pylint: enable=line-too-long

n = F.shape[0]

Expand Down
Loading