Component List for building definition elements
Building
Base component for the definition of a building. The building is made up of a set of spaces (Space component).
Parameters
- file_met [component, default = "not_defined", component type = File_met]: Reference to the component where the weather file is defined.
- azimuth [float, unit = "°", default = 0, min = -180, max = 180]: Angle formed between the x-axis of the building and the east (Global x-axis). The coordinates of all building elements refer to the building coordinate system.
- albedo [float, unit = "frac", default = 0.3, min = 0, max = 1]: Solar reflectivity of the ground surrounding the building. Used to calculate the solar radiation reflected to the exterior surfaces of the building.
- initial_temperature [float, unit = "°C", default = 20]: Initial temperature of all building components at the beginning of the simulation.
- initial_humidity [float, unit = "g/kg", default = 7.3]: Initial absolute humidity of all building spaces at the beginning of the simulation.
- shadow_calculation [option, default = "INSTANT", options = ["NO","INSTANT","INTERPOLATION"]]: Procedure used for the exterior calculation of the shadows produced by the shading surfaces "Shadow_surface" and the building itself. “NO": no shadows are calculated, "INSTANT": Shadows are calculated for each instant of simulated time. "INTERPOLATION": The shadows are calculated for 36 x 18 = 648 fixed solar positions and then the shadows for every time step are obtained by interpolating on these tables.
The following figure shows the building's coordinate system:
Example:
...
building = osm.components.Building("building",project)
param = {
"file_met": "met"
"azimuth": 90,
"albedo": 0.4
}
building.set_parameters(param)
functions
The Building component include the following functions:
-
show3D(hide, opacity, coordinate_system, space): Displays in Jupyter an interactive 3D visualization of the building (using pyVista). hide: (default value: []) List of the types of components that we do not want to show, for example [“Interior_surface”, "Underground_surface"] will hide these two types of components. opacity: Opacity of the surfaces, 1 (default value) for totally opaque and 0 for totally transparent. coordinate_system: Coordinate system in which the building will be displayed, “global” (default value), “local” the coordinate system of the building. space: (default value: “all”) If a space name is specified, the rest of the spaces will be shown dimmed (opacity = 0.25).
-
show3D_shadows(date): Calculates and displays an interactive 3D visualization of the building with the shadows occurring for the date specified. date: Python datetime object specifying a specific date. See next figure as example.
Space_type
Component used to define the type of space. This component will be referenced by all spaces that are of the same type. This component defines the internal loads and some of the functional characteristics of the space.
Parameters
- input_variables [variable_list, default = []]: List of variables from other components used in this component. They may be used in parameters of the type math_exp.
- people_density [math_exp, unit = "p/m²", default = "0.1"]: Occupancy density, defined in persons per m² of floor. The mathematical expression may contain any of the variables declared in the "input_variables" parameter, to be able to reflect the time variation of this value. See example below
- people_sensible [float, unit = "W/p", default = 70, min = 0]: Sensible heat generated by each of the occupants of the space.
- people_latent [float, unit = "W/p", default = 35, min = 0]: Latent heat generated by each of the occupants of the space.
- people_radiant_fraction [float, unit = "frac", default = 0.6, min = 0, max = 1]: Long wave radiant fraction of heat generated by occupants. The rest of the heat is assumed to be convective.
- light_density [math_exp, unit = "W/m²", default = "10"]: Lighting density, defined as the electrical lighting power [W] per m² of floor. The mathematical expression may contain any of the variables declared in the "input_variables" parameter, to be able to reflect the time variation of this value. See example below.
- light_radiant_fraction [float, unit = "frac", default = 0.6, min = 0, max = 1]: Short wave radiant fraction of heat generated by lights. The rest of the heat is assumed to be convective.
- other_gains_density [math_exp, unit = "W/m²", default = "10"]: Other gains density, defined as the heat generated by other gains (Household appliances, office automation, miscellaneous electrical equipment, etc.) [W] per m² of floor. The mathematical expression may contain any of the variables declared in the "input_variables" parameter, to be able to reflect the time variation of this value. See example below.
- other_gains_radiant_fraction [float, unit = "frac", default = 0.5, min = 0, max = 1]: Long wave radiant fraction of the heat generated by other gains. The convective fraction is calculated by subtracting the radiant and latent fractions.
- other_gains_latent_fraction [float, unit = "frac", default = 0.0, min = 0, max = 1]: Latent fraction of the heat generated by other gains. The convective fraction is calculated by subtracting the radiant and latent fractions.
- infiltration [math_exp, unit = "1/h", default = "1"]: Air flow rate infiltrated into the space from outside and expressed in volumes of the space per hour. The mathematical expression may contain any of the variables declared in the "input_variables" parameter, to be able to reflect the time variation of this value.
Assuming that the variation of occupancy, lighting and other loads has been defined in a "Year_schedule" component, named "schedule" with values between 0 and 1, the following example would capture that variation.
Example:
...
office_space = osm.components.Space_type("office_space",project)
param = {
"input_variables": ["f = schedule.values"]
"people_density": "0.1*f",
"light_density": "10*f",
"other_gains_density": "4.2*f",
"other_gains_radiant_fraction": 0.6,
"infiltration": "0.5"
}
office_space.set_parameters(param)
Variables
After the simulation we will have the following variables of this component:
- people_convective [W/m²]: Convective heat due to occupancy.
- people_radiant [W/m²]: Radiant heat (long wave) due to occupancy.
- people_latent [W/m²]: Latent heat due to occupancy.
- light_convective [W/m²]: Convective heat due to lighting.
- light_radiant [W/m²]: Radiant heat (short wave) due to lighting.
- other_gains_convective [W/m²]: Convective heat due to other gains.
- other_gains_radiant [W/m²]: Radiant heat (long wave) due to other gains.
- other_gains_latent [W/m²]: Latent heat due to other gains.
- infiltration_rate [1/h]: Air flow rate infiltrated into the space from outside, expressed in volumes of the space per hour.
Space
Component used to define each of the building's spaces. The spaces of a building are each of the volumes of the building where we can find a different temperatures. The spaces will be referenced by the different surfaces that comprise them.
Parameters
- building [component, default = "not_defined", component type = Building]: Reference to the "Building" component of which it is a part.
- space_type [component, default = "not_defined", component type = Space_type]: Reference to the "Space_type" component that defines its occupational and functional characteristics.
- floor_area [float, unit = "m²", default = 1, min = 0]: Floor area of the space.
- volume [float, unit = "m³", default = 1, min = 0]: Volume of the space.
- furniture_weight [float, unit = "kg/m²", default = 10, min = 0]: Weight of the furniture in the space. Used to increase the thermal inertia of the space which will be added to that of the air (for the furniture a specific heat of 1000 J/kg·K will be used).
Example:
...
space_1 = osm.components.Space("space_1",project)
param = {
"building": "building",
"space_type": "office_space",
"floor_area": 30,
"volume": 90
}
space_1.set_parameters(param)
Variables
After the simulation we will have the following variables of this component:
- temperatura [°C]: Space dry air temperatura.
- abs_humidity [g/kg]: Absolute space air humidity.
- rel_humidity [%]: Relative space air humidity.
- people_convective [W]: Convective heat due to occupancy.
- people_radiant [W]: Radiant heat (long wave) due to occupancy.
- people_latent [W]: Latent heat due to occupancy.
- light_convective [W]: Convective heat due to lighting.
- light_radiant [W]: Radiant heat (short wave) due to lighting.
- other_gains_convective [W]: Convective heat due to other gains.
- other_gains_radiant [W]: Radiant heat (long wave) due to other gains.
- other_gains_latent [W]: Latent heat due to other gains.
- solar_direct_gains [W]: Direct solar radiation gains.
- infiltration_flow [m³/s]: Air flow rate infiltrated into the space from outside.
- infiltration_sensible_heat [W]: Sensible heat due to air infiltration from outdoor.
- surfaces_convective [W]: Convective heat flux exchanged between interior surfaces and space air.
- delta_int_energy [W]: Increase of internal energy of the space (air and furniture).
- u_system_sensible_heat [W]: Sensible heat introduced by uncontrolled systems in space. Spaces can collect airflows from various types of systems, those that are not capable of controlling the room temperature are called ‘uncontrolled systems’. For example, a flow of outside air, a flow from a dedicated outdoor air system, etc.
- u_system_sensible_latent [W]: Latent heat introduced by uncontrolled systems in space.
- system_sensible_heat [W]: Sensible heat introduced by the system responsible for space control. Positive for heating and negative for cooling.
- system_sensible_latent [W]: Latent heat introduced by control system in space. Positive for humidification and negative for dehumidification.
Exterior_surface
Component to define the exterior surfaces of the building: vertical or inclined walls and horizontal or inclined roofs.
Parameters
- shape [option, default = "RECTANGLE", options = ["RECTANGLE","POLYGON"]]: Shape of the surface, for a rectangle the parameters "width" and "height" will be used and for a polygon the parameters "x-polygon" and "y-polygon".
- width [float, unit = "m", default = 1, min = 0]: Width of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- height [float, unit = "m", default = 1, min = 0]: Height of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- ref_point [float-list, unit = "m", default = [0,0,0]]: Three-dimensional coordinate of the surface reference point. For rectangular surfaces the lower left corner of the surface viewed from the outside, for surfaces defined by polygons the three-dimensional location of the coordinate origin used to define the polygon in two dimensions.
- x_polygon [float-list, unit = "m", default = [0,10,10,0]]: List with the x-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- y_polygon [float-list, unit = "m", default = [0,0,10,10]]: List with the y-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- azimuth [float, unit = "°", default = 0, min = -180, max = 180]: Angle formed between the x-axis of the building and the projection of the x-axis of the surface.
- altitude [float, unit = "°", default = 0, min = -90, max = 90]: Angle formed between the z-axis of the building and the y-axis of the surface.
- construction [component, default = "not_defined", component type = Construction]: Reference to the "Construction" component that defines its composition.
- space [component, default = "not_defined", component type = Space]: Reference to the "Space" component to which it belongs.
- h_cv [float-list, unit = "W/m²K", default = [19.3,2], min = 0]: Convective film coefficients of the exterior and interior surfaces, respectively.
The following figures show the surface coordinate system versus the building coordinate system for rectangular or polygonal surfaces.
Example:
...
north_wall = osm.components.Exterior_surface("north_wall",project)
param = {
"ref_point": [8,0,-6],
"width": 8,
"height": 2.7,
"azimuth": 180,
"altitude": 0,
"construction": "Multilayer_wall",
"space": "space_1"
}
north_wall.set_parameters(param)
Variables
After the simulation we will have the following variables of this component, all variables ending in 0 refer to the outer surface and those ending in 1 to the inner surface:
- T_s0, T_s1 [°C]: Surface temperatures
- q_cd0, q_cd1 [W/m²]: Conductive heat flux at the surfaces.
- q_cv0, q_cv1 [W/m²]: Convective heat flux at the surfaces.
- q_sol0, q_sol1 [W/m²]: Solar heat flux at the surfaces.
- q_swig0, q_swig1 [W/m²]: Radiant short wave heat flux at the surfaces due to internal gains.
- q_lwig0, q_lwig1 [W/m²]: Radiant long wave heat flux at the surfaces due to internal gains.
- q_lwt0, q_lwt1 [W/m²]: Radiant long wave heat flux at the surfaces due other surfaces temperatures.
- p_0, p_1 [W/m²]: Conductive heat flux at the surfaces due to previous time steps.
- T_rm [°C]: Exterior radiant mean temperature.
- E_dir [W/m²]: Direct solar radiation incident on the exterior surface.
- E_dif [W/m²]: Diffuse solar radiation incident on the exterior surface.
Interior_surface
Component to define the interior surfaces of the building: vertical or inclined interior walls and slabs between floors.
Parameters
- shape [option, default = "RECTANGLE", options = ["RECTANGLE","POLYGON"]]: Shape of the surface, for a rectangle the parameters "width" and "height" will be used and for a polygon the parameters "x-polygon" and "y-polygon".
- width [float, unit = "m", default = 1, min = 0]: Width of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- height [float, unit = "m", default = 1, min = 0]: Height of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- ref_point [float-list, unit = "m", default = [0,0,0]]: Three-dimensional coordinate of the surface reference point. For rectangular surfaces the lower left corner of the surface viewed the "0" side, for surfaces defined by polygons the three-dimensional location of the coordinate origin used to define the polygon in two dimensions.
- x_polygon [float-list, unit = "m", default = [0,10,10,0]]: List with the x-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- y_polygon [float-list, unit = "m", default = [0,0,10,10]]: List with the y-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- azimuth [float, unit = "°", default = 0, min = -180, max = 180]: Angle formed between the x-axis of the building and the projection of the x-axis of the surface.
- altitude [float, unit = "°", default = 0, min = -90, max = 90]: Angle formed between the z-axis of the building and the y-axis of the surface.
- construction [component, default = "not_defined", component type = Construction]: Reference to the "Construction" component that defines its composition.
- spaces [component-list, default = ["not_defined","not_defined], component type = Space]: Reference to the "Space" components for the side 0 and the side 1.
- h_cv [float-list, unit = "W/m²K", default = [2,2], min = 0]: Convective film coefficients of the 0 an 1 side, respectively.
See figures of the coordinate systems in the "Exterior_surface" component.
Example:
...
interior_wall = osm.components.Interior_surface("interior_wall",project)
param = {
"ref_point": [8,0,-3],
"width": 8,
"height": 2.7,
"azimuth": 0,
"altitude": 0,
"construction": "Multilayer_wall",
"spaces": ["space_0", "space_1"]
}
interior_wall.set_parameters(param)
Variables
After the simulation we will have the following variables of this component, all variables ending in 0 refer "0" surface and those ending in 1 to the "1" surface:
- T_s0, T_s1 [°C]: Surface temperatures
- q_cd0, q_cd1 [W/m²]: Conductive heat flux at the surfaces.
- q_cv0, q_cv1 [W/m²]: Convective heat flux at the surfaces.
- q_sol0, q_sol1 [W/m²]: Solar heat flux at the surfaces.
- q_swig0, q_swig1 [W/m²]: Radiant short wave heat flux at the surfaces due to internal gains.
- q_lwig0, q_lwig1 [W/m²]: Radiant long wave heat flux at the surfaces due to internal gains.
- q_lwt0, q_lwt1 [W/m²]: Radiant long wave heat flux at the surfaces due other surfaces temperatures.
- p_0, p_1 [W/m²]: Conductive heat flux at the surfaces due to previous time steps.
Underground_surface
Component define the surfaces in contact with the ground. Floors or vertical undergorund enclosures.
Parameters
- shape [option, default = "RECTANGLE", options = ["RECTANGLE","POLYGON"]]: Shape of the surface, for a rectangle the parameters "width" and "height" will be used and for a polygon the parameters "x-polygon" and "y-polygon".
- width [float, unit = "m", default = 1, min = 0]: Width of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- height [float, unit = "m", default = 1, min = 0]: Height of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- ref_point [float-list, unit = "m", default = [0,0,0]]: Three-dimensional coordinate of the surface reference point. For rectangular surfaces the lower left corner of the surface viewed the "0" side, for surfaces defined by polygons the three-dimensional location of the coordinate origin used to define the polygon in two dimensions.
- x_polygon [float-list, unit = "m", default = [0,10,10,0]]: List with the x-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- y_polygon [float-list, unit = "m", default = [0,0,10,10]]: List with the y-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- azimuth [float, unit = "°", default = 0, min = -180, max = 180]: Angle formed between the x-axis of the building and the projection of the x-axis of the surface.
- altitude [float, unit = "°", default = 0, min = -90, max = 90]: Angle formed between the z-axis of the building and the y-axis of the surface.
- construction [component, default = "not_defined", component type = Construction]: Reference to the "Construction" component that defines its composition.
- space [component, default = "not_defined", component type = Space]: Reference to the "Space" component to which it belongs.
- h_cv [float, unit = "W/m²K", default = 2, min = 0]: Convective film coefficient of interior surface.
See figures of the coordinate systems in the "Exterior_surface" component.
Example:
...
floor = osm.components.Underground_surface("floor",project)
param = {
"shape": "POLYGON",
"ref_point": [0,0,0],
"x_polygon": [0,8,8,0],
"y_polygon": [0,0,6,6],
"azimuth": 0,
"altitude": -90,
"construction": "Multilayer wall",
"space": "space_1"
}
floor.set_parameters(param)
Variables
After the simulation we will have the following variables of this component, all variables ending in 0 refer to the underground surface and those ending in 1 to the interior surface:
- T_s0, T_s1 [°C]: Surface temperatures
- q_cd0, q_cd1 [W/m²]: Conductive heat flux at the surfaces.
- q_cv1 [W/m²]: Convective heat flux at the ineterior surface.
- q_sol1 [W/m²]: Solar heat flux at the surfaces.
- q_swig1 [W/m²]: Radiant short wave heat flux at the interior surface due to internal gains.
- q_lwig1 [W/m²]: Radiant long wave heat flux at the interior surface due to internal gains.
- q_lwt1 [W/m²]: Radiant long wave heat flux at the interior surface due other surfaces temperatures.
- p_0, p_1 [W/m²]: Conductive heat flux at the surfaces due to previous time steps.
Virtual_surface
Virtual surfaces are used to define gaps between two spaces. Spaces in OpenSimula must be completely enclosed by surfaces for the radiant exchange calculation to work correctly.
Parameters
- shape [option, default = "RECTANGLE", options = ["RECTANGLE","POLYGON"]]: Shape of the surface, for a rectangle the parameters "width" and "height" will be used and for a polygon the parameters "x-polygon" and "y-polygon".
- width [float, unit = "m", default = 1, min = 0]: Width of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- height [float, unit = "m", default = 1, min = 0]: Height of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- ref_point [float-list, unit = "m", default = [0,0,0]]: Three-dimensional coordinate of the surface reference point. For rectangular surfaces the lower left corner of the surface viewed from the outside, for surfaces defined by polygons the three-dimensional location of the coordinate origin used to define the polygon in two dimensions.
- x_polygon [float-list, unit = "m", default = [0,10,10,0]]: List with the x-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- y_polygon [float-list, unit = "m", default = [0,0,10,10]]: List with the y-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- azimuth [float, unit = "°", default = 0, min = -180, max = 180]: Angle formed between the x-axis of the building and the projection of the x-axis of the surface.
- altitude [float, unit = "°", default = 0, min = -90, max = 90]: Angle formed between the z-axis of the building and the y-axis of the surface.
- spaces [component-list, default = ["not_defined","not_defined], component type = Space]: Reference to the "Space" components for the side 0 and the side 1.
See figures of the coordinate systems in the "Exterior_surface" component.
Example:
...
interior_hole = osm.components.Virtual_surface("interior_hole",project)
param = {
"ref_point": [8,0,-3],
"width": 8,
"height": 2.7,
"azimuth": 0,
"altitude": 0,
"spaces": ["space_0","space_1"]
}
interior_hole.set_parameters(param)
Opening
Component for defining openings in exterior surfaces, e.g. windows or doors. These elements must be rectangular.
Parameters
- surface [component, default = "not_defined", component type = Exterior_surface]: Reference to the "Exterior_surface" in which it is located.
- width [float, unit = "m", default = 1, min = 0]: Width of the opening.
- height [float, unit = "m", default = 1, min = 0]: Height of the opening.
- ref_point [float-list, unit = "m", default = [0,0]]: Two-dimensional coordinate of the opening reference point in the exterior wall coordinate system. The reference point is the lower left corner of the opening viewed from the outside.
- opening_type [component, default = "not_defined", component type = Opening_type]: Reference to the "Opening_type" component that defines its composition.
- h_cv [float-list, unit = "W/m²K", default = [19.3,2], min = 0]: Convective film coefficients of the exterior and interior surfaces, respectively.
The following figure show geometrical definition of the opening in the surface coordinate system.
Example:
...
south_window = osm.components.Opening("south_window",project)
param = {
"surface": "south_wall"
"ref_point": [2,1],
"width": 3,
"height": 1.3,
"opening_type": "double_glazed_window"
}
south_window.set_parameters(param)
Variables
After the simulation we will have the following variables of this component, all variables ending in 0 refer to the outer surface and those ending in 1 to the inner surface:
- T_s0, T_s1 [°C]: Surface temperatures
- q_cd [W/m²]: Conductive heat flux.
- q_sol_dir_trans [W/m²]: Direct solar radiation passing through into space.
- q_cv0, q_cv1 [W/m²]: Convective heat flux at the surfaces.
- q_sol0, q_sol1 [W/m²]: Solar heat flux at the surfaces.
- q_sol01, q_sol10 [W/m²]: Solar heat flux appearing on surface "i" due to the absorption of solar radiation on surface "j".
- q_swig0, q_swig1 [W/m²]: Radiant short wave heat flux at the surfaces due to internal gains.
- q_lwig0, q_lwig1 [W/m²]: Radiant long wave heat flux at the surfaces due to internal gains.
- q_lwt0, q_lwt1 [W/m²]: Radiant long wave heat flux at the surfaces due other surfaces temperatures.
- T_rm [°C]: Exterior radiant mean temperature.
- E_dir [W/m²]: Direct solar radiation incident on the exterior surface.
- E_dif [W/m²]: Diffuse solar radiation incident on the exterior surface.
Shadow_surface
Component for defining shading surfaces external to the building.
Parameters
- building [component, default = "not_defined", component type = Building]: Reference to the "Building" component of which it is a part.
- shape [option, default = "RECTANGLE", options = ["RECTANGLE","POLYGON"]]: Shape of the surface, for a rectangle the parameters "width" and "height" will be used and for a polygon the parameters "x-polygon" and "y-polygon".
- width [float, unit = "m", default = 1, min = 0]: Width of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- height [float, unit = "m", default = 1, min = 0]: Height of the rectangular surface. Only used if "shape" is equal to "RECTANGLE".
- ref_point [float-list, unit = "m", default = [0,0,0]]: Three-dimensional coordinate of the surface reference point. For rectangular surfaces the lower left corner of the surface viewed from the outside, for surfaces defined by polygons the three-dimensional location of the coordinate origin used to define the polygon in two dimensions.
- x_polygon [float-list, unit = "m", default = [0,10,10,0]]: List with the x-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- y_polygon [float-list, unit = "m", default = [0,0,10,10]]: List with the y-coordinates of the points defining the surface polygon. Only used if "shape" is equal to "POLYGON".
- azimuth [float, unit = "°", default = 0, min = -180, max = 180]: Angle formed between the x-axis of the building and the projection of the x-axis of the surface.
- altitude [float, unit = "°", default = 0, min = -90, max = 90]: Angle formed between the z-axis of the building and the y-axis of the surface.
Example:
...
overhang = osm.components.Shadow_surface("overhang")
param = {
"building": "Building",
"ref_point": [0,-1,2.7],
"width": 8,
"height": 1,
"azimuth": 0,
"altitude": 90
},
overhang.set_parameters(param)
