Grid Power Limitation

[BuntBaum]

Add "available_grid_power" State to Simulate Grid Constraints

Description:

First, I would like to express my appreciation for the fantastic work on the CityLearn Simulator. It has been an incredibly valuable tool for my research and development in building energy management. The flexibility and depth of the simulation capabilities are truly impressive.

Feature Request:

I am writing to request a new feature that would greatly enhance the realism and applicability of the CityLearn Simulator, particularly in scenarios involving grid constraints. Specifically, I propose the addition of a new state variable called "available_grid_power" to the simulator.

Motivation:

In real-world scenarios, the power available from the grid to a building can be subject to limitations. For instance, under normal conditions, the power supply may be effectively unlimited up to the connection's capacity. However, during periods of grid stress or regulatory actions (e.g., as stipulated by §14a ENWG in Germany), the power supply to individual buildings may be curtailed. These scenarios necessitate a more resilient control solution for Distributed Energy Resources (DERs) to ensure the safety and comfort of occupants during such constraints.

Proposed Implementation:

1. New State Variable:

   • Add a new state variable available_grid_power to each building's state.
   • This variable can range from 0 (representing a complete blackout) to infinity (representing no constraint).

2. Configuration Options:

   • Allow users to set the maximum grid power capacity for each building, reflecting the connection capacity.
   • Provide mechanisms to specify available_grid_power per time step via:
     • A CSV file input, where each row corresponds to a time step and columns to each building.
     • A stochastic model to generate random available_grid_power values, simulating realistic grid constraints.

3. Integration with Existing Systems:

   • Ensure that the energy management algorithms within CityLearn can adapt to changes in available_grid_power, modifying their behavior to optimize for resilience and occupant safety during grid constraints.

Benefits:

• This feature would enhance the simulator's realism, making it a more powerful tool for developing and testing control strategies for DERs under varying grid conditions.
• It would provide a valuable testing environment for regulatory compliance and emergency preparedness.
• Researchers and practitioners would be able to explore the impact of grid constraints on building energy systems more comprehensively.

Once again, thank you for the excellent work on CityLearn. I am excited about the potential for this new feature to further enrich the simulation capabilities and am eager to see its implementation.

Best regards,
Tobi

[nagyzoltan]

Thanks! I'll let @kingsleynweye respond properly, but I think this is on our roadmap somewhere

[kingsleynweye]

Thanks for this feature request @BuntBaum. I agree that limiting the available power buildings can draw from the grid makes for a more realistic simulation.

I think we have this implemented already to some degree that reflects what you have described albeit for a complete blackout scenario alone. There is a citylearn.building.downward_electrical_flexibility function that we had implemented to appropriately limit the available energy to meet the building loads if the power_outage state variable equalled 1. Under normal conditions, the value is infinite and during a blackout, it is limited to available solar generation + current stored energy in the energy storage systems. You can see how the function is used if you trace the execution order in the citylearn.building.apply_actions function. Does this resemble what you were thinking of?

Right now, downward_electrical_flexibility it isn't included as a state variable but it is definitely something we can add. Also, with the addition of the timestep-wise configuration option, we will just add what ever value is defined in the building file to the storage + generation value and that will define the limit.

I think what we will need to update to make this reflect all use cases you have described is to:

1. Add the state variable
2. Add configuration option to the building file

Let me know what you think.

[BuntBaum]

Hi @kingsleynweye,

Thank you for taking the time to review and respond to my feature request. I agree that the existing downward_electrical_flexibility function can indeed represent scenarios where the available power is constrained to the sum of available_grid_power, PV production, and the energy storage (including bidirectional BEVs). This aligns well with my initial suggestion.

The addition of a timestep-wise configuration option would be a valuable enhancement, as it would allow more granular control over the available power limits, ensuring the simulation can more accurately reflect real-world grid constraints and varying conditions.

I'm excited to see how this feature evolves and look forward to any updates. Once again, thank you for your thoughtful consideration!

Best regards,
Tobi

[GundugolluMVALakshmi]

Hi! I’m also working with CityLearn for research, and this feature request really caught my attention.

Thanks @kingsleynweye for the detailed explanation of the current downward_electrical_flexibility approach. I agree that adding a dedicated available_grid_power state variable—plus a timestep-wise configuration option (via building file or CSV)—would make the environment much more realistic for partial grid constraint scenarios.

Having:

An observable state for available grid power, and

A configurable per-timestep limit

would greatly help in designing RL agents that can adapt to dynamic curtailments, capacity throttling, and other demand-response mechanisms. This would add strong value for both research and practical DR strategy development.

Excited to follow the progress on this feature!

[nagyzoltan]

@GundugolluMVALakshmi we agree. CityLearn will be moving into a community foundation model very soon, and we welcome pull requests for features like this :)

[GundugolluMVALakshmi]

Thank you for the response!

I’ll start working on an implementation for the available_grid_power state along with the timestep-wise configuration option and will open a pull request once a working version is ready.

@kingsleynweye If there are any design guidelines or preferences I should follow during development, please let me know.
@nagyzoltan Thanks again for the encouragement!