CITYtwin
CITYtwin is the catch-all term that refers to all the back-end components of TOOLS4CITIES.
The primary functions of CITYtwin 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 CITYtwin 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 CITYtwin. You can find detailed descriptions of each one in the pages below.
CITYtwin Architecture
The urban data stored in CITYtwin, 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, CITYhub, 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 CITYhub to make the required digital twin, get the CITYhub 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 CITYlayers 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, (CITYlayers, WORKFLOWlauncher, and RETROfitter), allowing them to access the data, simulations and calculations contained within CITYtwin.
Note - the CITYplayer front-end has no real-time connection to CITYtwin, but it does use much of the same urban data to generate its 3D visualisation of cities.
All components of CITYtwin are coded in Python and each repository is distributed under GNU L-GPL open source license.
CITYtwin Components