################################
CITY\ **twin**
################################

CITY\ **twin** is the catch-all term that refers to all the back-end components of **TOOLS**\4CITIES.

The primary functions of CITY\ **twin** are:

- Creating digital twins of cities.
- Running sustainability-related simulations.
- Making GHG emission and energy-related cost calculations.
- Storing simulation results for future reference.
- Making the simulations, calculations, urban data, and simulation results all available to the front-end tools, so services can be offered to users without the need to write Python code.

The ultimate goal is for CITY\ **twin** is to have simulation capabilities across all domains that affect urban sustainability, but the initial focus has been on building energy modelling.
New work is underway in 2026 to include the domains of electrical distribution, traffic emissions, and neighborhood-scale energy modelling.

Here is an overview of the components of CITY\ **twin**.  You can find detailed descriptions of each one in the pages below.

|

.. figure:: /images/citytwin-architecture.jpg
   :width: 1000
   :align: center
   :alt: CITY\ **twin** architecture

   **CITYtwin Architecture**


The urban data stored in CITY\ **twin**, includes infrastructure (e.g. building geometry, building metadata, road networks), system data (eg energy system
descriptions & performance metrics, weather data, occupancy schedules) and properties (e.g. construction material thermal values, embodied carbon emissions, cost catalogs).

The core component of the back-end, CITY\ **hub**, uses this urban data to create digital twins of cities. It then outputs the necessary data files needed to run simulations.

The simulations are the packages that do the complex calculations. For example, EnergyPlus calculates the energy demand of a building, hour by hour, through an entire year.
Simplified Radiosity Algorithm calculates the solar radiation hitting the surfaces of a building throughout a year and the District Heating and Cooling Network (DCHN) simulation calculates the topology
and dimensionality of a DHCN for a given set of buildings.

The workflows are Python scripts that coordinate all these steps for any required simulation. They send the correct urban data to the CITY\ **hub** to make the required digital twin, get the CITY\ **hub** to export
the files needed to run a particular simulation, then run the simulation and collect the results, and finally send the results to the required destination.

Simulation results can be stored in a persistent database making them accessible for future reference. This is used extensively by the services in CITY\ **layers** to allow
users to do what-if scenarios in real-time because time-consuming energy simulations have been pre-run in advance, and the results all stored. The user scenarios then filter for
just the simulation results needed (e.g. a selection of buildings or choice of retrofit scenario).

Finally, the APIs provide end-points that can be called by the front-ends, (CITY\ **layers**, WORKFLOW\ **launcher**, and RETRO\ **fitter**), allowing them to access the data, simulations and calculations contained within CITY\ **twin**.

Note - the CITY\ **player** front-end has no real-time connection to CITY\ **twin**, but it does use much of the same urban data to generate its 3D visualisation
of cities.

All components of CITY\ **twin** are coded in Python and each repository is distributed under GNU L-GPL open source license.

.. toctree::
   :maxdepth: 1
   :caption: CITYtwin Components

   cityhub/index
   urbandata/index
   simulations/index
   workflows/index
   apis/index