################################################ Architecture ################################################ ******************************** 1. Introduction and Goals ******************************** **CITYhub** is a combination of two concepts, *Digital Twin* and *ETLs*. By doing so, it homogenizes data from different sources in a consistent and unified way that later on can be exported in formats compatible with industry-standard software, such as EnergyPlus. It's provided as a Python package and provides the following functionalities. - Simplify the creation of a data structure representing a city. - Provides a backend for different tools. - Provide conversions and base files for industry-standard simulation tools. 1.1 Requirements Overview -------------------------- **CITYhub** starts by importing geometry files for the area you want to study, then enrich the city's digital twin based on archetypes, at the moment, the proper archetype selection is performed based on the user selection, year of construction, and building function and use. 1.2 Quality Goals ------------------ +-----------------------------------+-----------------------------------+ | Goal | Description | +===================================+===================================+ | Familiarity | For domain experts, the classes | | | and terms should be familiar, to | | | flatten the learning curve for | | | experts in the field. | +-----------------------------------+-----------------------------------+ | Consistency | Same code patterns and style are | | | enforced in the code base. | +-----------------------------------+-----------------------------------+ | Abstraction | Abstract the users from the | | | particularities and complications | | | of the heterogeneous data | | | sources. | +-----------------------------------+-----------------------------------+ 1.3 Stakeholders ----------------- The following people and organizations influence **CITYhub**: +-----------------------------------+-----------------------------------+ | Stakeholder | Description | +===================================+===================================+ | Next-Generation Cities Institute | The research institute | | | responsible for designing and | | | developing **CITYhub**. | +-----------------------------------+-----------------------------------+ | Research Partners | Researchers who collaborate with | | | the NGCI to validate and enhance | | | **CITYhub**. | +-----------------------------------+-----------------------------------+ ******************************** 2. Architectural Constraints ******************************** **CITYhub** shall be: - Easy to use for researchers. - Multiplatform. - Easty to modify. Therefore, we use Python, a multiplatform language, considered the most friendly language by the NGCI researchers. ******************************** 3. Context & Scope ******************************** 3.1 End-user Context --------------------- **CITYhub** is designed and structured to perform at an urban scale analysis using generic data; therefore, it doesn’t aim to perform single building simulations; it could be used as a starting point for such simulations, but post-refining will be required. 3.2 Technical Context ---------------------- **CITYhub** is developed in Python under the LGPL license. We do our best to keep it compatible with the latest Python versions, and we try to fulfill the researchers' requests as long as the request may also be beneficial for others. ******************************** 4. Solution Strategy ******************************** +-----------------------------------+-----------------------------------+ | Goal | Strategy | +===================================+===================================+ | Familiarity | We follow the international unit | | | system, our naming and structures | | | try to follow the domain experts | | | advice. | +-----------------------------------+-----------------------------------+ | Consistency | We mostly follow PEP8 and provide | | | programming guidelines. | +-----------------------------------+-----------------------------------+ | Abstraction | Importers and exporters | | | simplifies the transformation | | | between formats. | +-----------------------------------+-----------------------------------+ ******************************** 5. Building Block View ******************************** .. figure:: ../images/hub-architecture.jpg :alt: Components that are part of the CITYhub library Components of the CITYhub library ******************************** 6. Architectural Decisions ******************************** **Why Python?** Python is a very popular language in science, making easier for non-developer researchers to use and incorporate their research questions. **Why not 100% PEP8?** PEP8 significantly impacts the code quality, and we try to follow it as much as possible, but the PEP8 character limitation may, in some cases, make the code more complex. **Why are the ETLs organized in Exports and Imports?** This structure, allows us to abstract the researchers from the heterogeneous data formats details, making it easier for software developers and scientists to cooperate, as it’s easier for the formers to *parse* from or to a specific format to understand a complex domain. **Why do we have a central data model?** A central data model homogenizes the heterogeneous data and abstract the researchers from the data source, so they don’t need to *know* or *understand* a specific data source, but just the central data model that we adapt following the researcher's guidelines *(domain driven design)* and that is, by design, familiar to them. **Why do we have catalogs?** Catalogs are a valuable source of information for researchers, and the catalog structure provides an additional convenience to researchers who are only interested in our archetypes. ******************************** 7. Quality Requirements ******************************** +-----------------------------------+-----------------------------------+ | Goal | Description | +===================================+===================================+ | Domain experts | Domain experts can use the hub to | | | perform out of the box | | | simulations even without previous | | | coding experience. | +-----------------------------------+-----------------------------------+ | Advanced researchers | Hub is designed so that the domain| | | experts can understand and modify | | | the code so it fits their own | | | research questions. | +-----------------------------------+-----------------------------------+ | High-level users | For high-level users, hub | | | provides a way to run workflows | | | that synthesize the researchers | | | simulations without knowing the | | | fine details. | +-----------------------------------+-----------------------------------+ ******************************** 8. Risks & Technical Debt ******************************** +-----------------------------------+-----------------------------------+ | Risk | Mitigation strategy | +===================================+===================================+ | Inconsistency | We perform regular code quality | | | checks to mitigate the risk | | | inconsistencies. | +-----------------------------------+-----------------------------------+ | Documentation | We generate up-to-date automatic | | | documentation. | +-----------------------------------+-----------------------------------+ | Compatibility | We try to keep our dependencies | | | up to date and avoid dependencies | | | in abandoned projects or | | | libraries. | +-----------------------------------+-----------------------------------+ ******************************** 9. Glossary ******************************** +-----------------------------------+-----------------------------------+ | Term | Definition | +===================================+===================================+ | Archetype | An average representation of | | | typical values for some domain, | | | like usages or construction | | | materials. | +-----------------------------------+-----------------------------------+ | Digital twin | A computer representation of | | | something, in our case, an urban | | | area. | +-----------------------------------+-----------------------------------+ | Domain driven design | A design strategy following the | | | opinions of domain experts over | | | other considerations. | +-----------------------------------+-----------------------------------+ | ETL | Extract, Transform, and Load. It’s| | | a basic strategy to deal with | | | data in big data projects. | +-----------------------------------+-----------------------------------+ | LGPL | GNU Lesser General Public | | | License, An open source license. | +-----------------------------------+-----------------------------------+