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 z-axis.
- Parameters:
spread (float [radians]) – The half-angle 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 half-angle 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 truncated-cone of vectors is aligned along the z-axis.
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 half-angles in the x and y directions that define the extent of thetruncated-cone 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
- 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 z-axis.
- Parameters:
spread (float [radians]) – The half-angle 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 truncated-cone of vectors is aligned along the z-axis.
Note
This distribution is identical to that used by the SHADOW raytracing code for both the ‘flat’ and ‘uniform’ distributions (as of 2021-01).
- Parameters:
spread (float or array [radians]) –
The half-angles in the x and y directions that define the extent of thetruncated-cone 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
- 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 z-axis, so the distribution is Gaussian in the x-y directions.
For small angles this distribution will approximate the Kent distribution and will be approximately gaussian in angle.
- Parameters:
spread (float [radians]) – The half-with-at-half-max (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.