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 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)[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 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)[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.