xicsrt_spread¶
xicsrt.tools.xicsrt_spread
A set of algorithms to generate vector distributions.
Note
The term ‘spread’ here denotes the angular range of emission. The term ‘divergence’ is not used because I normally think of a divergence as a gaussian distributed probability distribution of angles. This type of distribution is available, but for generality and consistency ‘spread’ will be used throughout.

vector_distribution
(spread, number, name=None)[source]¶ A convenience function to retrieve vector distributions by name.
Parameters:  spread (float or array [radians]) – Can be a scalar or an array. See individual distributions for format and definitions.
 number (int) – The number of vectors to generate.
 name (string ('isotropic')) – The name of the vector distribution. Available names: ‘isotropic’, ‘isotropic_xy’, ‘flat’, ‘flat_xy’, ‘gaussian’.
Returns: A numpy array of shape (number, 3) containing the generated unit vectors.
Return type: ndarray

solid_angle
(spread, name=None)[source]¶ A convenience function to retrieve solid angles that correspond to the various vector distributions.
Units: [sr]

vector_dist_isotropic
(spread, number)[source]¶ Return unit vectors from an isotropic (uniform spherical) distribution that fall within an angular spread (divergence) of theta.
The ray cone is aligned along the zaxis.
Parameters:  spread (float [radians]) – The halfangle of the emitted cone of vectors (axis to edge).
 number (int) – The number of vectors to generate.
Returns: A numpy array of shape (number, 3) containing the generated unit vectors.
Return type: ndarray

solid_angle_isotropic
(spread)[source]¶ Calculate the solid angle for the vector_dist_isotropic distribution.
Parameters: spread (float [radians]) – The halfangle of cone of vectors (axis to edge). Returns: Units: [sr] Return type: solid_angle

vector_dist_isotropic_xy
(spread, number)[source]¶ Return random unit vectors from an isotroptic (uniform spherical) distribution that fall within a given x and y angular spread.
The truncatedcone of vectors is aligned along the zaxis.
Note
This routine repeatedly filters from a circular distribution, which is accurate but not efficent. Efficiency goes down for more unequal values of the x and y spread.
Todo
Replace vector_dist_isotropic_xy with a more efficent calculation. A possible approach is to calculate the 2D Joint Cumulative Distribution Function for isotropic emission on a flat plane.
Parameters:  spread (float or array [radians]) – The halfangles in the x and y directions that define the extent of thetruncatedcone of vectors. Spread can be contain either 1,2 or 4 values.s or [s]A single value that will be used for both the x and y directions.[x, y]Two values values that will be used for the x and y directions.[xmin, xmax, ymin, ymax]For values that define the asymmetric exent in x and y directions.Example: [0.1, 0.1, 0.5, 0.5]
 number (int) – The number of vectors to generate.
Returns: A numpy array of shape (number, 3) containing the generated unit vectors.
Return type: ndarray
 spread (float or array [radians]) –

solid_angle_isotropic_xy
(spread)[source]¶ Calculate the solid angle for the vector_dist_isotropic_xy distribution.
Units: [sr]

vector_dist_flat
(spread, number)[source]¶ Return unit vectors from an flat (uniform planar) distribution that fall within an angular spread.
The ray cone is aligned along the zaxis.
Parameters:  spread (float [radians]) – The halfangle of the emitted cone of vectors (axis to edge).
 number (int) – The number of vectors to generate.
Returns: A numpy array of shape (number, 3) containing the generated unit vectors.
Return type: ndarray

vector_dist_flat_xy
(spread, number)[source]¶ Return random unit vectors from an flat (uniform planar) distribution that fall within a given x and y angular spread.
The truncatedcone of vectors is aligned along the zaxis.
Note
This distribution is identical to that used by the SHADOW raytracing code for both the ‘flat’ and ‘uniform’ distributions (as of 202101).
Parameters:  spread (float or array [radians]) – The halfangles in the x and y directions that define the extent of thetruncatedcone of vectors. Spread can be contain either 1,2 or 4 values.s or [s]A single value that will be used for both the x and y directions.[x, y]Two values values that will be used for the x and y directions.[xmin, xmax, ymin, ymax]For values that define the asymmetric exent in x and y directions.Example: [0.1, 0.1, 0.5, 0.5]
 number (int) – The number of vectors to generate.
Returns: A numpy array of shape (number, 3) containing the generated unit vectors.
Return type: ndarray
 spread (float or array [radians]) –

vector_dist_flat_gaussian
(spread, num_samples)[source]¶ Create distribution of vectors with a Gaussian distribution on a flat plane. The ray code is aligned with the zaxis, so the distribution is Gaussian in the xy directions.
For small angles this distribution will approximate the Kent distribution and will be approximately gaussian in angle.
Parameters: spread (float [radians]) – The halfwithathalfmax (hwhm) of the Gaussian angular distribution. Returns: A numpy array of shape (number, 3) containing the generated unit vectors. Return type: ndarray
Private Members¶

_parse_spread_single
(spread)[source] Parse the number of input values in spread and return a standard array. Use only for distribution with a single spread value.

_parse_spread_xy
(spread)[source] Parse the number of input values in spread and return a standard array. Use only for assymetric xy distributions.

_to_ndarray
(spread)[source] Convert input value to an numpy array. Scalars will be transformed to a one element array.