pycity_scheduling.classes package
Submodules
pycity_scheduling.classes.apartment module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.apartment.Apartment(environment, net_floor_area=None, occupancy=None)
Bases:
EntityContainer
,Apartment
Extension of pyCity_base class Apartment for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances
net_floor_area (float, optional) – netto floor area in [m^2]
occupancy (Occupancy, optional) – Occupancy profile from pycity_base for the apartment.
Notes
Apartments inherit their set of constraints from EntityContainer.
Methods
addEntity
(entity)Add entity to apartment.
Yield all lower-level entities.
- addEntity(entity)
Add entity to apartment.
- Parameters:
entity (OptimizationEntity) – Entity to be added to the apartment; must be of type FixedLoad, DeferrableLoad, CurtailableLoad, SpaceHeating, SpaceCooling or DomesticHotWater.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
pycity_scheduling.classes.battery module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.battery.Battery(environment, e_el_max, p_el_max_charge, p_el_max_discharge=None, soc_init=0.5, eta=0.95, storage_end_equality=False)
Bases:
ElectricalEntity
,Battery
Extension of pyCity_base class Battery for scheduling purposes.
Initialize Battery.
- Parameters:
environment (Environment) – Common Environment instance.
e_el_max (float) – Electric capacity of the battery [kWh].
p_el_max_charge (float) – Maximum charging power [kW].
p_el_max_discharge (float, optional) – Maximum discharging power [kW]. Defaults to zero.
soc_init (float, optional) – Initial state of charge. Defaults to 50%.
eta (float, optional) – Charging and discharging efficiency. Must be in (0,1]. Defaults to one.
storage_end_equality (bool, optional) – True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc. Defaults to False.
Notes
Batteries offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the battery:
\[\begin{split}p_{el} &=& p_{el\_demand} - p_{el\_supply} \\ p_{el\_max\_discharge} &\geq& p_{el\_supply} \geq 0 \\ p_{el\_max\_charge} &\geq& p_{el\_demand} \geq 0 \\ e_{el\_max} &\geq& e_{el} \geq 0 \\ e_{el} &=& e_{el\_previous} + (\eta * p_{el\_demand} - (1 / \eta) * p_{el\_supply}) * \Delta t \\ \text{with} \quad e_{el\_previous} &=& \ \begin{bmatrix} e_{el\_ini} & e_{el\_0} & \cdots & e_{el\_n-1}\end{bmatrix}\end{split}\]Additional constraints generated by the parameters are:
\[\begin{split}e_{el\_t\_last} &=& soc\_init * e_{el\_max}, & \quad \text{if storage_end_equality} \\ e_{el\_t\_last} &\geq& soc\_init * e_{el\_max}, & \quad \text{else}\end{split}\]In integer mode the following constraints are added in addition:
\[\begin{split}p_{el\_demand} &\leq& p_{state} * p_{el\_max\_discharge} \\ p_{el\_supply} &\leq& (1-p_{state}) * p_{el\_max\_charge}\end{split}\]Methods
populate_model
(model[, mode])Add device block of variables and constraints to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block of variables and constraints to pyomo ConcreteModel.
Call parent’s populate_model method and set variables lower bounds to None. Then add variables for demand, supply and the state of charge, with their corresponding upper bounds (self.p_el_max_charge, self.p_el_max_discharge, self.e_el_max). Finally add continuity constraints to the block.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.boiler module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.boiler.Boiler(environment, p_th_nom, eta=1, lower_activation_limit=0.0, min_off_time=1, min_on_time=1)
Bases:
ThermalEntityHeating
,Boiler
Extension of pyCity_base class Boiler for scheduling purposes.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal heat output in [kW].
eta (float, optional) – Efficiency of the gas boiler (without unit).
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the gas boiler as a percentage of the rated power. When the gas boiler is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the boiler must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the boiler must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
Notes
Gas boilers offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the boiler:
\[0 \geq p_{th\_heat} \geq -p_{th\_nom}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the boiler weighted with coeff. Sum of p_th_heat.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables upper bounds to self.p_th_nom.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.building module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.building.Building(environment, objective='price', name=None, profile_type=None, building_type=None, storage_end_equality=False, least_squares_profile=None)
Bases:
EntityContainer
,Building
Extension of pyCity_base class Building for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
objective (str, optional) –
Objective for the scheduling. The default is ‘price’.
’price’ : Optimize for the prices given by prices.tou_prices.
’co2’ : Optimize for the CO2 emissions given by prices.co2_prices.
’peak-shaving’ : Try to flatten the schedule as much as possible.
’max-consumption’ : Try to reduce the maximum of the absolute values of the schedule as much as possible.
’self-consumption’ : Try to maximize the self-consumption of the local power generation.
’least-squares’: Try to follow a given reference power profile.
’none’ : No objective (leave all flexibility to other participants).
name (str, optional) – Name for the building. If name is None, set it to self._long_id.
profile_type (str, optional) –
Thermal SLP profile name Requires method=1
’HEF’ : Single family household
’HMF’ : Multi family household
’GBA’ : Bakeries
’GBD’ : Other services
’GBH’ : Accommodations
’GGA’ : Restaurants
’GGB’ : Gardening
’GHA’ : Retailers
’GHD’ : Summed load profile business, trade and services
’GKO’ : Banks, insurances, public institutions
’GMF’ : Household similar businesses
’GMK’ : Automotive
’GPD’ : Paper and printing
’GWA’ : Laundries
building_type (str, optional) – Build year profile name, the detailed list is implemented in tabula_data.py.
storage_end_equality (bool, optional) – True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc.
least_squares_profile (numpy.ndarray, optional) – Profile to be used by the least-squares objective.
Notes
The exchange of thermal energy between different buildings is currently not supported. As a result, the building additionally adds the following set of constrains to the ones of the EntityContainer:
\[\begin{split}p_{th\_heat} &=& 0 \\ p_{th\_cool} &=& 0\end{split}\]The building can also add robustness constrains for thermal heating storage:
\[\begin{split}e_{u\_bound} \geq \sum_i e_{th\_heat\_i} \geq e_{l\_bound} \\\end{split}\]The \(E_{u\_bound}\) and \(E_{l\_bound}\) are determined by the robustness parameter, the available capacity of thermal heating storage, the magnitude of heating required by SpaceHeating and the magnitude of heating that can be produced by the building’s heating units.
Methods
Yield all lower-level entities.
populate_model
(model[, mode, robustness])Add building block to pyomo ConcreteModel.
update_model
([mode, robustness])Update block parameters and bounds.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- populate_model(model, mode='convex', robustness=None)
Add building block to pyomo ConcreteModel.
Call parent’s populate_model method and set variables lower bounds to None. Then call populate_model method of the BES and all contained apartments and add constraints that the sum of their variables for each period equals the corresponding own variable.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
robustness (tuple, optional) – Tuple of two floats. First entry defines how many time steps are protected from deviations. Second entry defines the magnitude of deviations which are considered.
- update_model(mode='', robustness=None)
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
robustness (tuple, optional) – Tuple of two floats. First entry defines how many time steps are protected from deviations. Second entry defines the magnitude of deviations which are considered.
pycity_scheduling.classes.building_energy_system module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.building_energy_system.BuildingEnergySystem(environment)
Bases:
EntityContainer
,BES
Extension of pyCity_base class BES for scheduling purposes.
- Parameters:
environment (Environment)
Notes
The constraints generated by a BES are the same as the ones created by an EntityContainer.
Methods
getHasDevices
([all_devices, battery, ...])Get information if certain devices are installed devices.
Yield all lower-level entities.
- getHasDevices(all_devices=True, battery=False, boiler=False, chp=False, chiller=False, electrical_heater=False, heatpump=False, inverter_acdc=False, inverter_dcac=False, pv=False, ths=False, tcs=False)
Get information if certain devices are installed devices. The result is in alphabetical order, starting with “battery”
- Parameters:
all_devices (boolean, optional) – If true: Return all installed devices If false: Only return the specified devices
battery (boolean, optional) – Return information about the battery unit
boiler (boolean, optional) – Return information about the boiler unit
chp (boolean, optional) – Return information about the chp unit
chiller (boolean, optional) – Return information about the chiller unit
electrical_heater (boolean, optional) – Return information about the electric heater unit
heatpump (boolean, optional) – Return information about the heat pump unit
inverter_acdc (boolean, optional) – Return information about the AC-DC inverter unit
inverter_dcac (boolean, optional) – Return information about the DC-AC inverter unit
pv (boolean, optional) – Return information about the PV unit
ths (boolean, optional) – Return information about the thermal heating storage unit
tcs (boolean, optional) – Return information about the thermal cooling storage unit
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- property tcs_units
Provides all TCS units.
- property ths_units
Provides all THS units.
pycity_scheduling.classes.chiller module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.chiller.Chiller(environment, p_th_nom, cop=None, eta=0.36, t_min=4.0, lower_activation_limit=0, min_off_time=1, min_on_time=1, t_flow=16.0)
Bases:
ThermalEntityCooling
,ElectricalEntity
,CompressionChiller
Extension of pyCity_base class CompressionChiller for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power of the chiller in [kW].
cop (numpy.ndarray or int or float, optional) – The chiller’s coefficient of performance (without unit) If array, it must provide the coefficient of performance (cop) for each time step in the simulation horizon. If int or float, a constant cop over the whole horizon is assumed. If omitted, an air-water chiller is assumed and the cop is calculated based on the ambient air temperature, eta and t_flow.
eta (int or float, optional) – The Carnot efficiency of the chiller. If cop is omitted, eta is used to calculate the cop based on T_sink and T_source according to: cop = eta * T_sink * (T_sink - T_source) with T_sink and T_source in Kelvin
t_min (float, optional) – The chiller’s minimum provided temperature in °C
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the chiller as a percentage of the rated power. When the chiller is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the chiller must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the chiller must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
t_flow (float, optional) – T_sink temperature delivered by CC in °C. Is used for cop calculation if cop is omitted. Note that t_flow >= t_min must hold.
Notes
CHs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the CH:
\[\begin{split}0 \geq p_{th\_cool} &\geq& -p_{th\_nom} \\ cop * p_{el} &=& - p_{th\_cool}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call parent’s populate_model method and set thermal variables lower bounds to -self.p_th_nom and the upper bounds to zero. Also add constraint to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.city_district module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.city_district.CityDistrict(environment, objective='price', valley_profile=None, least_squares_profile=None, electrical_grid=None)
Bases:
ElectricalEntity
,CityDistrict
Extension of pyCity_base class CityDistrict for scheduling purposes. Also represents the district operator.
- Parameters:
environment (Environment)
objective (str, optional) –
Objective for the district operator. Default is ‘price’.
’price’ : Optimize for the minimum total cost given by prices.da_prices.
’peak-shaving’ : Try to ‘flatten’ the schedule as much as possible.
’co2’ : Optimize for the minimum total co2 emissions given by prices.co2_prices.
’valley-filling’ : Try to fill the ‘valleys’ given by self.valley_profile.
’max-consumption’ : Try to minimize the maximum power subscription.
’self-consumption’ : Try to maximize the self-consumption of the local power generation.
’least-squares’: Try to follow a given reference power profile.
’flexibility-quantification’ : To be used to quantify the flexibility potential of the city district only.
’none’ : No objective.
valley_profile (numpy.ndarray, optional) – Profile to be filled by applying the valley filling objective.
least_squares_profile (numpy.ndarray, optional) – Profile to be used by the least-squares objective.
electrical_grid (ElectricalGrid, optional) – Assign an ElectricalGrid object to the city district representing the local power grid
Notes
The constraints generated by a CD are the same as the ones created by an EntityContainer.
Methods
Changes the current schedule to account imbalances.
addElectricalGrid
(environment, max_p_slack, ...)Add electrical grid to the city district.
Return the decision varaible(s) of the entity's objective function.
Yield all lower-level entities.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add city district block to pyomo ConcreteModel.
- account_imbalance()
Changes the current schedule to account imbalances.
The imbalances are determined from the current schedules of the contained entities.
- addElectricalGrid(environment, max_p_slack, max_q_slack, slack_V=None, ref_V=400, V_min=0.95, V_max=1.05)
Add electrical grid to the city district.
Create an ElectricalGrid object and link it to the city district through the electrical_grid attribute. Add an electrical node the electrical grid for each entity contained in the city district.
- Parameters:
environment (Environment)
max_p_slack (float) – Maximum active power that can be exchanged through slack node of the grid in kW.
max_q_slack (float) – Maximum reactive power that can be exchanged through slack node of the grid in kVar.
slack_V (float) – If not None, voltage at which the slack node should be operated in V. Default is None.
ref_V (float) – Nominal voltage in the electrical grid in V. Default is 400V.
V_min (float) – Minimal per unit voltage allowed in the electrical grid. Default is 0.95.
V_max (float) – Maximal per unit voltage allowed in the electrical grid. Default is 1.05.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the entity weighted with coeff.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add city district block to pyomo ConcreteModel.
Call parent’s populate_model methods and set variables lower bounds to None.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
pycity_scheduling.classes.combined_heat_power module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.combined_heat_power.CombinedHeatPower(environment, p_th_nom, p_el_nom=None, eta=6.0, lower_activation_limit=0.5, min_off_time=1, min_on_time=1)
Bases:
ThermalEntityHeating
,ElectricalEntity
,CHP
Extension of pyCity_base class CHP for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power output in [kW].
p_el_nom (float, optional) – Nominal electrical power output in [kW]. Defaults to the product of p_th_nom and ‘eta’.
eta (float, optional) – Efficiency of the CHP unit by means of the ratio thermal vs. electrical (without unit).
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the CHP as a percentage of the rated power. When the CHP is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the CHP unit must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the CHP unit must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
Notes
CHPs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the CHP:
\[\begin{split}0 &\geq& p_{th\_heat} \geq -p_{th\_nom} \\ 0 &\geq& p_{el} \geq -p_{el\_nom} \\ \frac{p_{el}}{p_{el\_nom}} &=& \frac{p_{th\_heat}}{p_{th\_nom}}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call both parents’ populate_model methods and set the upper bounds of the thermal variables to self.p_th_nom, the lower bounds of the electrical variables to -self.p_el_nom and the upper bounds to zero. Also add constraints to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.curtailable_load module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.curtailable_load.CurtailableLoad(environment, p_el_nom, max_curtailment, max_low=None, min_full=None)
Bases:
ElectricalEntity
,ElectricalDemand
Extension of pyCity_base class ElectricalDemand for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
p_el_nom (float) – Nominal electric power in [kW].
max_curtailment (float) – Maximal Curtailment of the load
max_low (int, optional) – Maximum number of timesteps the curtailable load can stay under nominal load
min_full (int, optional) – Minimum number of timesteps the curtailable load has to stay at nominal operation level when switching to the nominal operation level
Notes
CLs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the CL:
\[\begin{split}p_{el\_nom} * max\_curtailment \geq p_{el} \geq 0 \\ \sum_{j=i}^{i+max\_low+min\_full} p_{el\_j} \geq p_{el\_nom} * (min\_full + max\_low * max\_curtailment)\end{split}\]The last constraint is replaced in integer mode with the following constraints:
\[\begin{split}p_{el} \geq p_{state} * p_{el\_nom} \\ \sum_{j=i}^{i+max\_low} p_{state\_j} \geq 1 \\ \sum_{j=i}^{i+min\_full-1} p_{state\_j} \geq (p_{state\_i} - p_{state\_i-1}) * min\_full\end{split}\]These constraints take also the previous values before the current optimization horizon into account using the current schedule. Values before \(t=0\) are assumed to be perfect.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables upper bounds to the loadcurve and lower bounds to self.p_el_Min.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Uses integer variables for max_low and min_full constraints if necessary
- update_model(mode='convex')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.deferrable_load module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.deferrable_load.DeferrableLoad(environment, p_el_nom, e_consumption, load_time=None, lt_pattern=None)
Bases:
ElectricalEntity
,ElectricalDemand
Extension of pyCity_base class ElectricalDemand for scheduling purposes.
The Load will always run once in the op_horizon
- Parameters:
environment (Environment) – Common Environment instance.
p_el_nom (float) – Nominal electric power in [kW].
e_consumption (float) – Power to be consumed over the op_horizon in [kWh].
load_time (array of binaries, optional) – Indicator when deferrable load can be turned on. Defaults to always. load_time[t] == 0: device is off in t load_time[t] == 1: device can be turned on in t It must contain at least one 0 otherwise the model will become infeasible. Its length has to be consistent with lt_pattern.
lt_pattern (str, optional) –
Define how the load_time profile is to be used
None : Profile matches simulation horizon.
’daily’ : Profile matches one day.
’weekly’ : Profile matches one week.
- Raises:
ValueError : – If lt_pattern does not match load_time.
Notes
DLs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the DL:
\[\begin{split}p_{el\_nom} \geq p_{el\_i} \geq 0, & \quad \text{if} \quad lt\_pattern_i = 1 \\ p_{el\_i} = 0, & \quad \text{else}\end{split}\]\[\sum_i p_{el\_i} * \Delta t = e_{consumption}\]The constraints are replaced in integer mode with the following constraints:
\[\begin{split}\sum_i p_{state\_i} &=& 1 \\ runtime &=& \lfloor \frac{p_{el\_nom} * \Delta t}{e_{consumption}} \rceil \\ p_{el\_i} &=& p_{el\_nom} * \sum_{j=i-runtime+1}^{i} p_{state\_j} \\ p_{state\_i} &=& 0, \quad \text{if} \quad \sum_{j=i}^{i+runtime-1} lt\_pattern_j = runtime \\\end{split}\]These constraints do not take the previous values before the current optimization horizon into account. In the optimization horizon \(e_{consumption}\) always has to be consumed.
Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the deferrable load weighted with coeff. Quadratic term minimizing the deviation from the optimal loadcurve.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set the upper bounds to the nominal power or zero depending on self.load_time. Also set a constraint for the minimum load. If mode == integer add binary variables to model load as one block that can be shifted in time.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
- integerUses integer variables to restrict the DL to operate
at nominal load or no load and restricts the DL to consume E_Min_Consumption when DL is started without returning to a no load state
- update_model(mode='convex')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.electric_heater module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.electric_heater.ElectricHeater(environment, p_th_nom, eta=1, lower_activation_limit=1.0, min_off_time=1, min_on_time=1)
Bases:
ThermalEntityHeating
,ElectricalEntity
,ElectricalHeater
Extension of pyCity_base class ElectricalHeater for scheduling purposes.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power output in [kW].
eta (float, optional) – Efficiency of the electric heater. Defaults to one.
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the electric heater as a percentage of the rated power. When the electric heater is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the EH must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the EH must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
Notes
EHs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the EH:
\[\begin{split}0 \geq p_{th\_heat} &\geq& -p_{th\_nom} \\ \eta * p_{el} &=& - p_{th\_heat}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call parent’s populate_model method and set thermal variables upper bounds to self.p_th_nom. Also add constraint to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.electric_vehicle module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.electric_vehicle.ElectricVehicle(environment, e_el_max, p_el_max_charge, p_el_max_discharge=0.0, soc_init=0.5, charging_time=None, ct_pattern=None, simulate_driving=False, minimum_soc_end=0.8, eta=1.0)
Bases:
Battery
Class representing an electric vehicle for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
e_el_max (float) – Electric capacity of the battery in [kWh].
p_el_max_charge (float) – Maximum charging power in [kW].
p_el_max_discharge (float, optional) – Maximum discharging power in [kW]. Defaults to zero.
soc_init (float, optional) – Initial state of charge. Defaults to 50%.
charging_time (array of binaries, optional) –
Indicator when electric vehicle can be charged.
charging_time[t] == 0: EV cannot be charged in t
charging_time[t] == 1: EV can be charged in t
It must contain at least one 0 otherwise the model will become infeasible. Its length has to be consistent with ct_pattern. Defaults to only charge during night.
ct_pattern (str, optional) –
Define how the charging_time profile is to be used.
None : Profile matches simulation horizon (default).
’daily’ : Profile matches one day.
’weekly’ : Profile matches one week.
simulate_driving (bool, optional) –
Simulate driving.
True: EV may drive and lose energy during the trip
False: EV cannot drive and lose energy during the trip
minimum_soc_end (float, optional) – Set the minimum state of charge for an EV at the end of the optimization horizon. Must be in (0,1]. Defaults to 80%.
eta (float, optional) – Charging and discharging efficiency of the EV. Must be in (0,1]. Defaults to 100%.
Notes
EVs offer sets of constraints for operation. The \(e_{el}\) equivalence constraint is replaced by the following constraint:
\[\begin{split}e_{el} &=& e_{el\_previous} + (\eta * p_{el\_demand} - (1 / \eta) * p_{el\_supply} - p_{el\_drive}) * \Delta t \\\end{split}\]The following constraints are added:
\[\begin{split}p_{el\_drive} \geq 0 \\ p_{el\_demand\_i} = p_{el\_supply} = 0, & \quad \text{if} \quad ct\_pattern_i = 0 \\ p_{el\_drive\_i} = 0, & \quad \text{if} \quad ct\_pattern_i = 1 \\ e_{el\_i} = soc\_init * e_{el\_max}, & \quad \text{if} \quad \sum_{j=0}^i ct\_pattern_j = 0 \\ e_{el\_i} = 0.2 * e_{el\_max}, & \quad \text{else if} \quad ct\_pattern_i = 0 \\ e_{el\_i} = e_{el\_max}, & \quad \text{else if} \quad ct\_pattern_i+1 = 0\end{split}\]The constraint for the parameter storage_end_equality is removed. Instead, the EV needs to be fully charged at the end of the simu_horizon if parameter ct_pattern is one at the end of the simulation horizon.
Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the electric vehicle weighted with coeff. Quadratic term with additional weights to reward charging the vehicle earlier.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method. Replace coupling constraints from Battery class with coupling constraints of EV. Simulate power consumption while driving.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.electrical_entity module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.electrical_entity.ElectricalEntity(environment, *args, **kwargs)
Bases:
OptimizationEntity
Base class for all electrical entities derived from OptimizationEntity.
This class provides functionality common to all electrical entities. It adds variables for the electrical demand / supply of the entity to the block.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
Notes
EEs add the \(p_{el}\) variable to the model. When not modified by other classes, the following constraint is added:
\[p_{el} \geq 0\]Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the entity weighted with coeff.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
pycity_scheduling.classes.electrical_grid module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.electrical_grid.ElectricalGrid(environment, related_entity, max_p_slack, max_q_slack, slack_V=None, ref_V=400, min_V=0.95, max_V=1.05, *args, **kwargs)
Bases:
ElectricalEntity
Class ElectricalGrid for scheduling purposes. Connects buildings within pycity_scheduling via a shared electrical grid.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
related_entity (CityDistrict) – City district object that ‘maintains’ the ElectricalGrid.
max_p_slack (float) – Maximum active power that can be exchanged through slack node of the grid in kW.
max_q_slack (float) – Maximum reactive power that can be exchanged through slack node of the grid in kVar.
slack_V (float, optional) – If not None, voltage at which the slack node should be operated in V. Default is None.
ref_V (float, optional) – Nominal voltage in the electrical grid in V. Default is 400V.
V_min (float, optional) – Minimal per unit voltage allowed in the electrical grid. Default is 0.95.
V_max (float, optional) – Maximal per unit voltage allowed in the electrical grid. Default is 1.05.
Methods
add_line
(line)Add a line to the electrical grid.
add_node
(node)Add a node to the electrical grid.
Build the incidence matrix of the electrical grid.
connect_entities
(entity1, entity2, ...[, ...])Add a line of specified length and capacity linking two entities in an electrical grid.
Plot the optimization results for the electrical grid in an oriented graph for one time step.
populate_model
(model[, mode])Add electrical grid block to pyomo ConcreteModel.
remove_line
(line)Remove a line from the electrical grid.
update_cable_properties
(R_cable, X_cable)Update the resistance and reactance cable parameters of the electrical grid.
- add_line(line)
Add a line to the electrical grid.
Check whether the sending and receiving nodes of the line are already in the electrical grid. If not they are added. The line is added to the lines list of the grid and the line number is incremented by 1.
- Parameters:
line (ElectricalLine) – The line that should be added to the network.
- add_node(node)
Add a node to the electrical grid.
Check whether the node is already in the grid. If not, the node is assigned a number in the node dictionary and the node number is incremented by 1. If the node has a related entity, this entity is added to the connected_entity dictionary. The nodes inherit the voltage bounds of the electrical grid to which it is added.
- Parameters:
node (ElectricalNode) – The node that should be added to the network.
- build_incidence_matrix()
Build the incidence matrix of the electrical grid.
- Returns:
A – Incidence matrix of the grid.
- Return type:
np.ndarray
- connect_entities(entity1, entity2, line_capacity, line_length, R_line_per_km=None, X_line_per_km=None)
Add a line of specified length and capacity linking two entities in an electrical grid.
Convert line capacity in per unit according to the electrical grid nominal power. Calculate per unit resistance and reactance of the line using the grid cable properties. Add a line to the electrical grid to connect two entities, that can be electrical nodes or buildings.
- Parameters:
entity1 (Union[ElectricalNode, Building]) – First entity to connect, sending node of the line.
entity2 (Union[ElectricalNode, Building]) – Second entity to connect, receiving node of the line.
line_capacity (float) – Line capacity in kVA.
line_length (float) – Line length in km.
- plot_graph_results(t)
Plot the optimization results for the electrical grid in an oriented graph for one time step.
Represented electrical nodes of the electrical grid as graph nodes and lines as edges. Display the optimal values of power flow, power injection or generation and node voltages in per unit.
- Parameters:
t (int) – Time step for which results are plotted.
- populate_model(model, mode='convex')
Add electrical grid block to pyomo ConcreteModel.
Call parent’s populate_model method. Then call populate_model method of all contained electrical lines and electrical nodes. Add constraints on slack node operation; bounded exchange power and enforcement of specified slack voltage if any. Add coupling constraints between nodes and their related entities. Add power conservation constraint at each node.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- remove_line(line)
Remove a line from the electrical grid.
Remove the line from the line list and decrement the line number by 1.
- Parameters:
line (ElectricalLine) – The line that should be removed from the network.
- update_cable_properties(R_cable, X_cable)
Update the resistance and reactance cable parameters of the electrical grid.
Update the R_cable (ohm/km) and X_cable (ohm/km) attributes of the grid with the provided values.
pycity_scheduling.classes.electrical_line module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.electrical_line.ElectricalLine(environment, sending_node, receiving_node, resistance, reactance, max_capacity, *args, **kwargs)
Bases:
ElectricalEntity
Class ElectricalLine for scheduling purposes. Represents a connecting line/cable for the interconnection of buildings in pycity_scheduling.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
sending_node (Union[ElectricalNode, Building]) – First entity to connect, sending node of the line.
receiving_node (Union[ElectricalNode, Building]) – Second entity to connect, receiving node of the line.
resistance (float, optional) – Line resistance in Ohm.
reactance (float, optional) – Line reactance in Ohm.
max_capacity (float, optional) – Maximum line capacity (power) in kVA.
Methods
populate_model
(model[, mode])Add electrical line block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add electrical line block to pyomo ConcreteModel.
Call parent’s populate_model method. Set bounds on power flow according to line capacity. Perform max affine approximation for the square function. Coefficients of the approximation are used to set lower bounds on power square p_app_el_vars. Set disjunctive upper bounds constraints on p_app_el_vars using the big-M method. Set equality constraints to calculate power losses based on square power approximation. Add voltage drop constraint.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
pycity_scheduling.classes.electrical_node module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.electrical_node.ElectricalNode(environment, related_entity=None, position=None, min_V=0.95, max_V=1.05, ratio_pq_power=0.3333333333333333, *args, **kwargs)
Bases:
ElectricalEntity
Class ElectricalNode for scheduling purposes. Represents a building as a grid node inside an electrical grid within pycity_scheduling.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
related_entity (Building, optional) – The entity coupled to the grid node.
position (list, optional) – List of two floats specifying the position of the node inside the grid.
min_V (float, optional) – Minimum voltage allowed for healthy operation in p.u.
max_V (float, optional) – Maximum voltage allowed for healthy operation in p.u.
ratio_pq_power (float, optional) – The fixed ratio of reactive power demand with respect to the active power demand, for the building connected to this node.
Methods
populate_model
(model[, mode])Add electrical node block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add electrical node block to pyomo ConcreteModel.
Call parent’s populate_model method and set variables lower bound to None. Set bound constraints on node voltage.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
pycity_scheduling.classes.entity_container module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.entity_container.EntityContainer(environment, *args, **kwargs)
Bases:
ThermalEntityCooling
,ThermalEntityHeating
,ElectricalEntity
Base class for entities containing other entities.
p_th and p_el imbalances are propagated to this entities variables. During calls to its scheduling functions, the contained entities are also called with the same parameters.
Notes
EntityContainers offer sets of constraints for operation. The following constraints are added.
\[\begin{split}p_{th\_cool} &=& \sum_i p_{th\_cool\_i} \\ p_{th\_heat} &=& \sum_i p_{th\_heat\_i} \\ p_{el} &=& \sum_i p_{el\_i}\end{split}\]\(p_{th\_cool\_i}\), \(p_{th\_heat\_i}\), and \(p_{el\_i}\) are the variables from lower entities. The Bounds from TEC, TEH, and EE are removed.
Methods
Yield all lower-level entities.
populate_model
(model[, mode])Add entity block and lower entities blocks to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
Update the schedule with the scheduling model solution.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- populate_model(model, mode='convex')
Add entity block and lower entities blocks to pyomo ConcreteModel.
Call both parent’s populate_model methods and set variables lower bounds to None. Then call populate_model method of all contained entities and add constraints that the sum of their variables for each period equals the corresponding own variable.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule()
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
pycity_scheduling.classes.environment module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.environment.Environment(timer, weather, prices, location=(50.76, 6.07))
Bases:
Environment
Extension of pyCity_base class Environment for scheduling purposes.
pycity_scheduling.classes.fixed_load module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.fixed_load.FixedLoad(environment, method=0, demand=0, annual_demand=0, profile_type='H0', single_family_house=True, total_nb_occupants=0, randomize_appliances=True, light_configuration=0, occupancy=None, do_normalization=False, method_3_type=None, method_4_type=None, prev_heat_dev=False, app_filename=None, light_filename=None, season_light_mod=False, light_mod_fac=0.25)
Bases:
ElectricalEntity
,ElectricalDemand
Extension of pyCity_base class ElectricalDemand for scheduling purposes.
As for all uncontrollable loads, the p_el_schedule contains the forecast of the load.
- Parameters:
environment (Environment) – Common Environment instance.
method (int, optional) –
Defaults to method zero.
0 : provide load curve directly
1 : standard load profile (for households)
2 : stochastic electrical load model
3 : annual profile based on measured weekly profiles (non-residential)
4 : annual profile based on measured annual profiles (non-residential)
demand (numpy.ndarray, optional) – Demand for all investigated time steps in [kW] when using method=0.
annual_demand (float, optional) – Required for SLP and recommended for method 2. Defines the annual electrical demand in [kWh]. If method 2 is chosen but no value is given, a standard value for Germany (https://lena.sachsen-anhalt.de/fileadmin/Bibliothek/Sonstige_Webprojekte/Lena/Pressemitteilungen/ Stromspiegel/Stromspiegel2014_Medienblatt.pdf, accessed on 2020/09/28) is used.
profile_type (str, optional) –
H0 : Household
L0 : Farms
L1 : Farms with breeding / cattle
L2 : Farms without cattle
G0 : Business (general)
G1 : Business (workingdays 8:00 AM - 6:00 PM)
G2 : Business with high loads in the evening
G3 : Business (24 hours)
G4 : Shops / Barbers
G5 : Bakery
G6 : Weekend operation
total_nb_occupants (int, optional) – Number of people living in the household for method=2.
randomize_appliances (bool, optional) –
Randomization of appliances for method=2. Defaults to True.
True : distribute installed appliances randomly
False : use the standard distribution
light_configuration (int, optional) – There are 100 light bulb configurations predefined for the stochastic model when using method=2. Defaults to zero. A value between 0 and 100 should be provided.
occupancy (int, optional) – Occupancy given at 10-minute intervals for a full year for method=2.
do_normalization (bool, optional) – Defines, if stochastic profile (method=2) should be normalized to given annual_demand value. Defaults to False. If set to False, annual el. demand depends on stochastic el. load profile generation. If set to True, does normalization with annual_demand.
method_3_type (str, optional) –
Defines type of profile for method=3. Defaults to None. Options:
’food_pro’: Food production
’metal’: Metal company
’rest’: Restaurant (with large cooling load)
’sports’: Sports hall
’repair’: Repair / metal shop
method_4_type (str, optional) –
Defines type of profile for method=4. Defaults to None.
’metal_1’ : Metal company with smooth profile
’metal_2’ : Metal company with fluctuation in profile
’warehouse’ : Warehouse
prev_heat_dev (bool, optional) – Defines, if heating devices should be prevented within chosen appliances for method=2. Defaults to False. If set to True, DESWH, E-INST, Electric shower, Storage heaters and Other electric space heating are set to zero.
app_filename (str, optional) – Path to Appliances file for method=2. Defaults to None. If set to None, uses default file Appliances.csv in /inputs/stochastic_electrical_load/.
light_filename (str, optional) – Path to Lighting configuration file for method=2. Defaults to None. If set to None, uses default file Appliances.csv in /inputs/stochastic_electrical_load/.
season_light_mod (bool, optional) – Defines, if cosine-wave should be used to strengthen seasonal influence on lighting. Defaults to False. If True, enlarges lighting power demand in winter month and reduces lighting power demand in summer month.
light_mod_fac (float, optional) – Define factor, related to maximal lighting power, which is used to implement seasonal influence. Defaults to 25%. Only relevant, if season_light_mod == True
Notes
Standard load profiles, for instance for Germany, can be found here: https://www.bdew.de/energie/standardlastprofile-strom/ (accessed on 2020/09/28)
Average German electricity consumption data per household can be found here: https://lena.sachsen-anhalt.de/fileadmin/Bibliothek/Sonstige_Webprojekte/Lena/Pressemitteilungen/ Stromspiegel/Stromspiegel2014_Medienblatt.pdf (accessed on 2020/09/28)
The following constraint is added for removing the bounds from EE:
\[p_{el} = load\_curve\]Methods
new_schedule
(schedule)Create a new schedule with default values.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
Update the schedule with the scheduling model solution.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule()
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
pycity_scheduling.classes.heat_pump module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.heat_pump.HeatPump(environment, p_th_nom, cop=None, eta=0.36, t_max=55.0, lower_activation_limit=0.3, min_off_time=1, min_on_time=1, t_flow=55.0)
Bases:
ThermalEntityHeating
,ElectricalEntity
,Heatpump
Extension of pyCity_base class Heatpump for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power of the heat pump in [kW].
cop (numpy.ndarray or int or float, optional) – The heat pump’s coefficient of performance (without unit) If array, it must provide the coefficient of performance (cop) for each time step in the simulation horizon. If int or float, a constant cop over the whole horizon is assumed. If omitted, an air-water heat pump is assumed and the cop is calculated with the ambient air temperature.
eta (int or float, optional) – The Carnot efficiency of the heat pump. If cop is omitted, eta is used to calculate the cop based on T_sink and T_source according to: cop = eta * T_sink * (T_sink - T_source) with T_sink and T_source in Kelvin
t_max (float, optional) – The heat pump’s maximum provided temperature in °C
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the heat pump as a percentage of the rated power. When the heat pump is in operation, its power must be zero or between the lower activation limit and its rated power. Today’s (air-to-water) heat pumps typically have a lower activation limit of 30%.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the heat pump must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the heat pump must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
t_flow (float, optional) – T_sink temperature delivered by HP in °C. Is used for cop calculation if cop is omitted. Note that t_flow <= t_max must hold.
Notes
HPs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the HP:
\[\begin{split}0 \geq p_{th\_heat} &\geq& -p_{th\_nom} \\ cop * p_{el} &=& - p_{th\_heat}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call parent’s populate_model method and set thermal variables lower bounds to -self.p_th_nom and the upper bounds to zero. Also add constraint to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.optimization_entity module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.optimization_entity.OptimizationEntity(environment, *args, **kwargs)
Bases:
object
Base class for all optimization entities.
This class provides functionality common to all entities which take part in the scheduling optimization.
- Parameters:
environment (Environment) – Common Environment instance.
- Attributes:
op_horizon
Number of time steps in a scheduling period.
op_slice
Slice to select values of current scheduling from whole horizon.
op_time_vec
Iterator over scheduling period.
schedule
The current loaded schedule.
simu_horizon
Number of time steps in the whole simulation horizon.
time_slot
Length of a time step as a portion of an hour.
timestep
Time step indicating the current scheduling.
Methods
copy_schedule
([dst, src, name])Copy values of one schedule in another schedule.
Yield all entities.
Return the decision varaible(s) of the entity's objective function.
Yield all lowest contained entities.
Yield all lower-level entities.
get_objective
([coeff])Objective function for entity level scheduling.
load_schedule
(schedule)Copy values of one schedule in another schedule.
load_schedule_into_model
([schedule, nudge])Overwrites the values in the entity model with the values in the schedule.
new_schedule
(schedule)Create a new schedule with default values.
new_var
(name[, dtype, func])Create a new entry and empty schedule for variable with specified name.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
set_objective
(objective)Set a new objective to be returned by get_objective.
update_model
([mode])Update block parameters and bounds.
update_schedule
([verbose])Update the schedule with the scheduling model solution.
- copy_schedule(dst=None, src=None, name=None)
Copy values of one schedule in another schedule.
- get_all_entities()
Yield all entities.
- Yields:
All contained entities and sub-entities.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_entities()
Yield all lowest contained entities.
- Yields:
Lowest contained entities or self.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the entity weighted with coeff.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- load_schedule(schedule)
Copy values of one schedule in another schedule.
- Parameters:
schedule (str)
schedule. (Name of schedule to set as current)
- load_schedule_into_model(schedule=None, nudge=True)
Overwrites the values in the entity model with the values in the schedule.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- new_var(name, dtype=<class 'numpy.float64'>, func=None)
Create a new entry and empty schedule for variable with specified name.
- Parameters:
name (str) – Name to access new variable with.
dtype (numpy.dtype, optional) – Data type which should be used for new schedule.
func (Callable[[int], Any], optional) – Function to generate schedule with. If None, schedule is generated with values of variables.
- property op_horizon
Number of time steps in a scheduling period.
- property op_slice
Slice to select values of current scheduling from whole horizon.
- property op_time_vec
Iterator over scheduling period.
- populate_model(model, mode='')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- property schedule
The current loaded schedule.
- set_objective(objective)
Set a new objective to be returned by get_objective.
- Parameters:
objective (str) –
Objective for the scheduling.
’none’ : No objective (leave all flexibility to other participants).
- property simu_horizon
Number of time steps in the whole simulation horizon.
- static_entity_id = 0
- property time_slot
Length of a time step as a portion of an hour.
Examples
time step length = 60 mins => time_slot = 1 time step length = 15 mins => time_slot = 0.25
- property timestep
Time step indicating the current scheduling.
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule(verbose=False)
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
pycity_scheduling.classes.photovoltaic module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.photovoltaic.Photovoltaic(environment, method, area=0.0, peak_power=0.0, eta_noct=0.18, radiation_noct=1000.0, t_cell_noct=45.0, t_ambient_noct=20.0, alpha_noct=0, beta=0, gamma=0, tau_alpha=0.9, force_renewables=True)
Bases:
ElectricalEntity
,PV
Extension of pyCity_base class PV for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
method (int) –
0 : Calculate PV power based on an area in m^2 equipped with PV panels
1 : Calculate PV power based on the installed PV peak power in kWp
area (float, optional) – PV unit installation area in m^2 for method=0.
peak_power (float, optional) – PV peak power installation in kWp for method=1.
eta_noct (float, optional) – Electrical efficiency at NOCT conditions (without unit) for method=0. NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
radiation_noct (float, optional) – Nominal solar radiation at NOCT conditions (in W/m^2) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
t_cell_noct (float, optional) – Nominal cell temperature at NOCT conditions (in degree Celsius) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
t_ambient_noct (float, optional) – Nominal ambient air temperature at NOCT conditions (in degree Celsius) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
alpha_noct (float, optional) – Temperature coefficient at NOCT conditions (without unit) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
beta (float, optional) – Slope, the angle (in degree) between the plane of the surface in question and the horizontal. 0 <= beta <= 180. If beta > 90, the surface faces downwards.
gamma (float, optional) – Surface azimuth angle. The deviation of the projection on a horizontal plane of the normal to the surface from the local meridian, with zero due south, east negative, and west positive. -180 <= gamma <= 180
tau_alpha (float, optional) – Optical properties of the PV unit. Product of absorption and transmission coeffients. According to Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 758, this value is typically close to 0.9
force_renewables (bool, optional) – True if generation may not be reduced for optimization purposes.
Notes
The following constraint is added for removing the bounds from EE:
\[\begin{split}p_{el} &=& -p_{el\_supply}, & \quad \text{if force_renewables} \\ 0 \geq p_{el} &\geq& -p_{el\_supply} , & \quad \text{else}\end{split}\]Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function of the Photovoltaic.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function of the Photovoltaic.
Return the objective function of the photovoltaic weighted with coeff. Depending on self.force_renewables leave objective function empty or build quadratic objective function to minimize discrepancy between available power and produced power.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.prices module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.prices.Prices(timer, da_prices=None, tou_prices=None, co2_prices=None, feedin_factor=0)
Bases:
Prices
Extension of pyCity_base class Prices for scheduling purposes.
- Parameters:
timer (Timer) – Timer instance for generating needed prices.
da_prices (array_like, optional) – Day-ahead prices for each timestep in the simu_horizon in [ct/kWh].
tou_prices (array_like, optional) – Time-of-use prices for each timestep in the simu_horizon in [ct/kWh].
co2_prices (array_like, optional) – CO2 emissions for each timestep in the simu_horizon in [g/kWh].
feedin_factor (float, optional) – Factor which is multiplied to the prices for feed-in revenue. Should be in [0,1], as prices for feed-in are usually lower than for consumption.
Notes
If prices are loaded automatically, the simulation period must lie within a single year.
CO2 emissions and day-ahead prices are currently available for the year 2015 only.
- Attributes:
- co2_price_cache
- da_price_cache
- tou_price_cache
- tou_price_cache_year
- co2_price_cache = None
- da_price_cache = None
- tou_price_cache = None
- tou_price_cache_year = None
pycity_scheduling.classes.space_cooling module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.space_cooling.SpaceCooling(environment, method=0, loadcurve=1, living_area=0, specific_demand=0, profile_type='HEF')
Bases:
ThermalEntityCooling
,SpaceCooling
Extension of pyCity_base class SpaceCooling for scheduling purposes.
As for all uncontrollable loads, the p_th_schedule contains the forecast of the load.
- Parameters:
environment (Environment object) – Common to all other objects. Includes time and weather instances
method (integer, optional) –
0 : Provide load curve directly
1 : Use thermal standard load profile (not implemented yet!)
loadcurve (Array-like, optional) – Load curve for all investigated time steps Requires method=0
living_area (Float, optional) – Living area of the apartment in m^2 Requires method=1
specific_demand (Float, optional) – Specific thermal demand of the building in kWh/(m^2 a) Requires method=1
profile_type (str, optional) – Thermal SLP profile name Requires method=1 - HEF : Single family household - HMF : Multi family household - GBA : Bakeries - GBD : Other services - GBH : Accomodations - GGA : Restaurants - GGB : Gardening - GHA : Retailers - GHD : Summed load profile business, trade and services - GKO : Banks, insurances, public institutions - GMF : Household similar businesses - GMK : Automotive - GPD : Paper and printing - GWA : Laundries
Notes
The following constraint is added for removing the bounds from the TEC:
\[p_{th\_cool} = load\_curve\]Methods
new_schedule
(schedule)Create a new schedule with default values.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
Update the schedule with the scheduling model solution.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal cooling demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule()
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
pycity_scheduling.classes.space_heating module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.space_heating.SpaceHeating(environment, method=0, loadcurve=1, living_area=0, specific_demand=0, profile_type='HEF', zone_parameters=None, t_m_init=None, ventilation=0, t_cooling_set=200, t_heating_set=-50, occupancy=0, appliances=0, lighting=0)
Bases:
ThermalEntityHeating
,SpaceHeating
Extension of pyCity_base class SpaceHeating for scheduling purposes.
As for all uncontrollable loads, the p_th_heat_schedule contains the forecast of the load.
- Parameters:
environment (Environment) – common to all other objects, includes time and weather instances
method (int, optional) –
0 : Provide load curve directly
1 : Use thermal standard load profile
2 : Use ISO 13790 standard to compute thermal load
loadcurve (numpy.ndarray of float, optional) – load curve for all investigated time steps in [kW] requires method=0.
living_area (float, optional) – living area of the apartment in m2 requires method=1
specific_demand (float, optional) – specific thermal demand of the building in [kWh /(m2*a)] requires method=1
profile_type (str, optional) – thermal SLP profile name requires method=1 - “HEF” : Single family household - “HMF” : Multi family household - “GBA” : Bakeries - “GBD” : Other services - “GBH” : Accomodations - “GGA” : Restaurants - “GGB” : Gardening - “GHA” : Retailers - “GHD” : Summed load profile business, trade and services - “GKO” : Banks, insurances, public institutions - “GMF” : Household similar businesses - “GMK” : Automotive - “GPD” : Paper and printing - “GWA” : Laundries
zone_parameters (ZoneParameters object, optional) – parameters of the building (floor area, building class, etc.) for method=2.
t_m_init (float, optional) – Initial temperature of the internal heat capacity in [°C] for method=2.
ventilation (array_like, optional) – Ventilation rate in [1/h] for method=2.
t_cooling_set (array_like, optional) – Cooling starts if the room temperature exceeds this value for method=2.
t_heating_set (array_like, optional) – Heating starts if the room temperature drops below this value for method=2.
occupancy (array_like, optional) – Full year occupancy profile for method=2.
appliances (array_like, optional) – Internal gains from electrical appliances in [W] for method=2.
lighting (array_like, optional) – Internal gains from lighting in Watt for method=2.
Notes
The thermal standard load profile is based on the dissertation of Mark Hellwig “Entwicklung und Anwendung parametrisierter Standard-Lastprofile”, TU München, Germany, 2003: http://mediatum.ub.tum.de/doc/601557/601557.pdf (accessed on 2020/09/28)
The following constraint is added for removing the bounds from TEH:
\[p_{th\_heat} = load\_curve\]Methods
new_schedule
(schedule)Create a new schedule with default values.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
update_schedule
([mode])Update the schedule with the scheduling model solution.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal heating demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule(mode='')
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
pycity_scheduling.classes.thermal_cooling_storage module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.thermal_cooling_storage.ThermalCoolingStorage(environment, e_th_max, soc_init=0.5, loss_factor=0, storage_end_equality=False)
Bases:
ThermalEntityCooling
,ThermalEnergyStorage
Extension of pyCity_base class ThermalEnergyStorage for scheduling purposes. A thermal cooling storage device can be used as a ‘buffer’ within a cooling system setup.
- Parameters:
environment (Environment) – Common Environment instance.
e_th_max (float) – Amount of energy the TCS is able to store in [kWh].
soc_init (float) – Initial state of charge.
loss_factor (float, optional) – Storage’s loss factor (area*U_value) in [W/K].
storage_end_equality (bool, optional) – Defaults to False. True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc.
Notes
TCSs offer sets of constraints for operation. The following constraints and bounds are generated by the TCS:
\[\begin{split}e_{th\_cool} &=& e_{th\_cool\_previous} * (1-th\_loss) + p_{th\_cool} * \Delta t \\ \text{with} \quad e_{th\_cool\_previous} &=& \begin{bmatrix} e_{th\_ini} & e_{th\_cool\_0} & \cdots & e_{th\_cool\_n-1}\end{bmatrix}\end{split}\]Additional constraints generated by the parameters are:
\[\begin{split}e_{th\_cool\_t\_last} &=& soc\_init * e_{th\_max}, & \quad \text{if storage_end_equality} \\ e_{th\_cool\_t\_last} &\geq& soc\_init * e_{th\_max}, & \quad \text{else}\end{split}\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables lower bounds to None. Then add variables for the state of charge with an upper bound of self.e_th_max. Also add continuity constraints to the model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.thermal_entity_cooling module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.thermal_entity_cooling.ThermalEntityCooling(environment, *args, **kwargs)
Bases:
OptimizationEntity
Base class for all thermal cooling entities derived from OptimizationEntity.
This class provides functionality common to all thermal cooling entities.
Notes
Cooling TEs add the \(p_{th\_cool}\) variable to the model. When not modified by other classes, the following constraint is added:
\[p_{th\_cool} \geq 0\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal cooling demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
pycity_scheduling.classes.thermal_entity_heating module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.thermal_entity_heating.ThermalEntityHeating(environment, *args, **kwargs)
Bases:
OptimizationEntity
Base class for all thermal heating entities derived from OptimizationEntity.
This class provides functionality common to all thermal heating entities.
Notes
Heating TEs add the \(p_{th\_heat}\) variable to the model. When not modified by other classes, the following constraint is added:
\[p_{th\_heat} \geq 0\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal heating demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
pycity_scheduling.classes.thermal_heating_storage module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.thermal_heating_storage.ThermalHeatingStorage(environment, e_th_max, soc_init=0.5, loss_factor=0, storage_end_equality=False)
Bases:
ThermalEntityHeating
,ThermalEnergyStorage
Extension of pyCity_base class ThermalEnergyStorage for scheduling purposes. A thermal heating storage device can be used as a ‘buffer’ within a heating system setup.
- Parameters:
environment (Environment) – Common Environment instance.
e_th_max (float) – Amount of energy the THS is able to store in [kWh].
soc_init (float) – Initial state of charge.
loss_factor (float, optional) – Storage’s loss factor (area*U_value) in [W/K].
storage_end_equality (bool, optional) – Defaults to False. True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc.
Notes
THSs offer sets of constraints for operation. The following constraints and bounds are generated by the THS:
\[\begin{split}e_{th\_heat} &=& e_{th\_heat\_previous} * (1-th\_loss) + p_{th\_heat} * \Delta t \\ \text{with} \quad e_{th\_heat\_previous} &=& \begin{bmatrix} e_{th\_ini} & e_{th\_heat\_0} & \cdots & e_{th\_heat\_n-1}\end{bmatrix}\end{split}\]Additional constraints generated by the parameters are:
\[\begin{split}e_{th\_heat\_t\_last} &=& soc\_init * e_{th\_max}, & \quad \text{if storage_end_equality} \\ e_{th\_heat\_t\_last} &\geq& soc\_init * e_{th\_max}, & \quad \text{else}\end{split}\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables lower bounds to None. Then add variables for the state of charge with an upper bound of self.e_th_max. Also add continuity constraints to the model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
pycity_scheduling.classes.timer module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.timer.Timer(step_size=900, op_horizon=96, mpc_horizon=None, mpc_step_width=None, initial_date=(2015, 1, 1), initial_time=(0, 0, 0))
Bases:
Timer
Extension of pyCity_base class Timer for scheduling purposes
- Parameters:
step_size (int, optional) – Number of seconds in one time step.
op_horizon (int, optional) – Number of time steps used in one scheduling optimization.
mpc_horizon (int, optional) – Number of time steps in whole simulation. All data must be available for this time. If None set value to op_horizon.
mpc_step_width (int, optional) – Number of timesteps between two optimizations in MPC. If None set value to op_horizon.
initial_date (tuple, optional) – Initial date in the format (year, month, day).
initial_time (tuple, optional) – Initial time in the format (hour, minute, second).
Notes
This class’ behaviour may differ from the one of the baseclass, as it keeps an actual date rather than a relative counter only
- Attributes:
date
The date of the current timestep.
datetime
The datetime of the current timestep.
day
The day of the month for the current timestep.
hour
The hour of the current timestep.
is_leap
If the year of the current timestep is a leap year.
minute
The minute of the current timestep.
month
The month of the current timestep.
second
The second of the current timestep.
time
The time for the current timestep.
weekday
The weekday of the current timestep.
year
The year of the current timestep.
Methods
Update Timer for MPC.
Update Timer for a normal scheduling optimization.
Print the datetime for the current timestep.
reset
()Reset the Timer to the initial state.
time_in_day
([unit, from_init])Time passed since beginning of the day.
time_in_week
([unit, from_init])Time passed since beginning of the day.
time_in_year
([unit, from_init])Time passed since the beginning of the year.
- property date
The date of the current timestep.
- property datetime
The datetime of the current timestep.
- property day
The day of the month for the current timestep.
- property hour
The hour of the current timestep.
- property is_leap
If the year of the current timestep is a leap year.
- property minute
The minute of the current timestep.
- property month
The month of the current timestep.
- mpc_update()
Update Timer for MPC.
Move self.mpc_step_width timesteps forward.
- op_update()
Update Timer for a normal scheduling optimization.
Go self.timesteps_used_horizon timesteps forward.
- print_datetime()
Print the datetime for the current timestep.
- reset()
Reset the Timer to the initial state.
- property second
The second of the current timestep.
- property time
The time for the current timestep.
- time_in_day(unit='timesteps', from_init=False)
Time passed since beginning of the day.
- Parameters:
- Returns:
Time in specified unit.
- Return type:
- time_in_week(unit='timesteps', from_init=False)
Time passed since beginning of the day.
- Parameters:
- Returns:
Time in specified unit.
- Return type:
- time_in_year(unit='timesteps', from_init=False)
Time passed since the beginning of the year.
- property weekday
The weekday of the current timestep.
- property year
The year of the current timestep.
pycity_scheduling.classes.weather module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.weather.Weather(timer, path_TRY=None, path_TMY3=None, new_try=False, path_temperature='', path_direct_radiation='', path_diffuse_radiation='', path_wind_speed='', path_humidity='', path_pressure='', path_cloudiness='', time_discretization=3600, delimiter='\t', use_TRY=True, use_TMY3=False, location=(50.76, 6.07), height_velocity_measurement=10, altitude=152.0, time_zone=1)
Bases:
Weather
Extension of pyCity_base class Weather for scheduling purposes.
pycity_scheduling.classes.wind_energy_converter module
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.wind_energy_converter.WindEnergyConverter(environment, velocity, power, hub_height=70, roughness=0.1, force_renewables=True)
Bases:
ElectricalEntity
,WindEnergyConverter
Extension of pyCity_base class WindEnergyConverter for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
velocity (numpy.ndarray) – Wind speeds in [m/s].
power (numpy.ndarray) – Power for given velocities in [kW].
hub_height (float, optional) – Height of the wind energy converter in [m].
roughness (float, optional) – Roughness of landscape in [m].
force_renewables (bool, optional) – True if generation may not be reduced for optimization purposes.
Notes
The following constraint is added for removing the bounds from EE:
\[\begin{split}p_{el} &=& -p_{el\_supply}, & \quad \text{if force_renewables} \\ 0 \geq p_{el} &\geq& -p_{el\_supply} , & \quad \text{else}\end{split}\]Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function of the WindEnergyConverter.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function of the WindEnergyConverter.
Return the objective function of the wind energy converter weighted with coeff. Depending on self.force_renewables leave objective function empty or build quadratic objective function to minimize discrepancy between available power and produced power.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
Module contents
The pycity_scheduling framework
Copyright (C) 2025, Institute for Automation of Complex Power Systems (ACS), E.ON Energy Research Center (E.ON ERC), RWTH Aachen University
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class pycity_scheduling.classes.Apartment(environment, net_floor_area=None, occupancy=None)
Bases:
EntityContainer
,Apartment
Extension of pyCity_base class Apartment for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances
net_floor_area (float, optional) – netto floor area in [m^2]
occupancy (Occupancy, optional) – Occupancy profile from pycity_base for the apartment.
Notes
Apartments inherit their set of constraints from EntityContainer.
Methods
addEntity
(entity)Add entity to apartment.
Yield all lower-level entities.
- addEntity(entity)
Add entity to apartment.
- Parameters:
entity (OptimizationEntity) – Entity to be added to the apartment; must be of type FixedLoad, DeferrableLoad, CurtailableLoad, SpaceHeating, SpaceCooling or DomesticHotWater.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- class pycity_scheduling.classes.Battery(environment, e_el_max, p_el_max_charge, p_el_max_discharge=None, soc_init=0.5, eta=0.95, storage_end_equality=False)
Bases:
ElectricalEntity
,Battery
Extension of pyCity_base class Battery for scheduling purposes.
Initialize Battery.
- Parameters:
environment (Environment) – Common Environment instance.
e_el_max (float) – Electric capacity of the battery [kWh].
p_el_max_charge (float) – Maximum charging power [kW].
p_el_max_discharge (float, optional) – Maximum discharging power [kW]. Defaults to zero.
soc_init (float, optional) – Initial state of charge. Defaults to 50%.
eta (float, optional) – Charging and discharging efficiency. Must be in (0,1]. Defaults to one.
storage_end_equality (bool, optional) – True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc. Defaults to False.
Notes
Batteries offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the battery:
\[\begin{split}p_{el} &=& p_{el\_demand} - p_{el\_supply} \\ p_{el\_max\_discharge} &\geq& p_{el\_supply} \geq 0 \\ p_{el\_max\_charge} &\geq& p_{el\_demand} \geq 0 \\ e_{el\_max} &\geq& e_{el} \geq 0 \\ e_{el} &=& e_{el\_previous} + (\eta * p_{el\_demand} - (1 / \eta) * p_{el\_supply}) * \Delta t \\ \text{with} \quad e_{el\_previous} &=& \ \begin{bmatrix} e_{el\_ini} & e_{el\_0} & \cdots & e_{el\_n-1}\end{bmatrix}\end{split}\]Additional constraints generated by the parameters are:
\[\begin{split}e_{el\_t\_last} &=& soc\_init * e_{el\_max}, & \quad \text{if storage_end_equality} \\ e_{el\_t\_last} &\geq& soc\_init * e_{el\_max}, & \quad \text{else}\end{split}\]In integer mode the following constraints are added in addition:
\[\begin{split}p_{el\_demand} &\leq& p_{state} * p_{el\_max\_discharge} \\ p_{el\_supply} &\leq& (1-p_{state}) * p_{el\_max\_charge}\end{split}\]Methods
populate_model
(model[, mode])Add device block of variables and constraints to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block of variables and constraints to pyomo ConcreteModel.
Call parent’s populate_model method and set variables lower bounds to None. Then add variables for demand, supply and the state of charge, with their corresponding upper bounds (self.p_el_max_charge, self.p_el_max_discharge, self.e_el_max). Finally add continuity constraints to the block.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.Boiler(environment, p_th_nom, eta=1, lower_activation_limit=0.0, min_off_time=1, min_on_time=1)
Bases:
ThermalEntityHeating
,Boiler
Extension of pyCity_base class Boiler for scheduling purposes.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal heat output in [kW].
eta (float, optional) – Efficiency of the gas boiler (without unit).
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the gas boiler as a percentage of the rated power. When the gas boiler is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the boiler must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the boiler must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
Notes
Gas boilers offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the boiler:
\[0 \geq p_{th\_heat} \geq -p_{th\_nom}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the boiler weighted with coeff. Sum of p_th_heat.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables upper bounds to self.p_th_nom.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.Building(environment, objective='price', name=None, profile_type=None, building_type=None, storage_end_equality=False, least_squares_profile=None)
Bases:
EntityContainer
,Building
Extension of pyCity_base class Building for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
objective (str, optional) –
Objective for the scheduling. The default is ‘price’.
’price’ : Optimize for the prices given by prices.tou_prices.
’co2’ : Optimize for the CO2 emissions given by prices.co2_prices.
’peak-shaving’ : Try to flatten the schedule as much as possible.
’max-consumption’ : Try to reduce the maximum of the absolute values of the schedule as much as possible.
’self-consumption’ : Try to maximize the self-consumption of the local power generation.
’least-squares’: Try to follow a given reference power profile.
’none’ : No objective (leave all flexibility to other participants).
name (str, optional) – Name for the building. If name is None, set it to self._long_id.
profile_type (str, optional) –
Thermal SLP profile name Requires method=1
’HEF’ : Single family household
’HMF’ : Multi family household
’GBA’ : Bakeries
’GBD’ : Other services
’GBH’ : Accommodations
’GGA’ : Restaurants
’GGB’ : Gardening
’GHA’ : Retailers
’GHD’ : Summed load profile business, trade and services
’GKO’ : Banks, insurances, public institutions
’GMF’ : Household similar businesses
’GMK’ : Automotive
’GPD’ : Paper and printing
’GWA’ : Laundries
building_type (str, optional) – Build year profile name, the detailed list is implemented in tabula_data.py.
storage_end_equality (bool, optional) – True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc.
least_squares_profile (numpy.ndarray, optional) – Profile to be used by the least-squares objective.
Notes
The exchange of thermal energy between different buildings is currently not supported. As a result, the building additionally adds the following set of constrains to the ones of the EntityContainer:
\[\begin{split}p_{th\_heat} &=& 0 \\ p_{th\_cool} &=& 0\end{split}\]The building can also add robustness constrains for thermal heating storage:
\[\begin{split}e_{u\_bound} \geq \sum_i e_{th\_heat\_i} \geq e_{l\_bound} \\\end{split}\]The \(E_{u\_bound}\) and \(E_{l\_bound}\) are determined by the robustness parameter, the available capacity of thermal heating storage, the magnitude of heating required by SpaceHeating and the magnitude of heating that can be produced by the building’s heating units.
Methods
Yield all lower-level entities.
populate_model
(model[, mode, robustness])Add building block to pyomo ConcreteModel.
update_model
([mode, robustness])Update block parameters and bounds.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- populate_model(model, mode='convex', robustness=None)
Add building block to pyomo ConcreteModel.
Call parent’s populate_model method and set variables lower bounds to None. Then call populate_model method of the BES and all contained apartments and add constraints that the sum of their variables for each period equals the corresponding own variable.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
robustness (tuple, optional) – Tuple of two floats. First entry defines how many time steps are protected from deviations. Second entry defines the magnitude of deviations which are considered.
- update_model(mode='', robustness=None)
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
robustness (tuple, optional) – Tuple of two floats. First entry defines how many time steps are protected from deviations. Second entry defines the magnitude of deviations which are considered.
- class pycity_scheduling.classes.BuildingEnergySystem(environment)
Bases:
EntityContainer
,BES
Extension of pyCity_base class BES for scheduling purposes.
- Parameters:
environment (Environment)
Notes
The constraints generated by a BES are the same as the ones created by an EntityContainer.
Methods
getHasDevices
([all_devices, battery, ...])Get information if certain devices are installed devices.
Yield all lower-level entities.
- getHasDevices(all_devices=True, battery=False, boiler=False, chp=False, chiller=False, electrical_heater=False, heatpump=False, inverter_acdc=False, inverter_dcac=False, pv=False, ths=False, tcs=False)
Get information if certain devices are installed devices. The result is in alphabetical order, starting with “battery”
- Parameters:
all_devices (boolean, optional) – If true: Return all installed devices If false: Only return the specified devices
battery (boolean, optional) – Return information about the battery unit
boiler (boolean, optional) – Return information about the boiler unit
chp (boolean, optional) – Return information about the chp unit
chiller (boolean, optional) – Return information about the chiller unit
electrical_heater (boolean, optional) – Return information about the electric heater unit
heatpump (boolean, optional) – Return information about the heat pump unit
inverter_acdc (boolean, optional) – Return information about the AC-DC inverter unit
inverter_dcac (boolean, optional) – Return information about the DC-AC inverter unit
pv (boolean, optional) – Return information about the PV unit
ths (boolean, optional) – Return information about the thermal heating storage unit
tcs (boolean, optional) – Return information about the thermal cooling storage unit
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- property tcs_units
Provides all TCS units.
- property ths_units
Provides all THS units.
- class pycity_scheduling.classes.Chiller(environment, p_th_nom, cop=None, eta=0.36, t_min=4.0, lower_activation_limit=0, min_off_time=1, min_on_time=1, t_flow=16.0)
Bases:
ThermalEntityCooling
,ElectricalEntity
,CompressionChiller
Extension of pyCity_base class CompressionChiller for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power of the chiller in [kW].
cop (numpy.ndarray or int or float, optional) – The chiller’s coefficient of performance (without unit) If array, it must provide the coefficient of performance (cop) for each time step in the simulation horizon. If int or float, a constant cop over the whole horizon is assumed. If omitted, an air-water chiller is assumed and the cop is calculated based on the ambient air temperature, eta and t_flow.
eta (int or float, optional) – The Carnot efficiency of the chiller. If cop is omitted, eta is used to calculate the cop based on T_sink and T_source according to: cop = eta * T_sink * (T_sink - T_source) with T_sink and T_source in Kelvin
t_min (float, optional) – The chiller’s minimum provided temperature in °C
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the chiller as a percentage of the rated power. When the chiller is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the chiller must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the chiller must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
t_flow (float, optional) – T_sink temperature delivered by CC in °C. Is used for cop calculation if cop is omitted. Note that t_flow >= t_min must hold.
Notes
CHs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the CH:
\[\begin{split}0 \geq p_{th\_cool} &\geq& -p_{th\_nom} \\ cop * p_{el} &=& - p_{th\_cool}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call parent’s populate_model method and set thermal variables lower bounds to -self.p_th_nom and the upper bounds to zero. Also add constraint to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.CityDistrict(environment, objective='price', valley_profile=None, least_squares_profile=None, electrical_grid=None)
Bases:
ElectricalEntity
,CityDistrict
Extension of pyCity_base class CityDistrict for scheduling purposes. Also represents the district operator.
- Parameters:
environment (Environment)
objective (str, optional) –
Objective for the district operator. Default is ‘price’.
’price’ : Optimize for the minimum total cost given by prices.da_prices.
’peak-shaving’ : Try to ‘flatten’ the schedule as much as possible.
’co2’ : Optimize for the minimum total co2 emissions given by prices.co2_prices.
’valley-filling’ : Try to fill the ‘valleys’ given by self.valley_profile.
’max-consumption’ : Try to minimize the maximum power subscription.
’self-consumption’ : Try to maximize the self-consumption of the local power generation.
’least-squares’: Try to follow a given reference power profile.
’flexibility-quantification’ : To be used to quantify the flexibility potential of the city district only.
’none’ : No objective.
valley_profile (numpy.ndarray, optional) – Profile to be filled by applying the valley filling objective.
least_squares_profile (numpy.ndarray, optional) – Profile to be used by the least-squares objective.
electrical_grid (ElectricalGrid, optional) – Assign an ElectricalGrid object to the city district representing the local power grid
Notes
The constraints generated by a CD are the same as the ones created by an EntityContainer.
Methods
Changes the current schedule to account imbalances.
addElectricalGrid
(environment, max_p_slack, ...)Add electrical grid to the city district.
Return the decision varaible(s) of the entity's objective function.
Yield all lower-level entities.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add city district block to pyomo ConcreteModel.
- account_imbalance()
Changes the current schedule to account imbalances.
The imbalances are determined from the current schedules of the contained entities.
- addElectricalGrid(environment, max_p_slack, max_q_slack, slack_V=None, ref_V=400, V_min=0.95, V_max=1.05)
Add electrical grid to the city district.
Create an ElectricalGrid object and link it to the city district through the electrical_grid attribute. Add an electrical node the electrical grid for each entity contained in the city district.
- Parameters:
environment (Environment)
max_p_slack (float) – Maximum active power that can be exchanged through slack node of the grid in kW.
max_q_slack (float) – Maximum reactive power that can be exchanged through slack node of the grid in kVar.
slack_V (float) – If not None, voltage at which the slack node should be operated in V. Default is None.
ref_V (float) – Nominal voltage in the electrical grid in V. Default is 400V.
V_min (float) – Minimal per unit voltage allowed in the electrical grid. Default is 0.95.
V_max (float) – Maximal per unit voltage allowed in the electrical grid. Default is 1.05.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the entity weighted with coeff.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add city district block to pyomo ConcreteModel.
Call parent’s populate_model methods and set variables lower bounds to None.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- class pycity_scheduling.classes.CombinedHeatPower(environment, p_th_nom, p_el_nom=None, eta=6.0, lower_activation_limit=0.5, min_off_time=1, min_on_time=1)
Bases:
ThermalEntityHeating
,ElectricalEntity
,CHP
Extension of pyCity_base class CHP for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power output in [kW].
p_el_nom (float, optional) – Nominal electrical power output in [kW]. Defaults to the product of p_th_nom and ‘eta’.
eta (float, optional) – Efficiency of the CHP unit by means of the ratio thermal vs. electrical (without unit).
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the CHP as a percentage of the rated power. When the CHP is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the CHP unit must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the CHP unit must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
Notes
CHPs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the CHP:
\[\begin{split}0 &\geq& p_{th\_heat} \geq -p_{th\_nom} \\ 0 &\geq& p_{el} \geq -p_{el\_nom} \\ \frac{p_{el}}{p_{el\_nom}} &=& \frac{p_{th\_heat}}{p_{th\_nom}}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call both parents’ populate_model methods and set the upper bounds of the thermal variables to self.p_th_nom, the lower bounds of the electrical variables to -self.p_el_nom and the upper bounds to zero. Also add constraints to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.CurtailableLoad(environment, p_el_nom, max_curtailment, max_low=None, min_full=None)
Bases:
ElectricalEntity
,ElectricalDemand
Extension of pyCity_base class ElectricalDemand for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
p_el_nom (float) – Nominal electric power in [kW].
max_curtailment (float) – Maximal Curtailment of the load
max_low (int, optional) – Maximum number of timesteps the curtailable load can stay under nominal load
min_full (int, optional) – Minimum number of timesteps the curtailable load has to stay at nominal operation level when switching to the nominal operation level
Notes
CLs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the CL:
\[\begin{split}p_{el\_nom} * max\_curtailment \geq p_{el} \geq 0 \\ \sum_{j=i}^{i+max\_low+min\_full} p_{el\_j} \geq p_{el\_nom} * (min\_full + max\_low * max\_curtailment)\end{split}\]The last constraint is replaced in integer mode with the following constraints:
\[\begin{split}p_{el} \geq p_{state} * p_{el\_nom} \\ \sum_{j=i}^{i+max\_low} p_{state\_j} \geq 1 \\ \sum_{j=i}^{i+min\_full-1} p_{state\_j} \geq (p_{state\_i} - p_{state\_i-1}) * min\_full\end{split}\]These constraints take also the previous values before the current optimization horizon into account using the current schedule. Values before \(t=0\) are assumed to be perfect.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables upper bounds to the loadcurve and lower bounds to self.p_el_Min.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Uses integer variables for max_low and min_full constraints if necessary
- update_model(mode='convex')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.DeferrableLoad(environment, p_el_nom, e_consumption, load_time=None, lt_pattern=None)
Bases:
ElectricalEntity
,ElectricalDemand
Extension of pyCity_base class ElectricalDemand for scheduling purposes.
The Load will always run once in the op_horizon
- Parameters:
environment (Environment) – Common Environment instance.
p_el_nom (float) – Nominal electric power in [kW].
e_consumption (float) – Power to be consumed over the op_horizon in [kWh].
load_time (array of binaries, optional) – Indicator when deferrable load can be turned on. Defaults to always. load_time[t] == 0: device is off in t load_time[t] == 1: device can be turned on in t It must contain at least one 0 otherwise the model will become infeasible. Its length has to be consistent with lt_pattern.
lt_pattern (str, optional) –
Define how the load_time profile is to be used
None : Profile matches simulation horizon.
’daily’ : Profile matches one day.
’weekly’ : Profile matches one week.
- Raises:
ValueError : – If lt_pattern does not match load_time.
Notes
DLs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the DL:
\[\begin{split}p_{el\_nom} \geq p_{el\_i} \geq 0, & \quad \text{if} \quad lt\_pattern_i = 1 \\ p_{el\_i} = 0, & \quad \text{else}\end{split}\]\[\sum_i p_{el\_i} * \Delta t = e_{consumption}\]The constraints are replaced in integer mode with the following constraints:
\[\begin{split}\sum_i p_{state\_i} &=& 1 \\ runtime &=& \lfloor \frac{p_{el\_nom} * \Delta t}{e_{consumption}} \rceil \\ p_{el\_i} &=& p_{el\_nom} * \sum_{j=i-runtime+1}^{i} p_{state\_j} \\ p_{state\_i} &=& 0, \quad \text{if} \quad \sum_{j=i}^{i+runtime-1} lt\_pattern_j = runtime \\\end{split}\]These constraints do not take the previous values before the current optimization horizon into account. In the optimization horizon \(e_{consumption}\) always has to be consumed.
Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the deferrable load weighted with coeff. Quadratic term minimizing the deviation from the optimal loadcurve.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set the upper bounds to the nominal power or zero depending on self.load_time. Also set a constraint for the minimum load. If mode == integer add binary variables to model load as one block that can be shifted in time.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
- integerUses integer variables to restrict the DL to operate
at nominal load or no load and restricts the DL to consume E_Min_Consumption when DL is started without returning to a no load state
- update_model(mode='convex')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.ElectricHeater(environment, p_th_nom, eta=1, lower_activation_limit=1.0, min_off_time=1, min_on_time=1)
Bases:
ThermalEntityHeating
,ElectricalEntity
,ElectricalHeater
Extension of pyCity_base class ElectricalHeater for scheduling purposes.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power output in [kW].
eta (float, optional) – Efficiency of the electric heater. Defaults to one.
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the electric heater as a percentage of the rated power. When the electric heater is in operation, its power must be zero or between the lower activation limit and its rated power.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the EH must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the EH must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
Notes
EHs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the EH:
\[\begin{split}0 \geq p_{th\_heat} &\geq& -p_{th\_nom} \\ \eta * p_{el} &=& - p_{th\_heat}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call parent’s populate_model method and set thermal variables upper bounds to self.p_th_nom. Also add constraint to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.ElectricVehicle(environment, e_el_max, p_el_max_charge, p_el_max_discharge=0.0, soc_init=0.5, charging_time=None, ct_pattern=None, simulate_driving=False, minimum_soc_end=0.8, eta=1.0)
Bases:
Battery
Class representing an electric vehicle for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
e_el_max (float) – Electric capacity of the battery in [kWh].
p_el_max_charge (float) – Maximum charging power in [kW].
p_el_max_discharge (float, optional) – Maximum discharging power in [kW]. Defaults to zero.
soc_init (float, optional) – Initial state of charge. Defaults to 50%.
charging_time (array of binaries, optional) –
Indicator when electric vehicle can be charged.
charging_time[t] == 0: EV cannot be charged in t
charging_time[t] == 1: EV can be charged in t
It must contain at least one 0 otherwise the model will become infeasible. Its length has to be consistent with ct_pattern. Defaults to only charge during night.
ct_pattern (str, optional) –
Define how the charging_time profile is to be used.
None : Profile matches simulation horizon (default).
’daily’ : Profile matches one day.
’weekly’ : Profile matches one week.
simulate_driving (bool, optional) –
Simulate driving.
True: EV may drive and lose energy during the trip
False: EV cannot drive and lose energy during the trip
minimum_soc_end (float, optional) – Set the minimum state of charge for an EV at the end of the optimization horizon. Must be in (0,1]. Defaults to 80%.
eta (float, optional) – Charging and discharging efficiency of the EV. Must be in (0,1]. Defaults to 100%.
Notes
EVs offer sets of constraints for operation. The \(e_{el}\) equivalence constraint is replaced by the following constraint:
\[\begin{split}e_{el} &=& e_{el\_previous} + (\eta * p_{el\_demand} - (1 / \eta) * p_{el\_supply} - p_{el\_drive}) * \Delta t \\\end{split}\]The following constraints are added:
\[\begin{split}p_{el\_drive} \geq 0 \\ p_{el\_demand\_i} = p_{el\_supply} = 0, & \quad \text{if} \quad ct\_pattern_i = 0 \\ p_{el\_drive\_i} = 0, & \quad \text{if} \quad ct\_pattern_i = 1 \\ e_{el\_i} = soc\_init * e_{el\_max}, & \quad \text{if} \quad \sum_{j=0}^i ct\_pattern_j = 0 \\ e_{el\_i} = 0.2 * e_{el\_max}, & \quad \text{else if} \quad ct\_pattern_i = 0 \\ e_{el\_i} = e_{el\_max}, & \quad \text{else if} \quad ct\_pattern_i+1 = 0\end{split}\]The constraint for the parameter storage_end_equality is removed. Instead, the EV needs to be fully charged at the end of the simu_horizon if parameter ct_pattern is one at the end of the simulation horizon.
Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the electric vehicle weighted with coeff. Quadratic term with additional weights to reward charging the vehicle earlier.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method. Replace coupling constraints from Battery class with coupling constraints of EV. Simulate power consumption while driving.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.ElectricalEntity(environment, *args, **kwargs)
Bases:
OptimizationEntity
Base class for all electrical entities derived from OptimizationEntity.
This class provides functionality common to all electrical entities. It adds variables for the electrical demand / supply of the entity to the block.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
Notes
EEs add the \(p_{el}\) variable to the model. When not modified by other classes, the following constraint is added:
\[p_{el} \geq 0\]Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function for entity level scheduling.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the entity weighted with coeff.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- class pycity_scheduling.classes.ElectricalGrid(environment, related_entity, max_p_slack, max_q_slack, slack_V=None, ref_V=400, min_V=0.95, max_V=1.05, *args, **kwargs)
Bases:
ElectricalEntity
Class ElectricalGrid for scheduling purposes. Connects buildings within pycity_scheduling via a shared electrical grid.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
related_entity (CityDistrict) – City district object that ‘maintains’ the ElectricalGrid.
max_p_slack (float) – Maximum active power that can be exchanged through slack node of the grid in kW.
max_q_slack (float) – Maximum reactive power that can be exchanged through slack node of the grid in kVar.
slack_V (float, optional) – If not None, voltage at which the slack node should be operated in V. Default is None.
ref_V (float, optional) – Nominal voltage in the electrical grid in V. Default is 400V.
V_min (float, optional) – Minimal per unit voltage allowed in the electrical grid. Default is 0.95.
V_max (float, optional) – Maximal per unit voltage allowed in the electrical grid. Default is 1.05.
Methods
add_line
(line)Add a line to the electrical grid.
add_node
(node)Add a node to the electrical grid.
Build the incidence matrix of the electrical grid.
connect_entities
(entity1, entity2, ...[, ...])Add a line of specified length and capacity linking two entities in an electrical grid.
Plot the optimization results for the electrical grid in an oriented graph for one time step.
populate_model
(model[, mode])Add electrical grid block to pyomo ConcreteModel.
remove_line
(line)Remove a line from the electrical grid.
update_cable_properties
(R_cable, X_cable)Update the resistance and reactance cable parameters of the electrical grid.
- add_line(line)
Add a line to the electrical grid.
Check whether the sending and receiving nodes of the line are already in the electrical grid. If not they are added. The line is added to the lines list of the grid and the line number is incremented by 1.
- Parameters:
line (ElectricalLine) – The line that should be added to the network.
- add_node(node)
Add a node to the electrical grid.
Check whether the node is already in the grid. If not, the node is assigned a number in the node dictionary and the node number is incremented by 1. If the node has a related entity, this entity is added to the connected_entity dictionary. The nodes inherit the voltage bounds of the electrical grid to which it is added.
- Parameters:
node (ElectricalNode) – The node that should be added to the network.
- build_incidence_matrix()
Build the incidence matrix of the electrical grid.
- Returns:
A – Incidence matrix of the grid.
- Return type:
np.ndarray
- connect_entities(entity1, entity2, line_capacity, line_length, R_line_per_km=None, X_line_per_km=None)
Add a line of specified length and capacity linking two entities in an electrical grid.
Convert line capacity in per unit according to the electrical grid nominal power. Calculate per unit resistance and reactance of the line using the grid cable properties. Add a line to the electrical grid to connect two entities, that can be electrical nodes or buildings.
- Parameters:
entity1 (Union[ElectricalNode, Building]) – First entity to connect, sending node of the line.
entity2 (Union[ElectricalNode, Building]) – Second entity to connect, receiving node of the line.
line_capacity (float) – Line capacity in kVA.
line_length (float) – Line length in km.
- plot_graph_results(t)
Plot the optimization results for the electrical grid in an oriented graph for one time step.
Represented electrical nodes of the electrical grid as graph nodes and lines as edges. Display the optimal values of power flow, power injection or generation and node voltages in per unit.
- Parameters:
t (int) – Time step for which results are plotted.
- populate_model(model, mode='convex')
Add electrical grid block to pyomo ConcreteModel.
Call parent’s populate_model method. Then call populate_model method of all contained electrical lines and electrical nodes. Add constraints on slack node operation; bounded exchange power and enforcement of specified slack voltage if any. Add coupling constraints between nodes and their related entities. Add power conservation constraint at each node.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- remove_line(line)
Remove a line from the electrical grid.
Remove the line from the line list and decrement the line number by 1.
- Parameters:
line (ElectricalLine) – The line that should be removed from the network.
- update_cable_properties(R_cable, X_cable)
Update the resistance and reactance cable parameters of the electrical grid.
Update the R_cable (ohm/km) and X_cable (ohm/km) attributes of the grid with the provided values.
- class pycity_scheduling.classes.ElectricalLine(environment, sending_node, receiving_node, resistance, reactance, max_capacity, *args, **kwargs)
Bases:
ElectricalEntity
Class ElectricalLine for scheduling purposes. Represents a connecting line/cable for the interconnection of buildings in pycity_scheduling.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
sending_node (Union[ElectricalNode, Building]) – First entity to connect, sending node of the line.
receiving_node (Union[ElectricalNode, Building]) – Second entity to connect, receiving node of the line.
resistance (float, optional) – Line resistance in Ohm.
reactance (float, optional) – Line reactance in Ohm.
max_capacity (float, optional) – Maximum line capacity (power) in kVA.
Methods
populate_model
(model[, mode])Add electrical line block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add electrical line block to pyomo ConcreteModel.
Call parent’s populate_model method. Set bounds on power flow according to line capacity. Perform max affine approximation for the square function. Coefficients of the approximation are used to set lower bounds on power square p_app_el_vars. Set disjunctive upper bounds constraints on p_app_el_vars using the big-M method. Set equality constraints to calculate power losses based on square power approximation. Add voltage drop constraint.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- class pycity_scheduling.classes.ElectricalNode(environment, related_entity=None, position=None, min_V=0.95, max_V=1.05, ratio_pq_power=0.3333333333333333, *args, **kwargs)
Bases:
ElectricalEntity
Class ElectricalNode for scheduling purposes. Represents a building as a grid node inside an electrical grid within pycity_scheduling.
- Parameters:
environment (pycity_scheduling.classes.Environment) – Common to all other objects. Includes time and weather instances.
related_entity (Building, optional) – The entity coupled to the grid node.
position (list, optional) – List of two floats specifying the position of the node inside the grid.
min_V (float, optional) – Minimum voltage allowed for healthy operation in p.u.
max_V (float, optional) – Maximum voltage allowed for healthy operation in p.u.
ratio_pq_power (float, optional) – The fixed ratio of reactive power demand with respect to the active power demand, for the building connected to this node.
Methods
populate_model
(model[, mode])Add electrical node block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add electrical node block to pyomo ConcreteModel.
Call parent’s populate_model method and set variables lower bound to None. Set bound constraints on node voltage.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- class pycity_scheduling.classes.Environment(timer, weather, prices, location=(50.76, 6.07))
Bases:
Environment
Extension of pyCity_base class Environment for scheduling purposes.
- class pycity_scheduling.classes.FixedLoad(environment, method=0, demand=0, annual_demand=0, profile_type='H0', single_family_house=True, total_nb_occupants=0, randomize_appliances=True, light_configuration=0, occupancy=None, do_normalization=False, method_3_type=None, method_4_type=None, prev_heat_dev=False, app_filename=None, light_filename=None, season_light_mod=False, light_mod_fac=0.25)
Bases:
ElectricalEntity
,ElectricalDemand
Extension of pyCity_base class ElectricalDemand for scheduling purposes.
As for all uncontrollable loads, the p_el_schedule contains the forecast of the load.
- Parameters:
environment (Environment) – Common Environment instance.
method (int, optional) –
Defaults to method zero.
0 : provide load curve directly
1 : standard load profile (for households)
2 : stochastic electrical load model
3 : annual profile based on measured weekly profiles (non-residential)
4 : annual profile based on measured annual profiles (non-residential)
demand (numpy.ndarray, optional) – Demand for all investigated time steps in [kW] when using method=0.
annual_demand (float, optional) – Required for SLP and recommended for method 2. Defines the annual electrical demand in [kWh]. If method 2 is chosen but no value is given, a standard value for Germany (https://lena.sachsen-anhalt.de/fileadmin/Bibliothek/Sonstige_Webprojekte/Lena/Pressemitteilungen/ Stromspiegel/Stromspiegel2014_Medienblatt.pdf, accessed on 2020/09/28) is used.
profile_type (str, optional) –
H0 : Household
L0 : Farms
L1 : Farms with breeding / cattle
L2 : Farms without cattle
G0 : Business (general)
G1 : Business (workingdays 8:00 AM - 6:00 PM)
G2 : Business with high loads in the evening
G3 : Business (24 hours)
G4 : Shops / Barbers
G5 : Bakery
G6 : Weekend operation
total_nb_occupants (int, optional) – Number of people living in the household for method=2.
randomize_appliances (bool, optional) –
Randomization of appliances for method=2. Defaults to True.
True : distribute installed appliances randomly
False : use the standard distribution
light_configuration (int, optional) – There are 100 light bulb configurations predefined for the stochastic model when using method=2. Defaults to zero. A value between 0 and 100 should be provided.
occupancy (int, optional) – Occupancy given at 10-minute intervals for a full year for method=2.
do_normalization (bool, optional) – Defines, if stochastic profile (method=2) should be normalized to given annual_demand value. Defaults to False. If set to False, annual el. demand depends on stochastic el. load profile generation. If set to True, does normalization with annual_demand.
method_3_type (str, optional) –
Defines type of profile for method=3. Defaults to None. Options:
’food_pro’: Food production
’metal’: Metal company
’rest’: Restaurant (with large cooling load)
’sports’: Sports hall
’repair’: Repair / metal shop
method_4_type (str, optional) –
Defines type of profile for method=4. Defaults to None.
’metal_1’ : Metal company with smooth profile
’metal_2’ : Metal company with fluctuation in profile
’warehouse’ : Warehouse
prev_heat_dev (bool, optional) – Defines, if heating devices should be prevented within chosen appliances for method=2. Defaults to False. If set to True, DESWH, E-INST, Electric shower, Storage heaters and Other electric space heating are set to zero.
app_filename (str, optional) – Path to Appliances file for method=2. Defaults to None. If set to None, uses default file Appliances.csv in /inputs/stochastic_electrical_load/.
light_filename (str, optional) – Path to Lighting configuration file for method=2. Defaults to None. If set to None, uses default file Appliances.csv in /inputs/stochastic_electrical_load/.
season_light_mod (bool, optional) – Defines, if cosine-wave should be used to strengthen seasonal influence on lighting. Defaults to False. If True, enlarges lighting power demand in winter month and reduces lighting power demand in summer month.
light_mod_fac (float, optional) – Define factor, related to maximal lighting power, which is used to implement seasonal influence. Defaults to 25%. Only relevant, if season_light_mod == True
Notes
Standard load profiles, for instance for Germany, can be found here: https://www.bdew.de/energie/standardlastprofile-strom/ (accessed on 2020/09/28)
Average German electricity consumption data per household can be found here: https://lena.sachsen-anhalt.de/fileadmin/Bibliothek/Sonstige_Webprojekte/Lena/Pressemitteilungen/ Stromspiegel/Stromspiegel2014_Medienblatt.pdf (accessed on 2020/09/28)
The following constraint is added for removing the bounds from EE:
\[p_{el} = load\_curve\]Methods
new_schedule
(schedule)Create a new schedule with default values.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
Update the schedule with the scheduling model solution.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule()
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
- class pycity_scheduling.classes.HeatPump(environment, p_th_nom, cop=None, eta=0.36, t_max=55.0, lower_activation_limit=0.3, min_off_time=1, min_on_time=1, t_flow=55.0)
Bases:
ThermalEntityHeating
,ElectricalEntity
,Heatpump
Extension of pyCity_base class Heatpump for scheduling purposes.
- Parameters:
environment (Environment) – Common to all other objects. Includes time and weather instances.
p_th_nom (float) – Nominal thermal power of the heat pump in [kW].
cop (numpy.ndarray or int or float, optional) – The heat pump’s coefficient of performance (without unit) If array, it must provide the coefficient of performance (cop) for each time step in the simulation horizon. If int or float, a constant cop over the whole horizon is assumed. If omitted, an air-water heat pump is assumed and the cop is calculated with the ambient air temperature.
eta (int or float, optional) – The Carnot efficiency of the heat pump. If cop is omitted, eta is used to calculate the cop based on T_sink and T_source according to: cop = eta * T_sink * (T_sink - T_source) with T_sink and T_source in Kelvin
t_max (float, optional) – The heat pump’s maximum provided temperature in °C
lower_activation_limit (float, optional (only adhered to in integer mode)) –
Must be in [0, 1]. Lower activation limit of the heat pump as a percentage of the rated power. When the heat pump is in operation, its power must be zero or between the lower activation limit and its rated power. Today’s (air-to-water) heat pumps typically have a lower activation limit of 30%.
lower_activation_limit = 0: Linear behavior
lower_activation_limit = 1: Two-point controlled
min_off_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the heat pump must remain turned off, once it has been decided that it should turn off subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
min_on_time (int, optional (only adhered to in integer mode)) – Minimum number of consecutive time steps the heat pump must remain turned on, once it has been decided that it should turn on subject to ‘lower_activation_limit’. Defaults to ‘1’, i.e., not limited to a consecutive number of time steps.
t_flow (float, optional) – T_sink temperature delivered by HP in °C. Is used for cop calculation if cop is omitted. Note that t_flow <= t_max must hold.
Notes
HPs offer sets of constraints for operation. In the convex mode the following constraints and bounds are generated by the HP:
\[\begin{split}0 \geq p_{th\_heat} &\geq& -p_{th\_nom} \\ cop * p_{el} &=& - p_{th\_heat}\end{split}\]- See also:
pycity_scheduling.util.generic_constraints.LowerActivationLimit: Generates additional constraints for the lower_activation_limit in integer mode.
Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Call parent’s populate_model method and set thermal variables lower bounds to -self.p_th_nom and the upper bounds to zero. Also add constraint to bind electrical demand to thermal output.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.OptimizationEntity(environment, *args, **kwargs)
Bases:
object
Base class for all optimization entities.
This class provides functionality common to all entities which take part in the scheduling optimization.
- Parameters:
environment (Environment) – Common Environment instance.
- Attributes:
op_horizon
Number of time steps in a scheduling period.
op_slice
Slice to select values of current scheduling from whole horizon.
op_time_vec
Iterator over scheduling period.
schedule
The current loaded schedule.
simu_horizon
Number of time steps in the whole simulation horizon.
time_slot
Length of a time step as a portion of an hour.
timestep
Time step indicating the current scheduling.
Methods
copy_schedule
([dst, src, name])Copy values of one schedule in another schedule.
Yield all entities.
Return the decision varaible(s) of the entity's objective function.
Yield all lowest contained entities.
Yield all lower-level entities.
get_objective
([coeff])Objective function for entity level scheduling.
load_schedule
(schedule)Copy values of one schedule in another schedule.
load_schedule_into_model
([schedule, nudge])Overwrites the values in the entity model with the values in the schedule.
new_schedule
(schedule)Create a new schedule with default values.
new_var
(name[, dtype, func])Create a new entry and empty schedule for variable with specified name.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
set_objective
(objective)Set a new objective to be returned by get_objective.
update_model
([mode])Update block parameters and bounds.
update_schedule
([verbose])Update the schedule with the scheduling model solution.
- copy_schedule(dst=None, src=None, name=None)
Copy values of one schedule in another schedule.
- get_all_entities()
Yield all entities.
- Yields:
All contained entities and sub-entities.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_entities()
Yield all lowest contained entities.
- Yields:
Lowest contained entities or self.
- get_lower_entities()
Yield all lower-level entities.
- Yields:
All contained entities.
- get_objective(coeff=1)
Objective function for entity level scheduling.
Return the objective function of the entity weighted with coeff.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- load_schedule(schedule)
Copy values of one schedule in another schedule.
- Parameters:
schedule (str)
schedule. (Name of schedule to set as current)
- load_schedule_into_model(schedule=None, nudge=True)
Overwrites the values in the entity model with the values in the schedule.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- new_var(name, dtype=<class 'numpy.float64'>, func=None)
Create a new entry and empty schedule for variable with specified name.
- Parameters:
name (str) – Name to access new variable with.
dtype (numpy.dtype, optional) – Data type which should be used for new schedule.
func (Callable[[int], Any], optional) – Function to generate schedule with. If None, schedule is generated with values of variables.
- property op_horizon
Number of time steps in a scheduling period.
- property op_slice
Slice to select values of current scheduling from whole horizon.
- property op_time_vec
Iterator over scheduling period.
- populate_model(model, mode='')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- property schedule
The current loaded schedule.
- set_objective(objective)
Set a new objective to be returned by get_objective.
- Parameters:
objective (str) –
Objective for the scheduling.
’none’ : No objective (leave all flexibility to other participants).
- property simu_horizon
Number of time steps in the whole simulation horizon.
- static_entity_id = 0
- property time_slot
Length of a time step as a portion of an hour.
Examples
time step length = 60 mins => time_slot = 1 time step length = 15 mins => time_slot = 0.25
- property timestep
Time step indicating the current scheduling.
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule(verbose=False)
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
- class pycity_scheduling.classes.Photovoltaic(environment, method, area=0.0, peak_power=0.0, eta_noct=0.18, radiation_noct=1000.0, t_cell_noct=45.0, t_ambient_noct=20.0, alpha_noct=0, beta=0, gamma=0, tau_alpha=0.9, force_renewables=True)
Bases:
ElectricalEntity
,PV
Extension of pyCity_base class PV for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
method (int) –
0 : Calculate PV power based on an area in m^2 equipped with PV panels
1 : Calculate PV power based on the installed PV peak power in kWp
area (float, optional) – PV unit installation area in m^2 for method=0.
peak_power (float, optional) – PV peak power installation in kWp for method=1.
eta_noct (float, optional) – Electrical efficiency at NOCT conditions (without unit) for method=0. NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
radiation_noct (float, optional) – Nominal solar radiation at NOCT conditions (in W/m^2) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
t_cell_noct (float, optional) – Nominal cell temperature at NOCT conditions (in degree Celsius) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
t_ambient_noct (float, optional) – Nominal ambient air temperature at NOCT conditions (in degree Celsius) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
alpha_noct (float, optional) – Temperature coefficient at NOCT conditions (without unit) NOCT conditions: See manufacturer’s data sheets or Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 759
beta (float, optional) – Slope, the angle (in degree) between the plane of the surface in question and the horizontal. 0 <= beta <= 180. If beta > 90, the surface faces downwards.
gamma (float, optional) – Surface azimuth angle. The deviation of the projection on a horizontal plane of the normal to the surface from the local meridian, with zero due south, east negative, and west positive. -180 <= gamma <= 180
tau_alpha (float, optional) – Optical properties of the PV unit. Product of absorption and transmission coeffients. According to Duffie, Beckman - Solar Engineering of Thermal Processes (4th ed.), page 758, this value is typically close to 0.9
force_renewables (bool, optional) – True if generation may not be reduced for optimization purposes.
Notes
The following constraint is added for removing the bounds from EE:
\[\begin{split}p_{el} &=& -p_{el\_supply}, & \quad \text{if force_renewables} \\ 0 \geq p_{el} &\geq& -p_{el\_supply} , & \quad \text{else}\end{split}\]Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function of the Photovoltaic.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function of the Photovoltaic.
Return the objective function of the photovoltaic weighted with coeff. Depending on self.force_renewables leave objective function empty or build quadratic objective function to minimize discrepancy between available power and produced power.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.Prices(timer, da_prices=None, tou_prices=None, co2_prices=None, feedin_factor=0)
Bases:
Prices
Extension of pyCity_base class Prices for scheduling purposes.
- Parameters:
timer (Timer) – Timer instance for generating needed prices.
da_prices (array_like, optional) – Day-ahead prices for each timestep in the simu_horizon in [ct/kWh].
tou_prices (array_like, optional) – Time-of-use prices for each timestep in the simu_horizon in [ct/kWh].
co2_prices (array_like, optional) – CO2 emissions for each timestep in the simu_horizon in [g/kWh].
feedin_factor (float, optional) – Factor which is multiplied to the prices for feed-in revenue. Should be in [0,1], as prices for feed-in are usually lower than for consumption.
Notes
If prices are loaded automatically, the simulation period must lie within a single year.
CO2 emissions and day-ahead prices are currently available for the year 2015 only.
- Attributes:
- co2_price_cache
- da_price_cache
- tou_price_cache
- tou_price_cache_year
- co2_price_cache = None
- da_price_cache = None
- tou_price_cache = None
- tou_price_cache_year = None
- class pycity_scheduling.classes.SpaceCooling(environment, method=0, loadcurve=1, living_area=0, specific_demand=0, profile_type='HEF')
Bases:
ThermalEntityCooling
,SpaceCooling
Extension of pyCity_base class SpaceCooling for scheduling purposes.
As for all uncontrollable loads, the p_th_schedule contains the forecast of the load.
- Parameters:
environment (Environment object) – Common to all other objects. Includes time and weather instances
method (integer, optional) –
0 : Provide load curve directly
1 : Use thermal standard load profile (not implemented yet!)
loadcurve (Array-like, optional) – Load curve for all investigated time steps Requires method=0
living_area (Float, optional) – Living area of the apartment in m^2 Requires method=1
specific_demand (Float, optional) – Specific thermal demand of the building in kWh/(m^2 a) Requires method=1
profile_type (str, optional) – Thermal SLP profile name Requires method=1 - HEF : Single family household - HMF : Multi family household - GBA : Bakeries - GBD : Other services - GBH : Accomodations - GGA : Restaurants - GGB : Gardening - GHA : Retailers - GHD : Summed load profile business, trade and services - GKO : Banks, insurances, public institutions - GMF : Household similar businesses - GMK : Automotive - GPD : Paper and printing - GWA : Laundries
Notes
The following constraint is added for removing the bounds from the TEC:
\[p_{th\_cool} = load\_curve\]Methods
new_schedule
(schedule)Create a new schedule with default values.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
Update the schedule with the scheduling model solution.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal cooling demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule()
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
- class pycity_scheduling.classes.SpaceHeating(environment, method=0, loadcurve=1, living_area=0, specific_demand=0, profile_type='HEF', zone_parameters=None, t_m_init=None, ventilation=0, t_cooling_set=200, t_heating_set=-50, occupancy=0, appliances=0, lighting=0)
Bases:
ThermalEntityHeating
,SpaceHeating
Extension of pyCity_base class SpaceHeating for scheduling purposes.
As for all uncontrollable loads, the p_th_heat_schedule contains the forecast of the load.
- Parameters:
environment (Environment) – common to all other objects, includes time and weather instances
method (int, optional) –
0 : Provide load curve directly
1 : Use thermal standard load profile
2 : Use ISO 13790 standard to compute thermal load
loadcurve (numpy.ndarray of float, optional) – load curve for all investigated time steps in [kW] requires method=0.
living_area (float, optional) – living area of the apartment in m2 requires method=1
specific_demand (float, optional) – specific thermal demand of the building in [kWh /(m2*a)] requires method=1
profile_type (str, optional) – thermal SLP profile name requires method=1 - “HEF” : Single family household - “HMF” : Multi family household - “GBA” : Bakeries - “GBD” : Other services - “GBH” : Accomodations - “GGA” : Restaurants - “GGB” : Gardening - “GHA” : Retailers - “GHD” : Summed load profile business, trade and services - “GKO” : Banks, insurances, public institutions - “GMF” : Household similar businesses - “GMK” : Automotive - “GPD” : Paper and printing - “GWA” : Laundries
zone_parameters (ZoneParameters object, optional) – parameters of the building (floor area, building class, etc.) for method=2.
t_m_init (float, optional) – Initial temperature of the internal heat capacity in [°C] for method=2.
ventilation (array_like, optional) – Ventilation rate in [1/h] for method=2.
t_cooling_set (array_like, optional) – Cooling starts if the room temperature exceeds this value for method=2.
t_heating_set (array_like, optional) – Heating starts if the room temperature drops below this value for method=2.
occupancy (array_like, optional) – Full year occupancy profile for method=2.
appliances (array_like, optional) – Internal gains from electrical appliances in [W] for method=2.
lighting (array_like, optional) – Internal gains from lighting in Watt for method=2.
Notes
The thermal standard load profile is based on the dissertation of Mark Hellwig “Entwicklung und Anwendung parametrisierter Standard-Lastprofile”, TU München, Germany, 2003: http://mediatum.ub.tum.de/doc/601557/601557.pdf (accessed on 2020/09/28)
The following constraint is added for removing the bounds from TEH:
\[p_{th\_heat} = load\_curve\]Methods
new_schedule
(schedule)Create a new schedule with default values.
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
reset
([schedule])Reset all values of specified schedule.
update_model
([mode])Update block parameters and bounds.
update_schedule
([mode])Update the schedule with the scheduling model solution.
- new_schedule(schedule)
Create a new schedule with default values.
- Parameters:
schedule (str) – Name of new schedule.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal heating demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- reset(schedule=None)
Reset all values of specified schedule.
- Parameters:
schedule (str, optional) –
Specify which schedule to reset.
None : Resets all schedules
’default’ : Resets normal schedule
’ref’ : Resets reference schedule
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- update_schedule(mode='')
Update the schedule with the scheduling model solution.
Retrieve the solution from the scheduling model and write it to the schedule. The model must be optimal. The time / position of the solution in the schedule is determined by self.timer.current_timestep.
- Parameters:
verbose (bool, optional) – Verbose mode and output.
- class pycity_scheduling.classes.ThermalCoolingStorage(environment, e_th_max, soc_init=0.5, loss_factor=0, storage_end_equality=False)
Bases:
ThermalEntityCooling
,ThermalEnergyStorage
Extension of pyCity_base class ThermalEnergyStorage for scheduling purposes. A thermal cooling storage device can be used as a ‘buffer’ within a cooling system setup.
- Parameters:
environment (Environment) – Common Environment instance.
e_th_max (float) – Amount of energy the TCS is able to store in [kWh].
soc_init (float) – Initial state of charge.
loss_factor (float, optional) – Storage’s loss factor (area*U_value) in [W/K].
storage_end_equality (bool, optional) – Defaults to False. True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc.
Notes
TCSs offer sets of constraints for operation. The following constraints and bounds are generated by the TCS:
\[\begin{split}e_{th\_cool} &=& e_{th\_cool\_previous} * (1-th\_loss) + p_{th\_cool} * \Delta t \\ \text{with} \quad e_{th\_cool\_previous} &=& \begin{bmatrix} e_{th\_ini} & e_{th\_cool\_0} & \cdots & e_{th\_cool\_n-1}\end{bmatrix}\end{split}\]Additional constraints generated by the parameters are:
\[\begin{split}e_{th\_cool\_t\_last} &=& soc\_init * e_{th\_max}, & \quad \text{if storage_end_equality} \\ e_{th\_cool\_t\_last} &\geq& soc\_init * e_{th\_max}, & \quad \text{else}\end{split}\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables lower bounds to None. Then add variables for the state of charge with an upper bound of self.e_th_max. Also add continuity constraints to the model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.ThermalEntityCooling(environment, *args, **kwargs)
Bases:
OptimizationEntity
Base class for all thermal cooling entities derived from OptimizationEntity.
This class provides functionality common to all thermal cooling entities.
Notes
Cooling TEs add the \(p_{th\_cool}\) variable to the model. When not modified by other classes, the following constraint is added:
\[p_{th\_cool} \geq 0\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal cooling demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- class pycity_scheduling.classes.ThermalEntityHeating(environment, *args, **kwargs)
Bases:
OptimizationEntity
Base class for all thermal heating entities derived from OptimizationEntity.
This class provides functionality common to all thermal heating entities.
Notes
Heating TEs add the \(p_{th\_heat}\) variable to the model. When not modified by other classes, the following constraint is added:
\[p_{th\_heat} \geq 0\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel.
Add variables for the thermal heating demand of the entity to the optimization model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- class pycity_scheduling.classes.ThermalHeatingStorage(environment, e_th_max, soc_init=0.5, loss_factor=0, storage_end_equality=False)
Bases:
ThermalEntityHeating
,ThermalEnergyStorage
Extension of pyCity_base class ThermalEnergyStorage for scheduling purposes. A thermal heating storage device can be used as a ‘buffer’ within a heating system setup.
- Parameters:
environment (Environment) – Common Environment instance.
e_th_max (float) – Amount of energy the THS is able to store in [kWh].
soc_init (float) – Initial state of charge.
loss_factor (float, optional) – Storage’s loss factor (area*U_value) in [W/K].
storage_end_equality (bool, optional) – Defaults to False. True if the soc at the end of the scheduling has to be equal to the initial soc. False if it has to be greater or equal than the initial soc.
Notes
THSs offer sets of constraints for operation. The following constraints and bounds are generated by the THS:
\[\begin{split}e_{th\_heat} &=& e_{th\_heat\_previous} * (1-th\_loss) + p_{th\_heat} * \Delta t \\ \text{with} \quad e_{th\_heat\_previous} &=& \begin{bmatrix} e_{th\_ini} & e_{th\_heat\_0} & \cdots & e_{th\_heat\_n-1}\end{bmatrix}\end{split}\]Additional constraints generated by the parameters are:
\[\begin{split}e_{th\_heat\_t\_last} &=& soc\_init * e_{th\_max}, & \quad \text{if storage_end_equality} \\ e_{th\_heat\_t\_last} &\geq& soc\_init * e_{th\_max}, & \quad \text{else}\end{split}\]Methods
populate_model
(model[, mode])Add device block to pyomo ConcreteModel
update_model
([mode])Update block parameters and bounds.
- populate_model(model, mode='convex')
Add device block to pyomo ConcreteModel
Call parent’s populate_model method and set variables lower bounds to None. Then add variables for the state of charge with an upper bound of self.e_th_max. Also add continuity constraints to the model.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use same constraints as convex mode
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- class pycity_scheduling.classes.Timer(step_size=900, op_horizon=96, mpc_horizon=None, mpc_step_width=None, initial_date=(2015, 1, 1), initial_time=(0, 0, 0))
Bases:
Timer
Extension of pyCity_base class Timer for scheduling purposes
- Parameters:
step_size (int, optional) – Number of seconds in one time step.
op_horizon (int, optional) – Number of time steps used in one scheduling optimization.
mpc_horizon (int, optional) – Number of time steps in whole simulation. All data must be available for this time. If None set value to op_horizon.
mpc_step_width (int, optional) – Number of timesteps between two optimizations in MPC. If None set value to op_horizon.
initial_date (tuple, optional) – Initial date in the format (year, month, day).
initial_time (tuple, optional) – Initial time in the format (hour, minute, second).
Notes
This class’ behaviour may differ from the one of the baseclass, as it keeps an actual date rather than a relative counter only
- Attributes:
date
The date of the current timestep.
datetime
The datetime of the current timestep.
day
The day of the month for the current timestep.
hour
The hour of the current timestep.
is_leap
If the year of the current timestep is a leap year.
minute
The minute of the current timestep.
month
The month of the current timestep.
second
The second of the current timestep.
time
The time for the current timestep.
weekday
The weekday of the current timestep.
year
The year of the current timestep.
Methods
Update Timer for MPC.
Update Timer for a normal scheduling optimization.
Print the datetime for the current timestep.
reset
()Reset the Timer to the initial state.
time_in_day
([unit, from_init])Time passed since beginning of the day.
time_in_week
([unit, from_init])Time passed since beginning of the day.
time_in_year
([unit, from_init])Time passed since the beginning of the year.
- property date
The date of the current timestep.
- property datetime
The datetime of the current timestep.
- property day
The day of the month for the current timestep.
- property hour
The hour of the current timestep.
- property is_leap
If the year of the current timestep is a leap year.
- property minute
The minute of the current timestep.
- property month
The month of the current timestep.
- mpc_update()
Update Timer for MPC.
Move self.mpc_step_width timesteps forward.
- op_update()
Update Timer for a normal scheduling optimization.
Go self.timesteps_used_horizon timesteps forward.
- print_datetime()
Print the datetime for the current timestep.
- reset()
Reset the Timer to the initial state.
- property second
The second of the current timestep.
- property time
The time for the current timestep.
- time_in_day(unit='timesteps', from_init=False)
Time passed since beginning of the day.
- Parameters:
- Returns:
Time in specified unit.
- Return type:
- time_in_week(unit='timesteps', from_init=False)
Time passed since beginning of the day.
- Parameters:
- Returns:
Time in specified unit.
- Return type:
- time_in_year(unit='timesteps', from_init=False)
Time passed since the beginning of the year.
- property weekday
The weekday of the current timestep.
- property year
The year of the current timestep.
- class pycity_scheduling.classes.Weather(timer, path_TRY=None, path_TMY3=None, new_try=False, path_temperature='', path_direct_radiation='', path_diffuse_radiation='', path_wind_speed='', path_humidity='', path_pressure='', path_cloudiness='', time_discretization=3600, delimiter='\t', use_TRY=True, use_TMY3=False, location=(50.76, 6.07), height_velocity_measurement=10, altitude=152.0, time_zone=1)
Bases:
Weather
Extension of pyCity_base class Weather for scheduling purposes.
- class pycity_scheduling.classes.WindEnergyConverter(environment, velocity, power, hub_height=70, roughness=0.1, force_renewables=True)
Bases:
ElectricalEntity
,WindEnergyConverter
Extension of pyCity_base class WindEnergyConverter for scheduling purposes.
- Parameters:
environment (Environment) – Common Environment instance.
velocity (numpy.ndarray) – Wind speeds in [m/s].
power (numpy.ndarray) – Power for given velocities in [kW].
hub_height (float, optional) – Height of the wind energy converter in [m].
roughness (float, optional) – Roughness of landscape in [m].
force_renewables (bool, optional) – True if generation may not be reduced for optimization purposes.
Notes
The following constraint is added for removing the bounds from EE:
\[\begin{split}p_{el} &=& -p_{el\_supply}, & \quad \text{if force_renewables} \\ 0 \geq p_{el} &\geq& -p_{el\_supply} , & \quad \text{else}\end{split}\]Methods
Return the decision varaible(s) of the entity's objective function.
get_objective
([coeff])Objective function of the WindEnergyConverter.
populate_model
(model[, mode])Add entity block to pyomo ConcreteModel.
update_model
([mode])Update block parameters and bounds.
- get_decision_var()
Return the decision varaible(s) of the entity’s objective function.
- Returns:
Decision variable.
- Return type:
pyomo.Var
- get_objective(coeff=1)
Objective function of the WindEnergyConverter.
Return the objective function of the wind energy converter weighted with coeff. Depending on self.force_renewables leave objective function empty or build quadratic objective function to minimize discrepancy between available power and produced power.
- Parameters:
coeff (float, optional) – Coefficient for the objective function.
- Returns:
Objective function.
- Return type:
ExpressionBase
- populate_model(model, mode='convex')
Add entity block to pyomo ConcreteModel.
Places the block with the name of the entity in the ConcreteModel.
- Parameters:
model (pyomo.ConcreteModel)
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : May use integer variables
- update_model(mode='')
Update block parameters and bounds.
Set parameters and bounds according to the current situation of the device according to the previous schedule and the current forecasts.
- Parameters:
mode (str, optional) –
Specifies which set of constraints to use.
convex : Use linear constraints
integer : Use integer variables representing discrete control decisions
- pycity_scheduling.classes.filter_entities(entities, entity_type)
Filter a list of entities for given entity types.
- Parameters:
entities (list or generator or) – pycity_scheduling.classes.OptimizationEntity Entities to be filtered. When an Optimization Entity is given its get_entities method is called.
entity_type (str or list or dict) –
- In case of str: must be the name of a dictionary from this module
(e.g. ‘generation_devices’) or the short name of an entity (e.g. ‘PV’)
- In case of list: must be a list of classes to be filtered for or a
list of short names (e.g. [‘PV’, ‘WEC’])
In case of dict: its values must be the classes to be filtered for
- Yields:
OptimizationEntity – All entities matching the given filter