Skip to content

First model and simulation

This tutorial will guide you in creating and simulating your first Building Energy Simulation model in Modelica using the Trano library. All you need is a configuration file and a few lines of code. This introductory tutorial demonstrates the simplicity of running building energy simulations with Trano, showcasing how to browse and modify the model using OpenModelica. Alternatively, you can run the simulation directly through Trano with the official OpenModelica Docker image. Additionally, Trano features automatic report generation for key parameters.

Input configuration file

The following file describes a simple configuration for a one-zone building, focusing solely on the building envelope.

The described building configuration appears to be a modest residential structure or small commercial building. It features:

  1. Material Composition: The walls are constructed with three layers of material, each having the same thermal properties (thermal conductivity of 0.035 W/m·K, density of 2000 kg/m³, and specific heat capacity of 1000 J/kg·K), indicating good insulation characteristics.

  2. Glazing: The building includes insulated glazing units made of two layers of glass with an air gap, enhancing thermal performance with a thermal conductivity of 1.0 W/m·K in the glass and a low conductivity air layer.

  3. Space and Dimensions: It offers a floor area of 100 m² and an average room height of 2.5 m, suggesting a standard layout for living or office space.

  4. Walls and Windows: The external walls have surfaces oriented towards the south (azimuth of 180°) and collectively form a well-insulated envelope. There is a single window with dimensions of 1 m², also oriented southward, allowing natural light while maintaining energy efficiency.

Overall, the building is designed for energy efficiency, potentially suitable for residential use, with an emphasis on thermal comfort.

material:
  - id: MATERIAL:001
    thermal_conductivity: 0.035
    density: 2000.0
    specific_heat_capacity: 1000.0
  - id: MATERIAL:002
    thermal_conductivity: 0.035
    density: 2000.0
    specific_heat_capacity: 1000.0
  - id: MATERIAL:003
    thermal_conductivity: 0.035
    density: 2000.0
    specific_heat_capacity: 1000.0

constructions:
  - id: CONSTRUCTION:001
    layers:
      - material: MATERIAL:001
        thickness: 0.1
      - material: MATERIAL:002
        thickness: 0.1
      - material: MATERIAL:003
        thickness: 0.1
glass_material:
  - density: 2500.0
    id: GLASS:001
    longwave_emissivity: 0.84
    shortwave_emissivity: 0.67
    specific_heat_capacity: 840.0
    thermal_conductivity: 1.0
gas:
  - density: 1.2
    id: AIR:001
    longwave_emissivity: 0.0
    shortwave_emissivity: 0.0
    specific_heat_capacity: 1006.0
    thermal_conductivity: 0.0256
glazings:
- id: INS2AR2020:001
  layers:
  - glass: GLASS:001
    thickness: 0.006
  - gas: AIR:001
    thickness: 0.016
  - glass: GLASS:001
    thickness: 0.006
spaces:
  - parameters:
      floor_area: 100.0
      average_room_height: 2.5
    external_boundaries:
      external_walls:
        - surface: 100.0
          azimuth: 180.0
          tilt: wall
          construction: CONSTRUCTION:001
        - surface: 100.0
          azimuth: 180.0
          tilt: wall
          construction: CONSTRUCTION:001
        - surface: 200.0
          azimuth: 180.0
          tilt: wall
          construction: CONSTRUCTION:001
      floor_on_grounds:
        - surface: 1.0
          construction: CONSTRUCTION:001
      windows:
        - surface: 1.0
          azimuth: 180.0
          tilt: wall
          construction: INS2AR2020:001
          width: 1.0
          height: 1.0

Generate Modelica model

Test tutorials
    from trano.main import create_model

    create_model(
        path_to_yaml_configuration_folder / "first_model.yaml",
    )

Explanation

The code snippet imports the create_model function from the trano.main module and then calls this function with a specified YAML configuration file to create a model based on the parameters defined in that file.

General Description and Parameters

  • Function: create_model
  • Parameter:
  • path_to_yaml_configuration_folder / "first_model.yaml":
    • Type: String (or path-like object)
    • Description: The path to the YAML file that contains configuration settings for the model being created.

The model is created in the same folder as the configuration file, with the extension .mo. In this case, the model is saved as first_model.mo. Provided that the necessary libraries, such as the Buildings library, are loaded, the generated model can be opened in OpenModelica, as illustrated in the figure below. Additionally, if not specified, Trano utilizes the Buildings library to generate the model.

Generated model

If one opens the main building components, the generated components are subdivided into various sub-components, as illustrated below. Since the configuration file contains only the building envelope information, only the envelope sub-component is generated.

Building components

Opening the envelope subcomponents reveals the various base components and information that constitute the building envelope model. At this stage, the user can modify the model as necessary.

Envelope components

Simulate

The following code snippet can be used to directly simulate the model after its generation. The model will not be generated; instead, it will be simulated within the OpenModelica container.

Test tutorials
    from trano.main import simulate_model

    simulate_model(
        path_to_yaml_configuration_folder / "first_simulation.yaml",
        library="Buildings",
        start=0,
        end=2 * 3600 * 24 * 7,
    )

Explanation of Code Snippet

The code snippet imports a function simulate_model from the trano.main module and calls it to run a simulation using a specified YAML configuration file and parameters.

General Description and Parameters

  • Function: simulate_model
  • Parameters:
  • path_to_yaml_configuration_folder / "first_simulation.yaml"
    • Path to the configuration file for the simulation.
  • library: "Buildings"
    • Specifies the library to be used for the simulation.
  • start: 0
    • Start time for the simulation in seconds.
  • end: 2 * 3600 * 24 * 7
    • End time for the simulation, calculated as two weeks in seconds.

Once the simulation is complete, key parameters are presented in a report file, as shown below.

Spaces

External Boundaries Table

hRoo AFlo linearizeRadiation m_flow_nominal mSenFac T_start volume
2.5 100.0 true 0.01 1.0 294.15 250.0
gain k occupancy name
[40; 75; 40] 1/7/3 3600*{9, 17} occupancy_1

Construction

Layer Information Table

Name Azimuth Construction Name Surface Tilt
externalwall_0 180.0 construction_001 100.0 wall
externalwall_1 180.0 construction_001 100.0 wall
externalwall_2 180.0 construction_001 200.0 wall
window_0 180.0 ins2ar2020_001 1.0 wall
flooronground_0 90.0 construction_001 1.0 floor
Layers for construction_001
Name c epsLw epsSw k rho Thickness
material_001 1000.0 0.85 0.85 0.035 2000.0 0.1
material_002 1000.0 0.85 0.85 0.035 2000.0 0.1
material_003 1000.0 0.85 0.85 0.035 2000.0 0.1
Layer Information Table
Layers for ins2ar2020_001
Name c epsLw epsSw k rho Thickness
glass_001 840.0 0.84 0.67 1.0 2500.0 0.006
air_001 1006.0 0.0 0.0 0.0256 1.2 0.016
glass_001 840.0 0.84 0.67 1.0 2500.0 0.006

00.2M0.4M0.6M0.8M1M1.2M28728828929029129229329429500.20.40.60.81
Legendspace_1 - Air temperature [K]space_1 - Occupied zone [-]Simulation time [-]Zone air temperature [K]Occupancy schedule [-]
00.2M0.4M0.6M0.8M1M1.2M050100150200250300350
Legendspace_1 - Radiative heat flow rate [W]space_1 - Convective heat flow rate [W]space_1 - Latent heat gain [W]space_1 - Convective heat gain [W]Simulation time [-]Heat flow rate [W]