teaser package

teaser

Tool for Energy Analysis and Simulation for Efficient Retrofit

Subpackages

Submodules

teaser.project module

This module includes the Project class, which is the API for TEASER.

class teaser.project.Project(load_data=False)[source]

Bases: object

Top class for TEASER projects it serves as an API

The Project class is the top class for all TEASER projects and serves as an API for script based interface. It is highly recommended to always instantiate the Project class before starting to work with TEASER. It contains functions to generate archetype buildings, to export models and to save information for later use.

Parameters:
load_databoolean

boolean if data bases for materials, type elements and use conditions should be loaded. default = False but will be automatically loaded once you add a archetype building. For building generation from scratch, set to True

Attributes:
namestr

Name of the Project (default is ‘Project’)

modelica_infoinstance of ModelicaInfo

TEASER instance of ModelicaInfo to store Modelica related information, like used compiler, start and stop time, etc.

buildingslist

List of all buildings in one project, instances of Building()

datainstance of DataClass

TEASER instance of DataClass containing JSON binding classes

weather_file_pathstr

Absolute path to weather file used for Modelica simulation. Default weather file can be find in inputdata/weatherdata.

number_of_elements_calcint

Defines the number of elements, that are aggregated (1, 2, 3 or 4), default is 2

merge_windows_calcbool

True for merging the windows into the outer walls, False for separate resistance for window, default is False (only supported for IBPSA)

used_library_calcstr

used library (AixLib and IBPSA are supported)

dir_reference_resultsstr

Path to reference results in BuildingsPy format. If not None, the results will be copied into the model output directories so that the exported models can be regression tested against these results with BuildingsPy.

add_non_residential(construction_data, geometry_data, name, year_of_construction, number_of_floors, height_of_floors, net_leased_area, with_ahu=True, internal_gains_mode=1, office_layout=None, window_layout=None)[source]

Add a non-residential building to the TEASER project. This function adds a non-residential archetype building to the TEASER project. You need to specify the method of the archetype generation. Currently TEASER supports only method according to Lichtmess and BMVBS for non-residential buildings. Further the type of geometry_data needs to be specified. Currently TEASER supports four different types of non-residential buildings (‘office’, ‘institute’, ‘institute4’, ‘institute8’). For more information on specific archetype buildings and methods, please read the docs of archetype classes.

This function also calculates the parameters of the buildings directly with the settings set in the project (e.g. used_library_calc or number_of_elements_calc).

Parameters:
construction_datastr

Used data for construction, for bmvbs non-residential buildings ‘iwu_heavy’ is supported

geometry_datastr

Main geometry_data of the obtained building, currently only ‘bmvbs_office’, ‘bmvbs_institute’, ‘bmvbs_institute4’, ‘bmvbs_institute8’ are supported

namestr

Individual name

year_of_constructionint

Year of first construction

height_of_floorsfloat [m]

Average height of the buildings’ floors

number_of_floorsint

Number of building’s floors above ground

net_leased_areafloat [m2]

Total net leased area of building. This is area is NOT the footprint of a building

with_ahuBoolean

If set to True, an empty instance of BuildingAHU is instantiated and assigned to attribute central_ahu. This instance holds information for central Air Handling units. Default is False.

internal_gains_mode: int [1, 2, 3]

mode for the internal gains calculation done in AixLib:

1. Temperature and activity degree dependent heat flux calculation for persons. The calculation is based on SIA 2024 (default)

2. Temperature and activity degree independent heat flux calculation for persons, the max. heatflowrate is prescribed by the parameter fixed_heat_flow_rate_persons.

3. Temperature and activity degree dependent calculation with consideration of moisture and co2. The moisture calculation is based on SIA 2024 (2015) and regards persons and non-persons, the co2 calculation is based on Engineering ToolBox (2004) and regards only persons.

office_layoutint

Structure of the floor plan of office buildings, default is 1, which is representative for one elongated floor.

  1. elongated 1 floor

  2. elongated 2 floors

  3. compact (e.g. for a square base building)

window_layoutint

Structure of the window facade type, default is 1, which is representative for a punctuated facade.

  1. punctuated facade (individual windows)

  2. banner facade (continuous windows)

  3. full glazing

Returns:
type_bldgInstance of Office()
add_residential(construction_data, geometry_data, name, year_of_construction, number_of_floors, height_of_floors, net_leased_area, with_ahu=False, internal_gains_mode=1, residential_layout=None, neighbour_buildings=None, attic=None, cellar=None, dormer=None, number_of_apartments=None)[source]

Add a residential building to the TEASER project.

This function adds a residential archetype building to the TEASER project. You need to specify the construction_data of the archetype generation. Currently TEASER supports only construction_data according ‘iwu’, ‘urbanrenet’, ‘tabula_de’ and ‘tabula_dk’ for residential buildings. Further the type of geometry_data needs to be specified. Currently TEASER supports one type of residential building for ‘iwu’ and eleven types for ‘urbanrenet’. For more information on specific archetype buildings and methods, please read the docs of archetype classes. This function also calculates the parameters of the buildings directly with the settings set in the project (e.g. used_library_calc or number_of_elements_calc).

Parameters:
construction_datastr

Used construction_data, currently supported values: ‘iwu_heavy’, ‘iwu_light’, ‘tabula_de_standard’, ‘tabula_de_retrofit’, ‘tabula_de_adv_retrofit’, ‘tabula_dk_standard’, ‘tabula_dk_retrofit’, ‘tabula_dk_adv_retrofit’ and the KfW Efficiency house standards ‘kfw_40’, ‘kfw_55’, ‘kfw_70’, ‘kfw_85, kfw_100’

geometry_datastr

Main geometry_data of the obtained building, currently supported values: ‘iwu_single_family_dwelling’, ‘urbanrenet_est1a’, ‘urbanrenet_est1b’, ‘urbanrenet_est2’, ‘urbanrenet_est3’, ‘urbanrenet_est4a’, ‘urbanrenet_est4b’, ‘urbanrenet_est5’ ‘urbanrenet_est6’, ‘urbanrenet_est7’, ‘urbanrenet_est8a’, ‘urbanrenet_est8b’ ‘tabula_de_single_family_house’, ‘tabula_de_terraced_house’, ‘tabula_de_multi_family_house’, ‘tabula_de_apartment_block’, ‘tabula_dk_single_family_house’, ‘tabula_dk_terraced_house’, ‘tabula_dk_multi_family_house’, ‘tabula_dk_apartment_block’

namestr

Individual name

year_of_constructionint

Year of first construction

height_of_floorsfloat [m]

Average height of the buildings’ floors

number_of_floorsint

Number of building’s floors above ground

net_leased_areafloat [m2]

Total net leased area of building. This is area is NOT the footprint of a building

with_ahuBoolean

If set to True, an empty instance of BuildingAHU is instantiated and assigned to attribute central_ahu. This instance holds information for central Air Handling units. Default is False.

internal_gains_mode: int [1, 2, 3]

mode for the internal gains calculation done in AixLib:

  1. Temperature and activity degree dependent heat flux calculation for persons. The calculation is based on SIA 2024 (default)

  2. Temperature and activity degree independent heat flux calculation for persons, the max. heatflowrate is prescribed by the parameter fixed_heat_flow_rate_persons.

  3. Temperature and activity degree dependent calculation with consideration of moisture and co2. The moisture calculation is based on SIA 2024 (2015) and regards persons and non-persons, the co2 calculation is based on Engineering ToolBox (2004) and regards only persons.

residential_layoutint

Structure of floor plan (default = 0) CAUTION only used for iwu

  1. compact

  2. elongated/complex

neighbour_buildingsint

Number of neighbour buildings. CAUTION: this will not change the orientation of the buildings wall, but just the overall exterior wall and window area(!) (default = 0)

  1. no neighbour

  2. one neighbour

  3. two neighbours

atticint

Design of the attic. CAUTION: this will not change the orientation or tilt of the roof instances, but just adapt the roof area(!) ( default = 0) CAUTION only used for iwu

  1. flat roof

  2. non heated attic

  3. partly heated attic

  4. heated attic

cellarint

Design of the of cellar CAUTION: this will not change the orientation, tilt of GroundFloor instances, nor the number or area of ThermalZones, but will change GroundFloor area(!) (default = 0) CAUTION only used for iwu

  1. no cellar

  2. non heated cellar

  3. partly heated cellar

  4. heated cellar

dormerstr

Is a dormer attached to the roof? CAUTION: this will not change roof or window orientation or tilt, but just adapt the roof area(!) (default = 0) CAUTION only used for iwu

  1. no dormer

  2. dormer

number_of_apartmentsint

number of apartments inside Building (default = 1). CAUTION only used for urbanrenet

Returns:
type_bldgInstance of Archetype Building
add_residential_retrofit_combinations(elements: list | None = None, retrofit_choices: list | None = None, **add_residential_kwargs: dict)[source]

Generate residential buildings for all possible combinations of retrofit statuses for specified building elements.

This function creates multiple variations of a residential building based on different retrofit options for specified building elements. It’s designed to work with TABULA archetypes.

Parameters:
add_residential_kwargsdict

Keyword arguments for the function add_residential.

elementslist, optional

List of building elements to consider for retrofit. Defaults to [‘outer_walls’, ‘windows’, ‘rooftops’, ‘ground_floors’].

retrofit_choiceslist, optional

List of retrofit options to consider. Defaults to [‘standard’, ‘retrofit’, ‘adv_retrofit’].

Returns:
list: A list of names of the generated buildings.
Raises:
ValueError: If unsupported elements or retrofit choices are provided, or if the

construction data is not from TABULA DE or DK.

calc_all_buildings(raise_errors=False)[source]

Calculates values for all project buildings

You need to set the following parameters in the Project class.

number_of_elements_calcint

defines the number of elements, that area aggregated, between 1 and 4, default is 2 For AixLib you should always use 2 elements!!!

merge_windows_calcbool

True for merging the windows into the outer walls, False for separate resistance for window, default is False For AixLib vdi calculation is True, ebc calculation is False

used_library_calcstr

used library (AixLib and IBPSA are supported)

export_aixlib(building_model=None, zone_model=None, corG=None, internal_id=None, path=None, use_postprocessing_calc=False, report=False, export_vars=None)[source]

Exports values to a record file for Modelica simulation

Exports one (if internal_id is not None) or all buildings for AixLib.ThermalZones.ReducedOrder.Multizone.MultizoneEquipped models using the ThermalZoneEquipped model with a correction of g-value ( double pane glazing) and supporting models, like tables and weather model. In contrast to versions < 0.5 TEASER now does not support any model options, as we observed no need, since single ThermalZones are identically with IBPSA models. If you miss one of the old options please contact us.

Parameters:
internal_idfloat

setter of a specific building which will be exported, if None then all buildings will be exported

pathstring

if the Files should not be stored in default output path of TEASER, an alternative path can be specified as a full path

report: boolean

if True a model report in form of a html and csv file will be created for the exported project.

export_vars: dict[str:list]

dict where key is a name for this variable selection and value is a list of variables to export, wildcards can be used, multiple variable selections are possible. This works only for Dymola. See (https://www.claytex.com/blog/selection-of-variables-to-be-saved-in-the-result-file/)

export_besmod(internal_id: float | None = None, examples: List[str] | None = None, path: str | None = None, THydSup_nominal: float | Dict[str, float] | None = None, QBuiOld_flow_design: Dict[str, Dict[str, float]] | None = None, THydSupOld_design: float | Dict[str, float] | None = None, custom_examples: Dict[str, str] | None = None, custom_script: Dict[str, str] | None = None, report: bool = False) → str[source]

Exports buildings for BESMod simulation

Exports one (if internal_id is not None) or all buildings as BESMod.Systems.Demand.Building.TEASERThermalZone models. Additionally, BESMod.Examples can be specified and directly exported including the building.

Parameters:
internal_idOptional[float]

Specifies a specific building to export by its internal ID. If None, all buildings are exported.

examplesOptional[List[str]]

Names of BESMod examples to export alongside the building models. Supported Examples: “TEASERHeatLoadCalculation”, “HeatPumpMonoenergetic”, and “GasBoilerBuildingOnly”.

pathOptional[str]

Alternative output path for storing the exported files. If None, the default TEASER output path is used.

THydSup_nominalOptional[Union[float, Dict[str, float]]]

Nominal supply temperature(s) for the hydraulic system. Required for certain examples (e.g., HeatPumpMonoenergetic, GasBoilerBuildingOnly). See docstring of teaser.data.output.besmod_output.convert_input() for further information.

QBuiOld_flow_designOptional[Dict[str, Dict[str, float]]]

For partially retrofitted systems specify the old nominal heat flow of all zones in the Buildings in a nested dictionary with the building names and in a level below the zone names as keys. By default, only the radiator transfer system is not retrofitted in BESMod.

THydSupOld_designOptional[Union[float, Dict[str, float]]]

Design supply temperatures for old, non-retrofitted hydraulic systems.

custom_examples: Optional[Dict[str, str]]

Specify custom examples with a dictionary containing the example name as the key and the path to the corresponding custom mako template as the value.

custom_script: Optional[Dict[str, str]]

Specify custom .mos scripts for the existing and custom examples with a dictionary containing the example name as the key and the path to the corresponding custom mako template as the value.

reportbool

If True, generates a model report in HTML and CSV format for the exported project. Default is False.

Returns:
str

The path where the exported files are stored.

export_ibpsa(library='AixLib', internal_id=None, path=None)[source]

Exports values to a record file for Modelica simulation

For Annex 60 Library

Parameters:
librarystr

Used library within the framework of IBPSA library. The models are identical in each library, but IBPSA Modelica library is just a core set of models and should not be used standalone. Valid values are ‘AixLib’ (default), ‘Buildings’, ‘BuildingSystems’ and ‘IDEAS’.

internal_idfloat

setter of a specific building which will be exported, if None then all buildings will be exported

pathstring

if the Files should not be stored in default output path of TEASER, an alternative path can be specified as a full path

static instantiate_data_class()[source]

Initialization of DataClass

Returns:
DataClassInstance of DataClass()
load_project(path)[source]

Load the project from a json file (new format).

Calls the function load_teaser_json.

Parameters:
pathstring

full path to a json file

property merge_windows_calc
property name
property number_of_elements_calc
static process_export_vars(export_vars)[source]

Process export vars to fit __Dymola_selections syntax.

retrofit_all_buildings(year_of_retrofit=None, type_of_retrofit=None, window_type=None, material=None)[source]

Retrofits all buildings in the project.

Depending on the used Archetype approach this function will retrofit the building. If you have archetypes of both typologies (tabula and iwu/BMBVS) you need to pass all keywords (see also Parameters section).

If TABULA approach is used, it will replace the current construction with the construction specified in ‘type_of_retrofit’, where ‘retrofit’ and ‘adv_retrofit’ are allowed.

‘iwu’ or ‘BMVBS’ Buildings in the project are retrofitted in the following manner:

  • replace all windows of the building to retrofitted window according to the year of retrofit.

  • add an additional insulation layer to all outer walls (including roof, and ground floor). The thickness of the insulation layer is calculated that the U-Value of the wall corresponds to the retrofit standard of the year of retrofit.

The needed parameters for the Modelica Model are calculated automatically, using the calculation_method specified in the first scenario.

Note: To Calculate U-Value, the standard TEASER coefficients for outer and inner heat transfer are used.

Parameters:
year_of_retrofitint

the year the buildings are retrofitted, only ‘iwu’/’bmbvs’ archetype approach.

type_of_retrofitstr

The classification of retrofit, if the archetype building approach of TABULA is used.

window_typestr

Default: EnEv 2014, only ‘iwu’/’bmbvs’ archetype approach.

materialstr

Default: EPS035, only ‘iwu’/’bmbvs’ archetype approach.

save_project(file_name=None, path=None)[source]

Saves the project to a JSON file

Calls the function save_teaser_json in data.output.teaserjson_output

Parameters:
file_namestring

name of the new file

pathstring

if the Files should not be stored in OutputData, an alternative can be specified

set_default(load_data=None)[source]

Sets all attributes to default

Caution: this will delete all buildings.

Parameters:
load_databoolean, None-type

boolean if data bindings for type elements and use conditions should be loaded (default = False), in addition it could be a None- type to use the already used data bindings

set_location_parameters(t_outside=262.65, t_ground=286.15, weather_file_path=None, calc_all_buildings=True)[source]

Set location specific parameters

Temperatures are used for static heat load calculation and as parameters in the exports. Default location is Mannheim.

Parameters:
t_outside: float [K]

Normative outdoor temperature for static heat load calculation. The input of t_inside is ALWAYS in Kelvin

t_ground: float [K]

Temperature directly at the outer side of ground floors for static heat load calculation. The input of t_ground is ALWAYS in Kelvin

weather_file_pathstr

Absolute path to weather file used for Modelica simulation. Default weather file can be find in inputdata/weatherdata.

calc_all_buildings: boolean

If True, calculates all buildings new. Default is True. Important for new calculation of static heat load.

property used_library_calc
property weather_file_path