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

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.