matrix

Frads Matrix class simply encapsulate the components necessary to generate a matrix, such as ray sender and receiver. The matrix data is by default store as numpy array in memory for later access.

frads.Matrix

Matrix(sender, receivers, octree=None, surfaces=None)

General matrix object for daylight and view factor calculations.

This class represents a transfer matrix between senders and receivers, encoding how light travels from source points/surfaces to destination points/surfaces. Used for daylight simulations, view factor calculations, and lighting analysis.

Attributes:

Name	Type	Description
sender		Sender object (sensors, view, or surface) that emits light.
receivers		List of receiver objects that collect light.
array		Numpy array or list of arrays storing the matrix data with shape (nrows, ncols, ncomp) where ncomp is typically 3 for RGB.
ncols		Number of columns (receiver basis size) or list of sizes for multiple receivers.
nrows	int	Number of rows (sender basis size or sensor count).
dtype		Matrix data type ('d' for double, 'f' for float).
ncomp		Number of color components (typically 3 for RGB).
octree		Path to octree file used for ray tracing acceleration.
surfaces		List of environment surface primitives for the scene.

Initialize a matrix object.

Parameters:

Name	Type	Description	Default
sender	SensorSender | ViewSender | SurfaceSender	Sender object (SensorSender, ViewSender, or SurfaceSender).	required
receivers	list[SkyReceiver] | list[SurfaceReceiver] | list[SunReceiver]	List of receiver objects (SurfaceReceiver, SkyReceiver, or SunReceiver). Multiple receivers are only supported for SurfaceReceiver types.	required
octree	None | str	Optional path to octree file for ray tracing.	None
surfaces	None | list[Primitive]	Optional list of environment surface primitives for the scene.	None

Raises:

Type	Description
ValueError	If sender/receiver types are invalid or incompatible.

generate

generate(params, nproc=1, sparse=False, to_file=False, memmap=False)

Generate the matrix using Radiance rfluxmtx tool.

Parameters:

Name	Type	Description	Default
params	list[str]	List of rfluxmtx command-line parameters (e.g., ['-ab', '3', '-ad', '1000']).	required
nproc	int	Number of parallel processes to use for calculation.	1
sparse	bool	If True, convert result to sparse matrix format for memory efficiency.	False
to_file	bool	If True, write matrix directly to file without storing in memory. Useful for very large matrices that exceed available RAM.	False
memmap	bool	If True, use memory mapping to store matrix data on disk. Allows handling of matrices larger than available RAM.	False

frads.SensorSender

SensorSender(sensors, ray_count=1)

Sender object representing a collection of point sensors.

This class creates a sender object from a list of point sensors, where each sensor is defined by position and direction vectors. Used for illuminance calculations at specific points in space.

Attributes:

Name	Type	Description
sensors		List of sensors, each containing 6 float values [x, y, z, dx, dy, dz] representing position (x,y,z) and direction (dx,dy,dz) vectors.
content		Sensor data encoded as bytes for Radiance input.
yres		Number of unique sensor locations (before ray multiplication).

Initialize a sensor sender object.

Parameters:

Name	Type	Description	Default
sensors	list[list[float]]	List of sensors, each containing 6 float values [x, y, z, dx, dy, dz] representing position and direction vectors.	required
ray_count	int	Number of rays to generate per sensor for Monte Carlo sampling. Higher values improve accuracy but increase computation time.	1

frads.ViewSender

ViewSender(view, ray_count=1, xres=800, yres=800)

Sender object representing a camera view for luminance calculations.

This class creates a sender object from a camera view definition, generating rays for each pixel in the view. Used for creating luminance images and view-based daylight analysis.

Attributes:

Name	Type	Description
view		Pyradiance View object defining camera parameters (position, direction, etc.).
content		View rays encoded as bytes for Radiance input.
xres		Horizontal resolution (number of pixels in x-direction).
yres		Vertical resolution (number of pixels in y-direction).

Initialize a view sender object.

Parameters:

Name	Type	Description	Default
view	View	Pyradiance View object defining camera parameters.	required
ray_count	int	Number of rays per pixel for anti-aliasing and Monte Carlo sampling.	1
xres	int	Horizontal resolution in pixels.	800
yres	int	Vertical resolution in pixels.	800

frads.SurfaceSender

SurfaceSender(surfaces, basis, left_hand=False, offset=None)

Sender object representing surfaces with directional sampling.

This class creates a sender object from surface primitives using a specified sampling basis. Used for calculating inter-surface view factors and daylight transmission through surfaces like windows.

Attributes:

Name	Type	Description
surfaces		List of surface primitives (polygons or rings) to use as senders.
basis		Sampling basis string (e.g., 'kf', 'r4', 'sc6') defining directional discretization for the surface.
content		Surface data encoded as string for Radiance rfluxmtx input.

Initialize a surface sender object.

Parameters:

Name	Type	Description	Default
surfaces	list[Primitive]	List of surface primitives (polygons or rings) to use as senders.	required
basis	str	Sampling basis string defining directional discretization (e.g., 'kf' for Klems full, 'r4' for Reinhart 4-division).	required
left_hand	bool	Whether to use left-hand coordinate system for basis orientation.	False
offset	float | None	Distance to offset the sender surface along its normal vector. Useful for avoiding self-intersection in calculations.	None

frads.SkyReceiver

SkyReceiver(basis, out=None)

Bases: Receiver

Receiver object representing the sky dome for daylight calculations.

This class creates a receiver object that represents the entire sky dome, including both sky and ground hemispheres. Used in daylight matrix calculations to capture contributions from all sky directions.

Attributes:

Name	Type	Description
basis		Sampling basis string defining sky patch discretization.
content		Sky dome definition encoded as string for Radiance input.

Initialize a sky receiver object.

Parameters:

Name	Type	Description	Default
basis	str	Sampling basis string defining sky patch discretization (e.g., 'kf' for Klems full, 'r4' for Reinhart 4-division).	required
out	str | None	Optional output file path for matrix results.	None

frads.SurfaceReceiver

SurfaceReceiver(surfaces, basis, left_hand=False, offset=None, source='glow', out=None)

Bases: Receiver

Receiver object representing surfaces that collect light.

This class creates a receiver object from surface primitives using a specified sampling basis. Used for calculating how much light surfaces receive from various sources in daylight and artificial lighting simulations.

Attributes:

Name	Type	Description
surfaces		List of surface primitives (polygons or rings) acting as receivers.
basis		Sampling basis string defining directional discretization.
content		Surface data encoded as string for Radiance rfluxmtx input.

Initialize a surface receiver object.

Parameters:

Name	Type	Description	Default
surfaces	list[Primitive]	List of surface primitives (polygons or rings) to use as receivers.	required
basis	str	Sampling basis string defining directional discretization.	required
left_hand	bool	Whether to use left-hand coordinate system for basis orientation.	False
offset	float | None	Distance to offset the receiver surface along its normal vector.	None
source	str	Light source type for the receiver ('glow' or 'light').	'glow'
out	str | None	Optional output file path for matrix results.	None

Raises:

Type	Description
ValueError	If surfaces are not primitives or contain invalid types.

frads.SunMatrix

SunMatrix(sender, receiver, octree, surfaces=None)

Bases: Matrix

Specialized matrix object for direct solar radiation calculations.

This class extends the base Matrix class to handle sun-only calculations using the Radiance rcontrib tool. It's optimized for sparse matrices since most solar positions contribute zero radiation at any given time.

Attributes:

Name	Type	Description
sender		Sender object (SensorSender or ViewSender only).
receiver		SunReceiver object representing discrete solar positions.
octree		Path to octree file for ray tracing acceleration.
surfaces		List of environment surface file paths.
array		Sparse matrix array storing sun contribution data.
nrows	int	Number of rows (sender basis size or sensor count).
ncols		Number of columns (solar position count).
dtype		Matrix data type ('d' for double, 'f' for float).
ncomp		Number of color components (typically 3 for RGB).

Initialize a sun matrix object.

Parameters:

Name	Type	Description	Default
sender	SensorSender | ViewSender	Sender object (SensorSender or ViewSender only).	required
receiver	SunReceiver	SunReceiver object representing discrete solar positions.	required
octree	str | None	Optional path to octree file for ray tracing acceleration.	required
surfaces	list[str] | None	Optional list of environment surface file paths.	None

Raises:

Type	Description
TypeError	If sender is a SurfaceSender (not supported for sun matrices).

generate

generate(parameters, nproc=1, radmtx=False, sparse=False)

Generate the sun matrix using Radiance rcontrib tool.

Parameters:

Name	Type	Description	Default
parameters	list[str]	List of rcontrib command-line parameters (e.g., ['-ab', '1', '-ad', '512']).	required
nproc	int	Number of parallel processes to use for calculation.	1
radmtx	bool	If True, return raw matrix bytes instead of processing into numpy array.	False
sparse	bool	If True, store result as sparse matrix format (recommended for sun matrices due to their inherently sparse nature).	False

Returns:

Type	Description
None | bytes	Raw matrix bytes if radmtx=True, otherwise None (matrix stored in self.array).

Raises:

Type	Description
TypeError	If receiver is not a SunReceiver object.

frads.SunReceiver

SunReceiver(basis, sun_matrix=None, window_normals=None, full_mod=False)

Bases: Receiver

Receiver object representing discrete solar positions for direct sun calculations.

This class creates a receiver object that represents the sun at discrete positions based on a Reinhart-Tregenza sky division. The number of active sun positions can be reduced based on annual solar data or window visibility constraints.

Attributes:

Name	Type	Description
basis		Sampling basis string (must be Reinhart-Tregenza format like 'r4').
content		Sun positions encoded as Radiance light sources.
modifiers		List of sun modifier names for active solar positions.

Initialize a sun receiver object.

Parameters:

Name	Type	Description	Default
basis	str	Sampling basis string (must be Reinhart-Tregenza format like 'r4').	required
sun_matrix	None | ndarray	Optional annual sun matrix to filter out zero-contribution solar positions. Shape should be (time_steps, sun_positions, components).	None
window_normals	None | list[ndarray]	Optional list of window normal vectors to filter out sun positions not visible through windows.	None
full_mod	bool	If True, include all sun modifiers regardless of filtering. If False, only include modifiers for active sun positions.	False

Raises:

Type	Description
ValueError	If basis is not a valid Reinhart-Tregenza format.

frads.load_matrix

load_matrix(file, dtype='float')

Load a Radiance matrix file into a numpy array.

Parameters:

Name	Type	Description	Default
file	bytes | str | Path	Path to Radiance matrix file or raw matrix bytes.	required
dtype	str	Data type for the output array ('float' or 'double').	'float'

Returns:

Type	Description
ndarray	Numpy array with shape (nrows, ncols, ncomp) containing the matrix data.

frads.load_binary_matrix

load_binary_matrix(buffer, nrows, ncols, ncomp, dtype, header=False)

Load a binary matrix buffer into a numpy array.

Parameters:

Name	Type	Description	Default
buffer	bytes	Raw binary data containing the matrix.	required
nrows	int	Number of matrix rows.	required
ncols	int	Number of matrix columns.	required
ncomp	int	Number of color components (typically 3 for RGB).	required
dtype	str	Data type string ('d' for double, 'f' for float).	required
header	bool	If True, strip Radiance header from buffer before parsing.	False

Returns:

Type	Description
ndarray	Numpy array with shape (nrows, ncols, ncomp) containing the matrix data.

frads.surfaces_view_factor

surfaces_view_factor(surfaces, env, ray_count=10000)

Calculate surface-to-surface view factors using rfluxmtx.

Computes geometric view factors between surfaces, representing the fraction of radiation leaving one surface that directly reaches another surface.

Parameters:

Name	Type	Description	Default
surfaces	list[Primitive]	List of surface primitives to calculate view factors for. Surface normals must face outward (away from the surface).	required
env	list[Primitive]	List of environment surface primitives that surfaces are exposed to. Surface normals must face inward (toward the calculation domain).	required
ray_count	int	Number of rays to spawn from each surface for Monte Carlo integration. Higher values improve accuracy but increase computation time.	10000

Returns:

Type	Description
dict[str, dict[str, list[float]]]	Nested dictionary where outer keys are source surface identifiers and
dict[str, dict[str, list[float]]]	inner keys are target surface identifiers, with values being RGB view factors.