pycity_base

Python package for data handling and scenario generation of city districts and urban energy systems.

Contributing

1. Clone repository: git clone git@github.com:RWTH-EBC/pyCity.git (for SSH usage) Alternatively: Clone via https: git clone https://github.com/RWTH-EBC/pyCity.git
2. Open an issue at https://github.com/RWTH-EBC/pyCity/issues
3. Checkout development branch: git checkout development
4. Update local development branch (if necessary): git pull origin development
5. Create your feature branch: git checkout -b issueXY_explanation
6. Commit your changes: git commit -m "Add some feature #XY"
7. Push to the branch: git push origin issueXY_explanation
8. Submit a pull request from issueXY_explanation to development branch via https://github.com/RWTH-EBC/pyCity/pulls

Installation

One important issue at the beginning: Please do NOT confuse pycitybase with the pycity package on pypi! This (other) pycity package is installable via pip. However, if you want to install pycitybase, follow this instruction.

pycity_base requires the following Python packages: - numpy==1.26.0 - matplotlib==3.8.0 - pandas==2.1.1 - Shapely==2.0.1 - openpyxl==3.1.2 - networkx==2.5.1 - pyproj==3.6.1

as well as the EBC Python packages:

• richardsonpy==0.2.1

which is available at https://github.com/RWTH-EBC/richardsonpy

• uesgraphs==0.6.4 (with dependencies to shapely and pyproj)

which is available at https://github.com/RWTH-EBC/uesgraphs

richardsonpy and uesgraphs can be installed via pip.

Installation of pycity_base

The latest version of pycity_base is 0.3.3.

When uesgraph and its dependencies are installed, you should be able to install pycity_base via pip:

pip install pycity_base

or:

pip install -e '<your_path_to_pycity_setup_folder>'

or:

<path_to_your_python_dist\Python.exe> -m pip install -e '<your_path_to_pycity_setup_folder>'

You can check if installation / adding packages to python has been successful by adding new .py file and trying to import uesgraphs and pyCity.

import uesgraphs

import pycity_base

Import should be possible without errors.

Example usage

```Python import shapely.geometry.point as point import matplotlib.pyplot as plt

import uesgraphs.visuals as uesvis

import pycitybase.classes.timer as time import pycitybase.classes.weather as weath import pycitybase.classes.prices as price import pycitybase.classes.environment as env import pycitybase.classes.demand.apartment as apart import pycitybase.classes.demand.occupancy as occ import pycitybase.classes.demand.domestichotwater as dhw import pycitybase.classes.demand.electricaldemand as eldem import pycitybase.classes.demand.spaceheating as spaceheat import pycitybase.classes.building as build import pycitybase.classes.citydistrict as citydist import pycitybase.classes.supply.buildingenergysystem as besys import pycitybase.classes.supply.boiler as boil import pycity_base.classes.supply.photovoltaic as pvsys

def main(): # Define the time discretization for the timer object timestep = 3600 # in seconds

#  Define the total number of timesteps (in this case for one year)
nb_timesteps = int(365 * 24 * 3600 / timestep)

#  Generate environment with timer, weather, and prices objects
#  ######################################################################
timer = time.Timer(timeDiscretization=timestep,
                   timestepsTotal=nb_timesteps)
weather = weath.Weather(timer=timer)
prices = price.Prices()

environment = env.Environment(timer=timer, weather=weather, prices=prices)

#  Generate city district object
#  ######################################################################
city_district = citydist.CityDistrict(environment=environment)
#  Annotations: To prevent some methods of subclasses uesgraph / nx.Graph
#  from failing (e.g. '.subgraph()) environment is set as optional input
#  parameter. However, it is necessary to use an environment object as
#  input parameter to initialize a working cityDistrict object!

#  Empty dictionary for building positions
dict_pos = {}

#  Generate shapely point positions
dict_pos[0] = point.Point(0, 0)  # (x, y)
dict_pos[1] = point.Point(20, 0)

#  Use for loop to generate two identical building objects for city
#  district
#  ######################################################################
for i in range(2):
    living_area = 200  # in m^2
    spec_sh_dem = 160  # Specific space heating demand in kWh/m^2
    number_occupants = 3  # Total number of occupants

    #  Generate space heating demand object (holding loadcurve attribute
    #  with space heating power)
    heat_demand = spaceheat.SpaceHeating(
        environment=environment,
        method=1,  # Standard load profile
        livingArea=living_area,  # in m^2
        specificDemand=spec_sh_dem)  # in kWh/m^2

    #  Generate occupancy object with stochastic user profile
    occupancy = occ.Occupancy(environment=environment,
                              number_occupants=number_occupants)

    #  Generate electrical demand object
    el_dem_stochastic = eldem.ElectricalDemand(
        environment=environment,
        method=2,  # stochastic Richardson profile (richardsonpy)
        total_nb_occupants=number_occupants,  # Number of occupants
        randomizeAppliances=True,  # Random choice of installed appliances
        lightConfiguration=10,  # Light bulb configuration nb.
        occupancy=occupancy.occupancy,  # Occupancy profile (600 sec resolution)
        prev_heat_dev=True,  # Prevent space heating and hot water devices
        annualDemand=None,  # Annual el. demand in kWh could be used for
        do_normalization=False)  # rescaling (if do_normalization is True)
    #  Annotation: The calculation of stochastic electric load profiles
    #  is time consuming. If you prefer a faster method, you can either
    #  hand over an own array-like load curve (method=0) or generate a
    #  standardized load profile (SLP) (method=1)

    #  Generate domestic hot water demand object
    dhw_obj = dhw.DomesticHotWater(
        environment=environment,
        tFlow=60,  # DHW output temperature in degree Celsius
        method=2,  # Stochastic dhw profile
        supplyTemperature=25,  # DHW inlet flow temperature in degree C.
        occupancy=occupancy.occupancy)  # Occupancy profile (600 sec resolution)

    #  Generate apartment and add demand curves
    apartment = apart.Apartment(environment)
    apartment.addMultipleEntities([heat_demand,
                                   el_dem_stochastic,
                                   dhw_obj])

    #  Generate building and add apartment
    building = build.Building(environment)
    building.addEntity(apartment)

    #  Add buildings to city district
    city_district.addEntity(entity=building,
                            position=dict_pos[i])

#  Access information on city district object instance
#  ######################################################################
print('Get number of building entities:')
print(city_district.get_nb_of_building_entities())
print()

print('Get list with node ids of building entities:')
print(city_district.get_list_build_entity_node_ids())
print()

print('Get city district overall space heating power load curve:')
print(city_district.get_aggr_space_heating_power_curve(current_values=True))
print()

print('Get city district overall space cooling power load curve:')
print(city_district.get_aggr_space_cooling_power_curve(current_values=True))
print()

#  We can use the Visuals class of uesgraphs to plot the city district

#  Generate uesgraphs visuals object instance
uesvisuals = uesvis.Visuals(uesgraph=city_district)

fig = plt.figure()
ax = fig.gca()
ax = uesvisuals.create_plot_simple(ax=ax)
plt.show()
plt.close()

#  Access buildings
#  ######################################################################
#  As city_district is a networkx graph object, we can access the building
#  entities with the corresponding building node,
#  Pointer to building object with id 1001:
building_1001 = city_district.nodes[1001]['entity']

print('Get building 1001 electric load curve:')
print(building_1001.get_electric_power_curve())
print()

#  Add energy systems to buildings
#  ######################################################################
#  We can also add building energy systems (BES) to each building object

#  Generate boiler object
boiler = boil.Boiler(environment=environment,
                     qNominal=10000,  # Boiler thermal power in Watt
                     eta=0.85)  # Boiler efficiency

#  Generate PV module object
pv = pvsys.PV(environment=environment,
              area=30,  # Area in m^2
              eta=0.15)  # Electrical efficiency at NOCT conditions

# Instantiate BES (container object for all energy systems)
bes = besys.BES(environment)

#  Add energy systems to bes
bes.addMultipleDevices([boiler, pv])

#  Add bes to building 1001
building_1001.addEntity(entity=bes)

print('Does building 1001 has a building energy system (BES)?')
print(building_1001.hasBes)

#  Access boiler nominal thermal power
print('Nominal thermal power of boiler in kW:')
print(building_1001.bes.boiler[0].qNominal / 1000)

if name == 'main': # Run program main()

```

Tutorial

pycitybase also has also a jupyter notebook tutorial script under pycity/examples/tutorials/... To open the jupyter notebook, open a command/terminal window and change your directory to the directory, where tutorialpycitycalc1.ipynb is stored. Then type 'jupyter notebook' (without '' signs) and press Enter. Jupyter notebook should open within your browser (such as Firefox). Click on one notebook to start. If your Pyhton path does not point at your Python installation, you have to open jupyter notebook directly, e.g. by looking for the jupyter.exe in your distribution.

How to cite pycity_base

• Schiefelbein, J., Rudnick, J., Scholl, A., Remmen, P., Fuchs, M., Müller, D. (2019), Automated urban energy system modeling and thermal building simulation based on OpenStreetMap data sets, Building and Environment, Volume 149, Pages 630-639, ISSN 0360-1323 pdf, bibtex

If you require a reference in German language: + Schiefelbein, J. , Javadi, A. , Fuchs, M. , Müller, D. , Monti, A. and Diekerhof, M. (2017), Modellierung und Optimierung von Mischgebieten. Bauphysik, 39: 23-32. doi:10.1002/bapi.201710001 pdf, bibtex

License

pyCity is released by RWTH Aachen University's E.ON Energy Research Center (E.ON ERC), Institute for Energy Efficient Buildings and Indoor Climate (EBC) and Institute for Automation of Complex Power Systems (ACS) under the MIT License

Acknowledgements

We gratefully acknowledge the financial support by BMWi (German Federal Ministry for Economic Affairs and Energy) under promotional references 03ET1138D and 03ET1381A.