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.

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.

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.

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

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

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

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