34 Merge EBC Main into Main

.gitignore

@@ -31,6 +31,7 @@ errorfile.txt
 *.pkl
 __pycache__/
 .idea/
+demands/
 
 Distribution / packaging
 .Python

README.md

@@ -1,25 +1,48 @@
 ![E.ON EBC RWTH Aachen University](./img/EBC_Logo.png)
 
-# districtgenerator
+# DistrictGenerator
 
 [![License](http://img.shields.io/:license-mit-blue.svg)](http://doge.mit-license.org)
+[![Documentation](https://rwth-ebc.github.io/FiLiP/master/docs/doc.svg)](https://rwth-ebc.github.io/FiLiP/master/docs/index.html)
 
 The districtgenerator is a Python tool for generating building-specific thermal, electrical and occupancy profiles for districts. 
 By integrating several open-source data bases and tools like [TEASER](https://github.com/RWTH-EBC/TEASER) and 
 [richardsonpy](https://github.com/RWTH-EBC/richardsonpy), 
 the districtgenerator is designed to provide easy access to profile generation. 
+Through the DistrictGenerator, we introduce an python-based open-source tool aimed at urban planners, energy suppliers,
+housing associations, engineering firms, architectural professionals, as well as academic and research institutions. 
+This tool furnishes crucial insights into energy demands, pivotal for the effective design and operation of 
+neighborhoods energy systems. Consequently, users can discern actionable measures to harmonize energy supply.
 
-The districtgenerator is being developed at [RWTH Aachen University, E.ON Energy
+
+The DistrictGenerator is being developed at [RWTH Aachen University, E.ON Energy
 Research Center, Institute for Energy Efficient Buildings and Indoor
 Climate](https://www.ebc.eonerc.rwth-aachen.de/cms/~dmzz/E-ON-ERC-EBC/?lidx=1) and [TU Berlin, Institute for Digital Networking of Buildings, Energy Supply Systems and Users](https://www.tu.berlin/en/dvg).
 
-## Version
+## General Motivation
+
+In the early stages of neighborhood planning, crucial data such as demand profiles of electricity, heating, 
+domestic hot water, and occupancy profiles are often not available. The absence of this data hampers 
+accurate evaluations of energy systems in districts. The DistrictGenerator seeks to advance the applicability 
+of sustainable, cross-sectoral energy systems in neighborhoods, with a specific emphasis on exploiting synergy 
+potentials among buildings of diverse usage structures through integrated concepts. We summarize the key contributions 
+of the DistrictGenerator as follows:
+
+- An open-source tool with minimal input requirements. Leveraging pre-set elements and default values of temporally 
+  resolved demand profiles, as well as decentralized heat generator sizing conforming to DIN standards.
+
+- The tool enables the bottom-up representation of entire urban structures through neighborhood models, affording a 
+  sufficiently detailed analysis foundation.
+
+- Facilitation of central operational optimization and presentation of analytical results and key performance 
+  indicators. This supports the examination of various neighborhood types and supply scenarios concerning technology 
+  selection and penetrations. We thereby create a platform for early-stage comparison of neighborhood concepts 
+  with the flexibility of selecting different variants, given the tool's rapid recalculations.
 
-The districtgenerator is an ongoing research project. The current version is v0.1.0.
 
 ## Getting started
 
-### Install the districtgenerator
+### Install the DistrictGenerator
 
 To install, first clone this repository with
 
@@ -38,9 +61,8 @@ activate the envrionment and run:
 pip install -e <path-to-districtgenerator> .
 ```
 
-### How to get started?
-
-Once you have installed the generator, you can check the [examples](./examples) to learn how to use the different components.
+Once you have installed the DistrictGenerator, you can check the [examples](EXAMPLES.md) 
+to learn how to use the different components.
 
 ### Minimum required input data
 
@@ -52,42 +74,95 @@ The minimal input data set was defined following the [TABULA archetype approach]
 * _retrofit_: retrofit state according to TABULA (0: existing state, 1: usual refurbishment, 2: advanced refurbishment)
 * _area_: reference floor area (given in square meters)
 
-Please find a template [here](./data/scenarios/example.csv).
+- id: building ID (just numerate the buildings)
+- building: residential building type (single family house, terraced house, multi family house or apartment block)
+- year: construction year (the calendar year in which the building was constructed)
+- retrofit: retrofit state according to TABULA (0: existing state, 1: usual refurbishment, 2: advanced refurbishment)
+- area: reference floor area (given in square meters)
+
+The example.csv file can be used as [template](../districtgenerator/data/scenarios/example.csv).
 
 ### What you get
 
-After executing district generation you can find building-specific profiles in 
+After executing district generation you can find building-specific and time-dependent profiles in 
 the .csv format in folder results/demands. The results contain: 
-* _heat_: space heating demand
-* _dhw_: domestic hot water demand
-* _elec_: electricity demand for lighting and electric household devices
-* _occ_: number of persons present
-* _gains_: internal gains from persons, lighting and electric household devices
 
-All values are given in Watt and for the [time resolution](./data/time_data.json) you require.
+- heat: space heating demand
+- dhw: domestic hot water demand
+- elec: electricity demand for lighting and electric household devices
+- occ: number of persons present
+- gains: internal gains from persons, lighting and electric household devices
 
 
 ## Known Limitations
 
 * Non-Residential Buildings need EPW-Files.
 
-## License
 
-The districtgenerator is released by RWTH Aachen University, E.ON Energy
-Research Center, Institute for Energy Efficient Buildings and Indoor Climate,
-under the
-[MIT License](LICENSE.md).
+## Structure of the DistrictGenerator
+
+![Library Structure](./img/Struktur_Quartiersgenerator.png)
+
+## Running examples for functional testing
+
+Once you have installed the DistrictGenerator, you can check the [examples](EXAMPLES.md) 
+to learn how to use the different components. 
+
+To test the tool's executability, run [test_examples.py](https://github.com/RWTH-EBC/districtgenerator/tree/15-joss-documentation/tests)  in the tests folder. 
+This functional testing checks the entire chain of the tool, from data input and 
+initialization to the output of the calculated profiles. It does not correspond to a 
+test of the functional units of the entire process. This  functional testing is based 
+on the examples automatically executed one after another.
+
+## How to contribute
+
+The documentation and examples should be understandable and the code bug-free. 
+As all users have different backgrounds, you may not understand everything or encounter bugs.
+If you have questions, want to contribute new features or fix bugs yourself,
+please [raise an issue here](https://github.com/RWTH-EBC/districtgenerator/issues/new).
+
+If you wrote a new feature, create a pull request and assign 
+a reviewer before merging. Once review is finished, you can merge.
+
+## Authors
+
+* [Joel Schölzel](https://www.ebc.eonerc.rwth-aachen.de/cms/e-on-erc-ebc/das-institut/mitarbeiter/digitale-energie-quartiere/~obome/schoelzel-joel/?allou=1) (corresponding)
+* [Tobias Beckhölter](https://www.ebc.eonerc.rwth-aachen.de/cms/E-ON-ERC-EBC/Das-Institut/Mitarbeiter/Team6/~scaj/Beckhoelter-Tobias/)
+* [Carla Wüller](https://www.ebc.eonerc.rwth-aachen.de/cms/E-ON-ERC-EBC/Das-Institut/Mitarbeiter/Digitale-Energie-Quartiere/~beoyus/Wueller-Carla/)
+* [Felix Rehmann](https://github.com/c0nb4)
+
+## Alumni
+
+* Sarah Henn
 
 ## Reference
 
-coming soon :)
+We presented or applied the library in the following publications:
+
+- J. Schölzel, S. Henn, R. Streblow, D. Müller. Evaluation of Energy Sharing on a 
+  Local Energy Market Through Comparison of Energy Management Techniques. 36th International 
+  Conference on Efficiency, Cost, Optimization, Simulation and Environmental Impact of Energy Systems.
+  https://doi.org/10.52202/069564-0307
+
+- J. Schölzel, T. Beckhölter, S. Henn, C.Wüller, R. Streblow, D. Müller.
+  Districtgenerator: A Novel Open-Source Webtool to Generate Building-Specific Load 
+  Profiles and Evaluate Energy Systems of Residential Districts. 37th International 
+  Conference on Efficiency, Cost, Optimization, Simulation and Environmental Impact of 
+  Energy Systems.
+
+- C. Wüller, J. Schölzel, R. Streblow, D. Müller.Optimizing Local Energy Trading in Residential Neighborhoods:A Price Signal Approach 
+  in Local Energy Markets. 37th International Conference on Efficiency, Cost, Optimization, 
+  Simulation and Environmental Impact of Energy Systems.
+
+## License
+
+The DistrictGenerator is released by RWTH Aachen University, E.ON Energy
+Research Center, Institute for Energy Efficient Buildings and Indoor Climate,
+under the [MIT License](about/LICENSE.md).
 
 ## Acknowledgements
 
 The districtgenerator has been developed within the public funded projects 
 "BF2020 Begleitforschung ENERGIEWENDEBAUEN - Modul Quartiere" (promotional reference: 03EWB003B) and "BF2020 Begleitforschung ENERGIEWENDEBAUEN - Modul Digitalisierung" (promotional reference: 04EWB003A) and with financial support by BMWK (German Federal Ministry for Economic Affairs and Climate Action).
 
 <img src="https://www.innovation-beratung-foerderung.de/INNO/Redaktion/DE/Bilder/Titelbilder/titel_foerderlogo_bmwi.jpg?__blob=normal" width="200">
-
-## Problems?
-Please [raise an issue here](https://github.com/RWTH-EBC/districtgenerator/issues/new).

districtgenerator.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.1
+Name: districtgenerator
+Version: 0.0.1
+Summary: Energy profile generation and optimization of districts
+Home-page: https://github.com/RWTH-EBC/districtgenerator
+Author: Joel Schölzel
+Author-email: joel.schoelzel@eonerc.rwth-aachen.de
+License: MIT License
+Classifier: Programming Language :: Python :: 3
+License-File: LICENSE.md
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: teaser
+Requires-Dist: richardsonpy
+Requires-Dist: pylightxl

districtgenerator.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE.md
+README.md
+setup.py
+classes/__init__.py
+classes/datahandler.py
+classes/envelope.py
+classes/plots.py
+classes/profils.py
+classes/solar.py
+classes/users.py
+districtgenerator.egg-info/PKG-INFO
+districtgenerator.egg-info/SOURCES.txt
+districtgenerator.egg-info/dependency_links.txt
+districtgenerator.egg-info/requires.txt
+districtgenerator.egg-info/top_level.txt

districtgenerator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

districtgenerator.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy
+pandas
+matplotlib
+scipy
+teaser
+richardsonpy
+pylightxl

districtgenerator.egg-info/top_level.txt

@@ -0,0 +1 @@
+classes

districtgenerator/__init__.py

@@ -1,6 +0,0 @@
-from districtgenerator.datahandler import Datahandler
-from districtgenerator.envelope import Envelope
-from districtgenerator.solar import Sun
-from districtgenerator.users import Users
-from districtgenerator.profils import Profiles
-from districtgenerator.plots import DemandPlots