Skip to content

Integrate Community Documentation and Fix Links #112

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
igopalakrishna wants to merge 1 commit into
base: copybara_push
Choose a base branch
from
Open

Integrate Community Documentation and Fix Links #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 0 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,6 @@ from cloud storage.
View the official [Documentation Site](https://google.github.io/sbsim/) for a
complete auto-generated API reference.

There is also a legacy unofficial
[Community-run Documentation Site](https://gitwyd.github.io/sbsim_documentation/)
containing more information about the project and the codebase. We plan to merge
all this content into the official documentation site soon.

## Getting Started

A great place to start is by reviewing the
Expand Down
28 changes: 28 additions & 0 deletions docs/community/additional-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
layout: "default"
title: "Additional Resources"
nav_order: 11
parent: "Smart Control Project Documentation"
---

# Additional Resources

- **Gin Configuration Guide**:

- Learn more about Gin configurations at [Gin Config Documentation](https://github.com/google/gin-config).

- **TF-Agents Documentation**:

- Explore TF-Agents for reinforcement learning environments and agents at [TF-Agents](https://www.tensorflow.org/agents).

- **Energy Cost Modeling**:

- Research energy cost and carbon emission modeling for deeper understanding.

- **Reinforcement Learning Concepts**:

- Review reinforcement learning fundamentals to effectively develop and test agents.

---

[Back to Home](../index.md)
Binary file added docs/community/assets/visualization-module-images/action_plot.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/community/assets/visualization-module-images/cum_reward_plot.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/community/assets/visualization-module-images/reward_plot.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions docs/community/base-reward-function.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
layout: "default"
title: "BaseSetpointEnergyCarbonRewardFunction"
nav_order: 1
parent: "Reward Functions"
grand_parent: "Smart Control Project Documentation"
---

# BaseSetpointEnergyCarbonRewardFunction

**Purpose**: Provides a base class for reward functions that consider productivity, energy cost, and carbon emissions.

## Key Attributes

- `max_productivity_personhour_usd`: Maximum productivity per person-hour in USD.
- `productivity_midpoint_delta`: Temperature difference from setpoint at which productivity is half of the maximum.
- `productivity_decay_stiffness`: Controls the slope of the productivity decay curve.

## Key Methods

- `__init__(...)`: Initializes the reward function with productivity parameters.
- `compute_reward(energy_reward_info)`: Abstract method to compute the reward; to be implemented by subclasses.
- `_sum_zone_productivities(energy_reward_info)`: Calculates cumulative productivity across all zones.
- `_get_zone_productivity_reward(...)`: Computes productivity reward for a single zone based on temperature.
- `_get_delta_time_sec(energy_reward_info)`: Calculates the time interval in seconds.
- `_sum_electricity_energy_rate(energy_reward_info)`: Sums up electrical energy rates from devices.
- `_sum_natural_gas_energy_rate(energy_reward_info)`: Sums up natural gas energy rates from devices.

---

[Back to Reward Functions](reward-functions.md)

[Back to Home](../index.md)
42 changes: 42 additions & 0 deletions docs/community/best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
layout: "default"
title: "Best Practices"
nav_order: 10
parent: "Smart Control Project Documentation"
---

# Best Practices

- **Modular Design**:

- Keep modules and classes focused on single responsibilities.
- Facilitate reuse and maintainability.

- **Error Handling**:

- Use try-except blocks where exceptions might occur.
- Provide meaningful error messages and log exceptions.

- **Logging**:

- Use the `logging` module instead of print statements.
- Set appropriate logging levels (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).

- **Documentation**:

- Keep documentation up to date with code changes.
- Use comments to explain complex logic or decisions.

- **Performance Optimization**:

- Profile code to identify bottlenecks.
- Optimize algorithms and data structures where necessary.

- **Configuration Management**:

- Use configuration files (e.g., Gin) to manage parameters.
- Avoid hardcoding values in the codebase.

---

[Back to Home](../index.md)
36 changes: 36 additions & 0 deletions docs/community/building-simulation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
layout: "default"
title: "Building Simulation"
nav_order: 1
parent: "Simulation Components"
grand_parent: "Smart Control Project Documentation"
---

# Building Simulation

**Purpose**: Represents the thermal and physical properties of the building, simulating how it responds to HVAC inputs and environmental conditions.

## Key Classes and Components

- **`FloorPlanBasedBuilding`**:

- Simulates the building's structure based on a floor plan and zone mappings.

- **Attributes**:

- `cv_size_cm`: Control volume size in centimeters.
- `floor_height_cm`: Height of each floor.
- `initial_temp`: Initial uniform interior temperature.
- `inside_air_properties`: Thermal properties of the air inside the building.
- `inside_wall_properties`: Thermal properties of the interior walls.
- `building_exterior_properties`: Thermal properties of the exterior building.
- `floor_plan_filepath`: Path to the floor plan file.
- `zone_map_filepath`: Path to the zone mapping file.
- `convection_simulator`: Simulates heat convection within the building.
- `reset_temp_values`: Function to reset temperature values.

---

[Back to Simulation Components](simulation-components.md)

[Back to Home](../index.md)
124 changes: 124 additions & 0 deletions docs/community/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
layout: "default"
title: "Configuration"
nav_order: 6
parent: "Smart Control Project Documentation"
---

# Configuration

The project uses Gin configuration files (`*.gin`) to manage simulation settings, reward function parameters, and environment configurations.

## 1. Gin Configuration Files

Gin is a lightweight configuration framework for Python that allows parameter bindings via configuration files or command-line arguments.

### Structure of Gin Files

- **Parameter Definitions**: Define values for various parameters used throughout the simulation.
- **Function and Class Bindings**: Bind parameters to specific functions and classes.
- **References**: Use `@` to reference functions or classes, and `%` to reference parameters.

### Example from a Gin File

To illustrate, here is an example of a Gin configuration:

```
# paths
controller_reader.ProtoReader.input_dir = @get_histogram_path()
floor_plan_filepath = @get_zone_path()
zone_map_filepath = @get_zone_path()
metrics_path = @get_metrics_path()
```

## 2. Key Configuration Parameters

### Simulation Parameters

- **Weather Conditions**:
- `convection_coefficient`: Coefficient for heat convection between the building and the environment.
- `ambient_high_temp`, `ambient_low_temp`: High and low ambient temperatures for sinusoidal temperature variation.

- **Building Properties**:
- `control_volume_cm`: Size of the control volume in centimeters.
- `floor_height_cm`: Height of each floor.
- `initial_temp`: Initial temperature inside the building.
- `exterior_cv_conductivity`, `exterior_cv_density`, `exterior_cv_heat_capacity`: Thermal properties of the exterior building.
- `interior_wall_cv_conductivity`, `interior_wall_cv_density`, `interior_wall_cv_heat_capacity`: Thermal properties of the interior walls.
- `interior_cv_conductivity`, `interior_cv_density`, `interior_cv_heat_capacity`: Thermal properties of the interior air.

- **HVAC Settings**:
- `water_pump_differential_head`, `water_pump_efficiency`: Parameters for the water pump.
- `reheat_water_setpoint`: Setpoint temperature for reheating water.
- `boiler_heating_rate`, `boiler_cooling_rate`: Heating and cooling rates for the boiler.
- `fan_differential_pressure`, `fan_efficiency`: Parameters for the HVAC fan.
- `air_handler_heating_setpoint`, `air_handler_cooling_setpoint`: Temperature setpoints for the air handler.
- `air_handler_recirculation_ratio`: Recirculation ratio for the air handler.
- `vav_max_air_flowrate`, `vav_reheat_water_flowrate`: Maximum flow rates for VAV boxes.

- **Occupancy Model**:
- `morning_start_hour`, `evening_start_hour`: Hours defining the occupancy schedule.
- `heating_setpoint_day`, `cooling_setpoint_day`: Setpoints during the day.
- `heating_setpoint_night`, `cooling_setpoint_night`: Setpoints during the night.
- `work_occupancy`, `nonwork_occupancy`: Occupancy levels during work and non-work hours.
- `earliest_expected_arrival_hour`, `latest_expected_arrival_hour`: Arrival times.
- `earliest_expected_departure_hour`, `latest_expected_departure_hour`: Departure times.

- **Time Settings**:
- `time_step_sec`: Simulation time step in seconds.
- `start_timestamp`: Start time of the simulation.
- `time_zone`: Time zone for the simulation.

### Reward Function Parameters

- `max_productivity_personhour_usd`, `min_productivity_personhour_usd`: Productivity per person-hour.
- `productivity_midpoint_delta`, `productivity_decay_stiffness`: Parameters for productivity decay curve.
- `max_electricity_rate`, `max_natural_gas_rate`: Maximum energy rates for normalization.
- `productivity_weight`, `energy_cost_weight`, `carbon_emission_weight`: Weights for reward components.

### Action Normalization Parameters

- **Supply Water Setpoint**:
- `min_normalized_value`, `max_normalized_value`: Normalized action value range.
- `min_native_value`, `max_native_value`: Native action value range (e.g., temperature in Kelvin).

- **Supply Air Heating Temperature Setpoint**:
- Similar normalization parameters as above.

### Observation Normalization Parameters

- **Per-Measurement Normalizers**:
- For each measurement (e.g., `building_air_static_pressure_sensor`, `cooling_percentage_command`), define:
- `field_id`: Identifier for the field.
- `sample_mean`: Mean value used for normalization.
- `sample_variance`: Variance used for normalization.

### Environment Parameters

- `discount_factor`: Discount factor for future rewards.
- `num_days_in_episode`: Number of days in an episode.
- `metrics_reporting_interval`: Interval for reporting metrics.
- `label`: Label for the simulation or environment.
- `num_hod_features`, `num_dow_features`: Number of hour-of-day and day-of-week features.

### Bindings and References

Bind classes and functions to configured parameters, for example:

```
sim_building/TFSimulator:
building = @sim/FloorPlanBasedBuilding()
hvac = @sim/FloorPlanBasedHvac()
weather_controller = %weather_controller
time_step_sec = %time_step_sec
convergence_threshold = %convergence_threshold
iteration_limit = %iteration_limit
iteration_warning = %iteration_warning
start_timestamp = @sim/to_timestamp()
```

Reference parameters using `%` and functions or classes using `@`.

---

[Back to Home](../index.md)
24 changes: 24 additions & 0 deletions docs/community/ddpg.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
layout: "default"
title: "Deep Deterministic Policy Gradient"
nav_order: 3
parent: "Learning Algorithms"
grand_parent: "Smart Control Project Documentation"
---

# Deep Deterministic Policy Gradient (DDPG)
Implementation of this algorithm can be found in the `DDPG_Demo.ipynb` notebook.

---

Deep Deterministic Policy Gradient (DDPG) is a model-free reinforcement learning algorithm designed for continuous action spaces. It combines the actor-critic framework with deterministic policy gradients. Key features of DDPG include:

- **Actor-Critic Architecture**: Utilizes an actor network to select actions and a critic network to evaluate the Q-values of state-action pairs.
- **Off-Policy Learning**: Learns using a replay buffer to sample past experiences, improving stability and efficiency.
- **Target Networks**: Employs slowly updated target networks to stabilize training.
- **Exploration**: Uses noise (e.g., Ornstein-Uhlenbeck process) for exploration in continuous spaces.


[Back to Learning Algorithms](learning-algorithms.md)

[Back to Home](../index.md)
35 changes: 35 additions & 0 deletions docs/community/electricity-energy-cost.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
layout: "default"
title: "ElectricityEnergyCost"
nav_order: 4
parent: "Reward Functions"
grand_parent: "Smart Control Project Documentation"
---

# ElectricityEnergyCost

**Purpose**: Models the cost and carbon emissions associated with electricity consumption.

## Key Attributes

- `weekday_energy_prices`: Energy prices for weekdays by hour.
- `weekend_energy_prices`: Energy prices for weekends by hour.
- `carbon_emission_rates`: Carbon emission rates by hour.

## Key Methods

- `__init__(...)`: Initializes the energy cost model with price and emission schedules.
- `cost(start_time, end_time, energy_rate)`: Calculates the cost of electricity consumed over a time interval.
- `carbon(start_time, end_time, energy_rate)`: Calculates the carbon emissions from electricity consumption over a time interval.

## Calculation Logic

- Determines the appropriate energy price and carbon emission rate based on the time and day.
- Converts energy rates to costs and emissions using provided schedules.
- Supports variable pricing and emission factors throughout the day.

---

[Back to Reward Functions](reward-functions.md)

[Back to Home](../index.md)
Loading
Loading