honeybee-radiance 1.66.190__py3-none-any.whl

honeybee_radiance/lightsource/sky/skydome.py

@@ -0,0 +1,113 @@
+"""Virtual skydome for daylight coefficient studies with constant radiance."""
+
+from ._skybase import _SkyDome
+import honeybee.typing as typing
+
+
+class SkyDome(_SkyDome):
+    """Virtual skydome for daylight coefficient studies with constant radiance.
+
+    Use this sky to calculate daylight matrix.
+
+    .. code-block:: shell
+
+        #@rfluxmtx h=u u=Y
+        void glow ground_glow
+        0
+        0
+        4 0.2 0.2 0.2 0
+
+        ground_glow source ground
+        0
+        0
+        4 0 0 -1 180
+
+        #@rfluxmtx h=r1 u=Y
+        void glow sky_glow
+        0
+        0
+        4 1 1 1 0
+
+        sky_glow source sky
+        0
+        0
+        4 0 0 1 180
+
+    Args:
+        density: Sky patch subdivision density. This values is similar to -m option
+            in gendaymtx command. Default is 1 which means 145 sky patches and 1
+            patch for the ground.
+
+            One can add to the resolution typically by factors of two (2, 4, 8, ...)
+            which yields a higher resolution sky using the Reinhart patch subdivision
+            For example, setting density to 4 yields a sky with 2305 patches plus one
+            patch for the ground.
+        ground_emittance: Ground emittance value between 0.0 and 1.0 - Default: 0.2
+    """
+    __slots__ = ('_sky_density', '_ground_emittance')
+
+    def __init__(self, sky_density=1, ground_emittance=0.2):
+        _SkyDome.__init__(self, modifier='void')
+        self.sky_density = sky_density
+        self.ground_hemisphere.r_emittance = ground_emittance
+        self.ground_hemisphere.g_emittance = ground_emittance
+        self.ground_hemisphere.b_emittance = ground_emittance
+
+    @property
+    def sky_density(self):
+        """Set and get sky subdivision density."""
+        return self._sky_density
+
+    @sky_density.setter
+    def sky_density(self, v):
+        density = typing.int_in_range(v, 1, input_name='Sky subdivision density')
+        self._sky_density = density
+
+    def to_radiance(self):
+        """Radiance definition for SkyDome."""
+
+        return '#@rfluxmtx h=u u=Y\n%s\n\n#@rfluxmtx h=r%d u=Y\n%s\n' % (
+            self.ground_hemisphere, self.sky_density, self.sky_hemisphere
+        )
+
+
+class UniformSky(_SkyDome):
+    """Uniform sky is similar to a SkyDome but with no rfluxmtx header.
+
+    .. code-block:: shell
+
+        void glow sky_glow
+        0
+        0
+        4 1 1 1 0
+
+        sky_glow source sky
+        0
+        0
+        4 0 0 1 180
+
+        void glow ground_glow
+        0
+        0
+        4 0.2 0.2 0.2 0
+
+        ground_glow source ground
+        0
+        0
+        4 0 0 -1 180
+
+    Args:
+        ground_emittance: Ground emittance value between 0.0 and 1.0 - Default: 0.2
+
+    """
+    __slots__ = ('_ground_emittance',)
+
+    def __init__(self, ground_emittance=0.2):
+        _SkyDome.__init__(self, modifier='void')
+        self.ground_hemisphere.r_emittance = ground_emittance
+        self.ground_hemisphere.g_emittance = ground_emittance
+        self.ground_hemisphere.b_emittance = ground_emittance
+
+    def to_radiance(self):
+        """Radiance definition for uniform sky."""
+        return '%s\n\n%s\n' % (self.sky_hemisphere, self.ground_hemisphere)

honeybee_radiance/lightsource/sky/skymatrix.py

@@ -0,0 +1,163 @@
+"""Generate a point-in-time climate-based sky."""
+from __future__ import division
+
+from .sunmatrix import SunMatrix
+import honeybee.typing as typing
+from ladybug.wea import Wea
+
+
+class SkyMatrix(SunMatrix):
+    """Annual Climate-based Sky matrix.
+
+    The output of SkyMatrix is similar to using command Radiance's gendaymtx command with
+    default options. For more information see gendaymtx documentation.
+
+    https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf
+
+    Args:
+        wea: A Ladybug wea object.
+        north: A number between -360 and 360 for the counterclockwise difference between
+            the North and the positive Y-axis in degrees. 90 is West and 270 is East
+            (Default: 0)
+        density: Sky patch subdivision density. This values is similar to -m option
+            in gendaymtx command. Default is 1 which means 145 sky patches and 1
+            patch for the ground.
+
+            One can add to the resolution typically by factors of two (2, 4, 8, ...)
+            which yields a higher resolution sky using the Reinhart patch subdivision
+            For example, setting density to 4 yields a sky with 2305 patches plus one
+            patch for the ground.
+
+    Properties:
+        * wea
+        * location
+        * north
+        * is_point_in_time
+        * is_climate_based
+    """
+
+    __slots__ = ('_density',)
+
+    def __init__(self, wea, north=0, density=1):
+        """Create a climate-based sky matrix."""
+        SunMatrix.__init__(self, wea, north)
+        self.density = density
+
+    @property
+    def density(self):
+        """Set and get sky patch subdivision density.
+
+        This values is similar to -m option in gendaymtx command. Default is 1 which
+        means 145 sky patches and 1 patch for the ground.
+
+        One can add to the resolution typically by factors of two (2, 4, 8, ...) which
+        yields a higher resolution sky using the Reinhart patch subdivision. For example,
+        setting density to 4 yields a sky with 2305 patches plus one patch for the
+        ground.
+        """
+        return self._density
+
+    @density.setter
+    def density(self, value):
+        typing.int_in_range(value, 1, input_name='SkyMatrix subdivision density')
+        self._density = value
+
+    @classmethod
+    def from_dict(cls, input_dict):
+        """Create the sky from a dictionary.
+
+        Args:
+            input_dict: A python dictionary in the following format
+
+        .. code-block:: python
+
+                {
+                'type': 'SkyMatrix',
+                'wea': {},
+                'north': 0.0  # optional
+                'density': 1  # optional
+                }
+        """
+        if 'type' not in input_dict or input_dict['type'] != 'SkyMatrix':
+            raise ValueError('Input dict "type" must be "SkyMatrix".')
+        if 'north' in input_dict:
+            north = input_dict['north']
+        else:
+            north = 0
+        if 'density' in input_dict:
+            density = input_dict['density']
+        else:
+            density = 1
+
+        sky = cls(Wea.from_dict(input_dict['wea']), north, density)
+
+        return sky
+
+    # TODO: add support for additional parameters
+    # TODO: add gendaymtx to radiance-command and use it for validating inputs
+    def to_radiance(
+            self, output_type=0, wea_file=None, output_name=None, cumulative=False,
+            components=0):
+        """Return Radiance command to generate the sky.
+
+        Note that you need to write the wea to a file (in.wea) before running this
+        command.
+
+        Alternatively you can use write method which will write the wea data to a file.
+
+        Args:
+            output_type: An integer between 0 to 1 for output type.
+                * 0 = output in W/m2/sr visible (default)
+                * 1 = output in W/m2/sr solar
+            wea_file: Path to wea file (default: in.wea).
+            output_name: A name for output files (default: sky_mtx).
+            cumulative: A boolean to generate cumulative sky. This option is only
+                available in Radiance 5.3 and higher versions (default: False).
+            components: An integer between 0-2 to note the distribution of which
+                components should be included. 0 might be used to include both sun and
+                sky contribution. 1 may be used to produce a sun-only matrix, with no sky
+                contributions.  Alternatively, 2 may be used to exclude any sun component
+                from the output.  If there is a sun in the description, gendaymtx will
+                include its contribution in the four nearest sky patches, distributing
+                energy according to centroid proximity (default: 0).
+        """
+        output_type = typing.int_in_range(output_type, 0, 1, 'SkyMatrix output type')
+        wea_file = wea_file or 'in.wea'
+        output_name = output_name or 'sky'
+
+        options = ['-O{}'.format(output_type)]
+        if self.density != 1:
+            options.append('-m %d' % self.density)
+        if self.north != 0:
+            options.append('-r {}'.format(self.north))
+        if cumulative:
+            options.append('-A')
+        if components == 1:
+            # sun-only
+            options.append('-d')
+        elif components == 2:
+            # sky only
+            options.append('-s')
+        options.append(wea_file)
+        # add all the other options here
+        command = 'gendaymtx {0} > {1}.mtx'.format(' '.join(options), output_name)
+
+        return command
+
+    def to_dict(self):
+        """Translate this matrix to a dictionary."""
+
+        return {
+            'type': 'SkyMatrix',
+            'wea': self.wea.to_dict(),
+            'north': self.north,
+            'density': self.density
+        }
+
+    def __eq__(self, value):
+        if type(value) != type(self) \
+            or value.wea != self.wea \
+            or value.north != self.north \
+                or value.density != self.density:
+            return False
+        return True

honeybee_radiance/lightsource/sky/strutil.py

@@ -0,0 +1,34 @@
+# coding=utf-8
+"""Utilities to convert sky strings to Python objects."""
+from honeybee_radiance.lightsource.sky.certainirradiance import CertainIrradiance
+from honeybee_radiance.lightsource.sky.cie import CIE
+from honeybee_radiance.lightsource.sky.climatebased import ClimateBased
+
+SKY_TYPES = {
+    'irradiance': CertainIrradiance,
+    'illuminance': CertainIrradiance,
+    'cie': CIE,
+    'climate-based': ClimateBased
+}
+
+
+def string_to_sky(sky_string, raise_exception=True):
+    """Get a Python object of any sky from a string representation.
+
+    Args:
+        sky_string: A text string representing a CIE, ClimateBased, or CertainIrradiance
+            sky. This can be a minimal representation of the sky (eg.
+            "cie -alt 71.6 -az 185.2 -type 0"). Or it can be a detailed specification of
+            time and location (eg. "cie 21 Jun 12:00 -lat 41.78 -lon -87.75 -type 0").
+        raise_exception: Boolean to note whether an exception should be raised
+            if the object is not identified as a sky. Default: True.
+
+    Returns:
+        A Python object derived from the input sky_string.
+    """
+    sky_type = sky_string.lower().split(' ')[0].strip()
+    try:
+        return SKY_TYPES[sky_type].from_string(sky_string)
+    except KeyError:
+        if raise_exception:
+            raise ValueError('{} is not a recognized radiance Sky type'.format(sky_type))

honeybee_radiance/lightsource/sky/sunmatrix.py

@@ -0,0 +1,212 @@
+"""Generate a point-in-time climate-based sky."""
+from __future__ import division
+import honeybee.typing as typing
+import ladybug.futil as futil
+from ladybug.wea import Wea
+from ladybug_geometry.geometry2d.pointvector import Vector2D
+
+import os
+import math
+
+
+class SunMatrix(object):
+    """Annual Climate-based Sun matrix.
+
+    The output of SkyMatrix is similar to using command Radiance's gendaymtx command with
+    ``-n -D`` options. The options are available in Radiance 5.3 and after that. For more
+    information see gendaymtx documentation.
+
+    https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/gendaymtx.pdf
+
+    Args:
+        wea: A Ladybug wea object.
+        north: A number between -360 and 360 for the counterclockwise difference between
+            the North and the positive Y-axis in degrees. 90 is West and 270 is East
+            (Default: 0)
+
+    Properties:
+        * wea
+        * location
+        * north
+        * is_point_in_time
+        * is_climate_based
+    """
+
+    __slots__ = ('_wea', '_north')
+
+    def __init__(self, wea, north=0):
+        """Create a climate-based sun matrix."""
+        self.wea = wea
+        self.north = north
+
+    @property
+    def wea(self):
+        """Get and set wea."""
+        return self._wea
+
+    @wea.setter
+    def wea(self, value):
+        assert isinstance(value, Wea), \
+            'wea must be from type Wea not {}'.format(type(value))
+        self._wea = value
+
+    @property
+    def north(self):
+        """Get and set north direction.
+
+        A number between -360 and 360 for the counterclockwise difference between
+        the North and the positive Y-axis in degrees. 90 is West and 270 is East.
+        """
+        return self._north
+
+    @north.setter
+    def north(self, value):
+        value = typing.float_in_range(value, -360, +360, 'Skymatrix north')
+        self._north = value
+
+    @property
+    def is_climate_based(self):
+        """Return True if the sky is created based on values from weather data."""
+        return True
+
+    @property
+    def is_point_in_time(self):
+        """Return True if the sky is generated for a single point in time."""
+        return False
+
+    @property
+    def location(self):
+        """Location information for sky matrix."""
+        return self.wea.location
+
+    def north_from_vector(self, north_vector):
+        """Automatically set the north property using a Vector2D.
+
+        Args:
+            north_vector: A ladybug_geometry Vector2D for the north direction
+        """
+        self._north = math.degrees(north_vector.angle_clockwise(Vector2D(0, 1)))
+
+    @classmethod
+    def from_dict(cls, input_dict):
+        """Create the sky from a dictionary.
+
+        Args:
+            input_dict: A python dictionary in the following format
+
+        .. code-block:: python
+
+            {
+                'type': 'SunMatrix',
+                'wea': {},
+                'north': 0.0  # optional
+            }
+        """
+        if 'type' not in input_dict or input_dict['type'] != 'SunMatrix':
+            raise ValueError('Input dict "type" must be "SunMatrix".')
+        if 'north' in input_dict:
+            sky = cls(Wea.from_dict(input_dict['wea']), input_dict['north'])
+        else:
+            sky = cls(input_dict['wea'])
+
+        return sky
+
+    # TODO: add support for additional parameters
+    # TODO: add gendaymtx to radiance-command and use it for validating inputs
+    def to_radiance(self, output_type=1, wea_file=None, output_name=None):
+        """Return Radiance command to generate the sky.
+
+        Note that you need to write the wea to a file (in.wea) before running this
+        command.
+
+        Alternatively you can use write method which will write the wea data to a file.
+
+        Args:
+            output_type: An integer between 0 to 1 for output type.
+                * 0 = output in W/m2/sr visible
+                * 1 = output in W/m2/sr solar (default)
+            wea_file: Path to wea file (default: in.wea).
+            output_name: A name for output files (default: suns).
+        """
+        output_type = typing.int_in_range(output_type, 0, 1, 'SunMatrix output type')
+        wea_file = wea_file or 'in.wea'
+        output_name = output_name or 'suns'
+        if self.north == 0:
+            command = 'gendaymtx -n -D {0}.mtx -M {0}.mod -O{1} {2}'.format(
+                output_name, output_type, wea_file
+            )
+        else:
+            command = 'gendaymtx -n -D {0}.mtx -M {0}.mod -O{1} -r {3} {2}'.format(
+                output_name, output_type, wea_file, self.north
+            )
+
+        return command
+
+    def to_dict(self):
+        """Translate this matrix to a dictionary."""
+
+        return {
+            'type': 'SunMatrix',
+            'wea': self.wea.to_dict(),
+            'north': self.north
+        }
+
+    def write_wea(self, folder='.', name=None, hoys=None):
+        """Write wea to a file.
+
+        Args:
+            folder: Path to target folder (Default: '.').
+            name: Optional name for the wea file (Default: in.wea)
+            hoys: Optional list of hoys to filter the hours of the wea. If None,
+                this object's wea will be used as-is. Note that you may not want
+                to use this input if this object's wea is not annual since an
+                exception will be raised if a given hoy is not found in the
+                wea. (Default: None).
+
+        Returns:
+            Path to wea file.
+        """
+        name = name or 'in.wea'
+        file_path = os.path.join(folder, name)
+        wea_obj = self.wea if hoys is None else self.wea.filter_by_hoys(hoys)
+        return wea_obj.write(file_path=file_path)
+
+    def to_file(self, folder, name=None, hoys=None, mkdir=False):
+        """Write matrix to a Radiance file.
+
+        This method also writes the wea information to a .wea file.
+
+        Args:
+            folder: Target folder.
+            name: File name.
+            hoys: Optional list of hoys to filter the hours of the wea. If None,
+                this object's wea will be used as-is. Note that you may not want
+                to use this input if this object's wea is not annual since an
+                exception will be raised if a given hoy is not found in the
+                wea. (Default: None).
+            mkdir: A boolean to note if the directory should be created if doesn't
+                exist (default: False).
+
+        Returns:
+            Full path to the newly created file.
+        """
+        name = typing.valid_string(name) if name \
+            else '%s.rad' % self.__class__.__name__.lower()
+        # write wea file first
+        wea_file = self.write_wea(folder, hoys=hoys)
+        content = self.to_radiance(wea_file=os.path.split(wea_file)[-1])
+        return futil.write_to_file_by_name(folder, name, '!' + content, mkdir)
+
+    def __eq__(self, value):
+        if not isinstance(value, self.__class__) \
+            or value.wea != self.wea \
+                or value.north != self.north:
+            return False
+        return True
+
+    def __ne__(self, value):
+        return not self.__eq__(value)
+
+    def __repr__(self):
+        """Matrix representation."""
+        return '%s: %s' % (self.__class__.__name__, self.wea.location.city)