jaxdem.utils.angles#

Utility functions to compute angles between vectors.

Functions

`angle`(v1, v2)	Angle from v1 -> v2 in $[0, \pi]$.
`angle_x`(v1)	Angle from v1 -> $\hat{x}$ in $[0, \pi]$.
`signed_angle`(v1, v2)	Directional angle from v1 -> v2 around normal $\hat{z}$ (right-hand rule), in $[-\pi, \pi)$.
`signed_angle_x`(v1)	Directional angle from v1 -> $\hat{x}$ around normal $\hat{z}$, in $(-\pi, \pi]$.

jaxdem.utils.angles.angle(v1: Array, v2: Array) → Array[source]#

Angle from v1 -> v2 in $[0, \pi]$.

Calculates the unsigned angle between two vectors $\vec{v}_1$ and :math:$vec{v}_2$ using a numerically stable half-angle formula:

\[\begin{split}\hat{v}_1 &= \text{unit}(\vec{v}_1) \\ \hat{v}_2 &= \text{unit}(\vec{v}_2) \\ y &= \|\hat{v}_1 - \hat{v}_2\| \\ x &= \|\hat{v}_1 + \hat{v}_2\| \\ \theta &= 2 \cdot \text{atan2}(y, x)\end{split}\]

Parameters:

v1 (jax.Array) – First vector. Shape (…, dim).
v2 (jax.Array) – Second vector. Shape (…, dim).

Returns:

Unsigned angle in radians.

Return type:

jax.Array

jaxdem.utils.angles.angle_x(v1: Array) → Array[source]#

Angle from v1 -> $\hat{x}$ in $[0, \pi]$.

Calculates the unsigned angle of a vector :math:`vec{v}_1$ relative to the positive x-axis :math:`(1, 0, dots)$:

\[\begin{split}\hat{v}_1 &= \text{unit}(\vec{v}_1) \\ y &= \sqrt{2(1 - \hat{v}_{1,x})} \\ x &= \sqrt{2(1 + \hat{v}_{1,x})} \\ \theta &= 2 \cdot \text{atan2}(y, x)\end{split}\]

Parameters:: v1 (jax.Array) – The input vector. Shape (…, dim).
Returns:: Unsigned angle in radians.
Return type:: jax.Array

jaxdem.utils.angles.signed_angle(v1: Array, v2: Array) → Array[source]#

Directional angle from v1 -> v2 around normal $\hat{z}$ (right-hand rule), in $[-\pi, \pi)$.

Calculates the signed angle between two 2D vectors $\vec{v}_1$ and :math:$vec{v}_2$ using the dot product and the 2D cross product:

\[\begin{split}\hat{v}_1 &= \text{unit}(\vec{v}_1) \\ \hat{v}_2 &= \text{unit}(\vec{v}_2) \\ d &= \hat{v}_1 \cdot \hat{v}_2 \\ s &= \hat{v}_{1,x} \hat{v}_{2,y} - \hat{v}_{1,y} \hat{v}_{2,x} \\ \theta &= \text{atan2}(s, d)\end{split}\]

Parameters:

v1 (jnp.ndarray) – First vector. Shape (…, 2).
v2 (jnp.ndarray) – Second vector. Shape (…, 2).

Returns:

Signed angle in radians.

Return type:

jnp.ndarray

jaxdem.utils.angles.signed_angle_x(v1: Array) → Array[source]#

Directional angle from v1 -> $\hat{x}$ around normal $\hat{z}$, in $(-\pi, \pi]$.

Calculates the signed angle of a 2D vector :math:`vec{v}_1$ relative to the positive x-axis :math:`(1, 0)$:

\[\theta = \text{atan2}(-v_{1,y}, v_{1,x})\]

Parameters:: v1 (jnp.ndarray) – The input vector. Shape (…, 2).
Returns:: Signed angle in radians.
Return type:: jnp.ndarray

`angle`(v1, v2)	Angle from v1 -> v2 in \([0, \pi]\).
`angle_x`(v1)	Angle from v1 -> \(\hat{x}\) in \([0, \pi]\).
`signed_angle`(v1, v2)	Directional angle from v1 -> v2 around normal \(\hat{z}\) (right-hand rule), in \([-\pi, \pi)\).
`signed_angle_x`(v1)	Directional angle from v1 -> \(\hat{x}\) around normal \(\hat{z}\), in \((-\pi, \pi]\).