# coding=utf-8
"""Window frame materials.
The materials here can only be applied as frames to window constructions.
"""
from __future__ import division
import xml.etree.ElementTree as ET
from ladybug.datatype.distance import Distance
from ladybug.datatype.rvalue import RValue
from honeybee._lockable import lockable
from honeybee.typing import float_in_range, float_in_range_excl_incl, float_positive, \
clean_and_id_string, clean_xml_tag_string
from ._base import _EnergyMaterialBase
from ..properties.extension import EnergyWindowFrameProperties
from ..reader import parse_idf_string
from ..writer import generate_idf_string
[docs]
@lockable
class EnergyWindowFrame(_EnergyMaterialBase):
"""A window frame assigned to a Window Construction.
Args:
identifier: Text string for a unique Material ID. Must be < 100 characters
and not contain any EnergyPlus special characters. This will be used to
identify the object across a model and in the exported IDF.
width: Number for the width of frame in plane of window [m]. The frame
width is assumed to be the same on all sides of window.
conductance: Number for the thermal conductance of the frame material measured
from inside to outside of the frame surface (no air films) and taking 2D
conduction effects into account [W/m2-K]. Values for typical frame
materials are as follows.
* Aluminum with Thermal Break - 5.68 W/m2-K
* Aluminum One-Sided (Flush) - 3.97 W/m2-K
* Wood - 3.5 W/m2-K
* Vinyl - 2.3 W/m2-K
edge_to_center_ratio: Number between 0 and 4 for the ratio of the glass
conductance near the frame (excluding air films) divided by the glass
conductance at the center of the glazing (excluding air films).
This is used only for multi-pane glazing constructions. This ratio should
usually be greater than 1.0 since the spacer material that separates
the glass panes is usually more conductive than the gap between panes.
A value of 1 effectively indicates no spacer. Values should usually be
obtained from the LBNL WINDOW program so that the unique characteristics
of the window construction can be accounted for. (Default: 1).
outside_projection: Number for the distance that the frame projects outward
from the outside face of the glazing [m]. This is used to calculate shadowing
of frame onto glass, solar absorbed by the frame, IR emitted and
absorbed by the frame, and convection from frame. (Default: 0).
inside_projection: Number for the distance that the frame projects inward
from the inside face of the glazing [m]. This is used to calculate solar
absorbed by the frame, IR emitted and absorbed by the frame, and
convection from frame. (Default: 0).
thermal_absorptance: A number between 0 and 1 for the fraction of incident long
wavelength radiation that is absorbed by the material. (Default: 0.9).
solar_absorptance: A number between 0 and 1 for the fraction of incident
solar radiation absorbed by the material. (Default: 0.7).
visible_absorptance: A number between 0 and 1 for the fraction of incident
visible wavelength radiation absorbed by the material.
Default is None, which will yield the same value as solar_absorptance.
Properties:
* identifier
* display_name
* width
* conductance
* edge_to_center_ratio
* outside_projection
* inside_projection
* thermal_absorptance
* solar_absorptance
* visible_absorptance
* solar_reflectance
* visible_reflectance
* u_value
* r_value
* user_data
* properties
"""
__slots__ = ('_identifier', '_display_name', '_width', '_conductance',
'_edge_to_center_ratio', '_outside_projection', '_inside_projection',
'_thermal_absorptance', '_solar_absorptance', '_visible_absorptance')
def __init__(self, identifier, width, conductance, edge_to_center_ratio=1,
outside_projection=0, inside_projection=0, thermal_absorptance=0.9,
solar_absorptance=0.7, visible_absorptance=None):
"""Initialize energy material."""
_EnergyMaterialBase.__init__(self, identifier)
self.width = width
self.conductance = conductance
self.edge_to_center_ratio = edge_to_center_ratio
self.outside_projection = outside_projection
self.inside_projection = inside_projection
self.thermal_absorptance = thermal_absorptance
self.solar_absorptance = solar_absorptance
self.visible_absorptance = visible_absorptance
self._locked = False
self._properties = EnergyWindowFrameProperties(self)
@property
def width(self):
"""Get or set the width of frame in plane of window [m]."""
return self._width
@width.setter
def width(self, value):
self._width = float_in_range_excl_incl(value, 0.0, 1.0, 'window frame width')
@property
def conductance(self):
"""Get or set the conductance of the frame material [W/m2-K]."""
return self._conductance
@conductance.setter
def conductance(self, cond):
self._conductance = float_positive(cond, 'window frame conductance')
@property
def edge_to_center_ratio(self):
"""Get or set the ratio between the edge and center glass conductances."""
return self._edge_to_center_ratio
@edge_to_center_ratio.setter
def edge_to_center_ratio(self, value):
self._edge_to_center_ratio = float_in_range_excl_incl(
value, 0.0, 4.0, 'window frame edge-to-center ratio')
@property
def outside_projection(self):
"""Get or set the distance the frame projects from the outside [m]."""
return self._outside_projection
@outside_projection.setter
def outside_projection(self, value):
self._outside_projection = float_in_range(
value, 0.0, 0.5, 'window frame outside projection')
@property
def inside_projection(self):
"""Get or set the distance the frame projects from the inside [m]."""
return self._inside_projection
@inside_projection.setter
def inside_projection(self, value):
self._inside_projection = float_in_range(
value, 0.0, 0.5, 'window frame inside projection')
@property
def thermal_absorptance(self):
"""Get or set the thermal absorptance of the frame material."""
return self._thermal_absorptance
@thermal_absorptance.setter
def thermal_absorptance(self, t_abs):
self._thermal_absorptance = float_in_range(
t_abs, 0.0, 1.0, 'window frame thermal absorptance')
@property
def solar_absorptance(self):
"""Get or set the solar absorptance of the frame material."""
return self._solar_absorptance
@solar_absorptance.setter
def solar_absorptance(self, s_abs):
self._solar_absorptance = float_in_range(
s_abs, 0.0, 1.0, 'window frame solar absorptance')
@property
def visible_absorptance(self):
"""Get or set the visible absorptance of the frame material."""
return self._visible_absorptance if self._visible_absorptance is not None \
else self._solar_absorptance
@visible_absorptance.setter
def visible_absorptance(self, v_abs):
self._visible_absorptance = float_in_range(
v_abs, 0.0, 1.0, 'window frame visible absorptance') if v_abs is not None \
else None
@property
def solar_reflectance(self):
"""Get or set the front solar reflectance of the frame material."""
return 1 - self.solar_absorptance
@solar_reflectance.setter
def solar_reflectance(self, v_ref):
v_ref = float_in_range(v_ref, 0.0, 1.0, 'window frame solar reflectance')
self.solar_absorptance = 1 - v_ref
@property
def visible_reflectance(self):
"""Get or set the front visible reflectance of the frame material."""
return 1 - self.visible_absorptance
@visible_reflectance.setter
def visible_reflectance(self, v_ref):
v_ref = float_in_range(v_ref, 0.0, 1.0, 'window frame visible reflectance')
self.visible_absorptance = 1 - v_ref
@property
def r_value(self):
"""Get or set the R-value of the frame material in [m2-K/W] (excluding films).
"""
return 1 / self.conductance
@r_value.setter
def r_value(self, r_val):
_new_conductance = 1 / float_positive(r_val, 'window frame r-value')
self._conductance = _new_conductance
@property
def u_value(self):
"""Get or set the U-value of the frame material [W/m2-K] (excluding films).
"""
return self.conductance
@u_value.setter
def u_value(self, u_val):
self.conductance = u_val
[docs]
@classmethod
def from_idf(cls, idf_string):
"""Create an EnergyWindowFrame from an EnergyPlus text string.
Args:
idf_string: A text string fully describing an EnergyPlus material.
"""
ep_strs = parse_idf_string(idf_string, 'WindowProperty:FrameAndDivider,')
idf_defaults = ('unnamed', 0, 0, 0, 0, 1, 0.7, 0.7, 0.9)
for i, d_val in enumerate(idf_defaults): # fill in any default values
try:
if ep_strs[i] == '':
ep_strs[i] = d_val
except IndexError:
ep_strs.append(d_val)
if float(ep_strs[1]) == 0 or float(ep_strs[4]) == 0:
return None # no frame definition within WindowProperty:FrameAndDivider
return cls(
ep_strs[0], ep_strs[1], ep_strs[4], ep_strs[5], ep_strs[2], ep_strs[3],
ep_strs[6], ep_strs[7], ep_strs[8])
[docs]
@classmethod
def from_gbxml(cls, gbxml_str):
"""Create an EnergyWindowFrame from an gbXML string.
Args:
gbxml_element: A Frame string from a gbXML file.
.. code-block:: xml
<Frame id="Wood_Frame_050_032" type="Wood">
<Name>Pine Wooden Frame</Name>
<Width unit="Meters">0.1</Thickness>
<R-value unit="SquareMeterKPerW">3.2</R-value>
<Absorptance unit="Fraction" type="ExtIR">0.9</Absorptance>
</Frame>
"""
gbxml_element = ET.fromstring(gbxml_str)
return cls.from_gbxml_element(gbxml_element)
[docs]
@classmethod
def from_gbxml_element(cls, gbxml_element):
"""Create an EnergyWindowFrame from an gbXML Element.
Args:
gbxml_element: A Frame Element from a gbXML file.
"""
# get all required properties and make the object
mat_id = gbxml_element.get('id')
mat_id = clean_and_id_string('Frame') if mat_id is None else mat_id.replace('_', ' ')
# get the width
width = 0.1
xml_width = gbxml_element.find('Width')
if xml_width is not None:
width, w_unit = float(xml_width.text), xml_width.get('unit')
if w_unit != 'Meters':
assert w_unit == 'Feet', \
'Thickness unit "{}" is not supported'.format(w_unit)
width = round(Distance().to_si([width], 'ft')[0][0], 4)
# try to derive the conductance from the frame type
r_value = None
frame_type = gbxml_element.get('type')
if frame_type == 'Wood':
r_value = 3.5
elif frame_type == 'Vinyl':
r_value = 2.3
elif frame_type in ('Aluminum', 'AluminumWithBreak'):
r_value = 5.6
# see if the object is using IESVE's convention instead of gbXML schema
if r_value is None:
xml_r_value = gbxml_element.find('R-value')
if xml_r_value is not None:
r_value, r_unit = float(xml_r_value.text), xml_r_value.get('unit')
if r_unit != 'SquareMeterKPerW':
assert r_unit == 'HrSquareFtFPerBTU', \
'R-value unit "{}" is not supported'.format(r_unit)
r_value = round(RValue().to_si([r_value], 'F-ft2-h/Btu')[0][0], 4)
if r_value is None: # just assume that it is aluminum to import it
r_value = 5.6
new_obj = cls(mat_id, width, r_value)
# add optional properties if they are found
name = gbxml_element.find('Name')
if name is not None:
new_obj.display_name = name.text
return new_obj
[docs]
@classmethod
def from_dict(cls, data):
"""Create a EnergyWindowFrame from a dictionary.
Args:
data: A python dictionary in the following format
.. code-block:: python
{
"type": 'EnergyWindowFrame',
"identifier": 'Wood_Frame_050_032',
"display_name": 'Pine Wooden Frame',
"width": 0.05,
"conductance": 3.2,
"edge_to_center_ratio": 2.6,
"outside_projection": 0.05,
"inside_projection": 0.1,
"thermal_absorptance": 0.9,
"solar_absorptance": 0.7,
"visible_absorptance": 0.7
}
"""
assert data['type'] == 'EnergyWindowFrame', \
'Expected EnergyWindowFrame. Got {}.'.format(data['type'])
ratio = data['edge_to_center_ratio'] if 'edge_to_center_ratio' in data and \
data['edge_to_center_ratio'] is not None else 1
out_pro = data['outside_projection'] if 'outside_projection' in data and \
data['outside_projection'] is not None else 0
in_pro = data['inside_projection'] if 'inside_projection' in data and \
data['inside_projection'] is not None else 0
t_abs = data['thermal_absorptance'] if 'thermal_absorptance' in data and \
data['thermal_absorptance'] is not None else 0.9
s_abs = data['solar_absorptance'] if 'solar_absorptance' in data and \
data['solar_absorptance'] is not None else 0.7
v_abs = data['visible_absorptance'] if 'visible_absorptance' in data else None
new_mat = cls(data['identifier'], data['width'], data['conductance'],
ratio, out_pro, in_pro, t_abs, s_abs, v_abs)
if 'display_name' in data and data['display_name'] is not None:
new_mat.display_name = data['display_name']
if 'user_data' in data and data['user_data'] is not None:
new_mat.user_data = data['user_data']
if 'properties' in data and data['properties'] is not None:
new_mat._properties._load_extension_attr_from_dict(data['properties'])
return new_mat
[docs]
def to_idf(self):
"""Get an EnergyPlus string representation of the window frame.
.. code-block:: shell
WindowProperty:FrameAndDivider,
TestFrameAndDivider, ! Frame/Divider Name
0.05, ! Frame Width
0.04, ! Frame Outside Projection
0.03, ! Frame Inside Projection
5.0, ! Frame Conductance
1.3, ! Ratio of Frame-Edge Glass Conductance to Center-Of-Glass Conductance
0.8, ! Frame Solar Absorptance
0.8, ! Frame Visible Absorptance
"""
values = (
self.identifier, self.width, self.outside_projection, self.inside_projection,
self.conductance, self.edge_to_center_ratio, self.solar_absorptance,
self.visible_absorptance, self.thermal_absorptance)
comments = (
'name', 'width {m}', 'outside projection {m}', 'inside projection {m}',
'conductance {W/m2-K}', 'edge-to-center-of-glass conductance ratio',
'solar absorptance', 'visible absorptance', 'thermal absorptance')
return generate_idf_string('WindowProperty:FrameAndDivider', values, comments)
[docs]
def to_gbxml_element(self, ip_units=False, parent_element=None):
"""Get a gbXML Frame Element representation of this object.
Args:
ip_units: A boolean to note whether the R-value should be reported
in IP units (True) or SI units (False). (Default: False).
parent_element: An optional XML Element for the gbXML root to which the
material element will be added. If None, a new XML Element
will be generated. (Default: None).
"""
# create the Material element
mat_id = clean_xml_tag_string(self.identifier)
if parent_element is not None:
xml_mat = ET.SubElement(parent_element, 'Frame', id=mat_id)
else:
xml_mat = ET.Element('Frame', id=mat_id)
# set the width
if ip_units:
width_units = 'Feet'
width = round(Distance().to_ip([self.width], 'm')[0][0], 4)
else:
width_units = 'Meters'
width = round(self.width, 4)
xml_width = ET.SubElement(xml_mat, 'Width', unit=width_units)
xml_width.text = str(width)
# derive the frame type from conductance
if self.conductance <= 3:
frame_type = 'Vinyl'
elif self.conductance >= 5:
frame_type = 'AluminumWithBreak'
else:
frame_type = 'Wood'
xml_mat.set('type', frame_type)
# add the name
xml_name = ET.SubElement(xml_mat, 'Name')
xml_name.text = str(self.display_name)
return xml_mat
[docs]
def to_gbxml(self, ip_units=False):
"""Generate an gbXML string representation of this object.
Args:
ip_units: A boolean to note whether the U-value should be reported
in IP units (True) or SI units (False). (Default: False).
"""
xml_root = self.to_gbxml_element(ip_units)
try: # try to indent the XML to make it read-able
ET.indent(xml_root)
return ET.tostring(xml_root, encoding='unicode')
except AttributeError: # we are in Python 2 and no indent is available
return ET.tostring(xml_root)
[docs]
def to_dict(self):
"""EnergyWindowFrame dictionary representation."""
base = {
'type': 'EnergyWindowFrame',
'identifier': self.identifier,
'width': self.width,
'conductance': self.conductance,
'edge_to_center_ratio': self.edge_to_center_ratio,
'outside_projection': self.outside_projection,
'inside_projection': self.inside_projection,
'thermal_absorptance': self.thermal_absorptance,
'solar_absorptance': self.solar_absorptance,
'visible_absorptance': self.visible_absorptance
}
if self._display_name is not None:
base['display_name'] = self.display_name
if self._user_data is not None:
base['user_data'] = self.user_data
prop_dict = self._properties.to_dict()
if prop_dict is not None:
base['properties'] = prop_dict
return base
def __key(self):
"""A tuple based on the object properties, useful for hashing."""
return (
self.identifier, self.width, self.conductance, self.edge_to_center_ratio,
self.outside_projection, self.inside_projection,
self.thermal_absorptance, self.solar_absorptance, self.visible_absorptance)
def __hash__(self):
return hash(self.__key())
def __eq__(self, other):
return isinstance(other, EnergyWindowFrame) and self.__key() == other.__key()
def __ne__(self, other):
return not self.__eq__(other)
def __repr__(self):
return self.to_idf()
def __copy__(self):
new_material = self.__class__(
self.identifier, self.width, self.conductance, self.edge_to_center_ratio,
self.outside_projection, self.inside_projection, self.thermal_absorptance,
self.solar_absorptance, self._visible_absorptance)
new_material._display_name = self._display_name
new_material._user_data = None if self._user_data is None \
else self._user_data.copy()
new_material._properties._duplicate_extension_attr(self._properties)
return new_material