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)

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)

A convenience function to retrieve solid angles that correspond to the various vector distributions.

Units: [sr]

vector_dist_isotropic(spread, number)

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)

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)

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 the

  truncated-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)

Calculate the solid angle for the vector_dist_isotropic_xy distribution.

Units: [sr]

vector_dist_flat(spread, number)

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)

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 the

  truncated-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)

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)

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)

Parse the number of input values in spread and return a standard array. Use only for assymetric xy distributions.

_to_ndarray(spread)

Convert input value to an numpy array. Scalars will be transformed to a one element array.