raytraverse.sky

skycalc

functions for loading sky data and computing sun position

raytraverse.sky.skycalc.read_epw(epw)

read daylight sky data from epw or wea file

Returns

out – (month, day, hour, dirnorn, difhoriz)

Return type

np.array

raytraverse.sky.skycalc.read_epw_full(epw, columns=None)

Parameters

• epw –

• columns (list, optional) – integer indices or keys of columns to return

Return type

requested columns from epw as np.array shape (8760, N)

raytraverse.sky.skycalc.get_loc_epw(epw, name=False)

get location from epw or wea header

raytraverse.sky.skycalc.sunpos_utc(timesteps, lat, lon, builtin=True)

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in UTC)

Parameters

• timesteps (np.array(datetime.datetime)) –

• lon (float) – longitude in decimals. West is +ve

• lat (float) – latitude in decimals. North is +ve

• builtin (bool) – use skyfield builtin timescale

Returns

• (skyfield.units.Angle, skyfield.units.Angle)

• altitude and azimuth in degrees

raytraverse.sky.skycalc.row_2_datetime64(ts, year=2020)

raytraverse.sky.skycalc.datetime64_2_datetime(timesteps, mer=0.0)

convert datetime representation and offset for timezone

Parameters

• timesteps (np.array(np.datetime64)) –

• mer (float) – Meridian of the time zone. West is +ve

Return type

np.array(datetime.datetime)

raytraverse.sky.skycalc.sunpos_degrees(timesteps, lat, lon, mer, builtin=True, ro=0.0)

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in local time)

Parameters

• timesteps (np.array(np.datetime64)) –

• lon (float) – longitude in decimals. West is +ve

• lat (float) – latitude in decimals. North is +ve

• mer (float) – Meridian of the time zone. West is +ve

• builtin (bool, optional) – use skyfield builtin timescale

• ro (float, optional) – ccw rotation (project to true north) in degrees

Returns

Sun position as (altitude, azimuth) in degrees

Return type

np.array([float, float])

raytraverse.sky.skycalc.sunpos_radians(timesteps, lat, lon, mer, builtin=True, ro=0.0)

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in local time)

Parameters

• timesteps (np.array(np.datetime64)) –

• lon (float) – longitude in decimals. West is +ve

• lat (float) – latitude in decimals. North is +ve

• mer (float) – Meridian of the time zone. West is +ve

• builtin (bool) – use skyfield builtin timescale

• ro (float, optional) – ccw rotation (project to true north) in radians

Returns

Sun position as (altitude, azimuth) in radians

Return type

np.array([float, float])

raytraverse.sky.skycalc.sunpos_xyz(timesteps, lat, lon, mer, builtin=True, ro=0.0)

Calculate sun position with local time

Calculate sun position (altitude, azimuth) for a particular location (longitude, latitude) for a specific date and time (time is in local time)

Parameters

• timesteps (np.array(np.datetime64)) –

• lon (float) – longitude in decimals. West is +ve

• lat (float) – latitude in decimals. North is +ve

• mer (float) – Meridian of the time zone. West is +ve

• builtin (bool) – use skyfield builtin timescale

• ro (float, optional) – ccw rotation (project to true north) in degrees

Returns

Sun position as (x, y, z)

Return type

np.array

raytraverse.sky.skycalc.generate_wea(ts, wea, interp='linear')

raytraverse.sky.skycalc.coeff_lum_perez(sunz, epsilon, delta, catn)

matches coeff_lum_perez in gendaylit.c

raytraverse.sky.skycalc.perez_apply_coef(coefs, cgamma, dz)

raytraverse.sky.skycalc.perez_lum_raw(tp, dz, sunz, coefs)

matches calc_rel_lum_perez in gendaylit.c

raytraverse.sky.skycalc.perez_lum(xyz, coefs, intersky=True)

matches perezlum.cal

raytraverse.sky.skycalc.scale_efficacy(dirdif, sunz, csunz, skybright, catn, td=10.9735311509)

raytraverse.sky.skycalc.perez(sxyz, dirdif, md=None, ground_fac=0.2, td=10.9735311509)

compute perez coefficients

Notes

to match the results of gendaylit, for a given sun angle without associated date, the assumed eccentricity is 1.035020

Parameters

• sxyz (np.array) – (N, 3) dx, dy, dz sun position

• dirdif (np.array) – (N, 2) direct normal, diffuse horizontal W/m^2

• md (np.array, optional) – (N, 2) month day of sky calcs (for more precise eccentricity calc)

• ground_fac (float) – scaling factor (reflectance) for ground brightness

• td (np.array float, optional) – (N,) dew point temperature in C

Returns

perez – (N, 10) diffuse normalization, ground brightness, perez coefs, x, y, z

Return type

np.array

raytraverse.sky.skycalc.sky_mtx(sxyz, dirdif, side, jn=4, intersky=True, **kwargs)

generate sky, ground and sun values from sun position and sky values

Parameters

• sxyz (np.array) – sun directions (N, 3)

• dirdif (np.array) – direct normal and diffuse horizontal radiation (W/m^2) (N, 2)

• side (int) – sky subdivision

• jn (int, optional) – sky patch subdivision n = jn^2

• intersky (bool, optional) – include interreflection between ground and sky (mimics perezlum.cal, not present in gendaymtx

• kwargs (dict, optional) – passed to perez()

Returns

• skymtx (np.array) – (N, side*side)

• grndval (np.array) – (N,)

• sunval (np.array) – (N, 4) - sun direction and radiance

raytraverse.sky.skycalc.radiance_skydef(sunpos, dirdif, loc=None, md=None, ground_fac=0.2, td=10.9735311509, ro=0.0)

similar to gendaylit, returns strings

Parameters

• sunpos (Sequence) – dx, dy, dz sun position or m,d,h (if loc is not None)

• dirdif (Sequence) – direct normal, diffuse horizontal W/m^2

• loc (tuple, optional) – location data given as lat, lon, mer with + west of prime meridian triggers sunpos treated as timestep

• md (tuple, optional) – month day of sky calcs (for more precise eccentricity calc with xyz sunpos)

• ground_fac (float) – scaling factor (reflectance) for ground brightness

• td (np.array float, optional) – (N,) dew point temperature in C

• ro (float, optional) – ignored if sunpos is xyz, else angle in degrees counter-clockwise to rotate sky (to correct model north, equivalent to clockwise rotation of scene)

Returns

• desc (str) – comments with sky info

• sund (str) – solar material and sun object (”” if no sun)

• skyd (str) – perezlum brightfunc definition and sky/ground objects

SkyData

class raytraverse.sky.SkyData(wea, loc=None, skyro=0.0, ground_fac=0.2, intersky=True, skyres=15, minalt=2.0, mindiff=5.0, mindir=0.0, ground=True, srcname='sky')

Bases: object

class to generate sky conditions

This class provides an interface to generate sky data using the perez sky model

Parameters

• wea (str np.array) – path to epw, wea, .npy file or np.array, or .npz file, if loc not set attempts to extract location data (if needed).

• loc (tuple, optional) – location data given as lat, lon, mer with + west of prime meridian overrides location data in wea (but not in sunfield)

• skyro (float, optional) – angle in degrees counter-clockwise to rotate sky (to correct model north, equivalent to clockwise rotation of scene)

• ground_fac (float, optional) – ground reflectance

• intersky (bool, optional) – include interreflection between ground and sky (mimics perezlum.cal, not present in gendaymtx)

• skyres (int, optional) – resolution of sky patches (sqrt(patches / hemisphere))

• minalt (float, optional) – minimum solar altitude for daylight masking

• mindiff (float, optional) – minumum diffuse horizontal irradiance for daylight masking

skyres

sky patach resolution

property skyro

sky rotation (in degrees, ccw)

property loc

lot, lon, mer (in degrees, west is positive)

skydata_dew()

property rowlabel

m,d,h (if known)

property skydata

sun position and dirnorm diffhoriz

write(name='skydata', scene=None, compressed=True)

format_skydata(dat)

process dat argument as skydata

see sky.setter for details on argument

Returns

dx, dy, dz, dir, diff

Return type

np.array

property daysteps

property daymask

shape (len(skydata),) boolean array masking timesteps when sun is below horizon

property fullmask

property maskindices

property mask

an additional mask for smtx data

property smtx

shape (np.sum(daymask), skyres**2 + 1) coefficients for each sky patch each row is a timestep, coefficients exclude sun

property sun

shape (np.sum(daymask), 5) sun position (index 0,1,2) and coefficients for sun at each timestep assuming the true solid angle of the sun (index 3) and the weighted value for the sky patch (index 4).

property sunproxy

corresponding sky bin for each sun position in daymask

smtx_patch_sun(includesky=True)

generate smtx with solar energy applied to proxy patch for directly applying to skysampler data (without direct sun components) can also be used in a partial mode (with sun view / without sun reflection.)

header()

generate image header string

fill_data(x, fill_value=0.0, rowlabels=False)

Parameters

• x (np.array) – first axis size = len(self.daymask[self.mask])

• fill_value (Union[int, float], optional) – value in padded array

• rowlabels (bool, optional) – include rowlabels

Returns

data in x padded with fill value to original shape of skydata

Return type

np.array

label(x)

masked_idx(i)

radiance_sky_matrix(outf, fmt='float', sun=True, sky=True, ncomps=3)

sky_description(i, prefix='skydata', grid=False, sun=True, ground=True, sunpatch=False)

generate radiance scene files to directly render sky data at index i

Parameters

• i (int) – index of sky vector to generate (indexed from skydata, not daymask)

• prefix (str, optional) – name/path for output files

• grid (bool, optional) – render sky patches with grid lines

• sun (bool, optional) – include sun source in rad file

• ground (bool, optional) – include ground source

• sunpatch (bool, optional) – include sun energy in sun_patch (sun should be false)

Returns

basename of 3 files written: prefix_i (.rad, .cal, and .dat) .cal and .dat must be located in RAYPATH (which can include .) or else edit the .rad file to explicitly point to their locations. note that if grid is True, the sky will not be accurate, so only use this for illustrative purposes.

Return type

str

Raises

IndexError – if i is not in masked indices

SkyDataMask

class raytraverse.sky.SkyDataMask(hours)

Bases: SkyData

spoofed skydata class for use with light results

Parameters

hours (np.array) – hours of year given as (m, d, h) where hour is H.5 (assumes 8760) to use as daymask.

property skydata

sun position and dirnorm diffhoriz