magali.random_directions

magali.random_directions#

magali.random_directions(inclination, declination, dispersion_angle, size, random_state=None)[source]#

Creates random directions around a preferred direction.

Parameters:

  • inclination (float) – Inclination of the preferred direction in degrees.

  • declination (float) – Declination of the preferred direction in degrees.

  • dispersion_angle (float) – Dispersion angle in degrees that defines a region on the surface of a sphere. Corresponds to the variance of the generated directions.

  • size (int) – Number of random directions to be generated.

  • random_state (numpy.random.RandomState or an int seed) – A random number generator used to define the state of the random permutations. Use a fixed seed to make sure computations are reproducible. Use None to choose a seed automatically (resulting in different numbers with each run).

Returns:

  • inclination (numpy.array) – Inclination of the generated directions in degrees.

  • declination (numpy.array) – Declination of the generated directions in degrees.

Notes

We calculate the azimuth (\(\alpha\)) via a random uniform distribution ranging from 0° to 360°, to represent the equal probability for each value in a stereographic polar projection. The distance to the pole (\(\psi\)) for each vector is obtained with a normal distribution. Given the values of azimuth (\(\alpha\)) and distance to the pole (\(\psi\)), we calculate the cartesian coordinates

\[x = \sin(\psi) * cos(\alpha)\]
\[y = np.sin(\psi) * sin(\alpha)\]
\[z = np.cos(\psi)\]

The rotation of the pole is performed to the preferred direction using the specified values of inclination and declination to obtain the rotation vector. With \(\theta=90°+inclination\) and \(\phi=90°-declination\) we calculate the rotation vector by

\[\begin{split}\mathbf{u}=\begin{bmatrix} x\\y\\z \end{bmatrix}\\\end{split}\]
\[\begin{split}\mathbf{R}_z(\phi)\mathbf{R}_y(\theta)\mathbf{u}=\begin{bmatrix} \cos(\theta)&0&\sin(\theta)\\ 0&1&0\\ -\sin(\theta)&0&\cos(\cos) \end{bmatrix}\begin{bmatrix} \cos(\phi)&-\sin(\phi)&0\\ \sin(\phi)&\cos(\phi)&0\\ 0&0&1 \end{bmatrix}\begin{bmatrix} x\\y\\z \end{bmatrix}\\\end{split}\]
\[\begin{split}\mathbf{R}_z(\phi) \mathbf{R}_y(\theta)\mathbf{u} = \begin{bmatrix} \cos(\phi)(x\cos(\theta)+z\sin(\theta))-y\sin(\phi) \\ \sin(\phi)(x\cos(\theta)+z\sin(\theta))+y\cos(\phi) \\ -x\sin(\theta)+z\cos(\theta) \end{bmatrix}\end{split}\]

in which \(\mathbf{R}_z(\phi)\) and \(\mathbf{R}_z(\phi)\) are the rotation matrices on the z and y axes, respectively.