+[docs]
+defoccupancy_schedule_8_to_6(
+ timestep:int=1,as_list:bool=False)->Union[np.ndarray,list]:
+"""Create an occupancy schedule for LEED (8 am to 6 pm).
+
+ Args:
+ timestep: An integer value noting the number of timesteps per hour.
+ Defaults to 1.
+ as_list: Boolean toggle to output the schedule as a Python list instead
+ of a NumPy array. Defaults to False.
+
+ Returns:
+ A schedule as an array or list.
+ """
+ full_analysis_period=AnalysisPeriod(timestep=timestep)
+ analysis_period=AnalysisPeriod(st_hour=8,end_hour=17,timestep=timestep)
+ schedule=np.zeros(8760*timestep).astype(int)
+ hours=np.where(np.isin(full_analysis_period.hoys,analysis_period.hoys))[0]
+ schedule[hours]=1
+ ifas_list:
+ schedule=schedule.tolist()
+
+ returnschedule
+
+
+
+
+[docs]
+defschedule_to_hoys(
+ schedule:Union[list,np.ndarray],
+ sun_up_hours:Union[list,np.ndarray]=None,as_list:bool=False
+ )->Union[np.ndarray,list]:
+"""Convert a schedule to hoys.
+
+ Args:
+ schedule: A list of 8760 values for the occupancy schedule.
+ sun_up_hours: An optional list of sun up hours as integers. If sun up
+ hours are provided the function will exclude all values from the
+ schedule that are not among the sun up hours. Defaults to None.
+ as_list: Boolean toggle to output the schedule as a Python list instead
+ of a NumPy array. Defaults to False.
+
+ Returns:
+ An array or list of occupancy expressed as hoys.
+ """
+ assertlen(schedule)==8760
+ ifnotisinstance(schedule,np.ndarray):
+ schedule=np.array(schedule).astype(int)
+
+ hours=np.arange(0,8760,1)
+ ifsun_up_hours:
+ sun_up_hours=np.array(sun_up_hours).astype(int)
+ mask=np.ones(schedule.size,dtype=bool)
+ mask[sun_up_hours]=False
+ schedule[mask]=0
+
+ occ_hoys=filter_array(hours,np.array(schedule))
+
+ ifas_list:
+ occ_hoys=occ_hoys.tolist()
+
+ returnocc_hoys
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/annualdaylight.html b/docs/_modules/honeybee_radiance_postprocess/annualdaylight.html
new file mode 100644
index 00000000..251897a3
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/annualdaylight.html
@@ -0,0 +1,989 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.annualdaylight — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Source code for honeybee_radiance_postprocess.annualdaylight
+"""Functions for post-processing annual daylight outputs.
+
+Note: These functions will most likely be moved to a separate package in the near future.
+"""
+importjson
+importos
+importnumpyasnp
+
+fromladybug.colorimportColorset
+fromladybug.datatype.fractionimportFraction
+fromladybug.legendimportLegendParameters
+fromhoneybee_radiance.postprocess.annualimportfilter_schedule_by_hours, \
+ _process_input_folder
+
+from.metricsimportda_array2d,cda_array2d,udi_array2d, \
+ udi_lower_array2d,udi_upper_array2d
+from.utilimportfilter_array
+
+
+
+[docs]
+defmetrics_to_files(ill_file,occ_pattern,output_folder,threshold=300,
+ min_t=100,max_t=3000,grid_name=None,total_hours=None,
+ sun_down_occ_hours=0):
+"""Compute annual metrics for an ill file and write the results to a folder.
+
+ This function generates 5 different files or daylight autonomy, continuous daylight
+ autonomy, lower than useful daylight illuminance, useful daylight illuminance and
+ higher than useful daylight illuminance.
+
+ Args:
+ ill_file: Path to an ill file generated by Radiance. The ill file should be
+ tab separated and shot NOT have a header. The results for each sensor point
+ should be available in a row and and each column should be the illuminance
+ value for a sun_up_hour. The number of columns should match the number of
+ sun up hours.
+ occ_pattern: A list of 0 and 1 values for hours of occupancy.
+ output_folder: An output folder where the results will be written to. The folder
+ will be created if not exist.
+ threshold: Threshold illuminance level for daylight autonomy. Default: 300.
+ min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+ max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+ grid_name: An optional name for grid name which will be used to name the output
+ files. If None the name of the input file will be used.
+ total_hours: An integer for the total number of occupied hours in the
+ occupancy schedule. If None, it will be assumed that all of the
+ occupied hours are sun-up hours and are already accounted for
+ in the the occ_pattern.
+
+ Returns:
+ Tuple(file.da, file.cda, file.udi, file.udi, file.udi)
+
+ """
+ ifnotos.path.isdir(output_folder):
+ os.makedirs(output_folder)
+
+ grid_name=grid_nameoros.path.split(ill_file)[-1][-4:]
+ da=os.path.join(output_folder,'da','%s.da'%grid_name).replace('\\','/')
+ cda=os.path.join(output_folder,'cda','%s.cda'%grid_name).replace('\\','/')
+ udi=os.path.join(output_folder,'udi','%s.udi'%grid_name).replace('\\','/')
+ udi_lower= \
+ os.path.join(output_folder,'udi_lower','%s.udi'%grid_name).replace('\\','/')
+ udi_upper= \
+ os.path.join(output_folder,'udi_upper','%s.udi'%grid_name).replace('\\','/')
+
+ forfile_pathin[da,cda,udi,udi_upper,udi_lower]:
+ folder=os.path.dirname(file_path)
+ ifnotos.path.isdir(folder):
+ os.makedirs(folder)
+
+ mask=np.array(occ_pattern)
+ results=np.load(ill_file)
+ results_occ=np.apply_along_axis(filter_array,1,results,mask=mask)
+
+ dar=da_array2d(results_occ,total_occ=total_hours,threshold=threshold)
+ np.savetxt(da,dar,fmt='%.2f')
+
+ cdar=cda_array2d(results_occ,total_occ=total_hours,threshold=threshold)
+ np.savetxt(cda,cdar,fmt='%.2f')
+
+ udir=udi_array2d(results_occ,total_occ=total_hours,min_t=min_t,max_t=max_t)
+ np.savetxt(udi,udir,fmt='%.2f')
+
+ udi_lowerr=udi_lower_array2d(results_occ,total_occ=total_hours,min_t=min_t,
+ sun_down_occ_hours=sun_down_occ_hours)
+ np.savetxt(udi_lower,udi_lowerr,fmt='%.2f')
+
+ udi_upperr=udi_upper_array2d(results_occ,total_occ=total_hours,max_t=max_t)
+ np.savetxt(udi_upper,udi_upperr,fmt='%.2f')
+
+ returnda,cda,udi_lower,udi,udi_upper
+
+
+
+# TODO - support a list of schedules/schedule folder to match the input grids
+
+[docs]
+defmetrics_to_folder(
+ results_folder,schedule=None,threshold=300,min_t=100,max_t=3000,
+ grids_filter='*',sub_folder='metrics'
+ ):
+"""Compute annual metrics in a folder and write them in a subfolder.
+
+ This folder is an output folder of annual daylight recipe. Folder should include
+ grids_info.json and sun-up-hours.txt - the script uses the list in grids_info.json
+ to find the result files for each sensor grid.
+
+ Args:
+ results_folder: Results folder.
+ schedule: An annual schedule for 8760 hours of the year as a list of values.
+ threshold: Threshold illuminance level for daylight autonomy. Default: 300.
+ min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+ max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+ grids_filter: A pattern to filter the grids. By default all the grids will be
+ processed.
+ sub_folder: An optional relative path for subfolder to copy results files.
+ Default: metrics
+
+ Returns:
+ str -- Path to results folder.
+
+ """
+ grids,sun_up_hours=_process_input_folder(results_folder,grids_filter)
+ occ_pattern,total_occ,sun_down_occ_hours= \
+ filter_schedule_by_hours(sun_up_hours=sun_up_hours,schedule=schedule)
+
+ metrics_folder=os.path.join(results_folder,sub_folder)
+ ifnotos.path.isdir(metrics_folder):
+ os.makedirs(metrics_folder)
+
+ forgridingrids:
+ ill_file=os.path.join(results_folder,'%s.npy'%grid['full_id'])
+ metrics_to_files(
+ ill_file,occ_pattern,metrics_folder,threshold,min_t,
+ max_t,grid['full_id'],total_occ,sun_down_occ_hours
+ )
+
+ # copy info.json to all results folders
+ forfolder_namein['da','cda','udi_lower','udi','udi_upper']:
+ grid_info=os.path.join(metrics_folder,folder_name,'grids_info.json')
+ withopen(grid_info,'w')asoutf:
+ json.dump(grids,outf)
+
+ metric_info_dict=_annual_daylight_vis_metadata()
+ formetric,datainmetric_info_dict.items():
+ file_path=os.path.join(metrics_folder,metric,'vis_metadata.json')
+ withopen(file_path,'w')asfp:
+ json.dump(data,fp,indent=4)
+
+ returnmetrics_folder
Source code for honeybee_radiance_postprocess.cli.grid
+"""honeybee radiance postprocess grid commands."""
+importclick
+importsys
+importlogging
+importjson
+importnumpyasnp
+frompathlibimportPath
+
+fromhoneybee_radiance_postprocess.readerimportbinary_to_array
+from..annualdaylightimport_annual_daylight_vis_metadata
+
+_logger=logging.getLogger(__name__)
+
+
+@click.group(help='Commands for generating and modifying sensor grids.')
+defgrid():
+ pass
+
+
+@grid.command('merge-folder')
+@click.argument(
+ 'input-folder',
+ type=click.Path(exists=True,file_okay=False,dir_okay=True,resolve_path=True))
+@click.argument(
+ 'output-folder',
+ type=click.Path(file_okay=False,dir_okay=True,resolve_path=True))
+@click.argument('extension',type=str)
+@click.option(
+ '--dist-info','-di',
+ help='An optional input for distribution information to put the grids back together '
+ '. Alternatively, the command will look for a _redist_info.json file inside the '
+ 'folder.',type=click.Path(file_okay=True,dir_okay=False,resolve_path=True)
+)
+@click.option(
+ '--output-extension','-oe',
+ help='Output file extension. This is only used if as_text is set to True. '
+ 'Otherwise the output extension will be npy.',default='ill',type=click.STRING
+)
+@click.option(
+ '--as-text','-at',
+ help='Set to True if the output files should be saved as text instead of '
+ 'NumPy files.',default=False,type=click.BOOL
+)
+@click.option(
+ '--fmt',
+ help='Format for the output files when saved as text.',default='%.2f',
+ type=click.STRING
+)
+@click.option(
+ '--delimiter',
+ help='Delimiter for the output files when saved as text.',
+ type=click.Choice(['space','tab']),default='tab'
+)
+defmerge_grid_folder(input_folder,output_folder,extension,dist_info,
+ output_extension,as_text,fmt,delimiter):
+"""Restructure files in a distributed folder.
+
+ \b
+ Args:
+ input_folder: Path to input folder.
+ output_folder: Path to the new restructured folder
+ extension: Extension of the files to collect data from. It will be ``pts`` for
+ sensor files. Another common extension is ``ill`` for the results of daylight
+ studies.
+ """
+ try:
+ # handle optional case for Functions input
+ ifdist_infoandnotPath(dist_info).is_file():
+ dist_info=None
+ restore_original_distribution(
+ input_folder,output_folder,extension,dist_info,output_extension,
+ as_text,fmt,delimiter)
+ exceptException:
+ _logger.exception('Failed to restructure data from folder.')
+ sys.exit(1)
+ else:
+ sys.exit(0)
+
+
+@grid.command('merge-folder-metrics')
+@click.argument(
+ 'input-folder',
+ type=click.Path(exists=True,file_okay=False,dir_okay=True,resolve_path=True))
+@click.argument(
+ 'output-folder',
+ type=click.Path(file_okay=False,dir_okay=True,resolve_path=True))
+@click.option(
+ '--dist-info','-di',
+ help='An optional input for distribution information to put the grids back together '
+ '. Alternatively, the command will look for a _redist_info.json file inside the '
+ 'folder.',type=click.Path(file_okay=True,dir_okay=False,resolve_path=True)
+)
+@click.option(
+ '--grids-info','-gi',
+ help='An optional input for grid information that will be copied to each '
+ 'metric folder. This file is usually called grids_info.json.',
+ type=click.Path(file_okay=True,dir_okay=False,resolve_path=True)
+)
+defmerge_metrics_folder(input_folder,output_folder,dist_info,grids_info):
+"""Restructure annual daylight metrics in a distributed folder.
+
+ Since this command redistributes metrics it is expected that the input
+ folder has sub folder
+
+ \b
+ Args:
+ input_folder: Path to input folder.
+ output_folder: Path to the new restructured folder
+ """
+ try:
+ # handle optional case for Functions input
+ ifdist_infoandnotPath(dist_info).is_file():
+ dist_info=None
+ ifgrids_info:
+ withopen(grids_info)asgi:
+ grids_info=json.load(gi)
+ extension_mapper={
+ 'da':'da',
+ 'cda':'cda',
+ 'udi':'udi',
+ 'udi_lower':'udi',
+ 'udi_upper':'udi'
+ }
+ metric_info_dict=_annual_daylight_vis_metadata()
+ input_folder=Path(input_folder)
+ output_folder=Path(output_folder)
+ formetric,extensioninextension_mapper.items():
+ metric_folder=input_folder.joinpath(metric)
+ metric_out=output_folder.joinpath(metric)
+ restore_original_distribution_metrics(
+ metric_folder,output_folder,metric,extension,dist_info)
+
+ ifgrids_info:
+ info_file=metric_out.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+ vis_data=metric_info_dict[metric]
+ vis_metadata_file=metric_out.joinpath('vis_metadata.json')
+ vis_metadata_file.write_text(json.dumps(vis_data,indent=4))
+ exceptException:
+ _logger.exception('Failed to restructure data from folder.')
+ sys.exit(1)
+ else:
+ sys.exit(0)
+
+
+
+[docs]
+defrestore_original_distribution(
+ input_folder,output_folder,extension='npy',dist_info=None,
+ output_extension='ill',as_text=False,fmt='%.2f',input_delimiter=',',
+ delimiter='tab'):
+"""Restructure files to the original distribution based on the distribution info.
+
+ It will assume that the files in the input folder are NumPy files. However,
+ if it fails to load the files as arrays it will try to load from binary
+ Radiance files to array.
+
+ Args:
+ input_folder: Path to input folder.
+ output_folder: Path to the new restructured folder
+ extension: Extension of the files to collect data from. Default is ``npy`` for
+ NumPy files. Another common extension is ``ill`` for the results of daylight
+ studies.
+ dist_info: Path to dist_info.json file. If None, the function will try to load
+ ``_redist_info.json`` file from inside the input_folder. (Default: None).
+ output_extension: Output file extension. This is only used if as_text
+ is set to True. Otherwise the output extension will be ```npy``.
+ as_text: Set to True if the output files should be saved as text instead
+ of NumPy files.
+ fmt: Format for the output files when saved as text.
+ input_delimiter: Delimiter for the input files. This is used only if the
+ input files are text files.
+ delimiter: Delimiter for the output files when saved as text.
+ """
+ ifnotdist_info:
+ _redist_info_file=Path(input_folder,'_redist_info.json')
+ else:
+ _redist_info_file=Path(dist_info)
+
+ assert_redist_info_file.is_file(),'Failed to find %s'%_redist_info_file
+
+ withopen(_redist_info_file)asinf:
+ data=json.load(inf)
+
+ # create output folder
+ output_folder=Path(output_folder)
+ ifnotoutput_folder.is_dir():
+ output_folder.mkdir(parents=True,exist_ok=True)
+
+ src_file=Path()
+ forfindata:
+ output_file=Path(output_folder,f['identifier'])
+ # ensure the new folder is created. in case the identifier has a subfolder
+ parent_folder=output_file.parent
+ ifnotparent_folder.is_dir():
+ parent_folder.mkdir()
+
+ out_arrays=[]
+ forsrc_infoinf['dist_info']:
+ st=src_info['st_ln']
+ end=src_info['end_ln']
+ new_file=Path(input_folder,'%s.%s'%(src_info['identifier'],extension))
+ ifnotnew_file.samefile(src_file):
+ src_file=new_file
+ try:
+ array=np.load(src_file)
+ except:
+ try:
+ array=binary_to_array(src_file)
+ except:
+ try:
+ array=np.loadtxt(
+ src_file,delimiter=input_delimiter)
+ exceptException:
+ raiseRuntimeError(
+ f'Failed to load input file "{src_file}"')
+ slice_array=array[st:end+1,:]
+
+ out_arrays.append(slice_array)
+
+ out_array=np.concatenate(out_arrays)
+ # save numpy array, .npy extension is added automatically
+ ifnotas_text:
+ np.save(output_file,out_array)
+ else:
+ ifoutput_extension.startswith('.'):
+ output_extension=output_extension[1:]
+ ifdelimiter=='tab':
+ delimiter='\t'
+ elifdelimiter=='space':
+ delimiter=' '
+ elifdelimiter=='comma':
+ delimiter=','
+ np.savetxt(output_file.with_suffix(f'.{output_extension}'),
+ out_array,fmt=fmt,delimiter=delimiter)
+
+
+
+
+[docs]
+defrestore_original_distribution_metrics(
+ input_folder,output_folder,metric,extension,dist_info=None):
+"""Restructure files to the original distribution based on the distribution info.
+
+ It will assume that the files in the input folder are NumPy files. However,
+ if it fails to load the files as arrays it will try to load from binary
+ Radiance files to array.
+
+ Args:
+ input_folder: Path to input folder.
+ output_folder: Path to the new restructured folder
+ metric: Name of the metric to redistribute.
+ extension: Extension of the files to collect data from. For annual
+ daylight metrics the extension can be 'da', 'cda', or 'udi'.
+ dist_info: Path to dist_info.json file. If None, the function will try to load
+ ``_redist_info.json`` file from inside the input_folder. (Default: None).
+ """
+ ifnotdist_info:
+ _redist_info_file=Path(input_folder,'_redist_info.json')
+ else:
+ _redist_info_file=Path(dist_info)
+
+ assert_redist_info_file.is_file(),'Failed to find %s'%_redist_info_file
+
+ withopen(_redist_info_file)asinf:
+ data=json.load(inf)
+
+ # create output folder
+ output_folder=Path(output_folder)
+ ifnotoutput_folder.is_dir():
+ output_folder.mkdir()
+
+ src_file=Path()
+ forfindata:
+ output_file=Path(output_folder,metric,'%s.%s'%(f['identifier'],extension))
+ # ensure the new folder is created. in case the identifier has a subfolder
+ parent_folder=output_file.parent
+ ifnotparent_folder.is_dir():
+ parent_folder.mkdir()
+
+ out_arrays=[]
+ forsrc_infoinf['dist_info']:
+ st=src_info['st_ln']
+ end=src_info['end_ln']
+ new_file=Path(input_folder,'%s.%s'%(src_info['identifier'],extension))
+ ifnotnew_file.samefile(src_file):
+ src_file=new_file
+ array=np.loadtxt(src_file)
+ slice_array=array[st:end+1]
+ out_arrays.append(slice_array)
+
+ out_array=np.concatenate(out_arrays)
+ # save array as txt file
+ np.savetxt(output_file,out_array,fmt='%.2f')
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/cli/util.html b/docs/_modules/honeybee_radiance_postprocess/cli/util.html
new file mode 100644
index 00000000..c531c6cd
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/cli/util.html
@@ -0,0 +1,832 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.cli.util — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+defsmallest_float_dtype(array:np.ndarray,rtol:float=1e-5,
+ atol:float=1e-5)->np.floating:
+"""Return the smallest possible float dtype.
+
+ The allclose function is used to check if a certain floating-point precision
+ can be used without losing accuracy.
+
+ Args:
+ array: NumPy array.
+ rtol: The relative tolerance parameter for `np.allclose`. The default
+ is 1e-5.
+ atol: The absolute tolerance parameter for `np.allclose`. The default
+ is 1e-5.
+
+ Returns:
+ A NumPy floating dtype.
+ """
+ ifnp.all((array>=np.finfo(np.float16).min)& \
+ (array<=np.finfo(np.float16).max)):
+ ifnp.allclose(array,array.astype(np.float16),rtol=rtol,atol=atol):
+ returnnp.float16
+ ifnp.all((array>=np.finfo(np.float32).min)& \
+ (array<=np.finfo(np.float32).max)):
+ ifnp.allclose(array,array.astype(np.float32),rtol=rtol,atol=atol):
+ returnnp.float32
+ ifnp.all((array>=np.finfo(np.float64).min)& \
+ (array<=np.finfo(np.float64).max)):
+ ifnp.allclose(array,array.astype(np.float64),rtol=rtol,atol=atol):
+ returnnp.float64
+
+
+
+
+[docs]
+defsmallest_dtype(array:np.ndarray,rtol:float=1e-5,atol:float=1e-5
+ )->Tuple[np.signedinteger,np.floating]:
+"""Return the smallest possible dtype.
+
+ Args:
+ array: NumPy array.
+ rtol: The relative tolerance parameter for `np.allclose`. The default
+ is 1e-5. This is also used if the dtype of the array is np.floating.
+ atol: The absolute tolerance parameter for `np.allclose`. The default
+ is 1e-5. This is also used if the dtype of the array is np.floating.
+
+ Returns:
+ A NumPy dtype.
+ """
+ ifnp.issubdtype(array.dtype,np.integer):
+ returnsmallest_integer_dtype(array)
+ elifnp.issubdtype(array.dtype,np.floating):
+ returnsmallest_float_dtype(array,rtol=rtol,atol=atol)
+ else:
+ raiseTypeError(f'Expected integer or floating dtype. Got {array.dtype}')
+
+
+
+
+[docs]
+defset_smallest_dtype(array:np.ndarray,rtol:float=1e-5,
+ atol:float=1e-5)->np.ndarray:
+"""Return a NumPy array with the smallest possible dtype.
+
+ Args:
+ array: NumPy array.
+ rtol: The relative tolerance parameter for `np.allclose`. The default
+ is 1e-5. This is also used if the dtype of the array is np.floating.
+ atol: The absolute tolerance parameter for `np.allclose`. The default
+ is 1e-5. This is also used if the dtype of the array is np.floating.
+
+ Returns:
+ A new NumPy array with a smaller dtype.
+ """
+ dtype=smallest_dtype(array,rtol=rtol,atol=atol)
+ returnarray.astype(dtype)
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/dynamic.html b/docs/_modules/honeybee_radiance_postprocess/dynamic.html
new file mode 100644
index 00000000..66c6dca8
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/dynamic.html
@@ -0,0 +1,1014 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.dynamic — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classApertureGroupSchedule(object):
+"""ApertureGroupSchedule.
+
+ This class contains the dynamic states schedule of a single ApertureGroup.
+
+ Args:
+ identifier: Identifier of the ApertureGroup.
+ schedule: A list or tuple of integer values.
+
+ Properties:
+ * identifier
+ * schedule
+ * is_static
+ """
+ __slots__=('_identifier','_schedule','_is_static')
+
+ def__init__(self,identifier,schedule,is_static=None):
+"""Initialize ApertureGroupSchedule."""
+ self._identifier=identifier
+ self.schedule=schedule
+ self.is_static=is_static
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Initialize a ApertureGroupSchedule from a dictionary.
+
+ Args:
+ data: A dictionary representation of an ApertureGroupSchedule
+ object.
+ """
+ identifier=data['identifier']
+ schedule=data['schedule']
+ is_static=data['is_static']if'is_static'indataelseNone
+ returncls(identifier,schedule,is_static)
+
+
+ @property
+ defidentifier(self):
+"""Return identifier."""
+ returnself._identifier
+
+ @property
+ defschedule(self):
+"""Return ApertureGroup schedule."""
+ returnself._schedule
+
+ @schedule.setter
+ defschedule(self,schedule):
+ assertisinstance(schedule,(list,tuple)), \
+ ('Failed to add schedule. Received input of type: '
+ '%s. Expected input of type: list or tuple.'%type(schedule))
+ ifisinstance(schedule,tuple):
+ schedule=list(schedule)
+ iflen(schedule)<8760:
+ schedule=list(islice(cycle(schedule),8760))
+ eliflen(schedule)>8760:
+ error_message=(
+ 'The light path %s has %s values in '
+ 'its states schedule. Maximum allowed number of values '
+ 'is 8760.'%(self.identifier,len(schedule))
+ )
+ raiseValueError(error_message)
+ self._schedule=schedule
+
+ @property
+ defis_static(self):
+"""Return True if schedule is static."""
+ returnself._is_static
+
+ @is_static.setter
+ defis_static(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,bool)
+ self._is_static=value
+ else:
+ iflen(set(self.schedule))==1:
+ self._is_static=True
+ else:
+ self._is_static=False
+
+
+[docs]
+ defto_dict(self):
+"""Return ApertureGroupSchedule as a dictionary."""
+ base={}
+ base['identifier']=self.identifier
+ base['schedule']=self.schedule
+ base['is_static']=self.is_static
+ returnbase
+[docs]
+classDynamicSchedule(object):
+"""DynamicSchedule.
+
+ This class contains a single property (dynamic_schedule). This property is
+ a dictionary where keys are ApertureGroup identifiers and the value for
+ each key is the dynamic schedule for the ApertureGroup.
+
+ Args:
+ dynamic_schedule: A dictionary of ApertureGroup identifier and
+ schedules.
+
+ Properties:
+ * dynamic_schedule
+ """
+ __slots__=('_dynamic_schedule',)
+
+ def__init__(self,dynamic_schedule=None):
+ self.dynamic_schedule=dynamic_schedule
+
+
+[docs]
+ @classmethod
+ deffrom_group_schedules(cls,group_schedules):
+"""Initialize a DynamicSchedule from a list of ApertureGroupSchedules.
+
+ The method will automatically sense if there are duplicated groups in
+ the list and ensure the group schedule only appears once.
+
+ Args:
+ data: A dictionary representation of a DynamicSchedule objects.
+ """
+ dyn_sch=cls()
+ dyn_sch_ids=set()
+ for_ap_groupingroup_schedules:
+ assertisinstance(_ap_group,ApertureGroupSchedule), \
+ 'Expected Aperture Group Schedule. Got {}'.format(type(_ap_group))
+ if_ap_group.identifiernotindyn_sch_ids:
+ dyn_sch_ids.add(_ap_group.identifier)
+ dyn_sch.add_aperture_group_schedule(_ap_group)
+ returndyn_sch
+
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Initialize a DynamicSchedule from a dictionary.
+
+ Args:
+ data: A dictionary representation of a DynamicSchedule objects.
+ """
+ dynamic_schedule={}
+ foridentifier,groupindata.items():
+ dynamic_schedule[identifier]=ApertureGroupSchedule.from_dict(group)
+ returncls(dynamic_schedule)
+
+
+
+[docs]
+ @classmethod
+ deffrom_json(cls,json_file):
+"""Initialize a DynamicSchedule from a JSON file.
+
+ Args:
+ json_file: Path to JSON file.
+ """
+ assertos.path.isfile(json_file),'Failed to find %s'%json_file
+ ifsys.version_info<(3,0):
+ withopen(json_file)asinf:
+ data=json.load(inf)
+ else:
+ withopen(json_file,encoding='utf-8')asinf:
+ data=json.load(inf)
+ returncls.from_dict(data)
+[docs]
+ defto_json(self,folder=None,file_name=None,indent=None,simplified=False):
+"""Write a DynamicSchedule to JSON.
+
+ Args:
+ folder: A text string for the directory where the JSON file will be
+ written. If unspecified, the default simulation folder will be
+ used. This is usually at "C:\\Users\\USERNAME\\simulation."
+ file_name: _description_. Defaults to None.
+ indent: A positive integer to set the indentation used in the
+ resulting JSON file. (Default: None).
+
+ Returns:
+ json_file: Path to JSON file.
+ """
+ # create dictionary of the DynamicSchedule
+ dyn_sch_dict=self.to_dict(simplified=simplified)
+
+ # set up name and folder for the JSON
+ file_name=file_nameiffile_nameelse'dynamic_schedule'
+ ifnotfile_name.endswith('.json'):
+ file_name+='.json'
+ folder=folderiffolderisnotNoneelsefolders.default_simulation_folder
+ json_file=os.path.join(folder,file_name)
+
+ # write JSON
+ withopen(json_file,'w')asfp:
+ json.dump(dyn_sch_dict,fp,indent=indent)
+ returnjson_file
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+[docs]
+defen17037_to_files(
+ array:np.ndarray,metrics_folder:Path,grid_info:dict)->list:
+"""Compute annual EN 17037 metrics for a NumPy array and write the results
+ to a folder.
+
+ This function generates 6 different files for daylight autonomy based on
+ the varying level of recommendation in EN 17037.
+
+ Args:
+ array: A 2D NumPy array.
+ metrics_folder: An output folder where the results will be written to.
+ The folder will be created if it does not exist.
+ grid_info: A grid information dictionary.
+
+ Returns:
+ tuple -- Tuple of lists of paths for da, sda, and compliance folders.
+ """
+ recommendations={
+ 'minimum_illuminance':{
+ 'minimum':100,
+ 'medium':300,
+ 'high':500
+ },
+ 'target_illuminance':{
+ 'minimum':300,
+ 'medium':500,
+ 'high':750
+ }
+ }
+ compliance_value={
+ 'minimum':1,
+ 'medium':2,
+ 'high':3
+ }
+
+ grid_id=grid_info['full_id']
+ grid_count=grid_info['count']
+
+ da_folders=[]
+ sda_folders=[]
+ compliance_folders=[]
+ da_folder=metrics_folder.joinpath('da')
+ sda_folder=metrics_folder.joinpath('sda')
+ compliance_folder=metrics_folder.joinpath('compliance_level')
+
+ fortarget_type,thresholdsinrecommendations.items():
+ compliance_level=None
+ forlevel,thresholdinthresholds.items():
+ # da
+ da_level_folder= \
+ da_folder.joinpath('_'.join([target_type,str(threshold)]))
+ da_file=da_level_folder.joinpath(f'{grid_id}.da')
+ ifnotda_file.parent.is_dir():
+ da_file.parent.mkdir(parents=True)
+ da=da_array2d(array,total_occ=4380,threshold=threshold)
+ np.savetxt(da_file,da,fmt='%.2f')
+
+ # sda
+ sda_level_folder= \
+ sda_folder.joinpath('_'.join([target_type,str(threshold)]))
+ sda_file=sda_level_folder.joinpath(f'{grid_id}.sda')
+ ifnotsda_file.parent.is_dir():
+ sda_file.parent.mkdir(parents=True)
+ sda=(da>=50).mean()*100
+ withopen(sda_file,'w')assdaf:
+ sdaf.write(str(round(sda,2)))
+
+ space_target=50iftarget_type=='target_illuminance'else95
+ ifsda>=space_target:
+ compliance_level=np.full((grid_count),compliance_value[level],dtype=int)
+
+ da_folders.append(da_file.parent)
+ sda_folders.append(sda_file.parent)
+
+ ifcompliance_levelisNone:
+ compliance_level=np.zeros(grid_count,dtype=int)
+ compliance_level_folder=compliance_folder.joinpath(target_type)
+ compliance_level_file=compliance_level_folder.joinpath(f'{grid_id}.pf')
+ ifnotcompliance_level_file.parent.is_dir():
+ compliance_level_file.parent.mkdir(parents=True)
+ np.savetxt(compliance_level_file,compliance_level,fmt='%i')
+ compliance_folders.append(compliance_level_file.parent)
+
+ returnda_folders,sda_folders,compliance_folders
+
+
+
+
+[docs]
+defen17037_to_folder(
+ results:Union[str,AnnualDaylight],schedule:list,
+ states:DynamicSchedule=None,grids_filter:str='*',
+ sub_folder:str='en17037')->Path:
+"""Compute annual EN 17037 metrics in a folder and write them in a subfolder.
+
+ The results is an output folder of annual daylight recipe.
+
+ Args:
+ results: Results folder.
+ schedule: An annual schedule for 8760 hours of the year as a list of
+ values. This should be a daylight hours schedule.
+ grids_filter: A pattern to filter the grids. By default all the grids
+ will be processed.
+ states: A dictionary of states. Defaults to None.
+ sub_folder: An optional relative path for subfolder to copy results
+ files. Default: en17037.
+
+ Returns:
+ str -- Path to results folder.
+ """
+ ifnotisinstance(results,AnnualDaylight):
+ results=AnnualDaylight(results,schedule=schedule)
+ else:
+ results.schedule=schedule
+
+ total_occ=results.total_occ
+ occ_mask=results.occ_mask
+
+ grids_info=results._filter_grids(grids_filter=grids_filter)
+
+ sub_folder=Path(sub_folder)
+
+ iftotal_occ!=4380:
+ raiseValueError(
+ f'There are {total_occ} occupied hours in the schedule. According '
+ 'to EN 17037 the schedule must consist of the daylight hours '
+ 'which is defined as the half of the year with the largest '
+ 'quantity of daylight')
+
+ forgrid_infoingrids_info:
+ array=results._array_from_states(
+ grid_info,states=states,res_type='total',zero_array=True)
+ ifnp.any(array):
+ array=np.apply_along_axis(
+ filter_array,1,array,occ_mask)
+ da_folders,sda_folders,compliance_folders=en17037_to_files(
+ array,sub_folder,grid_info)
+
+ # copy grids_info.json to all results folders
+ forfolderinda_folders+sda_folders+compliance_folders:
+ grids_info_file=Path(folder,'grids_info.json')
+ withopen(grids_info_file,'w')asoutf:
+ json.dump(grids_info,outf,indent=2)
+
+ metric_info_dict=_annual_daylight_en17037_vis_metadata()
+ da_folder=sub_folder.joinpath('da')
+ formetric,datainmetric_info_dict.items():
+ file_path=da_folder.joinpath(metric,'vis_metadata.json')
+ withopen(file_path,'w')asfp:
+ json.dump(data,fp,indent=4)
+
+ returnsub_folder
+[docs]
+defshade_transmittance_per_light_path(
+ light_paths:list,shade_transmittance:Union[float,dict],
+ shd_trans_dict:dict)->dict:
+"""Filter shade_transmittance by light paths and add default multiplier.
+
+ Args:
+ light_paths: A list of light paths.
+ shade_transmittance: A value to use as a multiplier in place of solar
+ shading. This input can be either a single value that will be used
+ for all aperture groups, or a dictionary where aperture groups are
+ keys, and the value for each key is the shade transmittance. Values
+ for shade transmittance must be 1 > value > 0.
+ shd_trans_dict: A dictionary used to store shade transmittance value
+ for each aperture group.
+
+ Returns:
+ A dictionary with filtered light paths.
+ """
+ shade_transmittances={}
+ ifisinstance(shade_transmittance,dict):
+ forlight_pathinlight_paths:
+ # default multiplier
+ shade_transmittances[light_path]=[1]
+ # add custom shade transmittance
+ iflight_pathinshade_transmittance:
+ shade_transmittances[light_path].append(
+ shade_transmittance[light_path])
+ shd_trans_dict[light_path]=shade_transmittance[light_path]
+ # add default shade transmittance (0.02)
+ eliflight_path!='__static_apertures__':
+ shade_transmittances[light_path].append(0.02)
+ shd_trans_dict[light_path]=0.02
+ else:
+ shade_transmittances[light_path].append(1)
+ shd_trans_dict[light_path]=1
+ else:
+ shd_trans=float(shade_transmittance)
+ forlight_pathinlight_paths:
+ # default multiplier
+ shade_transmittances[light_path]=[1]
+ # add custom shade transmittance
+ iflight_path!='__static_apertures__':
+ shade_transmittances[light_path].append(shd_trans)
+ shd_trans_dict[light_path]=shd_trans
+ else:
+ shade_transmittances[light_path].append(1)
+ shd_trans_dict[light_path]=1
+
+ returnshade_transmittances,shd_trans_dict
+
+
+
+
+[docs]
+defdynamic_schedule_direct_illuminance(
+ results:Union[str,AnnualDaylight],grids_filter:str='*',
+ shade_transmittance:Union[float,dict]=0.02,
+ use_states:bool=False
+ )->Tuple[dict,dict]:
+"""Calculate a schedule of each aperture group.
+
+ This function calculates an annual shading schedule of each aperture
+ group. Hour by hour it will select the least shaded aperture group
+ configuration, so that no more than 2% of the sensors points receive
+ direct illuminance of 1000 lux or more.
+
+ Args:
+ results: Path to results folder or a Results class object.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ shade_transmittance: A value to use as a multiplier in place of solar
+ shading. This input can be either a single value that will be used
+ for all aperture groups, or a dictionary where aperture groups are
+ keys, and the value for each key is the shade transmittance. Values
+ for shade transmittance must be 1 > value > 0.
+ Defaults to 0.02.
+ use_states: A boolean to note whether to use the simulated states. Set
+ to True to use the simulated states. The default is False which will
+ use the shade transmittance instead.
+
+ Returns:
+ Tuple: A tuple with a dictionary of the annual schedule and a
+ dictionary of hours where no shading configuration comply with the
+ 2% rule.
+ """
+ ifnotisinstance(results,AnnualDaylight):
+ results=AnnualDaylight(results)
+
+ grids_info=results._filter_grids(grids_filter=grids_filter)
+ schedule=occupancy_schedule_8_to_6(as_list=True)
+ occ_pattern= \
+ filter_schedule_by_hours(results.sun_up_hours,schedule=schedule)[0]
+ occ_mask=np.array(occ_pattern)
+
+ states_schedule=defaultdict(list)
+ fail_to_comply={}
+ shd_trans_dict={}
+
+ forgrid_infoingrids_info:
+ grid_states_schedule=defaultdict(list)
+
+ grid_count=grid_info['count']
+ light_paths=[]
+ forlpingrid_info['light_path']:
+ for_lpinlp:
+ if_lp=='__static_apertures__'andlen(lp)>1:
+ pass
+ else:
+ light_paths.append(_lp)
+
+ shade_transmittances,shd_trans_dict=(
+ shade_transmittance_per_light_path(
+ light_paths,shade_transmittance,shd_trans_dict
+ )
+ )
+
+ iflen(light_paths)>6:
+ ifuse_states:
+ grid_states_schedule,fail_to_comply=states_schedule_descending(
+ results,grid_info,light_paths,occ_mask,
+ grid_states_schedule,fail_to_comply)
+ else:
+ grid_states_schedule,fail_to_comply=shd_trans_schedule_descending(
+ results,grid_info,light_paths,shade_transmittances,occ_mask,
+ grid_states_schedule,fail_to_comply)
+ else:
+ ifuse_states:
+ combinations=results._get_state_combinations(grid_info)
+ else:
+ shade_transmittances,shd_trans_dict=shade_transmittance_per_light_path(
+ light_paths,shade_transmittance,shd_trans_dict)
+ keys,values=zip(*shade_transmittances.items())
+ combinations=[dict(zip(keys,v))forvinitertools.product(*values)]
+
+ array_list_combinations=[]
+ forcombinationincombinations:
+ combination_arrays=[]
+ forlight_path,valueincombination.items():
+ ifuse_states:
+ combination_arrays.append(
+ results._get_array(grid_info,light_path,state=value,
+ res_type='direct')
+ )
+ else:
+ array=results._get_array(
+ grid_info,light_path,res_type='direct')
+ ifvalue==1:
+ combination_arrays.append(array)
+ else:
+ combination_arrays.append(array*value)
+ combination_array=sum(combination_arrays)
+
+ combination_percentage= \
+ (combination_array>=1000).sum(axis=0)/grid_count
+ array_list_combinations.append(combination_percentage)
+ array_combinations=np.array(array_list_combinations)
+ array_combinations[array_combinations>0.02]=-np.inf
+
+ grid_comply=np.where(np.all(array_combinations==-np.inf,axis=0))[0]
+ ifgrid_comply.size!=0:
+ grid_comply=np.array(results.sun_up_hours)[grid_comply]
+ fail_to_comply[grid_info['name']]= \
+ [int(hoy)forhoyingrid_comply]
+
+ array_combinations_filter=np.apply_along_axis(
+ filter_array,1,array_combinations,occ_mask
+ )
+ max_indices=array_combinations_filter.argmax(axis=0)
+ # select the combination for each hour
+ combinations=[combinations[idx]foridxinmax_indices]
+
+ # merge the combinations of dicts
+ forcombinationincombinations:
+ forlight_path,valueincombination.items():
+ iflight_path!='__static_apertures__':
+ grid_states_schedule[light_path].append(value)
+
+ forkey,valueingrid_states_schedule.items():
+ ifkeynotinstates_schedule:
+ states_schedule[key]=value
+
+ occupancy_hoys=schedule_to_hoys(schedule,results.sun_up_hours)
+
+ # map states to 8760 values
+ ifuse_states:
+ aperture_group_schedules=[]
+ foridentifier,valuesinstates_schedule.items():
+ mapped_states=results.values_to_annual(
+ occupancy_hoys,values,results.timestep,dtype=np.int32)
+ aperture_group_schedules.append(
+ ApertureGroupSchedule(identifier,mapped_states.tolist())
+ )
+ states_schedule= \
+ DynamicSchedule.from_group_schedules(aperture_group_schedules)
+ else:
+ forlight_path,shd_transinstates_schedule.items():
+ mapped_states=results.values_to_annual(
+ occupancy_hoys,shd_trans,results.timestep)
+ states_schedule[light_path]=mapped_states
+
+ returnstates_schedule,fail_to_comply,shd_trans_dict
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/ies/lm_schedule.html b/docs/_modules/honeybee_radiance_postprocess/ies/lm_schedule.html
new file mode 100644
index 00000000..2c25ab60
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/ies/lm_schedule.html
@@ -0,0 +1,948 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.ies.lm_schedule — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+defshd_trans_schedule_descending(
+ results:AnnualDaylight,grid_info,light_paths,shade_transmittances,occ_mask,
+ states_schedule,fail_to_comply
+ )->Tuple[dict,dict]:
+ grid_count=grid_info['count']
+ full_direct=[]
+ full_thresh=[]
+ full_shd_trans_array=[]
+ forlight_pathinlight_paths:
+ array=results._get_array(grid_info,light_path,res_type="direct")
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+ full_direct.append(array)
+ full_thresh.append((array>=1000).sum(axis=0))
+ full_shd_trans_array.append(shade_transmittances[light_path][1])
+
+ # Sum the array element-wise.
+ # This array is the sum of all direct illuminance without shade
+ # transmittance.
+ full_direct_sum=sum(full_direct)
+
+ # Create base list of shading combinations (all set to 1).
+ # We will replace the 1s later.
+ combinations=[
+ {light_path:1forlight_pathinlight_paths}
+ foriinrange(full_direct_sum.shape[1])
+ ]
+
+ # Find the percentage of floor area >= 1000 lux.
+ # This array is the percentage for each hour (axis=0).
+ direct_pct_above=(full_direct_sum>=1000).sum(axis=0)/grid_count
+
+ # Find the indices where the percentage of floor area is > 2%.
+ # This array is the problematic hours.
+ above_2_indices=np.where(direct_pct_above>0.02)[0]
+
+ # Use the indices to get the relevant hours.
+ direct_sum=np.take(full_direct_sum,above_2_indices,axis=1)
+
+ # Use the indices to get the relevant hours.
+ direct=np.take(full_direct,above_2_indices,axis=2)
+
+ # Use the indices to get the relevant hours.
+ thresh=np.take(full_thresh,above_2_indices,axis=1)
+
+ # Sort and get indices. Negate the array to get descending order.
+ # Descending order puts the "highest offender" light path first.
+ sort_thresh=np.argsort(-thresh,axis=0).transpose()
+
+ _combinations=[]
+ _combinations.insert(
+ 0,(np.arange(full_direct_sum.shape[1]),combinations)
+ )
+
+ ifnp.any(above_2_indices):
+ # There are hours where the percentage of floor area is > 2%.
+ foridx,lpinenumerate(light_paths):
+ # Take column. For each iteration it will take the next column
+ # in descending order, i.e., the "highest offender" is the first
+ # column.
+ sort_indices=np.take(sort_thresh,idx,axis=1)
+
+ # Map light path identifiers to indices.
+ light_path_ids=np.take(light_paths,sort_indices)
+
+ # Map shade transmittance to indices.
+ shd_trans_array=np.take(full_shd_trans_array,sort_indices)
+
+ # Create combination for the subset.
+ _subset_combination=[
+ {light_path:_shd_trans}forlight_path,_shd_transin
+ zip(light_path_ids,shd_trans_array)
+ ]
+ _combinations.insert(0,(above_2_indices,_subset_combination))
+
+ # Take the values from each array by indexing.
+ direct_array= \
+ direct[sort_indices,:,range(len(sort_indices))].transpose()
+
+ # Subtract the illuminance values.
+ direct_sum=direct_sum-(direct_array*(1-shd_trans_array))
+
+ # Find the percentage of floor area >= 1000 lux.
+ direct_pct_above=(direct_sum>=1000).sum(axis=0)/grid_count
+
+ # Find the indices where the percentage of floor area is > 2%.
+ above_2_indices=np.where(direct_pct_above>0.02)[0]
+
+ # Break if there are no hours above 2%.
+ ifnotnp.any(above_2_indices):
+ break
+
+ # Update variables for the next iteration.
+ direct_sum=np.take(direct_sum,above_2_indices,axis=1)
+ direct=np.take(direct,above_2_indices,axis=2)
+ thresh=np.take(thresh,above_2_indices,axis=1)
+ sort_thresh=np.take(sort_thresh,above_2_indices,axis=0)
+
+ ifnp.any(above_2_indices):
+ # There are hours not complying with the 2% rule.
+ previous_indices=[]
+ previous_combination=[]
+ grid_comply=[]
+ # Merge the combinations from the iterations of the subsets.
+ fori,subsetinenumerate(_combinations):
+ ifi==0:
+ previous_indices=subset[0]
+ else:
+ _indices=subset[0]
+ grid_comply=[]
+ for_pr_idxinprevious_indices:
+ grid_comply.append(_indices[_pr_idx])
+ previous_indices=grid_comply
+ # Convert indices to sun up hours indices.
+ filter_indices=np.where(occ_mask.astype(bool))[0]
+ grid_comply=[filter_indices[_gc]for_gcingrid_comply]
+ grid_comply=np.array(results.sun_up_hours)[grid_comply]
+ fail_to_comply[grid_info['name']]= \
+ [int(hoy)forhoyingrid_comply]
+
+ previous_indices=None
+ previous_combination=None
+ # Merge the combinations from the iterations of the subsets.
+ fori,subsetinenumerate(_combinations):
+ ifi==0:
+ previous_indices,previous_combination=subset
+ else:
+ _indices,_combination=subset
+ for_pr_idx,_pr_combin \
+ zip(previous_indices,previous_combination):
+ forlight_path,_shd_transin_pr_comb.items():
+ _combination[_pr_idx][light_path]=_shd_trans
+ previous_indices=_indices
+ previous_combination=_combination
+
+ combinations=_combination
+
+ # Merge the combinations of dicts.
+ forcombinationincombinations:
+ forlight_path,shd_transincombination.items():
+ iflight_path!="__static_apertures__":
+ states_schedule[light_path].append(shd_trans)
+
+ returnstates_schedule,fail_to_comply
+
+
+
+
+[docs]
+defstates_schedule_descending(
+ results:AnnualDaylight,grid_info,light_paths,occ_mask,
+ states_schedule,fail_to_comply
+ )->Tuple[dict,dict]:
+ grid_count=grid_info['count']
+ full_direct=[]
+ full_thresh=[]
+ full_direct_blinds=[]
+ forlight_pathinlight_paths:
+ array=results._get_array(
+ grid_info,light_path,state=0,res_type="direct")
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+ full_direct.append(array)
+ full_thresh.append((array>=1000).sum(axis=0))
+
+ array=results._get_array(
+ grid_info,light_path,state=1,res_type="direct")
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+ full_direct_blinds.append(array)
+
+ full_direct=np.array(full_direct)
+ full_direct_blinds=np.array(full_direct_blinds)
+ full_direct_sum=full_direct.sum(axis=0)
+
+ new_array=full_direct.copy()
+
+ percentage_sensors=(full_direct_sum>=1000).sum(axis=0)/grid_count
+ ifnotnp.any(percentage_sensors>0.02):
+ combinations=[
+ {light_path:0forlight_pathinlight_paths}
+ foriinrange(full_direct_sum.shape[1])]
+ else:
+ tracking_array=np.zeros(
+ (new_array.shape[0],new_array.shape[2]),dtype=int)
+
+ percentage_sensors=(full_direct>=1000).sum(axis=1)/grid_count
+
+ ranking_indices=np.argsort(-percentage_sensors,axis=0)
+
+ forrankinrange(ranking_indices.shape[0]):
+ # Calculate the percentage of sensors with values >= 1000 for the current new_array
+ summed_array=np.sum(new_array,axis=0)
+ percentage_sensors_summed=np.sum(
+ summed_array>=1000,axis=0)/grid_count
+ indices_above_2_percent=np.where(
+ percentage_sensors_summed>0.02)[0]
+
+ # Exit if there are no more hours exceeding the threshold
+ iflen(indices_above_2_percent)==0:
+ break
+
+ # Array indices to use for replacement for these hours
+ replace_indices=indices_above_2_percent
+ array_indices=ranking_indices[rank,replace_indices]
+
+ # Use advanced indexing to replace values in new_array for these hours
+ forhour_idx,array_idxinzip(replace_indices,array_indices):
+ new_array[array_idx,:,hour_idx]=full_direct_blinds[
+ array_idx,:,hour_idx
+ ]
+
+ # Update the tracking array
+ tracking_array[array_indices,replace_indices]=1
+
+ combinations=[]
+ forhourinrange(new_array.shape[2]):
+ hour_dict={
+ light_paths[i]:tracking_array[i,hour]
+ foriinrange(tracking_array.shape[0])}
+ combinations.append(hour_dict)
+
+ final_summed_array=np.sum(new_array,axis=0)
+ final_percentage_sensors_summed=(
+ final_summed_array>=1000).sum(
+ axis=0)/grid_count
+ final_indices_above_2_percent=np.where(
+ final_percentage_sensors_summed>0.02)[0]
+ ifnp.any(final_indices_above_2_percent):
+ sun_up_hours_indices=np.where(occ_mask==1)[0][
+ final_indices_above_2_percent]
+ grid_comply=np.array(results.sun_up_hours)[sun_up_hours_indices]
+ fail_to_comply[grid_info['name']]=[
+ int(hoy)forhoyingrid_comply]
+
+ forcombinationincombinations:
+ forlight_path,valueincombination.items():
+ iflight_path!='__static_apertures__':
+ states_schedule[light_path].append(value)
+
+ returnstates_schedule,fail_to_comply
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/leed/leed.html b/docs/_modules/honeybee_radiance_postprocess/leed/leed.html
new file mode 100644
index 00000000..8d37bb6f
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/leed/leed.html
@@ -0,0 +1,1475 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.leed.leed — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Source code for honeybee_radiance_postprocess.leed.leed
+"""Functions for LEED post-processing."""
+fromtypingimportTuple,Union
+frompathlibimportPath
+fromcollectionsimportdefaultdict
+importjson
+importitertools
+importnumpyasnp
+
+fromladybug.analysisperiodimportAnalysisPeriod
+fromladybug.datatype.genericimportGenericType
+fromladybug.colorimportColorset
+fromladybug.datacollectionimportHourlyContinuousCollection
+fromladybug.datatype.fractionimportFraction
+fromladybug.datatype.timeimportTime
+fromladybug.legendimportLegendParameters
+fromladybug.headerimportHeader
+fromhoneybee.modelimportModel
+fromhoneybee.unitsimportconversion_factor_to_meters
+fromhoneybee_radiance.writerimport_filter_by_pattern
+fromhoneybee_radiance.postprocess.annualimportfilter_schedule_by_hours
+
+from..metricsimportda_array2d,ase_array2d
+from..annualimportschedule_to_hoys,occupancy_schedule_8_to_6
+from..results.annual_daylightimportAnnualDaylight
+from..utilimportfilter_array,recursive_dict_merge
+from..dynamicimportDynamicSchedule,ApertureGroupSchedule
+from.leed_scheduleimportshd_trans_schedule_descending,states_schedule_descending
+
+
+def_create_grid_summary(
+ grid_info,sda_grid,sda_blinds_up_grid,sda_blinds_down_grid,ase_grid,
+ pass_sda,pass_ase,total_floor,area_weighted=True):
+"""Create a LEED summary for a single grid.
+
+ Args:
+ grid_info: Grid information.
+ sda_grid: Spatial Daylight Autonomy.
+ ase_grid: Annual Sunlight Exposure.
+ pass_sda: The percentage of the sensor points or floor area that
+ passes sDA.
+ pass_ase: The percentage of the sensor points or floor area that
+ passes ASE.
+ total_floor: The number of sensor points or floor area.
+ area_weighted: Boolean to determine if the results are area
+ weighted. Defaults to True.
+
+ Returns:
+ Tuple:
+ - summary_grid: Summary of each grid individually.
+ """
+ grid_id=grid_info['full_id']
+ grid_name=grid_info['name']
+ grid_summary={
+ grid_id:{}
+ }
+ ifase_grid>10:
+ ase_note=(
+ 'The Annual Sunlight Exposure is greater than 10% for space: '
+ f'{grid_name}. Identify in writing how the space is designed to '
+ 'address glare.'
+ )
+ grid_summary[grid_id]['ase_note']=ase_note
+
+ ifarea_weighted:
+ _grid_summary={
+ grid_id:{
+ 'name':grid_name,
+ 'full_id':grid_id,
+ 'ase':round(ase_grid,2),
+ 'sda':round(sda_grid,2),
+ 'sda_blinds_up':round(sda_blinds_up_grid,2),
+ 'sda_blinds_down':round(sda_blinds_down_grid,2),
+ 'floor_area_passing_ase':round(pass_ase,2),
+ 'floor_area_passing_sda':round(pass_sda,2),
+ 'total_floor_area':round(total_floor,2)
+ }
+ }
+ else:
+ _grid_summary={
+ grid_id:{
+ 'name':grid_name,
+ 'full_id':grid_id,
+ 'ase':round(ase_grid,2),
+ 'sda':round(sda_grid,2),
+ 'sda_blinds_up':round(sda_blinds_up_grid,2),
+ 'sda_blinds_down':round(sda_blinds_down_grid,2),
+ 'sensor_count_passing_ase':int(round(pass_ase,2)),
+ 'sensor_count_passing_sda':int(round(pass_sda,2)),
+ 'total_sensor_count':total_floor
+ }
+ }
+
+ recursive_dict_merge(grid_summary,_grid_summary)
+
+ returngrid_summary
+
+
+def_leed_summary(
+ pass_ase_grids:list,pass_sda_grids:list,grids_info:list,
+ grid_areas:list,pass_sda_blinds_up_grids:list,
+ pass_sda_blinds_down_grids:list)->Tuple[dict,dict]:
+"""Create combined summary and summary for each grid individually.
+
+ Args:
+ pass_ase_grids: A list where each sublist is a list of True/False that
+ tells if each sensor point passes ASE.
+ pass_sda_grids: A list where each sublist is a list of True/False that
+ tells if each sensor point passes sDA.
+ grids_info: A list of grid information.
+ grid_areas: A list where each sublist is the area of each sensor point.
+ The alternative is a list of None values for each grid information.
+
+ Returns:
+ Tuple:
+ - summary: Summary of of all grids combined.
+ - summary_grid: Summary of each grid individually.
+ """
+ summary={}
+ summary_grid={}
+
+ ifall(grid_areaisnotNoneforgrid_areaingrid_areas):
+ # weighted by mesh face area
+ total_area=0
+ total_area_pass_ase=0
+ total_area_pass_sda=0
+ for(pass_ase,pass_sda,grid_area,grid_info,pass_sda_blinds_up,
+ pass_sda_blinds_down)in \
+ zip(pass_ase_grids,pass_sda_grids,grid_areas,grids_info,
+ pass_sda_blinds_up_grids,pass_sda_blinds_down_grids):
+ total_grid_area=grid_area.sum()
+
+ area_pass_ase=grid_area[pass_ase].sum()
+ ase_grid=(total_grid_area-area_pass_ase)/total_grid_area*100
+
+ area_pass_sda=grid_area[pass_sda].sum()
+ area_pass_sda_blind_up=grid_area[pass_sda_blinds_up].sum()
+ area_pass_sda_blinds_down=grid_area[pass_sda_blinds_down].sum()
+ sda_grid=area_pass_sda/total_grid_area*100
+ sda_blinds_up_grid=area_pass_sda_blind_up/total_grid_area*100
+ sda_blinds_down_grid=area_pass_sda_blinds_down/total_grid_area*100
+
+ # grid summary
+ grid_summary= \
+ _create_grid_summary(
+ grid_info,sda_grid,sda_blinds_up_grid,sda_blinds_down_grid,
+ ase_grid,area_pass_sda,area_pass_ase,total_grid_area,
+ area_weighted=True
+ )
+
+ recursive_dict_merge(summary_grid,grid_summary)
+
+ total_area+=total_grid_area
+ total_area_pass_ase+=area_pass_ase
+ total_area_pass_sda+=area_pass_sda
+
+ summary['ase']=round((total_area-total_area_pass_ase)/total_area*100,2)
+ summary['sda']=round(total_area_pass_sda/total_area*100,2)
+ summary['floor_area_passing_ase']=total_area_pass_ase
+ summary['floor_area_passing_sda']=total_area_pass_sda
+ summary['total_floor_area']=total_area
+ else:
+ # assume all sensor points cover the same area
+ total_sensor_count=0
+ total_sensor_count_pass_ase=0
+ total_sensor_count_pass_sda=0
+ for(pass_ase,pass_sda,grid_info,pass_sda_blinds_up,
+ pass_sda_blinds_down)in \
+ zip(pass_ase_grids,pass_sda_grids,grids_info,
+ pass_sda_blinds_up_grids,pass_sda_blinds_down_grids):
+ grid_count=grid_info['count']
+ sensor_count_pass_ase=pass_ase.sum()
+ ase_grid=(grid_count-sensor_count_pass_ase)/grid_count*100
+
+ sensor_count_pass_sda=pass_sda.sum()
+ sensor_count_pass_sda_blinds_up=pass_sda_blinds_up.sum()
+ sensor_count_pass_sda_blinds_down=pass_sda_blinds_down.sum()
+ sda_grid=sensor_count_pass_sda/grid_count*100
+ sda_blinds_up_grid=sensor_count_pass_sda_blinds_up/grid_count*100
+ sda_blinds_down_grid=sensor_count_pass_sda_blinds_down/grid_count*100
+
+ # grid summary
+ grid_summary= \
+ _create_grid_summary(
+ grid_info,sda_grid,sda_blinds_up_grid,sda_blinds_down_grid,
+ ase_grid,sensor_count_pass_sda,sensor_count_pass_ase,
+ grid_count,area_weighted=False
+ )
+
+ recursive_dict_merge(summary_grid,grid_summary)
+
+ total_sensor_count+=grid_count
+ total_sensor_count_pass_ase+=sensor_count_pass_ase
+ total_sensor_count_pass_sda+=sensor_count_pass_sda
+
+ summary['ase']=round((total_sensor_count-total_sensor_count_pass_ase)/
+ total_sensor_count*100,2
+ )
+ summary['sda']=round(total_sensor_count_pass_sda/total_sensor_count*100,2)
+ summary['sensor_count_passing_ase']=int(total_sensor_count_pass_ase)
+ summary['sensor_count_passing_sda']=int(total_sensor_count_pass_sda)
+ summary['total_sensor_count']=total_sensor_count
+
+ returnsummary,summary_grid
+
+
+def_ase_hourly_percentage(
+ results:AnnualDaylight,array:np.ndarray,grid_info:dict,
+ direct_threshold:float=1000,grid_area:Union[None,np.ndarray]=None
+ )->np.ndarray:
+"""Calculate the percentage of floor area that receives greater than 1000
+ direct lux for each hour.
+
+ Args:
+ results: A Results object.
+ array: A NumPy array of the grid to process.
+ grid_info: Grid information of the grid to process..
+ direct_threshold: Direct threshold.
+ grid_area: Grid area as a NumPy array with a area value for each sensor
+ point, or a None value if there is no area associated with the
+ sensor point.
+
+ Returns:
+ A hourly data collection of the percentage of floor area that receives
+ greater than 1000 direct lux.
+ """
+ ifgrid_areaisnotNone:
+ grid_area_2d=np.array([grid_area]*array.shape[1]).transpose()
+ area_above= \
+ np.where((array>direct_threshold),grid_area_2d,0).sum(axis=0)
+ percentage_above=area_above/grid_area.sum()*100
+ else:
+ percentage_above= \
+ (array>direct_threshold).sum(axis=0)/grid_info['count']*100
+
+ occupancy_hoys=schedule_to_hoys(results.schedule,results.sun_up_hours)
+ # map states to 8760 values
+ percentage_above=results.values_to_annual(
+ occupancy_hoys,percentage_above,results.timestep)
+ header=Header(Fraction('Percentage above 1000 direct lux'),'%',
+ AnalysisPeriod(results.timestep),
+ metadata={'SensorGrid':grid_info['name']})
+ data_collection=HourlyContinuousCollection(header,percentage_above.tolist())
+
+ returndata_collection
+
+
+[docs]
+defshade_transmittance_per_light_path(
+ light_paths:list,shade_transmittance:Union[float,dict],
+ shd_trans_dict:dict)->dict:
+"""Filter shade_transmittance by light paths and add default multiplier.
+
+ Args:
+ light_paths: A list of light paths.
+ shade_transmittance: A value to use as a multiplier in place of solar
+ shading. This input can be either a single value that will be used
+ for all aperture groups, or a dictionary where aperture groups are
+ keys, and the value for each key is the shade transmittance. Values
+ for shade transmittance must be 1 > value > 0.
+ shd_trans_dict: A dictionary used to store shade transmittance value
+ for each aperture group.
+
+ Returns:
+ A dictionary with filtered light paths.
+ """
+ shade_transmittances={}
+ ifisinstance(shade_transmittance,dict):
+ forlight_pathinlight_paths:
+ # default multiplier
+ shade_transmittances[light_path]=[1]
+ # add custom shade transmittance
+ iflight_pathinshade_transmittance:
+ shade_transmittances[light_path].append(
+ shade_transmittance[light_path])
+ shd_trans_dict[light_path]=shade_transmittance[light_path]
+ # add default shade transmittance (0.05)
+ eliflight_path!='__static_apertures__':
+ shade_transmittances[light_path].append(0.05)
+ shd_trans_dict[light_path]=0.05
+ else:
+ shade_transmittances[light_path].append(1)
+ shd_trans_dict[light_path]=1
+ else:
+ shd_trans=float(shade_transmittance)
+ forlight_pathinlight_paths:
+ # default multiplier
+ shade_transmittances[light_path]=[1]
+ # add custom shade transmittance
+ iflight_path!='__static_apertures__':
+ shade_transmittances[light_path].append(shd_trans)
+ shd_trans_dict[light_path]=shd_trans
+ else:
+ shade_transmittances[light_path].append(1)
+ shd_trans_dict[light_path]=1
+
+ returnshade_transmittances,shd_trans_dict
+
+
+
+
+[docs]
+defleed_states_schedule(
+ results:Union[str,AnnualDaylight],grids_filter:str='*',
+ shade_transmittance:Union[float,dict]=0.05,
+ use_states:bool=False
+ )->Tuple[dict,dict]:
+"""Calculate a schedule of each aperture group for LEED compliant sDA.
+
+ This function calculates an annual shading schedule of each aperture
+ group. Hour by hour it will select the least shaded aperture group
+ configuration, so that no more than 2% of the sensors points receive
+ direct illuminance of 1000 lux or more.
+
+ Args:
+ results: Path to results folder or a Results class object.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ shade_transmittance: A value to use as a multiplier in place of solar
+ shading. This input can be either a single value that will be used
+ for all aperture groups, or a dictionary where aperture groups are
+ keys, and the value for each key is the shade transmittance. Values
+ for shade transmittance must be 1 > value > 0.
+ Defaults to 0.05.
+ use_states: A boolean to note whether to use the simulated states. Set
+ to True to use the simulated states. The default is False which will
+ use the shade transmittance instead.
+
+ Returns:
+ Tuple: A tuple with a dictionary of the annual schedule and a
+ dictionary of hours where no shading configuration comply with the
+ 2% rule.
+ """
+ ifnotisinstance(results,AnnualDaylight):
+ results=AnnualDaylight(results)
+
+ grids_info=results._filter_grids(grids_filter=grids_filter)
+ schedule=occupancy_schedule_8_to_6(as_list=True)
+ occ_pattern= \
+ filter_schedule_by_hours(results.sun_up_hours,schedule=schedule)[0]
+ occ_mask=np.array(occ_pattern)
+
+ states_schedule=defaultdict(list)
+ fail_to_comply={}
+ shd_trans_dict={}
+
+ forgrid_infoingrids_info:
+ grid_states_schedule=defaultdict(list)
+ grid_count=grid_info['count']
+ light_paths=[]
+ forlpingrid_info['light_path']:
+ for_lpinlp:
+ if_lp=='__static_apertures__'andlen(lp)>1:
+ pass
+ else:
+ light_paths.append(_lp)
+
+ shade_transmittances,shd_trans_dict=(
+ shade_transmittance_per_light_path(
+ light_paths,shade_transmittance,shd_trans_dict
+ )
+ )
+
+ iflen(light_paths)>6:
+ ifuse_states:
+ grid_states_schedule,fail_to_comply=states_schedule_descending(
+ results,grid_info,light_paths,occ_mask,
+ grid_states_schedule,fail_to_comply)
+ else:
+ grid_states_schedule,fail_to_comply=shd_trans_schedule_descending(
+ results,grid_info,light_paths,shade_transmittances,occ_mask,
+ grid_states_schedule,fail_to_comply)
+ else:
+ ifuse_states:
+ combinations=results._get_state_combinations(grid_info)
+ else:
+ shade_transmittances,shd_trans_dict=shade_transmittance_per_light_path(
+ light_paths,shade_transmittance,shd_trans_dict)
+ keys,values=zip(*shade_transmittances.items())
+ combinations=[dict(zip(keys,v))forvinitertools.product(*values)]
+
+ array_list_combinations=[]
+ forcombinationincombinations:
+ combination_arrays=[]
+ forlight_path,valueincombination.items():
+ ifuse_states:
+ combination_arrays.append(
+ results._get_array(grid_info,light_path,state=value,
+ res_type='direct')
+ )
+ else:
+ array=results._get_array(
+ grid_info,light_path,res_type='direct')
+ ifvalue==1:
+ combination_arrays.append(array)
+ else:
+ combination_arrays.append(array*value)
+ combination_array=sum(combination_arrays)
+
+ combination_percentage= \
+ (combination_array>=1000).sum(axis=0)/grid_count
+ array_list_combinations.append(combination_percentage)
+ array_combinations=np.array(array_list_combinations)
+ array_combinations[array_combinations>0.02]=-np.inf
+
+ grid_comply=np.where(np.all(array_combinations==-np.inf,axis=0))[0]
+ ifgrid_comply.size!=0:
+ grid_comply=np.array(results.sun_up_hours)[grid_comply]
+ fail_to_comply[grid_info['name']]= \
+ [int(hoy)forhoyingrid_comply]
+
+ array_combinations_filter=np.apply_along_axis(
+ filter_array,1,array_combinations,occ_mask
+ )
+ max_indices=array_combinations_filter.argmax(axis=0)
+ # select the combination for each hour
+ combinations=[combinations[idx]foridxinmax_indices]
+ # merge the combinations of dicts
+ forcombinationincombinations:
+ forlight_path,valueincombination.items():
+ iflight_path!='__static_apertures__':
+ grid_states_schedule[light_path].append(value)
+
+ forkey,valueingrid_states_schedule.items():
+ ifkeynotinstates_schedule:
+ states_schedule[key]=value
+
+ occupancy_hoys=schedule_to_hoys(schedule,results.sun_up_hours)
+
+ # map states to 8760 values
+ ifuse_states:
+ aperture_group_schedules=[]
+ foridentifier,valuesinstates_schedule.items():
+ mapped_states=results.values_to_annual(
+ occupancy_hoys,values,results.timestep,dtype=np.int32)
+ aperture_group_schedules.append(
+ ApertureGroupSchedule(identifier,mapped_states.tolist())
+ )
+ states_schedule= \
+ DynamicSchedule.from_group_schedules(aperture_group_schedules)
+ else:
+ forlight_path,shd_transinstates_schedule.items():
+ mapped_states=results.values_to_annual(
+ occupancy_hoys,shd_trans,results.timestep)
+ states_schedule[light_path]=mapped_states
+
+ returnstates_schedule,fail_to_comply,shd_trans_dict
+
+
+
+
+[docs]
+defleed_option_one(
+ results:Union[str,AnnualDaylight],grids_filter:str='*',
+ shade_transmittance:Union[float,dict]=0.05,
+ use_states:bool=False,states_schedule:dict=None,
+ threshold:float=300,direct_threshold:float=1000,
+ occ_hours:int=250,target_time:float=50,sub_folder:str=None):
+"""Calculate credits for LEED v4.1 Daylight Option 1.
+
+ Args:
+ results: Path to results folder or a Results class object.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ shade_transmittance: A value to use as a multiplier in place of solar
+ shading. This input can be either a single value that will be used
+ for all aperture groups, or a dictionary where aperture groups are
+ keys, and the value for each key is the shade transmittance. Values
+ for shade transmittance must be 1 > value > 0.
+ Defaults to 0.05.
+ use_states: A boolean to note whether to use the simulated states. Set
+ to True to use the simulated states. The default is False which will
+ use the shade transmittance instead.
+ states_schedule: A custom dictionary of shading states. In case this is
+ left empty, the function will calculate a shading schedule by using
+ the shade_transmittance input. If a states schedule is provided it
+ will check that it is complying with the 2% rule. Defaults to None.
+ threshold: Threshold value for daylight autonomy. Default: 300.
+ direct_threshold: The threshold that determines if a sensor is overlit.
+ Defaults to 1000.
+ occ_hours: The number of occupied hours that cannot receive more than
+ the direct_threshold. Defaults to 250.
+ target_time: A minimum threshold of occupied time (eg. 50% of the
+ time), above which a given sensor passes and contributes to the
+ spatial daylight autonomy. Defaults to 50.
+ sub_folder: Relative path for a subfolder to write the output. If None,
+ the files will not be written. Defaults to None.
+
+ Returns:
+ Tuple:
+ - summary: Summary of all grids combined.
+ - summary_grid: Summary of each grid individually.
+ - da_grids: List of daylight autonomy values for each grid. Each item
+ in the list is a NumPy array of DA values.
+ - hours_above: List of hours above 1000 direct illuminance (with
+ default states) for each grid. Each item in the list is a NumPy
+ array of hours above 1000 lux.
+ - states_schedule: A dictionary of annual shading schedules for each
+ aperture group.
+ - fail_to_comply: A dictionary with the hoys where the 2% rule failed.
+ - grids_info: Grid information.
+ """
+ # use default leed occupancy schedule
+ schedule=occupancy_schedule_8_to_6(as_list=True)
+
+ ifnotisinstance(results,AnnualDaylight):
+ results=AnnualDaylight(results,schedule=schedule)
+ else:
+ # set schedule to default leed schedule
+ results.schedule=schedule
+
+ occ_mask=results.occ_mask
+ total_occ=results.total_occ
+
+ grids_info=results._filter_grids(grids_filter=grids_filter)
+
+ ifnotstates_schedule:
+ states_schedule,fail_to_comply,shd_trans_dict= \
+ leed_states_schedule(results,grids_filter=grids_filter,
+ shade_transmittance=shade_transmittance,use_states=use_states)
+ else:
+ raiseNotImplementedError(
+ 'Custom input for argument states_schedule is not yet implemented.'
+ )
+
+ # check to see if there is a HBJSON with sensor grid meshes for areas
+ grid_areas,units_conversion=[],1
+ forbase_fileinPath(results.folder).parent.iterdir():
+ ifbase_file.suffixin('.hbjson','.hbpkl'):
+ hb_model=Model.from_file(base_file)
+ units_conversion=conversion_factor_to_meters(hb_model.units)
+ filt_grids=_filter_by_pattern(
+ hb_model.properties.radiance.sensor_grids,filter=grids_filter)
+ fors_gridinfilt_grids:
+ ifs_grid.meshisnotNone:
+ grid_areas.append(s_grid.mesh.face_areas)
+ grid_areas=[np.array(grid)forgridingrid_areas]
+ break
+ ifnotgrid_areas:
+ grid_areas=[None]*len(grids_info)
+
+ # annual sunlight exposure
+ ase_grids=[]
+ hours_above=[]
+ pass_ase_grids=[]
+ ase_hr_pct=[]
+ for(grid_info,grid_area)inzip(grids_info,grid_areas):
+ light_paths=[]
+ forlpingrid_info['light_path']:
+ for_lpinlp:
+ if_lp=='__static_apertures__'andlen(lp)>1:
+ pass
+ else:
+ light_paths.append(_lp)
+ arrays=[]
+ # combine direct array for all light paths
+ forlight_pathinlight_paths:
+ array=results._get_array(
+ grid_info,light_path,res_type='direct')
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,occ_mask)
+ arrays.append(array_filter)
+ array=sum(arrays)
+ # calculate ase per grid
+ ase_grid,h_above=ase_array2d(
+ array,occ_hours=occ_hours,direct_threshold=direct_threshold)
+
+ # calculate the number of sensor points above 1000 lux for each hour
+ ase_hr_pct.append(
+ _ase_hourly_percentage(
+ results,array,grid_info,direct_threshold=direct_threshold,
+ grid_area=grid_area
+ )
+ )
+
+ ase_grids.append(ase_grid)
+ hours_above.append(h_above)
+ pass_ase=h_above<occ_hours
+ pass_ase_grids.append(pass_ase)
+
+ # spatial daylight autonomy
+ da_grids=[]
+ pass_sda_grids=[]
+ pass_sda_blinds_up_grids=[]
+ pass_sda_blinds_down_grids=[]
+ forgrid_infoingrids_info:
+ light_paths=[]
+ forlpingrid_info['light_path']:
+ for_lpinlp:
+ if_lp=='__static_apertures__'andlen(lp)>1:
+ pass
+ else:
+ light_paths.append(_lp)
+ base_zero_array=np.apply_along_axis(filter_array,1,np.zeros(
+ (grid_info['count'],len(results.sun_up_hours))),occ_mask)
+ arrays=[base_zero_array.copy()]
+ arrays_blinds_up=[base_zero_array.copy()]
+ arrays_blinds_down=[base_zero_array.copy()]
+ # combine total array for all light paths
+ ifuse_states:
+ array=results._array_from_states(grid_info,states=states_schedule,zero_array=True)
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+
+ forlight_pathinlight_paths:
+ # do an extra pass to calculate with blinds always up or down
+ iflight_path!='__static_apertures__':
+ array_blinds_up=results._get_array(
+ grid_info,light_path,state=0,res_type='total')
+ array_filter=np.apply_along_axis(
+ filter_array,1,array_blinds_up,occ_mask)
+ arrays_blinds_up.append(array_filter)
+ array_blinds_down=results._get_array(
+ grid_info,light_path,state=1,res_type='total')
+ array_filter=np.apply_along_axis(
+ filter_array,1,array_blinds_down,occ_mask)
+ arrays_blinds_down.append(array_filter)
+ else:
+ static_array=results._get_array(
+ grid_info,light_path,state=0,res_type='total')
+ array_filter=np.apply_along_axis(
+ filter_array,1,static_array,occ_mask)
+ arrays_blinds_up.append(array_filter)
+ arrays_blinds_down.append(array_filter)
+ else:
+ forlight_pathinlight_paths:
+ array=results._get_array(
+ grid_info,light_path,res_type='total')
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,occ_mask)
+ iflight_path!='__static_apertures__':
+ sun_up_hours=np.array(results.sun_up_hours).astype(int)
+ shd_trans_array=states_schedule[light_path][sun_up_hours]
+ shd_trans_array=shd_trans_array[occ_mask.astype(bool)]
+ arrays.append(array_filter*shd_trans_array)
+ arrays_blinds_up.append(array_filter)
+ arrays_blinds_down.append(
+ array_filter*shd_trans_dict[light_path])
+ else:
+ arrays.append(array_filter)
+ arrays_blinds_up.append(array_filter)
+ arrays_blinds_down.append(array_filter)
+ array=sum(arrays)
+
+ array_blinds_up=sum(arrays_blinds_up)
+ array_blinds_down=sum(arrays_blinds_down)
+ # calculate da per grid
+ da_grid=da_array2d(array,total_occ=total_occ,threshold=threshold)
+ da_grids.append(da_grid)
+ da_blinds_up_grid=da_array2d(
+ array_blinds_up,total_occ=total_occ,threshold=threshold)
+ da_blinds_down_grid=da_array2d(
+ array_blinds_down,total_occ=total_occ,threshold=threshold)
+ # calculate sda per grid
+ pass_sda_grids.append(da_grid>=target_time)
+ pass_sda_blinds_up_grids.append(da_blinds_up_grid>=target_time)
+ pass_sda_blinds_down_grids.append(da_blinds_down_grid>=target_time)
+
+ # create summaries for all grids and each grid individually
+ summary,summary_grid=_leed_summary(
+ pass_ase_grids,pass_sda_grids,grids_info,grid_areas,
+ pass_sda_blinds_up_grids,pass_sda_blinds_down_grids)
+
+ # credits
+ ifnotfail_to_comply:
+ ifsummary['sda']>=75:
+ summary['credits']=3
+ elifsummary['sda']>=55:
+ summary['credits']=2
+ elifsummary['sda']>=40:
+ summary['credits']=1
+ else:
+ summary['credits']=0
+
+ ifall(grid_summary['sda']>=55forgrid_summaryinsummary_grid.values()):
+ ifsummary['credits']<=2:
+ summary['credits']+=1
+ else:
+ summary['credits']='Exemplary performance'
+ else:
+ summary['credits']=0
+ fail_to_comply_rooms=', '.join(list(fail_to_comply.keys()))
+ note=(
+ '0 credits have been awarded. The following sensor grids have at '
+ 'least one hour where 2% of the floor area receives direct '
+ f'illuminance of 1000 lux or more: {fail_to_comply_rooms}.'
+ )
+ summary['note']=note
+
+ # convert to datacollection
+ defto_datacollection(aperture_group:str,values:np.ndarray):
+ # convert values to 0 and 1 (0 = no shading, 1 = shading)
+ ifuse_states:
+ header=Header(data_type=GenericType(aperture_group,''),unit='',
+ analysis_period=AnalysisPeriod())
+ hourly_data=HourlyContinuousCollection(header=header,values=values)
+ else:
+ values[values==1]=0
+ values[values==shd_trans_dict[aperture_group]]=1
+ header=Header(data_type=GenericType(aperture_group,''),unit='',
+ analysis_period=AnalysisPeriod(),
+ metadata={'Shade Transmittance':shd_trans_dict[aperture_group]})
+ hourly_data=HourlyContinuousCollection(header=header,values=values.tolist())
+ returnhourly_data.to_dict()
+
+ ifuse_states:
+ states_schedule={k:to_datacollection(k,v['schedule'])fork,vinstates_schedule.to_dict().items()}
+ else:
+ states_schedule={k:to_datacollection(k,v)fork,vinstates_schedule.items()}
+
+ ifsub_folder:
+ folder=Path(sub_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ summary_file=folder.joinpath('summary.json')
+ summary_file.write_text(json.dumps(summary,indent=2))
+ summary_grid_file=folder.joinpath('summary_grid.json')
+ summary_grid_file.write_text(json.dumps(summary_grid,indent=2))
+ states_schedule_file=folder.joinpath('states_schedule.json')
+ states_schedule_file.write_text(json.dumps(states_schedule))
+ grids_info_file=folder.joinpath('grids_info.json')
+ grids_info_file.write_text(json.dumps(grids_info,indent=2))
+
+ for(da,h_above,ase_hr_p,grid_info)in \
+ zip(da_grids,hours_above,ase_hr_pct,grids_info):
+ grid_id=grid_info['full_id']
+ da_file=folder.joinpath('results','da',f'{grid_id}.da')
+ da_file.parent.mkdir(parents=True,exist_ok=True)
+ hours_above_file=folder.joinpath(
+ 'results','ase_hours_above',f'{grid_id}.res')
+ hours_above_file.parent.mkdir(parents=True,exist_ok=True)
+ ase_hr_p_file=folder.joinpath(
+ 'datacollections','ase_percentage_above',f'{grid_id}.json')
+ ase_hr_p_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(da_file,da,fmt='%.2f')
+ np.savetxt(hours_above_file,h_above,fmt='%.0f')
+ ase_hr_p_file.write_text(json.dumps(ase_hr_p.to_dict()))
+
+ da_grids_info_file=folder.joinpath(
+ 'results','da','grids_info.json')
+ da_grids_info_file.write_text(json.dumps(grids_info,indent=2))
+ ase_grids_info_file=folder.joinpath(
+ 'results','ase_hours_above','grids_info.json')
+ ase_grids_info_file.write_text(json.dumps(grids_info,indent=2))
+ ase_hr_pct_info_file=folder.joinpath(
+ 'datacollections','ase_percentage_above','grids_info.json')
+ ase_hr_pct_info_file.write_text(json.dumps(grids_info,indent=2))
+
+ states_schedule_err_file= \
+ folder.joinpath('states_schedule_err.json')
+ states_schedule_err_file.write_text(json.dumps(fail_to_comply))
+
+ return(summary,summary_grid,da_grids,hours_above,states_schedule,
+ fail_to_comply,grids_info)
+[docs]
+defshd_trans_schedule_descending(
+ results:AnnualDaylight,grid_info,light_paths,shade_transmittances,occ_mask,
+ states_schedule,fail_to_comply
+ )->Tuple[dict,dict]:
+ grid_count=grid_info['count']
+ full_direct=[]
+ full_thresh=[]
+ full_shd_trans_array=[]
+ forlight_pathinlight_paths:
+ array=results._get_array(grid_info,light_path,res_type="direct")
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+ full_direct.append(array)
+ full_thresh.append((array>=1000).sum(axis=0))
+ full_shd_trans_array.append(shade_transmittances[light_path][1])
+
+ # Sum the array element-wise.
+ # This array is the sum of all direct illuminance without shade
+ # transmittance.
+ full_direct_sum=sum(full_direct)
+
+ # Create base list of shading combinations (all set to 1).
+ # We will replace the 1s later.
+ combinations=[
+ {light_path:1forlight_pathinlight_paths}
+ foriinrange(full_direct_sum.shape[1])
+ ]
+
+ # Find the percentage of floor area >= 1000 lux.
+ # This array is the percentage for each hour (axis=0).
+ direct_pct_above=(full_direct_sum>=1000).sum(axis=0)/grid_count
+
+ # Find the indices where the percentage of floor area is > 2%.
+ # This array is the problematic hours.
+ above_2_indices=np.where(direct_pct_above>0.02)[0]
+
+ # Use the indices to get the relevant hours.
+ direct_sum=np.take(full_direct_sum,above_2_indices,axis=1)
+
+ # Use the indices to get the relevant hours.
+ direct=np.take(full_direct,above_2_indices,axis=2)
+
+ # Use the indices to get the relevant hours.
+ thresh=np.take(full_thresh,above_2_indices,axis=1)
+
+ # Sort and get indices. Negate the array to get descending order.
+ # Descending order puts the "highest offender" light path first.
+ sort_thresh=np.argsort(-thresh,axis=0).transpose()
+
+ _combinations=[]
+ _combinations.insert(
+ 0,(np.arange(full_direct_sum.shape[1]),combinations)
+ )
+
+ ifnp.any(above_2_indices):
+ # There are hours where the percentage of floor area is > 2%.
+ foridx,lpinenumerate(light_paths):
+ # Take column. For each iteration it will take the next column
+ # in descending order, i.e., the "highest offender" is the first
+ # column.
+ sort_indices=np.take(sort_thresh,idx,axis=1)
+
+ # Map light path identifiers to indices.
+ light_path_ids=np.take(light_paths,sort_indices)
+
+ # Map shade transmittance to indices.
+ shd_trans_array=np.take(full_shd_trans_array,sort_indices)
+
+ # Create combination for the subset.
+ _subset_combination=[
+ {light_path:_shd_trans}forlight_path,_shd_transin
+ zip(light_path_ids,shd_trans_array)
+ ]
+ _combinations.insert(0,(above_2_indices,_subset_combination))
+
+ # Take the values from each array by indexing.
+ direct_array= \
+ direct[sort_indices,:,range(len(sort_indices))].transpose()
+
+ # Subtract the illuminance values.
+ direct_sum=direct_sum-(direct_array*(1-shd_trans_array))
+
+ # Find the percentage of floor area >= 1000 lux.
+ direct_pct_above=(direct_sum>=1000).sum(axis=0)/grid_count
+
+ # Find the indices where the percentage of floor area is > 2%.
+ above_2_indices=np.where(direct_pct_above>0.02)[0]
+
+ # Break if there are no hours above 2%.
+ ifnotnp.any(above_2_indices):
+ break
+
+ # Update variables for the next iteration.
+ direct_sum=np.take(direct_sum,above_2_indices,axis=1)
+ direct=np.take(direct,above_2_indices,axis=2)
+ thresh=np.take(thresh,above_2_indices,axis=1)
+ sort_thresh=np.take(sort_thresh,above_2_indices,axis=0)
+
+ ifnp.any(above_2_indices):
+ # There are hours not complying with the 2% rule.
+ previous_indices=[]
+ previous_combination=[]
+ grid_comply=[]
+ # Merge the combinations from the iterations of the subsets.
+ fori,subsetinenumerate(_combinations):
+ ifi==0:
+ previous_indices=subset[0]
+ else:
+ _indices=subset[0]
+ grid_comply=[]
+ for_pr_idxinprevious_indices:
+ grid_comply.append(_indices[_pr_idx])
+ previous_indices=grid_comply
+ # Convert indices to sun up hours indices.
+ filter_indices=np.where(occ_mask.astype(bool))[0]
+ grid_comply=[filter_indices[_gc]for_gcingrid_comply]
+ grid_comply=np.array(results.sun_up_hours)[grid_comply]
+ fail_to_comply[grid_info['name']]= \
+ [int(hoy)forhoyingrid_comply]
+
+ previous_indices=None
+ previous_combination=None
+ # Merge the combinations from the iterations of the subsets.
+ fori,subsetinenumerate(_combinations):
+ ifi==0:
+ previous_indices,previous_combination=subset
+ else:
+ _indices,_combination=subset
+ for_pr_idx,_pr_combin \
+ zip(previous_indices,previous_combination):
+ forlight_path,_shd_transin_pr_comb.items():
+ _combination[_pr_idx][light_path]=_shd_trans
+ previous_indices=_indices
+ previous_combination=_combination
+
+ combinations=_combination
+
+ # Merge the combinations of dicts.
+ forcombinationincombinations:
+ forlight_path,shd_transincombination.items():
+ iflight_path!="__static_apertures__":
+ states_schedule[light_path].append(shd_trans)
+
+ returnstates_schedule,fail_to_comply
+
+
+
+
+[docs]
+defstates_schedule_descending(
+ results:AnnualDaylight,grid_info,light_paths,occ_mask,
+ states_schedule,fail_to_comply
+ )->Tuple[dict,dict]:
+ grid_count=grid_info['count']
+ full_direct=[]
+ full_thresh=[]
+ full_direct_blinds=[]
+ forlight_pathinlight_paths:
+ array=results._get_array(
+ grid_info,light_path,state=0,res_type="direct")
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+ full_direct.append(array)
+ full_thresh.append((array>=1000).sum(axis=0))
+
+ array=results._get_array(
+ grid_info,light_path,state=1,res_type="direct")
+ array=np.apply_along_axis(filter_array,1,array,occ_mask)
+ full_direct_blinds.append(array)
+
+ full_direct=np.array(full_direct)
+ full_direct_blinds=np.array(full_direct_blinds)
+ full_direct_sum=full_direct.sum(axis=0)
+
+ new_array=full_direct.copy()
+
+ percentage_sensors=(full_direct_sum>=1000).sum(axis=0)/grid_count
+ ifnotnp.any(percentage_sensors>0.02):
+ combinations=[
+ {light_path:0forlight_pathinlight_paths}
+ foriinrange(full_direct_sum.shape[1])]
+ else:
+ tracking_array=np.zeros(
+ (new_array.shape[0],new_array.shape[2]),dtype=int)
+
+ percentage_sensors=(full_direct>=1000).sum(axis=1)/grid_count
+
+ ranking_indices=np.argsort(-percentage_sensors,axis=0)
+
+ forrankinrange(ranking_indices.shape[0]):
+ # Calculate the percentage of sensors with values >= 1000 for the current new_array
+ summed_array=np.sum(new_array,axis=0)
+ percentage_sensors_summed=np.sum(
+ summed_array>=1000,axis=0)/grid_count
+ indices_above_2_percent=np.where(
+ percentage_sensors_summed>0.02)[0]
+
+ # Exit if there are no more hours exceeding the threshold
+ iflen(indices_above_2_percent)==0:
+ break
+
+ # Array indices to use for replacement for these hours
+ replace_indices=indices_above_2_percent
+ array_indices=ranking_indices[rank,replace_indices]
+
+ # Use advanced indexing to replace values in new_array for these hours
+ forhour_idx,array_idxinzip(replace_indices,array_indices):
+ new_array[array_idx,:,hour_idx]=full_direct_blinds[
+ array_idx,:,hour_idx
+ ]
+
+ # Update the tracking array
+ tracking_array[array_indices,replace_indices]=1
+
+ combinations=[]
+ forhourinrange(new_array.shape[2]):
+ hour_dict={
+ light_paths[i]:tracking_array[i,hour]
+ foriinrange(tracking_array.shape[0])}
+ combinations.append(hour_dict)
+
+ final_summed_array=np.sum(new_array,axis=0)
+ final_percentage_sensors_summed=(
+ final_summed_array>=1000).sum(
+ axis=0)/grid_count
+ final_indices_above_2_percent=np.where(
+ final_percentage_sensors_summed>0.02)[0]
+ ifnp.any(final_indices_above_2_percent):
+ sun_up_hours_indices=np.where(occ_mask==1)[0][
+ final_indices_above_2_percent]
+ grid_comply=np.array(results.sun_up_hours)[sun_up_hours_indices]
+ fail_to_comply[grid_info['name']]=[
+ int(hoy)forhoyingrid_comply]
+
+ forcombinationincombinations:
+ forlight_path,valueincombination.items():
+ iflight_path!='__static_apertures__':
+ states_schedule[light_path].append(value)
+
+ returnstates_schedule,fail_to_comply
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/metrics.html b/docs/_modules/honeybee_radiance_postprocess/metrics.html
new file mode 100644
index 00000000..9e45f3d0
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/metrics.html
@@ -0,0 +1,1164 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.metrics — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Source code for honeybee_radiance_postprocess.metrics
+"""Functions to calculate various metrics for 1D and 2D NumPy arrays."""
+fromtypingimportTuple,Union
+importnumpyasnp
+
+from.utilimportcheck_array_dim
+
+
+
+[docs]
+defda_array2d(
+ array:np.ndarray,total_occ:int=None,
+ threshold:float=300)->np.ndarray:
+"""Calculate daylight autonomy for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not
+ given any input the number of occupied hours will be found by the
+ array shape, i.e., it is assumed that the array is filtered by
+ occupied hours.
+ threshold: Threshold value for daylight autonomy. Default: 300.
+
+ Returns:
+ A 1-dimensional NumPy array with the daylight autonomy for each row in
+ the input array.
+ """
+ check_array_dim(array,2)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.shape[1]
+
+ da=np.apply_along_axis(
+ da_array1d,1,array,total_occ=total_occ,threshold=threshold)
+
+ returnda
+
+
+
+
+[docs]
+defda_array1d(
+ array:np.ndarray,total_occ:int=None,
+ threshold:float=300)->np.float64:
+"""Calculate daylight autonomy for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ threshold: Threshold value for daylight autonomy. Default: 300.
+
+ Returns:
+ A NumPy float of the daylight autonomy.
+ """
+ check_array_dim(array,1)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.size
+
+ returnnp.float64((array>=threshold).sum()/total_occ*100)
+
+
+
+
+[docs]
+defcda_array2d(
+ array:np.ndarray,total_occ:int=None,
+ threshold:float=300)->np.ndarray:
+"""Calculate continuos daylight autonomy for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ threshold: Threshold value for continuos daylight autonomy. Default: 300.
+
+ Returns:
+ A 1-dimensional NumPy array with the continuos daylight autonomy for
+ each row in the input array.
+ """
+ check_array_dim(array,2)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.shape[1]
+
+ cda=np.apply_along_axis(
+ cda_array1d,1,array,total_occ=total_occ,threshold=threshold)
+
+ returncda
+
+
+
+
+[docs]
+defcda_array1d(
+ array:np.ndarray,total_occ:int=None,
+ threshold:float=300)->np.float64:
+"""Calculate continuos daylight autonomy for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ threshold: Threshold value for continuos daylight autonomy. Default: 300.
+
+ Returns:
+ A NumPy float of the continuos daylight autonomy.
+ """
+ check_array_dim(array,1)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.size
+
+ returnnp.float64(
+ np.where(array>=threshold,1,array/threshold).sum()/total_occ*100)
+
+
+
+
+[docs]
+defudi_array2d(
+ array:np.ndarray,total_occ:int=None,min_t:float=100,
+ max_t:float=3000)->np.ndarray:
+"""Calculate useful daylight illuminance for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+ max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+
+ Returns:
+ A 1-dimensional NumPy array with the useful daylight illuminance for
+ each row in the input array.
+ """
+ check_array_dim(array,2)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.shape[1]
+
+ udi=np.apply_along_axis(
+ udi_array1d,1,array,total_occ=total_occ,min_t=min_t,max_t=max_t)
+
+ returnudi
+
+
+
+
+[docs]
+defudi_array1d(
+ array:np.ndarray,total_occ:int=None,min_t:float=100,
+ max_t:float=3000)->np.float64:
+"""Calculate useful daylight illuminance for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+ max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+
+ Returns:
+ A NumPy float of the useful daylight illuminance.
+ """
+ check_array_dim(array,1)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.size
+
+ returnnp.float64(((array>=min_t)&(array<=max_t)).sum()/total_occ*100)
+
+
+
+
+[docs]
+defudi_lower_array2d(
+ array:np.ndarray,total_occ:int=None,min_t:float=100,
+ sun_down_occ_hours:int=0)->np.ndarray:
+"""Calculate lower than useful daylight illuminance for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+ sun_down_occ_hours: Number of occupied hours where the sun is down.
+
+ Returns:
+ A 1-dimensional NumPy array with the lower than useful daylight
+ illuminance for each row in the input array.
+ """
+ check_array_dim(array,2)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.shape[1]
+
+ udi=np.apply_along_axis(
+ udi_lower_array1d,1,array,total_occ=total_occ,min_t=min_t,
+ sun_down_occ_hours=sun_down_occ_hours)
+
+ returnudi
+
+
+
+
+[docs]
+defudi_lower_array1d(
+ array:np.ndarray,total_occ:int=None,min_t:float=100,
+ sun_down_occ_hours:int=0)->np.float64:
+"""Calculate lower than useful daylight illuminance for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ min_t: Minimum threshold for useful daylight illuminance. Default: 100.
+ sun_down_occ_hours: Number of occupied hours where the sun is down.
+
+ Returns:
+ A NumPy float of the lower than useful daylight illuminance.
+ """
+ check_array_dim(array,1)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.size
+
+ ifmin_t==0:
+ returnnp.float64(0)
+
+ returnnp.float64(((array<min_t).sum()+sun_down_occ_hours)/total_occ*100)
+
+
+
+
+[docs]
+defudi_upper_array2d(
+ array:np.ndarray,total_occ:int=None,
+ max_t:float=3000)->np.ndarray:
+"""Calculate higher than useful daylight illuminance for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ max_t: Maximum threshold for useful daylight illuminance. Default: 3000.
+
+ Returns:
+ A 1-dimensional NumPy array with the higher than useful daylight
+ illuminance for each row in the input array.
+ """
+ check_array_dim(array,2)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.shape[1]
+
+ udi=np.apply_along_axis(
+ udi_upper_array1d,1,array,total_occ=total_occ,max_t=max_t)
+
+ returnudi
+
+
+
+
+[docs]
+defudi_upper_array1d(
+ array:np.ndarray,total_occ:int=None,
+ max_t:float=3000)->np.float64:
+"""Calculate higher than useful daylight illuminance for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ total_occ: Integer indicating the number of occupied hours. If not given any
+ input the number of occupied hours will be found by the array shape.
+ max_t: Maximum threshold for higher than useful daylight illuminance.
+ Default: 3000.
+
+ Returns:
+ A NumPy float of the higher than useful daylight illuminance.
+ """
+ check_array_dim(array,1)
+ iftotal_occisNone:
+ # set total_occ to number of columns in array
+ total_occ=array.size
+
+ returnnp.float64((array>max_t).sum()/total_occ*100)
+
+
+
+
+[docs]
+defsda_array2d(
+ array:np.ndarray,target_time:float=50,threshold:float=300,
+ total_occ:int=None)->np.ndarray:
+"""Calculate spatial daylight autonomy for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ target_time: A minimum threshold of occupied time (eg. 50% of the
+ time), above which a given sensor passes and contributes to the
+ spatial daylight autonomy. Defaults to 50.
+ threshold: Threshold value for daylight autonomy. Default: 300.
+ total_occ: Integer indicating the number of occupied hours. If not
+ given any input the number of occupied hours will be found by the
+ array shape, i.e., it is assumed that the array is filtered by
+ occupied hours.
+
+ Returns:
+ A NumPy float of the sDA as a percentage (decimal)
+ """
+ da=da_array2d(array,total_occ=total_occ,threshold=threshold)
+ sda=(da>=target_time).mean()
+
+ returnsda
+
+
+
+
+[docs]
+defase_array2d(
+ array:np.ndarray,occ_hours:int=250,
+ direct_threshold:float=1000)->Tuple[np.ndarray,np.ndarray]:
+"""Calculate annual sunlight exposure for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ occ_hours: The number of occupied hours that cannot receive more than
+ the direct_threshold. Defaults to 250.
+ direct_threshold: The threshold that determines if a sensor is overlit.
+ Defaults to 1000.
+
+ Returns:
+ A NumPy float of the ASE as a percentage (decimal).
+ """
+ check_array_dim(array,2)
+ h_above=(array>direct_threshold).sum(axis=1)
+ ase=(h_above>occ_hours).sum()/array.shape[0]*100
+
+ returnase,h_above
+
+
+
+
+[docs]
+defaverage_values_array2d(
+ array:np.ndarray,full_length:int=8760)->np.ndarray:
+"""Calculate average values for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ full_length: Integer to use as divisor.
+
+ Returns:
+ A 1-dimensional NumPy array with the average value for each row in the
+ input array.
+ """
+ check_array_dim(array,2)
+
+ avg_values=array.sum(axis=1)/full_length
+
+ returnavg_values
+
+
+
+
+[docs]
+defaverage_values_array1d(
+ array:np.ndarray,full_length:int=8760)->np.float64:
+"""Calculate average value for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ full_length: Integer to use as divisor.
+
+ Returns:
+ A NumPy float of the average value.
+ """
+ check_array_dim(array,1)
+
+ returnarray.sum()/full_length
+
+
+
+
+[docs]
+defcumulative_values_array2d(
+ array:np.ndarray,timestep:int=1,t_step_multiplier:float=1
+ )->np.ndarray:
+"""Calculate cumulative values for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ timestep: Integer for the timestep of the analysis.
+ t_step_multiplier: A value that will be multiplied with the timestep.
+
+ Returns:
+ A 1-dimensional NumPy array with the cumulative value for each row in
+ the input array.
+ """
+ check_array_dim(array,2)
+
+ cumulative_values=array.sum(axis=1)/(timestep*t_step_multiplier)
+
+ returncumulative_values
+
+
+
+
+[docs]
+defcumulative_values_array1d(
+ array:np.ndarray,timestep:int=1,t_step_multiplier:float=1
+ )->np.float64:
+"""Calculate daylight autonomy for a 1D NumPy array.
+
+ Args:
+ array: A 1D NumPy array.
+ timestep: Integer for the timestep of the analysis.
+ t_step_multiplier: A value that will be multiplied with the timestep.
+
+ Returns:
+ A NumPy float of the cumulative value.
+ """
+ check_array_dim(array,1)
+
+ returnarray.sum()/(timestep*t_step_multiplier)
+
+
+
+
+[docs]
+defpeak_values_array2d(
+ array:np.ndarray,coincident:bool=False
+ )->Tuple[np.ndarray,Union[int,None]]:
+"""Calculate peak values for a 2D NumPy array.
+
+ Args:
+ array: A 2D NumPy array.
+ coincident: Boolean to indicate whether output values represent the
+ peak value for each sensor throughout the entire analysis (False)
+ or they represent the highest overall value across each sensor grid
+ at a particular timestep (True).
+
+ Returns:
+ A 1-dimensional NumPy array with the peak value for each row in the
+ input array, and the index of the maximum value representing the
+ timestep in the array with the largest value.
+ """
+ check_array_dim(array,2)
+
+ max_i=None
+ ifcoincident:
+ array_summed=array.sum(axis=0)
+ ifnp.any(array_summed):
+ max_i=np.argmax(array_summed)
+ peak_values=array[:,max_i]
+ else:
+ peak_values=np.zeros(array.shape[0])
+ else:
+ ifnp.any(array):
+ peak_values=np.amax(array,axis=1)
+ else:
+ peak_values=np.zeros(array.shape[0])
+
+ returnpeak_values,max_i
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/reader.html b/docs/_modules/honeybee_radiance_postprocess/reader.html
new file mode 100644
index 00000000..014674b4
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/reader.html
@@ -0,0 +1,780 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.reader — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+defbinary_to_array(
+ binary_file:str,nrows:int=None,ncols:int=None,
+ ncomp:int=None,fmt=None,line_count:int=0)->np.ndarray:
+"""Read a Radiance binary file as a NumPy array.
+
+ Args:
+ binary_file: Path to binary Radiance file.
+ nrows: Number of rows in the Radiance file.
+ ncols: Number of columns in the Radiance file.
+ ncomp: Number of components of each element in the Radiance file.
+ fmt: Format of the Radiance file. Can be either "ascii", "float", or "double.
+ line_count: Number of lines to skip in the input file. Usually used to
+ skip the header.
+
+ Returns:
+ A NumPy array.
+ """
+ if(nrowsorncolsorncomporfmt)isNone:
+ # get nrows, ncols and header line count
+ nrows,ncols,ncomp,line_count,fmt=binary_mtx_dimension(binary_file)
+ withopen(binary_file,'rb')asreader:
+ # skip first n lines from reader
+ foriinrange(line_count):
+ reader.readline()
+
+ iffmt=='ascii':
+ array=np.loadtxt(reader,dtype=np.float32)
+ eliffmt=='float':
+ array=np.fromfile(reader,dtype=np.float32)
+ eliffmt=='double':
+ array=np.fromfile(reader,dtype=np.float64)
+
+ ifncomp!=1:
+ array=array.reshape(nrows,ncols,ncomp)
+ else:
+ array=array.reshape(nrows,ncols)
+
+ returnarray
+
+
+
+
+[docs]
+defascii_to_array(
+ ascii_file:str,nrows:int=None,ncols:int=None,
+ ncomp:int=None,line_count:int=0)->np.ndarray:
+"""Read a Radiance ascii file as a NumPy array.
+
+ Args:
+ ascii_file: Path to ascii Radiance file.
+ nrows: Number of rows in the Radiance file.
+ ncols: Number of columns in the Radiance file.
+ ncomp: Number of components of each element in the Radiance file.
+ line_count: Number of lines to skip in the input file. Usually used to
+ skip the header.
+
+ Returns:
+ A NumPy array.
+ """
+ withopen(ascii_file,'r')asreader:
+ if(nrowsorncolsorncomp)isNone:
+ # get nrows, ncols and header line count
+ # we can reuse binary_mtx_dimension though the input file is ascii
+ nrows,ncols,ncomp,line_count,fmt=binary_mtx_dimension(ascii_file)
+
+ array=np.loadtxt(reader,dtype=np.float32,skiprows=line_count)
+ ifncomp!=1:
+ array=array.reshape(nrows,ncols,ncomp)
+ else:
+ array=array.reshape(nrows,ncols)
+
+ returnarray
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/results/annual_daylight.html b/docs/_modules/honeybee_radiance_postprocess/results/annual_daylight.html
new file mode 100644
index 00000000..8a581634
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/results/annual_daylight.html
@@ -0,0 +1,1498 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.results.annual_daylight — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classAnnualDaylight(Results):
+"""Annual Daylight Results class.
+
+ Args:
+ folder: Path to results folder.
+ schedule: 8760 values as a list. Values must be either 0 or 1. Values of 1
+ indicates occupied hours. If no schedule is provided a default schedule
+ will be used. (Default: None).
+ load_arrays: Set to True to load all NumPy arrays. If False the arrays will be
+ loaded only once they are needed. In both cases the loaded array(s) will be
+ stored in a dictionary under the arrays property. (Default: False).
+
+ Properties:
+ * schedule
+ * occ_pattern
+ * total_occ
+ * sun_down_occ_hours
+ * occ_mask
+ * arrays
+ * valid_states
+ * datatype
+ """
+ def__init__(self,folder,schedule:list=None,load_arrays:bool=False):
+"""Initialize Results."""
+ Results.__init__(self,folder,datatype=Illuminance('Illuminance'),
+ schedule=schedule,unit='lux',load_arrays=load_arrays)
+
+
+[docs]
+ defdaylight_autonomy(
+ self,threshold:float=300,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_metric:
+"""Calculate daylight autonomy.
+
+ Args:
+ threshold: Threshold value for daylight autonomy. Defaults to 300.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the daylight autonomy and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ da=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ results=da_array2d(
+ array_filter,total_occ=self.total_occ,threshold=threshold)
+ else:
+ results=np.zeros(grid_info['count'])
+ da.append(results)
+
+ returnda,grids_info
+
+
+
+[docs]
+ defcontinuous_daylight_autonomy(
+ self,threshold:float=300,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_metric:
+"""Calculate continuous daylight autonomy.
+
+ Args:
+ threshold: Threshold value for daylight autonomy. Defaults to 300.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the continuous daylight autonomy and grid
+ information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ cda=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ results=cda_array2d(
+ array_filter,total_occ=self.total_occ,threshold=threshold)
+ else:
+ results=np.zeros(grid_info['count'])
+ cda.append(results)
+
+ returncda,grids_info
+
+
+
+[docs]
+ defuseful_daylight_illuminance(
+ self,min_t:float=100,max_t:float=3000,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_metric:
+"""Calculate useful daylight illuminance.
+
+ Args:
+ min_t: Minimum threshold for useful daylight illuminance. Defaults to 100.
+ max_t: Maximum threshold for useful daylight illuminance. Defaults to 3000.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the useful daylight illuminance and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ udi=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ results=udi_array2d(
+ array_filter,total_occ=self.total_occ,min_t=min_t,max_t=max_t)
+ else:
+ results=np.zeros(grid_info['count'])
+ udi.append(results)
+
+ returnudi,grids_info
+
+
+
+[docs]
+ defuseful_daylight_illuminance_lower(
+ self,min_t:float=100,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_metric:
+"""Calculate lower than useful daylight illuminance.
+
+ Args:
+ min_t: Minimum threshold for useful daylight illuminance. Defaults to 100.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the lower than useful daylight illuminance and
+ grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ sun_down_occ_hours=self.sun_down_occ_hours
+
+ udi_lower=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ results=udi_lower_array2d(
+ array_filter,total_occ=self.total_occ,
+ min_t=min_t,sun_down_occ_hours=sun_down_occ_hours)
+ else:
+ results=np.zeros(grid_info['count'])
+ udi_lower.append(results)
+
+ returnudi_lower,grids_info
+
+
+
+[docs]
+ defuseful_daylight_illuminance_upper(
+ self,max_t:float=3000,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_metric:
+"""Calculate higher than useful daylight illuminance.
+
+ Args:
+ max_t: Maximum threshold for useful daylight illuminance. Defaults to 3000.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the higher than useful daylight illuminance and
+ grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ udi_upper=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ results=udi_upper_array2d(
+ array_filter,total_occ=self.total_occ,max_t=max_t)
+ else:
+ results=np.zeros(grid_info['count'])
+ udi_upper.append(results)
+
+ returnudi_upper,grids_info
+
+
+
+[docs]
+ defannual_metrics(
+ self,threshold:float=300,min_t:float=100,
+ max_t:float=3000,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_daylight_metrics:
+"""Calculate multiple annual daylight metrics.
+
+ This method will calculate the following metrics:
+ * Daylight autonomy
+ * Continuous daylight autonomy
+ * Useful daylight illuminance
+ * Lower than useful daylight illuminance
+ * Higher than useful daylight illuminance
+
+ Args:
+ threshold: Threshold value for daylight autonomy. Defaults to 300.
+ min_t: Minimum threshold for useful daylight illuminance. Defaults to 100.
+ max_t: Maximum threshold for useful daylight illuminance. Defaults to 3000.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the five annual daylight metrics and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ sun_down_occ_hours=self.sun_down_occ_hours
+
+ da=[]
+ cda=[]
+ udi=[]
+ udi_lower=[]
+ udi_upper=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ da_results=da_array2d(
+ array_filter,total_occ=self.total_occ,threshold=threshold)
+ cda_results=cda_array2d(
+ array_filter,total_occ=self.total_occ,threshold=threshold)
+ udi_results=udi_array2d(
+ array_filter,total_occ=self.total_occ,min_t=min_t,max_t=max_t)
+ udi_lower_results=udi_lower_array2d(
+ array_filter,total_occ=self.total_occ,min_t=min_t,
+ sun_down_occ_hours=sun_down_occ_hours)
+ udi_upper_results=udi_upper_array2d(
+ array_filter,total_occ=self.total_occ,max_t=max_t)
+ else:
+ da_results=cda_results=udi_results=udi_lower_results= \
+ udi_upper_results=np.zeros(grid_info['count'])
+ da.append(da_results)
+ cda.append(cda_results)
+ udi.append(udi_results)
+ udi_lower.append(udi_lower_results)
+ udi_upper.append(udi_upper_results)
+
+ returnda,cda,udi,udi_lower,udi_upper,grids_info
+
+
+
+[docs]
+ defannual_metrics_to_folder(
+ self,target_folder:str,threshold:float=300,
+ min_t:float=100,max_t:float=3000,states:DynamicSchedule=None,
+ grids_filter:str='*'):
+"""Calculate and write multiple annual daylight metrics to a folder.
+
+ This method will calculate the following metrics:
+ * Daylight autonomy
+ * Continuous daylight autonomy
+ * Useful daylight illuminance
+ * Lower than useful daylight illuminance
+ * Higher than useful daylight illuminance
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ threshold: Threshold value for daylight autonomy. Defaults to 300.
+ min_t: Minimum threshold for useful daylight illuminance. Defaults to 100.
+ max_t: Maximum threshold for useful daylight illuminance. Defaults to 3000.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ da,cda,udi,udi_lower,udi_upper,grids_info=self.annual_metrics(
+ threshold=threshold,min_t=min_t,max_t=max_t,states=states,
+ grids_filter=grids_filter)
+
+ pattern={
+ 'da':da,'cda':cda,'udi_lower':udi_lower,'udi':udi,
+ 'udi_upper':udi_upper
+ }
+ formetric,datainpattern.items():
+ metric_folder=folder.joinpath(metric)
+ extension=metric.split('_')[0]
+ forcount,grid_infoinenumerate(grids_info):
+ d=data[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.{extension}')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ formetricinpattern.keys():
+ info_file=folder.joinpath(metric,'grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+ metric_info_dict=_annual_daylight_vis_metadata()
+ formetric,datainmetric_info_dict.items():
+ vis_metadata_file=folder.joinpath(metric,'vis_metadata.json')
+ vis_metadata_file.write_text(json.dumps(data,indent=4))
+
+
+
+[docs]
+ defspatial_daylight_autonomy(
+ self,threshold:float=300,target_time:float=50,
+ states:DynamicSchedule=None,grids_filter:str='*'
+ )->type_hints.spatial_daylight_autonomy:
+"""Calculate spatial daylight autonomy.
+
+ Note: This component will only output a LEED compliant sDA if you've
+ run the simulation with blinds and blinds schedules as per the
+ IES-LM-83-12. Use the states option to calculate a LEED compliant sDA.
+
+ Args:
+ threshold: Threshold value for daylight autonomy. Defaults to 300.
+ target_time: A minimum threshold of occupied time (eg. 50% of the
+ time), above which a given sensor passes and contributes to the
+ spatial daylight autonomy. Defaults to 50.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the spatial daylight autonomy and grid
+ information.
+ """
+ da,grids_info=self.daylight_autonomy(
+ threshold=threshold,states=states,grids_filter=grids_filter)
+
+ sda=[]
+ forarrayinda:
+ sda.append((array>=target_time).mean())
+
+ returnsda,grids_info
+
+
+
+[docs]
+ defannual_sunlight_exposure(
+ self,direct_threshold:float=1000,occ_hours:int=250,
+ states:DynamicSchedule=None,grids_filter:str='*'
+ )->type_hints.annual_sunlight_exposure:
+"""Calculate annual sunlight exposure.
+
+ Args:
+ direct_threshold: The threshold that determines if a sensor is
+ overlit. Defaults to 1000.
+ occ_hours: The number of occupied hours that cannot receive more
+ than the direct_threshold. Defaults to 250.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the annual sunlight exposure, the number of
+ hours that exceeds the direct threshold for each sensor, and
+ grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ ase=[]
+ hours_above=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(
+ grid_info,states=states,res_type='direct')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ results,h_above=ase_array2d(
+ array_filter,occ_hours=occ_hours,
+ direct_threshold=direct_threshold)
+ else:
+ results=np.float64(0)
+ h_above=np.zeros(grid_info['count'])
+ ase.append(results)
+ hours_above.append(h_above)
+
+ returnase,hours_above,grids_info
+
+
+
+[docs]
+ defannual_sunlight_exposure_to_folder(
+ self,target_folder:str,direct_threshold:float=1000,
+ occ_hours:int=250,states:DynamicSchedule=None,
+ grids_filter:str='*'):
+"""Calculate and write annual sunlight exposure to a folder.
+
+ Args:
+ direct_threshold: The threshold that determines if a sensor is
+ overlit. Defaults to 1000.
+ occ_hours: The number of occupied hours that cannot receive more
+ than the direct_threshold. Defaults to 250.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ ase,hours_above,grids_info=self.annual_sunlight_exposure(
+ direct_threshold=direct_threshold,occ_hours=occ_hours,
+ states=states,grids_filter=grids_filter
+ )
+
+ pattern={'ase':ase,'hours_above':hours_above}
+ formetric,datainpattern.items():
+ metric_folder=folder.joinpath(metric)
+ ifmetric=='hours_above':
+ extension='res'
+ else:
+ extension='ase'
+ forcount,grid_infoinenumerate(grids_info):
+ d=data[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.{extension}')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ ifmetric=='hours_above':
+ np.savetxt(output_file,d,fmt='%i')
+ elifmetric=='ase':
+ output_file.write_text('%.2f'%d)
+
+ formetricinpattern.keys():
+ info_file=folder.joinpath(metric,'grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+
+[docs]
+ defdaylight_control_schedules(
+ self,states:DynamicSchedule=None,grids_filter:str='*',
+ base_schedule:list=None,ill_setpoint:float=300,
+ min_power_in:float=0.3,min_light_out:float=0.2,
+ off_at_min:bool=False
+ )->Tuple[List[np.ndarray],List[dict]]:
+"""Generate electric lighting schedules from annual daylight results.
+
+ Such controls will dim the lights according to whether the illuminance values
+ at the sensor locations are at a target illuminance setpoint. The results can be
+ used to account for daylight controls in energy simulations.
+
+ This function will generate one schedule per sensor grid in the simulation. Each
+ grid should have sensors at the locations in space where daylight dimming sensors
+ are located. Grids with one, two, or more sensors can be used to model setups
+ where fractions of each room are controlled by different sensors. If the sensor
+ grids are distributed over the entire floor of the rooms, the resulting schedules
+ will be idealized, where light dimming has been optimized to supply the minimum
+ illuminance setpoint everywhere in the room.
+
+ Args:
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ base_schedule: A list of 8760 fractional values for the lighting schedule
+ representing the usage of lights without any daylight controls. The
+ values of this schedule will be multiplied by the hourly dimming
+ fraction to yield the output lighting schedules. If None, a schedule
+ from 9AM to 5PM on weekdays will be used. (Default: None).
+ ill_setpoint: A number for the illuminance setpoint in lux beyond which
+ electric lights are dimmed if there is sufficient daylight.
+ Some common setpoints are listed below. (Default: 300 lux).
+
+ * 50 lux - Corridors and hallways.
+ * 150 lux - Computer work spaces (screens provide illumination).
+ * 300 lux - Paper work spaces (reading from surfaces that need illumination).
+ * 500 lux - Retail spaces or museums illuminating merchandise/artifacts.
+ * 1000 lux - Operating rooms and workshops where light is needed for safety.
+
+ min_power_in: A number between 0 and 1 for the the lowest power the lighting
+ system can dim down to, expressed as a fraction of maximum
+ input power. (Default: 0.3).
+ min_light_out: A number between 0 and 1 the lowest lighting output the lighting
+ system can dim down to, expressed as a fraction of maximum light
+ output. Note that setting this to 1 means lights aren't dimmed at
+ all until the illuminance setpoint is reached. This can be used to
+ approximate manual light-switching behavior when used in conjunction
+ with the off_at_min input below. (Default: 0.2).
+ off_at_min: Boolean to note whether lights should switch off completely when
+ they get to the minimum power input. (Default: False).
+
+ Returns:
+ A tuple with two values.
+
+ - schedules: A list of lists where each sub-list represents an electric
+ lighting dimming schedule for a sensor grid.
+
+ - grids_info: A list of grid information.
+ """
+ # process the base schedule input into a list of values
+ ifbase_scheduleisNone:
+ base_schedule=occupancy_schedule_8_to_6(timestep=self.timestep)
+ base_schedule=np.array(base_schedule)
+
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ sun_up_hours=[int(h)forhinself.sun_up_hours]
+
+ dim_fracts=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(
+ grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ fract_list=array_to_dimming_fraction(
+ array,sun_up_hours,ill_setpoint,min_power_in,
+ min_light_out,off_at_min
+ )
+ else:
+ fract_list=np.ones(8760)
+ dim_fracts.append(fract_list)
+
+ schedules=[]
+ forgrid_info,dim_fractinzip(grids_info,dim_fracts):
+ sch_vals=base_schedule*dim_fract
+ schedules.append(sch_vals)
+
+ returnschedules,grids_info
+
+
+
+[docs]
+ defdaylight_control_schedules_to_folder(
+ self,target_folder:str,states:DynamicSchedule=None,
+ grids_filter:str='*',base_schedule:list=None,
+ ill_setpoint:float=300,min_power_in:float=0.3,
+ min_light_out:float=0.2,off_at_min:bool=False):
+"""Generate electric lighting schedules from annual daylight results and
+ write the schedules to a folder.
+
+ Such controls will dim the lights according to whether the illuminance values
+ at the sensor locations are at a target illuminance setpoint. The results can be
+ used to account for daylight controls in energy simulations.
+
+ This function will generate one schedule per sensor grid in the simulation. Each
+ grid should have sensors at the locations in space where daylight dimming sensors
+ are located. Grids with one, two, or more sensors can be used to model setups
+ where fractions of each room are controlled by different sensors. If the sensor
+ grids are distributed over the entire floor of the rooms, the resulting schedules
+ will be idealized, where light dimming has been optimized to supply the minimum
+ illuminance setpoint everywhere in the room.
+
+ Args:
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ base_schedule: A list of 8760 fractional values for the lighting schedule
+ representing the usage of lights without any daylight controls. The
+ values of this schedule will be multiplied by the hourly dimming
+ fraction to yield the output lighting schedules. If None, a schedule
+ from 9AM to 5PM on weekdays will be used. (Default: None).
+ ill_setpoint: A number for the illuminance setpoint in lux beyond which
+ electric lights are dimmed if there is sufficient daylight.
+ Some common setpoints are listed below. (Default: 300 lux).
+
+ * 50 lux - Corridors and hallways.
+ * 150 lux - Computer work spaces (screens provide illumination).
+ * 300 lux - Paper work spaces (reading from surfaces that need illumination).
+ * 500 lux - Retail spaces or museums illuminating merchandise/artifacts.
+ * 1000 lux - Operating rooms and workshops where light is needed for safety.
+
+ min_power_in: A number between 0 and 1 for the the lowest power the lighting
+ system can dim down to, expressed as a fraction of maximum
+ input power. (Default: 0.3).
+ min_light_out: A number between 0 and 1 the lowest lighting output the lighting
+ system can dim down to, expressed as a fraction of maximum light
+ output. Note that setting this to 1 means lights aren't dimmed at
+ all until the illuminance setpoint is reached. This can be used to
+ approximate manual light-switching behavior when used in conjunction
+ with the off_at_min input below. (Default: 0.2).
+ off_at_min: Boolean to note whether lights should switch off completely when
+ they get to the minimum power input. (Default: False).
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ schedules,grids_info=self.daylight_control_schedules(
+ states=states,grids_filter=grids_filter,
+ base_schedule=base_schedule,ill_setpoint=ill_setpoint,
+ min_power_in=min_power_in,min_light_out=min_light_out,
+ off_at_min=off_at_min)
+
+ schedule_folder=folder.joinpath('control_schedules')
+
+ forcount,grid_infoinenumerate(grids_info):
+ d=schedules[count]
+ full_id=grid_info['full_id']
+ output_file=schedule_folder.joinpath(f'{full_id}.txt')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ info_file=schedule_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+
+[docs]
+ defannual_uniformity_ratio(
+ self,threshold:float=0.5,states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_uniformity_ratio:
+"""Calculate annual uniformity ratio.
+
+ Args:
+ threshold: A threshold for the uniformity ratio. Defaults to 0.5.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the annual uniformity ratio, annual
+ data collections, and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ analysis_period=AnalysisPeriod(timestep=self.timestep)
+
+ data_collections=[]
+ annual_uniformity_ratio=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ su_min_array=array.min(axis=0)
+ su_mean_array=array.mean(axis=0)
+ su_uniformity_ratio=su_min_array/su_mean_array
+
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=self.occ_mask)
+ min_array=array_filter.min(axis=0)
+ mean_array=array_filter.mean(axis=0)
+ uniformity_ratio=min_array/mean_array
+ annual_uniformity_ratio.append(
+ np.float64(
+ (uniformity_ratio>=threshold).sum()/self.total_occ*100
+ )
+ )
+ else:
+ su_uniformity_ratio=np.zeros(len(self.sun_up_hours))
+ annual_uniformity_ratio.append(np.float64(0))
+
+ annual_array= \
+ self.values_to_annual(
+ self.sun_up_hours,su_uniformity_ratio,self.timestep)
+ header=Header(Fraction(),'%',analysis_period)
+ header.metadata['sensor grid']=grid_info['full_id']
+ data_collections.append(
+ HourlyContinuousCollection(header,annual_array.tolist()))
+
+ returnannual_uniformity_ratio,data_collections,grids_info
+
+
+
+[docs]
+ defannual_uniformity_ratio_to_folder(
+ self,target_folder:str,threshold:float=0.5,
+ states:DynamicSchedule=None,grids_filter:str='*'
+ ):
+"""Calculate annual uniformity ratio and write it to a folder.
+
+ Args:
+ target_folder: Folder path to write annual uniformity ratio in.
+ threshold: A threshold for the uniformity ratio. Defaults to 0.5.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the daylight autonomy and grid information.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ annual_uniformity_ratio,data_collections,grids_info= \
+ self.annual_uniformity_ratio(threshold=threshold,states=states,
+ grids_filter=grids_filter)
+
+ datacollection_folder=folder.joinpath('datacollections')
+ uniformity_ratio_folder=folder.joinpath('uniformity_ratio')
+
+ foraur,data_collection,grid_infoin \
+ zip(annual_uniformity_ratio,data_collections,grids_info):
+ grid_id=grid_info['full_id']
+ data_dict=data_collection.to_dict()
+ data_file=datacollection_folder.joinpath(f'{grid_id}.json')
+ data_file.parent.mkdir(parents=True,exist_ok=True)
+ data_file.write_text(json.dumps(data_dict))
+
+ aur_file=uniformity_ratio_folder.joinpath(f'{grid_id}.ur')
+ aur_file.parent.mkdir(parents=True,exist_ok=True)
+ aur_file.write_text(str(round(aur,2)))
+
+ info_file=uniformity_ratio_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+
+[docs]
+ defdynamic_schedule_from_sensor_maximum(
+ self,sensor_index:dict,grids_filter:str='*',
+ maximum:float=3000,res_type:str='total')->DynamicSchedule:
+"""Calculate a DynamicSchedule from a sensor and a maximum allowed
+ illuminance.
+
+ Args:
+ sensor_index: A dictionary with grids as keys and a list of sensor
+ indices as values. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ maximum: A float value of the maximum illuminance allowed for the
+ sensor.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ DynamicSchedule object.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ aperture_group_schedules=[]
+ forgrid_infoingrids_info:
+ control_sensor=sensor_index.get(grid_info['full_id'],None)
+ ifcontrol_sensorisNone:
+ continue
+ assertlen(control_sensor)==1,('Expected one control sensor for '
+ f'grid {grid_info["name"]}. Received {len(control_sensor)} '
+ 'control sensors.')
+ control_sensor_index=control_sensor[0]
+
+ combinations=self._get_state_combinations(grid_info)
+
+ array_list_combinations=[]
+ forcombinationincombinations:
+ combination_arrays=[]
+ forlight_path,state_indexincombination.items():
+ array=self._get_array(
+ grid_info,light_path,state=state_index,res_type=res_type)
+ sensor_array=array[control_sensor_index,:]
+ combination_arrays.append(sensor_array)
+ combination_array=sum(combination_arrays)
+ array_list_combinations.append(combination_array)
+ array_combinations=np.array(array_list_combinations)
+ array_combinations[array_combinations>maximum]=-np.inf
+ max_indices=array_combinations.argmax(axis=0)
+ combinations=[combinations[idx]foridxinmax_indices]
+
+ states_schedule=defaultdict(list)
+ forcombinationincombinations:
+ forlight_path,state_indexincombination.items():
+ iflight_path!='__static_apertures__':
+ states_schedule[light_path].append(state_index)
+
+ # map states to 8760 values
+ forlight_path,state_indicesinstates_schedule.items():
+ mapped_states=self.values_to_annual(
+ self.sun_up_hours,state_indices,self.timestep)
+ mapped_states=mapped_states.astype(int)
+ aperture_group_schedules.append(
+ ApertureGroupSchedule(light_path,mapped_states.tolist()))
+
+ dyn_sch=DynamicSchedule.from_group_schedules(aperture_group_schedules)
+
+ returndyn_sch
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/results/annual_irradiance.html b/docs/_modules/honeybee_radiance_postprocess/results/annual_irradiance.html
new file mode 100644
index 00000000..bad65a45
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/results/annual_irradiance.html
@@ -0,0 +1,903 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.results.annual_irradiance — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classAnnualIrradiance(Results):
+"""Annual Daylight Results class.
+
+ Args:
+ folder: Path to results folder.
+ schedule: 8760 values as a list. Values must be either 0 or 1. Values of 1
+ indicates occupied hours. If no schedule is provided a default schedule
+ will be used. (Default: None).
+ load_arrays: Set to True to load all NumPy arrays. If False the arrays will be
+ loaded only once they are needed. In both cases the loaded array(s) will be
+ stored in a dictionary under the arrays property. (Default: False).
+
+ Properties:
+ * schedule
+ * occ_pattern
+ * total_occ
+ * sun_down_occ_hours
+ * occ_mask
+ * arrays
+ * valid_states
+ * datatype
+ """
+ def__init__(self,folder,schedule:list=None,load_arrays:bool=False):
+"""Initialize Results."""
+ Results.__init__(self,folder,datatype=EnergyFlux('Irradiance'),
+ schedule=schedule,unit='W/m2',load_arrays=load_arrays)
+
+
+[docs]
+ defcumulative_values(
+ self,hoys:list=[],states:DynamicSchedule=None,
+ t_step_multiplier:float=1000,grids_filter:str='*',
+ res_type:str='total')->type_hints.cumulative_values:
+"""Get cumulative values for each sensor over a given period.
+
+ The hoys input can be used to filter the data for a particular time
+ period.
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ t_step_multiplier: A value that will be multiplied with the timestep.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with the cumulative value for each sensor and grid
+ information.
+ """
+ cumulative_values,grids_info= \
+ super(AnnualIrradiance,self).cumulative_values(
+ hoys=hoys,states=states,t_step_multiplier=t_step_multiplier,
+ grids_filter=grids_filter,res_type=res_type
+ )
+
+ returncumulative_values,grids_info
+
+
+
+[docs]
+ defcumulative_values_to_folder(
+ self,target_folder:str,hoys:list=[],
+ states:DynamicSchedule=None,t_step_multiplier:float=1000,
+ grids_filter:str='*',res_type:str='total'):
+"""Get cumulative values for each sensor over a given period and write
+ the values to a folder.
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ t_step_multiplier: A value that will be multiplied with the timestep.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+ """
+ super(AnnualIrradiance,self).cumulative_values_to_folder(
+ target_folder,hoys=hoys,states=states,
+ t_step_multiplier=t_step_multiplier,grids_filter=grids_filter,
+ res_type=res_type
+ )
+
+
+
+[docs]
+ defannual_metrics(
+ self,hoys:list=[],states:DynamicSchedule=None,
+ grids_filter:str='*')->type_hints.annual_irradiance_metrics:
+"""Calculate multiple annual irradiance metrics.
+
+ This method will calculate the following metrics:
+ * Average Irradiance (W/m2)
+ * Peak Irradiance (W/m2)
+ * Cumulative Radiation (kWh/m2)
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ Tuple: A tuple with the three annual irradiance metrics and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ mask=hoys_mask(self.sun_up_hours,hoys)
+ full_length=len(self.study_hours)
+
+ average=[]
+ peak=[]
+ cumulative=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type='total')
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=mask)
+ average_results=average_values_array2d(
+ array_filter,full_length=full_length)
+ peak_results,max_i=peak_values_array2d(
+ array_filter)
+ cumulative_results=cumulative_values_array2d(
+ array_filter,self.timestep,1000)
+ else:
+ average_results=peak_results=cumulative_results= \
+ np.zeros(grid_info['count'])
+ average.append(average_results)
+ peak.append(peak_results)
+ cumulative.append(cumulative_results)
+
+ returnaverage,peak,cumulative,grids_info
+
+
+
+[docs]
+ defannual_metrics_to_folder(
+ self,target_folder:str,hoys:list=[],
+ states:DynamicSchedule=None,grids_filter:str='*'):
+"""Calculate and write multiple annual irradiance metrics to a folder.
+
+ This command generates 3 files for each input grid.
+ * average_irradiance/{grid-name}.res -- Average Irradiance (W/m2)
+ * peak_irradiance/{grid-name}.res -- Peak Irradiance (W/m2)
+ * cumulative_radiation/{grid-name}.res -- Cumulative Radiation (kWh/m2)
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ average,peak,cumulative,grids_info=self.annual_metrics(
+ hoys=hoys,states=states,grids_filter=grids_filter)
+
+ pattern={
+ 'average_irradiance':average,'peak_irradiance':peak,
+ 'cumulative_radiation':cumulative,
+ }
+ formetric,datainpattern.items():
+ metric_folder=folder.joinpath(metric)
+ forcount,grid_infoinenumerate(grids_info):
+ d=data[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.res')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ formetricinpattern.keys():
+ info_file=folder.joinpath(metric,'grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+ metric_info_dict=_annual_irradiance_vis_metadata()
+ formetric,datainmetric_info_dict.items():
+ vis_metadata_file=folder.joinpath(metric,'vis_metadata.json')
+ vis_metadata_file.write_text(json.dumps(data,indent=4))
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/results/results.html b/docs/_modules/honeybee_radiance_postprocess/results/results.html
new file mode 100644
index 00000000..b66cefa5
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/results/results.html
@@ -0,0 +1,2121 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.results.results — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Source code for honeybee_radiance_postprocess.results.results
+"""Post-processing Results class."""
+importjson
+frompathlibimportPath
+fromitertoolsimportislice,cycle
+fromtypingimportTuple,Union,List
+importnumpyasnp
+importitertools
+
+fromladybug.analysisperiodimportAnalysisPeriod
+fromladybug.datacollectionimportHourlyContinuousCollection
+fromladybug.datatype.genericimportGenericType
+fromladybug.datatype.baseimportDataTypeBase
+fromladybug.dtimportDateTime
+fromladybug.headerimportHeader
+
+from..annualimportoccupancy_schedule_8_to_6
+from..metricsimport(average_values_array2d,cumulative_values_array2d,
+ peak_values_array2d)
+from..utilimportfilter_array,hoys_mask,check_array_dim, \
+ _filter_grids_by_pattern
+from..importtype_hints
+from..dynamicimportDynamicSchedule,ApertureGroupSchedule
+
+
+class_ResultsFolder(object):
+"""Base class for ResultsFolder.
+
+ This class includes properties that are independent of the results.
+
+ Args:
+ folder: Path to results folder.
+
+ Properties:
+ * folder
+ * grids_info
+ * sun_up_hours
+ * sun_down_hours
+ * light_paths
+ * default_states
+ * grid_states
+ * timestep
+ * study_hours
+
+ """
+ __slots__=('_folder','_grids_info','_sun_up_hours','_sun_down_hours',
+ '_sun_up_hours_mask','_sun_down_hours_mask','_datetimes',
+ '_light_paths','_default_states','_grid_states','_timestep',
+ '_study_hours')
+
+ def__init__(self,folder:Union[str,Path]):
+"""Initialize ResultsFolder."""
+ self._folder=Path(folder).absolute().as_posix()
+ self._timestep,self._study_hours=self._get_study_info()
+ self.grids_info=self._get_grids_info()
+ self.sun_up_hours=self._get_sun_up_hours()
+ self._sun_up_hours_mask=self._get_sun_up_hours_mask()
+ self._sun_down_hours_mask=self._get_sun_down_hours_mask()
+ self._datetimes=self._get_datetimes()
+ self._light_paths=self._get_light_paths()
+ self._default_states=self._get_default_states()
+ self._grid_states=self._get_grid_states()
+
+ @property
+ deffolder(self):
+"""Return full path to results folder as a string."""
+ returnself._folder
+
+ @property
+ defgrids_info(self):
+"""Return grids information as list of dictionaries for each grid."""
+ returnself._grids_info
+
+ @grids_info.setter
+ defgrids_info(self,grids_info):
+ assertisinstance(grids_info,list), \
+ f'Grids information must be a list. Got object of type: {type(grids_info)}.'
+ forgrid_infoingrids_info:
+ assertisinstance(grid_info,dict), \
+ 'Object in grids information must be a dictionary. ' \
+ f'Got object of type {type(grid_info)}.'
+ if'light_path'ingrid_info.keys():
+ _grid_info=[]
+ forlight_pathingrid_info['light_path']:
+ ifPath(self.folder,light_path[0]).exists():
+ _grid_info.append((light_path))
+ grid_info['light_path']=_grid_info
+ ifnotgrid_info['light_path']:
+ # if light path is empty
+ grid_info['light_path']=[['__static_apertures__']]
+ else:
+ # if light path key is nonexistent
+ grid_info['light_path']=[['__static_apertures__']]
+ self._grids_info=grids_info
+
+ @property
+ defsun_up_hours(self):
+"""Return sun up hours."""
+ returnself._sun_up_hours
+
+ @sun_up_hours.setter
+ defsun_up_hours(self,sun_up_hours):
+ assertisinstance(sun_up_hours,list), \
+ f'Sun up hours must be a list. Got object of type: {type(sun_up_hours)}'
+ self._sun_up_hours=sun_up_hours
+ self.sun_down_hours=np.setdiff1d(self.study_hours,sun_up_hours).tolist()
+
+ @property
+ defsun_up_hours_mask(self):
+"""Return sun up hours masking array."""
+ returnself._sun_up_hours_mask
+
+ @property
+ defsun_down_hours(self):
+"""Return sun down hours."""
+ returnself._sun_down_hours
+
+ @sun_down_hours.setter
+ defsun_down_hours(self,sun_down_hours):
+ assertisinstance(sun_down_hours,list), \
+ f'Sun down hours must be a list. Got object of type: {type(sun_down_hours)}'
+ self._sun_down_hours=sun_down_hours
+
+ @property
+ defsun_down_hours_mask(self):
+"""Return sun down hours masking array."""
+ returnself._sun_down_hours_mask
+
+ @property
+ defdatetimes(self):
+"""Return DateTimes for sun up hours."""
+ returnself._datetimes
+
+ @property
+ deflight_paths(self):
+"""Return the identifiers of the light paths."""
+ returnself._light_paths
+
+ @property
+ defdefault_states(self):
+"""Return default states as a dictionary."""
+ returnself._default_states
+
+ @property
+ defgrid_states(self):
+"""Return grid states as a dictionary."""
+ returnself._grid_states
+
+ @property
+ deftimestep(self):
+"""Return timestep as an integer."""
+ returnself._timestep
+
+ @property
+ defstudy_hours(self):
+"""Return study hours as a list."""
+ returnself._study_hours
+
+ def_get_light_paths(self)->list:
+"""Find all light paths in grids_info."""
+ lp=[]
+ forgrid_infoinself.grids_info:
+ try:
+ light_paths=grid_info['light_path']
+ exceptKeyError:
+ grid_info['light_path']=[['__static_apertures__']]
+ light_paths=grid_info['light_path']
+ forlight_pathinlight_paths:
+ foreleminlight_path:
+ ifeleminlp:
+ continue
+ ifelem=='__static_apertures__':
+ lp.insert(0,elem)
+ else:
+ lp.append(elem)
+ ifnotlight_pathsand'__static_apertures__'notinlp:
+ lp.insert(0,'__static_apertures__')
+
+ returnlp
+
+ def_get_default_states(self)->dict:
+"""Set default state to 0 for all light paths."""
+ default_states={}
+ forlight_pathinself.light_paths:
+ default_states[light_path]=[0]
+ returndefault_states
+
+ def_get_grid_states(self)->dict:
+"""Read grid_states.json if available."""
+ info=Path(self.folder,'grid_states.json')
+ ifinfo.is_file():
+ withopen(info)asdata_f:
+ data=json.load(data_f)
+ returndata
+ else:
+ # only static results
+ return{}
+
+ def_get_study_info(self)->Tuple[int,list]:
+"""Read study info file."""
+ study_info_file=Path(self.folder).joinpath('study_info.json')
+ ifstudy_info_file.exists():
+ withopen(study_info_file)asfile:
+ study_info=json.load(file)
+ ifstudy_info['timestep']==1:
+ study_info['study_hours']= \
+ list(map(int,study_info['study_hours']))
+ else:
+ study_info={}
+ study_info['timestep']=1
+ study_info['study_hours']=AnalysisPeriod().hoys
+
+ returnstudy_info['timestep'],study_info['study_hours']
+
+ def_get_datetimes(self)->List[DateTime]:
+"""Get a list of DateTimes of the sun up hours."""
+ datetimes=[
+ DateTime.from_hoy(hoy)forhoyinlist(map(float,self.sun_up_hours))
+ ]
+
+ returndatetimes
+
+ def_get_grids_info(self)->List[dict]:
+"""Get grids info from folder."""
+ info=Path(self.folder,'grids_info.json')
+ withopen(info)asdata_f:
+ grids=json.load(data_f)
+
+ returngrids
+
+ def_get_sun_up_hours(self)->List[float]:
+"""Get sun up hours from folder."""
+ suh_fp=Path(self.folder,'sun-up-hours.txt')
+ sun_up_hours=np.loadtxt(suh_fp,dtype=float).tolist()
+ ifself.timestep==1:
+ sun_up_hours=list(map(int,sun_up_hours))
+
+ returnsun_up_hours
+
+ def_get_sun_up_hours_mask(self)->List[int]:
+"""Get a sun up hours masking array of the study hours."""
+ sun_up_hours_mask= \
+ np.where(np.isin(self.study_hours,self.sun_up_hours))[0]
+
+ returnsun_up_hours_mask
+
+ def_get_sun_down_hours_mask(self)->List[int]:
+"""Get a sun down hours masking array of the study hours."""
+ sun_down_hours_mask= \
+ np.where(~np.isin(self.study_hours,self.sun_up_hours))[0]
+
+ returnsun_down_hours_mask
+
+ def__repr__(self):
+ returnf'{self.__class__.__name__}: {self.folder}'
+
+
+
+[docs]
+classResults(_ResultsFolder):
+"""Results class.
+
+ Args:
+ folder: Path to results folder.
+ schedule: 8760 values as a list. Values must be either 0 or 1. Values of 1
+ indicates occupied hours. If no schedule is provided a default schedule
+ will be used. (Default: None).
+ load_arrays: Set to True to load all NumPy arrays. If False the arrays will be
+ loaded only once they are needed. In both cases the loaded array(s) will be
+ stored in a dictionary under the arrays property. (Default: False).
+
+ Properties:
+ * schedule
+ * occ_pattern
+ * total_occ
+ * sun_down_occ_hours
+ * occ_mask
+ * arrays
+ * valid_states
+ * datatype
+ * unit
+ """
+ __slots__=('_schedule','_occ_pattern','_total_occ','_sun_down_occ_hours',
+ '_occ_mask','_arrays','_valid_states','_datatype','_unit')
+
+ def__init__(self,folder,datatype:DataTypeBase=None,
+ schedule:list=None,unit:str=None,
+ load_arrays:bool=False):
+"""Initialize Results."""
+ _ResultsFolder.__init__(self,folder)
+ self.schedule=schedule
+ self._arrays=self._load_arrays()ifload_arrayselse{}
+ self._valid_states=self._get_valid_states()
+ self.datatype=datatype
+ self.unit=unit
+
+ @property
+ defschedule(self):
+"""Return schedule."""
+ returnself._schedule
+
+ @schedule.setter
+ defschedule(self,schedule):
+ self._schedule=scheduleifscheduleelse \
+ occupancy_schedule_8_to_6(timestep=self.timestep,as_list=True)
+ self._update_occ()
+
+ @property
+ defocc_pattern(self):
+"""Return a filtered version of the annual schedule that only includes the
+ sun-up-hours."""
+ returnself._occ_pattern
+
+ @property
+ deftotal_occ(self):
+"""Return an integer for the total occupied hours of the schedule."""
+ returnself._total_occ
+
+ @property
+ defsun_down_occ_hours(self):
+"""Return an integer for the number of occupied hours where the sun is down and
+ there's no possibility of being daylit or experiencing glare."""
+ returnself._sun_down_occ_hours
+
+ @property
+ defocc_mask(self):
+"""Return an occupancy mask as a NumPy array that can be used to mask the
+ results."""
+ returnself._occ_mask
+
+ @property
+ defarrays(self):
+"""Return a dictionary of all the NumPy arrays that have been loaded."""
+ returnself._arrays
+
+ @arrays.setter
+ defarrays(self,value):
+ self._arrays=value
+
+ @property
+ defvalid_states(self):
+"""Return a dictionary with valid states. Each light path is represented by a
+ key-value pair where the light path identifier is the key and the value is a list
+ of valid states, e.g., [0, 1, 2, ...]."""
+ returnself._valid_states
+
+ @property
+ defdatatype(self):
+"""Return a Ladybug DataType object."""
+ returnself._datatype
+
+ @datatype.setter
+ defdatatype(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,DataTypeBase), \
+ f'data_type must be a Ladybug DataType. Got {type(value)}'
+ else:
+ value=GenericType('Generic','')
+ self._datatype=value
+
+ @property
+ defunit(self):
+"""Return unit of hourly values."""
+ returnself._unit
+
+ @unit.setter
+ defunit(self,value):
+ self._unit=value
+
+
+[docs]
+ deftotal(
+ self,hoys:list=[],states:DynamicSchedule=None,
+ grids_filter:str='*',res_type:str='total'
+ )->type_hints.total:
+"""Get summed values for each sensor.
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with total values and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ mask=hoys_mask(self.sun_up_hours,hoys)
+
+ total=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=mask
+ )
+ array_total=array_filter.sum(axis=1)
+ else:
+ array_total=np.zeros(grid_info['count'])
+ total.append(array_total)
+
+ returntotal,grids_info
+
+
+
+[docs]
+ defpoint_in_time(
+ self,datetime:Union[float,DateTime],states:DynamicSchedule=None,
+ grids_filter:str='*',res_type:str='total'
+ )->type_hints.point_in_time:
+"""Get point in time values.
+
+ Args:
+ datetime: Hour of the year as a float or DateTime object.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with point in time values and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+
+ ifisinstance(datetime,float):
+ dt=DateTime.from_hoy(datetime)
+ elifisinstance(datetime,DateTime):
+ dt=datetime
+ else:
+ error_message=(
+ f'Input datetime must be of type {int} or {DateTime}. '
+ f'Received {type(DateTime)}.'
+ )
+ raiseValueError(error_message)
+
+ idx=self._index_from_datetime(dt)
+
+ pit_values=[]
+ forgrid_infoingrids_info:
+ ifidx:
+ array=self._array_from_states(
+ grid_info,states=states,res_type=res_type)
+ pit_values.append(array[:,idx])
+ else:
+ # datetime not in sun up hours, add zeros
+ pit_values.append(np.zeros(grid_info['count']))
+
+ returnpit_values,grids_info
+
+
+
+[docs]
+ defpoint_in_time_to_folder(
+ self,target_folder:str,datetime:Union[float,DateTime],
+ states:DynamicSchedule=None,grids_filter:str='*',
+ res_type:str='total'
+ )->type_hints.point_in_time:
+"""Get point in time values and write the values to a folder.
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ datetime: Hour of the year as a float or DateTime object.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with point in time values and grid information.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ pit_values,grids_info=self.point_in_time(
+ datetime=datetime,states=states,
+ grids_filter=grids_filter,res_type=res_type)
+
+ metric_folder=folder.joinpath('point_in_time')
+
+ forcount,grid_infoinenumerate(grids_info):
+ d=pit_values[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.pit')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ info_file=metric_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+ returnpit_values,grids_info
+
+
+
+[docs]
+ defaverage_values(
+ self,hoys:list=[],states:DynamicSchedule=None,grids_filter:str='*',
+ res_type:str='total')->type_hints.average_values:
+"""Get average values for each sensor over a given period.
+
+ The hoys input can be used to filter the data for a particular time
+ period.
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with the average value for each sensor and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ full_length=len(self.study_hours)iflen(hoys)==0elselen(hoys)
+ mask=hoys_mask(self.sun_up_hours,hoys)
+
+ average_values=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=mask)
+ results=average_values_array2d(
+ array_filter,full_length)
+ else:
+ results=np.zeros(grid_info['count'])
+ average_values.append(results)
+
+ returnaverage_values,grids_info
+
+
+
+[docs]
+ defaverage_values_to_folder(
+ self,target_folder:str,hoys:list=[],states:DynamicSchedule=None,
+ grids_filter:str='*',res_type:str='total'):
+"""Get average values for each sensor over a given period and write the
+ values to a folder.
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ average_values,grids_info=self.average_values(
+ hoys=hoys,states=states,
+ grids_filter=grids_filter,res_type=res_type)
+
+ metric_folder=folder.joinpath('average_values')
+
+ forcount,grid_infoinenumerate(grids_info):
+ d=average_values[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.average')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ info_file=metric_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+
+[docs]
+ defmedian_values(
+ self,hoys:list=[],states:dict=None,grids_filter:str='*',
+ res_type:str='total')->type_hints.median_values:
+"""Get median values for each sensor over a given period.
+
+ The hoys input can be used to filter the data for a particular time
+ period. If hoys is left empty the median values will likely be 0 since
+ there are likely more sun down hours than sun up hours.
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with the median value for each sensor and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ mask=hoys_mask(self.sun_up_hours,hoys)
+
+ median_values=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=mask)
+ ifnothoys:
+ # concatenate zero array
+ zero_array= \
+ np.zeros((grid_info['count'],len(self.sun_down_hours)))
+ array_filter=np.concatenate((array_filter,zero_array),axis=1)
+ else:
+ # find number of hoys that are sun down hours
+ sdh_hoys= \
+ len(set(self.sun_down_hours).intersection(hoys))
+ ifsdh_hoys!=0:
+ # concatenate zero array
+ zero_array=np.zeros((grid_info['count'],sdh_hoys))
+ array_filter= \
+ np.concatenate((array_filter,zero_array),axis=1)
+ results=np.median(array_filter,axis=1)
+ else:
+ results=np.zeros(grid_info['count'])
+ median_values.append(results)
+
+ returnmedian_values,grids_info
+
+
+
+[docs]
+ defmedian_values_to_folder(
+ self,target_folder:str,hoys:list=[],states:dict=None,
+ grids_filter:str='*',res_type:str='total'):
+"""Get median values for each sensor over a given period and write the
+ values to a folder.
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ median_values,grids_info=self.median_values(
+ hoys=hoys,states=states,
+ grids_filter=grids_filter,res_type=res_type)
+
+ metric_folder=folder.joinpath('median_values')
+
+ forcount,grid_infoinenumerate(grids_info):
+ d=median_values[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.median')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ info_file=metric_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+
+[docs]
+ defcumulative_values(
+ self,hoys:list=[],states:DynamicSchedule=None,
+ t_step_multiplier:float=1,grids_filter:str='*',
+ res_type:str='total')->type_hints.cumulative_values:
+"""Get cumulative values for each sensor over a given period.
+
+ The hoys input can be used to filter the data for a particular time
+ period.
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ t_step_multiplier: A value that will be multiplied with the timestep.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with the cumulative value for each sensor and grid
+ information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ mask=hoys_mask(self.sun_up_hours,hoys)
+
+ cumulative_values=[]
+ forgrid_infoingrids_info:
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=mask)
+ results=cumulative_values_array2d(
+ array_filter,self.timestep,t_step_multiplier)
+ else:
+ results=np.zeros(grid_info['count'])
+ cumulative_values.append(results)
+
+ returncumulative_values,grids_info
+
+
+
+[docs]
+ defcumulative_values_to_folder(
+ self,target_folder:str,hoys:list=[],
+ states:DynamicSchedule=None,t_step_multiplier:float=1,
+ grids_filter:str='*',res_type:str='total'):
+"""Get cumulative values for each sensor over a given period and write
+ the values to a folder.
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ t_step_multiplier: A value that will be multiplied with the timestep.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ res_type: Type of results to load. Defaults to 'total'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ cumulative_values,grids_info=self.cumulative_values(
+ hoys=hoys,states=states,t_step_multiplier=t_step_multiplier,
+ grids_filter=grids_filter,res_type=res_type
+ )
+
+ metric_folder=folder.joinpath('cumulative_values')
+
+ forcount,grid_infoinenumerate(grids_info):
+ d=cumulative_values[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.cumulative')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ info_file=metric_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+
+[docs]
+ defpeak_values(
+ self,hoys:list=[],states:DynamicSchedule=None,grids_filter:str='*',
+ coincident:bool=False,res_type:str='total'
+ )->type_hints.peak_values:
+"""Get peak values for each sensor over a given period.
+
+ The hoys input can be used to filter the data for a particular time
+ period.
+
+ Args:
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ coincident: Boolean to indicate whether output values represent the peak
+ value for each sensor throughout the entire analysis (False) or they
+ represent the highest overall value across each sensor grid at a
+ particular timestep (True). Defaults to False.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with the peak value for each sensor and grid information.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ mask=hoys_mask(self.sun_up_hours,hoys)
+ filt_suh=hoysiflen(hoys)!=0elseself.sun_up_hours
+
+ peak_values=[]
+ max_hoys=[]
+ forgrid_infoingrids_info:
+ max_i=None
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ ifnp.any(array):
+ array_filter=np.apply_along_axis(
+ filter_array,1,array,mask=mask)
+ results,max_i=peak_values_array2d(
+ array_filter,coincident=coincident)
+ else:
+ results=np.zeros(grid_info['count'])
+ peak_values.append(results)
+ ifmax_i:
+ max_hoys.append(filt_suh[max_i])
+ else:
+ max_hoys.append(None)
+
+ returnpeak_values,max_hoys,grids_info
+
+
+
+[docs]
+ defpeak_values_to_folder(
+ self,target_folder:str,hoys:list=[],states:DynamicSchedule=None,
+ grids_filter:str='*',coincident:bool=False,res_type='total'):
+"""Get peak values for each sensor over a given period and write the
+ values to a folder.
+
+ Args:
+ target_folder: Folder path to write peak values in. Usually this
+ folder is called 'metrics'.
+ hoys: An optional numbers or list of numbers to select the hours of
+ the year (HOYs) for which results will be computed. Defaults to [].
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ coincident: Boolean to indicate whether output values represent the peak
+ value for each sensor throughout the entire analysis (False) or they
+ represent the highest overall value across each sensor grid at a
+ particular timestep (True). Defaults to False.
+ res_type: Type of results to load. Defaults to 'total'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ peak_values,max_hoys,grids_info=self.peak_values(
+ hoys=hoys,states=states,grids_filter=grids_filter,
+ coincident=coincident,res_type=res_type)
+
+ metric_folder=folder.joinpath('peak_values')
+
+ forcount,grid_infoinenumerate(grids_info):
+ d=peak_values[count]
+ full_id=grid_info['full_id']
+ output_file=metric_folder.joinpath(f'{full_id}.peak')
+ output_file.parent.mkdir(parents=True,exist_ok=True)
+ np.savetxt(output_file,d,fmt='%.2f')
+
+ max_hoys_file=metric_folder.joinpath('max_hoys.txt')
+ max_hoys_file.write_text('\n'.join(str(h)forhinmax_hoys))
+
+ info_file=metric_folder.joinpath('grids_info.json')
+ info_file.write_text(json.dumps(grids_info))
+
+
+ def_array_to_annual_data(
+ self,grid_info,states:DynamicSchedule=None,
+ sensor_index:list=None,res_type:str='total'
+ )->Tuple[List[HourlyContinuousCollection],dict,list]:
+"""Get annual data for one or multiple sensors.
+
+ Args:
+ grid_info: Grid information of the grid.
+ states: A dictionary of states. Defaults to None.
+ sensor_index: A list of sensor indices as integers. Defaults to None.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with Data Collections for each sensor, grid information,
+ and a list of the sensors.
+ """
+ analysis_period=AnalysisPeriod(timestep=self.timestep)
+
+ # if no sensor_index, create list with all sensors
+ ifnotsensor_index:
+ sensor_index=[range(grid_info['count'])]
+
+ data_collections=[]
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ foridxinsensor_index:
+ ifnp.any(array):
+ values=array[idx,:]
+ else:
+ values=np.zeros(len(self.sun_up_hours))
+ annual_array=Results.values_to_annual(
+ self.sun_up_hours,values,self.timestep,self.study_hours)
+ header=Header(self.datatype,self.unit,analysis_period)
+ header.metadata['sensor grid']=grid_info['full_id']
+ header.metadata['sensor index']=idx
+ data_collections.append(
+ HourlyContinuousCollection(header,annual_array.tolist()))
+
+ returndata_collections,grid_info,sensor_index
+
+
+[docs]
+ defannual_data(
+ self,states:DynamicSchedule=None,grids_filter:str='*',
+ sensor_index:dict=None,res_type:str='total'
+ )->type_hints.annual_data:
+"""Get annual data for one or multiple sensors.
+
+ Args:
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ sensor_index: A dictionary with grids as keys and a list of sensor
+ indices as values. Defaults to None.
+ res_type: Type of results to load. Defaults to 'total'.
+
+ Returns:
+ Tuple: A tuple with Data Collections for each sensor, grid information,
+ and a dictionary of the sensors.
+ """
+ grids_info=self._filter_grids(grids_filter=grids_filter)
+ analysis_period=AnalysisPeriod(timestep=self.timestep)
+
+ # if no sensor_index, create dict with all sensors
+ ifnotsensor_index:
+ sensor_index={}
+ forgrid_infoingrids_info:
+ sensor_index[grid_info['full_id']]= \
+ [iforiinrange(grid_info['count'])]
+
+ data_collections=[]
+ forgrid_infoingrids_info:
+ data_collections_grid=[]
+ grid_id=grid_info['full_id']
+ array=self._array_from_states(grid_info,states=states,res_type=res_type)
+ indices=sensor_index[grid_id]
+ foridxinindices:
+ ifnp.any(array):
+ values=array[idx,:]
+ else:
+ values=np.zeros(len(self.sun_up_hours))
+ annual_array=Results.values_to_annual(
+ self.sun_up_hours,values,self.timestep)
+ header=Header(self.datatype,self.unit,analysis_period)
+ header.metadata['sensor grid']=grid_id
+ header.metadata['sensor index']=idx
+ data_collections_grid.append(
+ HourlyContinuousCollection(header,annual_array.tolist()))
+ data_collections.append(data_collections_grid)
+
+ returndata_collections,grids_info,sensor_index
+
+
+
+[docs]
+ defannual_data_to_folder(
+ self,target_folder:str,states:DynamicSchedule=None,grids_filter:str='*',
+ sensor_index:dict=None,res_type:str='total'):
+"""Get annual data for one or multiple sensors and write the data to a
+ folder as Data Collections.
+
+ Args:
+ target_folder: Folder path to write annual metrics in. Usually this
+ folder is called 'metrics'.
+ states: A dictionary of states. Defaults to None.
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+ sensor_index: A dictionary with grids as keys and a list of sensor
+ indices as values. Defaults to None.
+ res_type: Type of results to load. Defaults to 'total'.
+ """
+ folder=Path(target_folder)
+ folder.mkdir(parents=True,exist_ok=True)
+
+ data_collections,grids_info,sensor_index=self.annual_data(
+ states=states,grids_filter=grids_filter,sensor_index=sensor_index,
+ res_type=res_type)
+
+ metric_folder=folder.joinpath('datacollections')
+
+ forcount,grid_infoinenumerate(grids_info):
+ grid_collections=data_collections[count]
+ fordata_collectioningrid_collections:
+ grid_id=grid_info['full_id']
+ sensor_id=data_collection.header.metadata['sensor index']
+ data_dict=data_collection.to_dict()
+ data_file=metric_folder.joinpath(f'{grid_id}_{sensor_id}.json')
+ data_file.parent.mkdir(parents=True,exist_ok=True)
+ data_file.write_text(json.dumps(data_dict))
+
+
+
+[docs]
+ @staticmethod
+ defvalues_to_annual(
+ hours:Union[List[float],np.ndarray],
+ values:Union[List[float],np.ndarray],
+ timestep:int,base_value:int=0,
+ dtype:np.dtype=np.float32)->np.ndarray:
+"""Map a 1D NumPy array based on a set of hours to an annual array.
+
+ This method creates an array with a base value of length 8760 and
+ replaces the base value with the input 'values' at the indices of the
+ input 'hours'.
+
+ Args:
+ hours: A list of hours. This can be a regular list or a 1D NumPy
+ array.
+ values: A list of values to map to an annual array. This can be a
+ regular list or a 1D NumPy array.
+ timestep: Time step of the simulation.
+ base_value: A value that will be applied for all the base array.
+ dtype: A NumPy dtype for the annual array.
+
+ Returns:
+ A 1D NumPy array.
+ """
+ values=np.array(values)
+ check_array_dim(values,1)
+ hours=np.array(hours)
+ asserthours.shape==values.shape
+ full_ap=AnalysisPeriod(timestep=timestep)
+ indices=np.where(np.isin(full_ap.hoys,hours))[0]
+ annual_array=np.repeat(base_value,8760*timestep).astype(dtype)
+ annual_array[indices]=values
+
+ returnannual_array
+
+
+ def_index_from_datetime(self,datetime:DateTime)->Union[int,None]:
+"""Returns the index of the input datetime in the list of datetimes
+ from the datetimes property.
+
+ If the DateTime is not in the list, the function will return None.
+
+ Args:
+ datetime: A DateTime object.
+
+ Returns:
+ Index as an integer or None.
+ """
+ assertisinstance(datetime,DateTime), \
+ f'Expected DateTime object but received {type(datetime)}'
+ try:
+ index=self.datetimes.index(datetime)
+ exceptException:
+ # DateTime not in sun up hours
+ index=None
+
+ returnindex
+
+ def_get_array(
+ self,grid_info:dict,light_path:str,state:int=0,
+ res_type:str='total',extension:str='.npy')->np.ndarray:
+"""Get an array for a given grid, light path, and state.
+
+ The array will be fetched from the 'arrays' property if it has been
+ loaded already.
+
+ Args:
+ grid_info: Grid information.
+ light_path: Identifier of the light path.
+ state: State as an integer. E.g., 0 for the default state.
+ Defaults to 0.
+ res_type: Type of results to load. Defaults to 'total'.
+ extension: File extension of the array to load. Defaults to '.npy'.
+
+ Returns:
+ np.ndarray: A NumPy array of a given grid, light path, and state.
+ """
+ grid_id=grid_info['full_id']
+
+ state_identifier=self._state_identifier(grid_id,light_path,state=state)
+
+ try:
+ array=self.arrays[grid_id][light_path][state_identifier][res_type]
+ exceptException:
+ array=self._load_array(
+ grid_info,light_path,state=state,res_type=res_type,
+ extension=extension
+ )
+
+ returnarray
+
+ def_load_array(
+ self,grid_info:dict,light_path:str,state:int=0,
+ res_type:str='total',extension:str='.npy')->np.ndarray:
+"""Load a NumPy file to an array.
+
+ This method will also update the arrays property value.
+
+ Args:
+ grid_info: Grid information.
+ light_path: Identifier of the light path.
+ state: State as an integer. E.g., 0 for the default state.
+ Defaults to 0.
+ res_type: Which type of result to return a file for. E.g., 'total' for total
+ illuminance or 'direct' for direct illuminance.
+ extension: File extension of the array to load. Defaults to '.npy'.
+
+ Returns:
+ np.ndarray: A NumPy array of a given grid, light path, and state
+ from a NumPy file.
+ """
+ grid_id=grid_info['full_id']
+
+ defmerge_dicts(array_dict,arrays):
+ forkey,valueinarray_dict.items():
+ ifisinstance(value,dict):
+ node=arrays.setdefault(key,{})
+ merge_dicts(value,node)
+ else:
+ arrays[key]=value
+ returnarrays
+
+ state_identifier=self._state_identifier(grid_id,light_path,state=state)
+ file=self._get_file(grid_id,light_path,state_identifier,res_type,
+ extension=extension)
+ array=np.load(file)
+
+ array_dict={grid_id:{light_path:{state_identifier:{res_type:array}}}}
+ arrays=merge_dicts(array_dict,self.arrays)
+ self.arrays=arrays
+
+ returnarray
+
+ def_state_identifier(
+ self,grid_id:str,light_path:str,state:int=0)->Union[str,None]:
+"""Get the state identifier from a light path and state integer.
+
+ Args:
+ grid_id: Grid identifier.
+ light_path: Identifier of the light path.
+ state: State as an integer. E.g., 0 for the default state.
+ Defaults to 0.
+
+ Returns:
+ State identifier. For static apertures the identifier is 'default',
+ and for other light paths it is the light path identifier preceded
+ by the state integer, e.g., '0_light_path'. If the state is -1 the
+ state identifier will be None.
+ """
+ # TODO: Figure out if there is a better way to handle the states.
+ # I.e., state integer <--> state identifier.
+ valid_states=self.valid_states[light_path]
+ ifstateinvalid_states:
+ iflight_path=='__static_apertures__':
+ state_identifier='default'
+ else:
+ state_identifier=self.grid_states[grid_id][light_path][state]
+ returnstate_identifier
+ elifstate==-1:
+ returnNone
+ else:
+ error_message=(
+ f'State of {light_path} must be any of {valid_states} for on '
+ f'or -1 for off. Received state {state}.'
+ )
+ raiseValueError(error_message)
+
+ def_get_file(
+ self,grid_id:str,light_path:str,state_identifier:str,
+ res_type:str='total',extension:str='.npy')->Path:
+"""Return the path of a results file.
+
+ Args:
+ grid_id: Grid identifier.
+ light_path: Identifier of the light path.
+ state_identifier: State identifier.
+ res_type: Which type of result to return a file for. E.g., 'total' for total
+ illuminance or 'direct' for direct illuminance.
+ extension: File extension of the array to load. Defaults to '.npy'.
+
+ Returns:
+ Path to a NumPy file.
+ """
+ file=Path(self.folder,light_path,state_identifier,
+ res_type,grid_id+extension)
+ ifnotfile.is_file():
+ raiseFileNotFoundError(f'File {file} not found in the results folder.')
+
+ returnfile
+
+ def_validate_dynamic_states(self,states:dict)->dict:
+"""Validate dynamic states and return states dictionary.
+
+ If all light paths in the dictionary have 8760 values, the states
+ dictionary is returned as is. If some light paths have less than 8760
+ values, pattern of values will be repeated until it reaches a length of
+ 8760.
+
+ Args:
+ states: A dictionary of states.
+
+ Returns:
+ dict: A dictionary of states.
+ """
+ ifall(len(values)==8760forvaluesinstates.values()):
+ returnstates
+ forlight_path,valuesinstates.items():
+ iflen(values)<8760:
+ states[light_path]=list(islice(cycle(values),8760))
+ eliflen(values)>8760:
+ error_message=(
+ f'The light path {light_path} has {len(values)} values in '
+ f'its states schedule. Maximum allowed number of values '
+ f'is 8760.'
+ )
+ raiseValueError(error_message)
+
+ returnstates
+
+ def_validate_states(self,states:dict)->dict:
+"""Validate states and return states dictionary.
+
+ If all light paths in the dictionary have integers only as values, the
+ states dictionary is returned as is. If some light paths have values
+ that are not integers, these values will be mapped as integers if
+ possible, e.g., if the values are strings ('0', '1', etc.) instead of
+ integers.
+
+ Args:
+ states: A dictionary of states.
+
+ Returns:
+ dict: A dictionary of states.
+ """
+ ifall(isinstance(v,int)forvaluesinstates.values()forvinvalues):
+ returnstates
+ forlight_path,valuesinstates.items():
+ try:
+ states[light_path]=list(map(int,values))
+ exceptValueErroraserr:
+ error_message=(
+ f'Failed to convert states schedule for light path '
+ f'{light_path} to integers.'
+ )
+ raiseValueError(error_message)fromerr
+
+ returnstates
+
+ def_filter_grid_states(self,grid_info,states:DynamicSchedule=None)->DynamicSchedule:
+"""Filter a dictionary of states by grid. Only light paths relevant to
+ the given grid will be returned.
+
+ Args:
+ grid_info: Grid information.
+ states: A dictionary of states. Light paths as keys and lists of
+ 8760 values for each key. The values should be integers
+ matching the states or -1 for off. Default to None.
+
+ Returns:
+ dict: A filtered states dictionary.
+ """
+ light_paths=[]
+ forlpingrid_info['light_path']:
+ for_lpinlp:
+ if_lp=='__static_apertures__'andlen(lp)>1:
+ pass
+ else:
+ light_paths.append(_lp)
+ ifstates:
+ states=states.filter_by_identifiers(light_paths)
+ else:
+ default_states=self.default_states
+ states=DynamicSchedule()
+ forlight_pathinlight_paths:
+ ap_group_schedule=ApertureGroupSchedule(
+ light_path,default_states[light_path],is_static=True)
+ states.add_aperture_group_schedule(ap_group_schedule)
+
+ returnstates
+
+ def_array_from_states(
+ self,grid_info,states:DynamicSchedule=None,
+ res_type:str='total',zero_array:bool=False
+ )->np.ndarray:
+"""Create an array for a given grid by the states settings.
+
+ Args:
+ grid_info: Grid information of the grid.
+ states: A dictionary of states. Light paths as keys and lists of 8760 values
+ for each key. The values should be integers matching the states or -1 for
+ off.
+ res_type: Which type of result to create an array for. E.g., 'total'
+ for total illuminance or 'direct' for direct illuminance.
+ zero_array: Boolean to note if a 2D zero array should be created if
+ the array of the grid is zero. This is the case if the
+ illuminance of the grid is zero. (Default: False).
+
+ Returns:
+ A NumPy array based on the states settings.
+ """
+ # get states that are relevant for the grid
+ states=self._filter_grid_states(grid_info,states=states)
+
+ arrays=[]
+ forlight_path,gr_scheduleinstates.dynamic_schedule.items():
+ ifgr_schedule.is_static:
+ state=gr_schedule.schedule[0]
+ # if state is -1 we continue since it is "turned off"
+ ifstate==-1:
+ continue
+ # load static array (state is static)
+ array=self._get_array(
+ grid_info,light_path,state=state,res_type=res_type)
+ arrays.append(array)
+ else:
+ # create default 0 array, we will add to this later
+ array=np.zeros((grid_info['count'],len(self.sun_up_hours)))
+ # slice states to match sun up hours
+ states_array=np.array(gr_schedule.schedule)[
+ list(map(int,self.sun_up_hours))]
+ forstateinnp.unique(states_array):
+ ifstate==-1:
+ # if state is -1 we continue since it is "turned off"
+ continue
+ # load static array (state is static)
+ _array=self._get_array(
+ grid_info,light_path,state=state,res_type=res_type)
+ # get indices and add values to base array
+ states_indicies=states_array==state
+ array[:,states_indicies]+=_array[:,states_indicies]
+ arrays.append(array)
+ array=sum(arrays)
+
+ ifnotnp.any(array):
+ ifzero_array:
+ array=np.zeros((grid_info['count'],len(self.sun_up_hours)))
+ else:
+ array=np.array([])
+
+ returnarray
+
+ def_update_occ(self):
+"""Set properties related to occupancy."""
+ occ_mask=np.array(self.schedule,dtype=int)[self.sun_up_hours_mask]
+ sun_down_sch= \
+ np.array(self.schedule,dtype=int)[self.sun_down_hours_mask].sum()
+
+ self._occ_mask=occ_mask
+ self._total_occ=sum(self.schedule)
+ self._sun_down_occ_hours=sun_down_sch
+
+ def_filter_grids(self,grids_filter:str='*')->list:
+"""Return grids information.
+
+ Args:
+ grids_filter: The name of a grid or a pattern to filter the grids.
+ Defaults to '*'.
+
+ Returns:
+ list: List of grid information for filtered grids.
+ """
+ ifgrids_filter!='*':
+ grids_info= \
+ _filter_grids_by_pattern(self.grids_info,grids_filter)
+ else:
+ grids_info=self.grids_info
+
+ returngrids_info
+
+ def_load_arrays(self)->dict:
+"""Load all the NumPy arrays in the results folder."""
+ arrays={}
+ grids_info=self.grids_info
+
+ forgrid_infoingrids_info:
+ grid_id=grid_info['full_id']
+ light_paths=grid_info['light_path']
+ arrays[grid_id]={}
+ forlight_pathinlight_paths:
+ light_path=light_path[0]
+ arrays[grid_id][light_path]={}
+ light_path_folder=Path(self.folder,light_path)
+ forstate_folderinPath(light_path_folder).iterdir():
+ state=state_folder.name
+ arrays[grid_id][light_path][state]={}
+ forres_type_folderinPath(state_folder).iterdir():
+ res_type=res_type_folder.name
+ file=Path(res_type_folder,grid_id+'.npy')
+ array=np.load(file)
+ arrays[grid_id][light_path][state][res_type]=array
+
+ returnarrays
+
+ def_get_valid_states(self)->dict:
+"""Returns a dictionary with valid states for each light path.
+
+ For each light path there will be a key (identifier of the light path)
+ and its value will be a list of valid states as integers.
+
+ Example of output format:
+ {
+ '__static_apertures__': [0],
+ 'Room1_North': [0, 1],
+ 'Room1_South': [0, 1],
+ 'Room2_North1': [0, 1],
+ 'Room2_North2': [0, 1]
+ }
+
+ Returns:
+ dict: Valid states integers for each light path.
+ """
+ valid_states={}
+ grid_states=self.grid_states
+ if'__static_apertures__'inself.light_paths:
+ valid_states['__static_apertures__']=[0]
+ forlight_pathsingrid_states.values():
+ forlight_path,statesinlight_paths.items():
+ iflight_pathnotinvalid_states:
+ valid_states[light_path]=list(range(len(states)))
+
+ returnvalid_states
+
+ def_light_paths_from_grid_info(self,grid_info:Union[dict,str])->list:
+ ifisinstance(grid_info,str):
+ for_grid_infoinself.grids_info:
+ if_grid_info['full_id']==grid_info:
+ grid_info=_grid_info
+ break
+ else:
+ raiseException(f'Grid info with full_id "{grid_info}" not found.')
+ light_paths=[]
+ forlpingrid_info['light_path']:
+ for_lpinlp:
+ if_lp=='__static_apertures__'andlen(lp)>1:
+ pass
+ else:
+ light_paths.append(_lp)
+
+ returnlight_paths
+
+ def_get_state_combinations(self,grid_info:Union[dict,str])->List[dict]:
+ light_paths=self._light_paths_from_grid_info(grid_info)
+ valid_states=self._get_valid_states()
+ filtered_states={lp:valid_states[lp]forlpinlight_paths}
+ keys,values=zip(*filtered_states.items())
+ combinations=[dict(zip(keys,v))forvinitertools.product(*values)]
+
+ returncombinations
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/honeybee_radiance_postprocess/util.html b/docs/_modules/honeybee_radiance_postprocess/util.html
new file mode 100644
index 00000000..160b2c45
--- /dev/null
+++ b/docs/_modules/honeybee_radiance_postprocess/util.html
@@ -0,0 +1,903 @@
+
+
+
+
+
+
+ honeybee_radiance_postprocess.util — honeybee-radiance-postprocess documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+defbinary_mtx_dimension(filepath:str)->Tuple[int,int,int,int,str]:
+"""Return binary Radiance matrix dimensions if exist.
+
+ This function returns NROWS, NCOLS, NCOMP and number of header lines including the
+ white line after last header line.
+
+ Args:
+ filepath: Full path to Radiance file.
+
+ Returns:
+ nrows, ncols, ncomp, line_count, fmt
+ """
+ try:
+ inf=open(filepath,'rb',encoding='utf-8')
+ exceptException:
+ inf=open(filepath,'rb')
+ try:
+ first_line=next(inf).rstrip().decode('utf-8')
+ iffirst_line[:10]!='#?RADIANCE':
+ error_message=(
+ f'File with Radiance header must start with #?RADIANCE not '
+ f'{first_line}.'
+ )
+ raiseValueError(error_message)
+
+ header_lines=[first_line]
+ nrows=ncols=ncomp=None
+ forlineininf:
+ line=line.rstrip().decode('utf-8')
+ header_lines.append(line)
+ ifline[:6]=='NROWS=':
+ nrows=int(line.split('=')[-1])
+ ifline[:6]=='NCOLS=':
+ ncols=int(line.split('=')[-1])
+ ifline[:6]=='NCOMP=':
+ ncomp=int(line.split('=')[-1])
+ ifline[:7]=='FORMAT=':
+ fmt=line.split('=')[-1]
+ break
+
+ ifnotnrowsornotncols:
+ error_message=(
+ f'NROWS or NCOLS was not found in the Radiance header. NROWS '
+ f'is {nrows} and NCOLS is {ncols}. The header must have both '
+ f'elements.'
+ )
+ raiseValueError(error_message)
+ returnnrows,ncols,ncomp,len(header_lines)+1,fmt
+ finally:
+ inf.close()
+
+
+
+
+[docs]
+defcheck_array_dim(array:np.ndarray,dim:int):
+"""Check NumPy array dimension.
+
+ Args:
+ array: A NumPy array.
+ dim: The dimension to check against.
+ """
+ assertarray.ndim==dim, \
+ f'Expected {dim}-dimensional array. Dimension of array is {array.ndim}'
+
+
+
+
+[docs]
+deffilter_array(array:np.ndarray,mask:np.ndarray)->np.ndarray:
+"""Filter a NumPy array by a masking array. The array will be passed as is
+ if the mask is None.
+
+ Args:
+ array: A NumPy array to filter.
+ mask: A NumPy array of ones/zeros or True/False.
+
+ Returns:
+ A filtered NumPy array.
+ """
+ ifmaskisnotNone:
+ returnarray[mask.astype(bool)]
+ returnarray
+
+
+
+
+[docs]
+defhoys_mask(sun_up_hours:list,hoys:list)->np.ndarray:
+"""Create a NumPy masking array from a list of hoys.
+
+ Args:
+ sun_up_hours: A list of sun up hours.
+ hoys: A list hoys to select.
+
+ Returns:
+ A NumPy array of booleans.
+ """
+ iflen(hoys)!=0:
+ hoys_mask=np.where(np.isin(sun_up_hours,hoys),True,False)
+ returnhoys_mask
+
+
+
+
+[docs]
+defarray_memory_size(
+ sensors:int,sun_up_hours:int,ncomp:int=None,
+ dtype:np.dtype=np.float32,gigabyte:bool=True)->float:
+"""Calculate the memory size of an array before creating or loading an
+ array.
+
+ Args:
+ sensors: Number of sensors in the array.
+ sun_up_hours: Number of sun up hours in the array.
+ ncomp: Optional number of components for each element in the array,
+ e.g., if the data is in RGB format then this value must be set
+ to 3. Defaults to None.
+ dtype: The data type of the array. Defaults to np.float32.
+ gigabyte: Boolean toggle to output the memory size in gigabytes.
+ Defaults to True.
+
+ Returns:
+ float: The memory size of an array.
+ """
+ # check if dtype is valid
+ dtypes=tuple(np.sctypes['float'])
+ ifnotisinstance(dtype,dtypes):
+ try:
+ dtype=dtype()
+ exceptTypeErroraserr:
+ error_message=(
+ f'Unable to instantiate input dtype. Expected any of the '
+ f'following: {dtypes}. Received: {type(dtype)}.'
+ )
+ raiseTypeError(error_message)fromerr
+
+ # calculate memory size
+ size=sensors*sun_up_hours*dtype.itemsize
+ ifncomp:
+ size*=ncomp
+ ifgigabyte:
+ size/=(1024**3)
+
+ returnsize
+
+
+
+
+[docs]
+defrecursive_dict_merge(dict_1:dict,dict_2:dict):
+"""Recursive merging of two dictionaries.
+
+ Args:
+ dict_1: Original dictionary.
+ dict_2: Dictionary to merge with dict_1.
+ """
+ forkindict_2:
+ if(kindict_1andisinstance(dict_1[k],dict)and
+ isinstance(dict_2[k],dict)):
+ recursive_dict_merge(dict_1[k],dict_2[k])
+ else:
+ dict_1[k]=dict_2[k]
+
+
+
+def_filter_grids_by_pattern(grids_info,filter_pattern):
+"""Filter grids_info by a pattern.
+
+ Args:
+ grids_info: Grid information.
+ filter_pattern: Pattern to filter grids by.
+
+ Returns:
+ A list of filtered grids.
+ """
+ grids=_filter_by_pattern(grids_info,filter=filter_pattern)
+
+ returngrids
+
+
+