angle returns different values for a unit quaternion and its antipodal quaternion

[empet]

If q is a unit quaternion, then q and -q define the same rotation:
$R_{-q}(v)=-qv(-\overline{q})= qv\overline{q}=R_q(v)$
Hence the rotation $R_{-q}$ has the same axis and angle of rotation as $R_q$.
Another argument::
If $q=\exp({\bf u} \theta/2)$ then $\mathtt{angle}(q)=\theta$.
$-q=-exp({\bf u}\theta/2)=-\cos(\theta/2)-u \sin(\theta/2)= \cos(\pi+\theta/2)+u \sin(\pi+\theta/2)$
Hence the rotation angle of $-q$ is $2\pi+\theta=\theta$ (modulo $2\pi$)
Quaternionic.jl returns two different angles for q and -q:
```
q = rotor(2, -1, 3, 1.5)
alpha = angle(q)
2.1033004250967466

beta = angle(-q)
4.17988488208284

alpha+beta
6.283185307179586

[moble]

It's true that q and -q map to the same rotations in $\mathrm{SO}(3)$, but they are not the same quaternion — and that's also important structure to retain when considering quaternion-valued functions, as in interpolation and differentiation. In particular, it should always be true that exp(angle(q)*normalize(QuatVec(q))/2) ≈ q. Your second argument is essentially making my point — except that you've forgotten that the sign of $\bf{u}$ would naturally be reversed in the second case.

Put another way, the current angle(q) returns the distance through which the spinor has to be rotated from $1$.

[empet]

I tried to use Quaternionic.angle for a different purpose, but the definition and the example given in docs are confusing.
The reader is tempted to think that it returns the rotation angle for the rotation corresponding to a given rotor.
I used this function in an attempt to check the probability distribution
of the rotation angle for a uniform sample on the 3-sphere (the group of unit quaternions).
This angle has the pdf $f(\theta)=(1-\cos(\theta))/\pi$, with the support $[0, \pi]$, but obviously
it didn't fit to the histogram of Quaternionic.angle(q) ,computed for each $q$ in the sample, because the angle values on these samples belong to $[0, 2\pi]$.
This is the code with a custom function for rotation angle:

using Random, Quaternionic, Plots
import Rotations: RotMatrix, rotation_angle
function Base.rand(rng::AbstractRNG, ::Random.SamplerType{Rotor{T}}) where T<:AbstractFloat
    u = rand(rng, T, 3)
    Rotor{T}(sqrt(1-u[1])*cos(2π*u[2]),  
                sqrt(u[1])*cos(2π*u[3]), sqrt(u[1])*sin(2π*u[3]), sqrt(1-u[1])*sin(2π*u[2]))    
end

rot_angle(q::Rotor)= rotation_angle(RotMatrix(to_rotation_matrix(q)))
begin
    quats = rand(Rotor{Float64}, 2000)
    #theta=angle.(q); #for this case define x=range(0, 2pi, 150)
    theta = [rot_angle(p) for p in quats]
    x = range(0, pi, 100)
    bins = range(0, pi, 20)

    pl = Plots.histogram(theta, bins=bins, normalize=:pdf, label="hist rot angles", size=(400, 200))
    plot!(pl, x, (1 .-cos.(x))/pi, lw=2, label="rot angles pdf")
end 

with the attached image as plot.

Here is how Quaternionic.angle works compared to my function rot_angle, that leads to the right experimental distribution of the rotation angles:

q = exp(1.43*imz)
angle(q), angle(-q)  

(2.86, 3.4231853071795864) 

rot_angle(q), rot_angle(-q)  
                        
(2.86, 2.86) 

rot_angle(q), rot_angle(-q) return the same angle because, as I pointed out in the initial post,
$-q$ has the same polar angle, computed modulo $2\pi$, as $q$.

[moble]

Right, and for the angle function, the PDF is $f(\theta)=(1-\cos(\theta))/2\pi$, with the support $[0, 2\pi]$. The reason you get your PDF for rotation_angle is that

$$ \exp\left[ (\theta) (\bf{u}) / 2 \right] = -\exp\left[ (2\pi-\theta) (-\bf{u}) / 2 \right]. $$

So if you don't care about the overall sign, the angles $\theta$ and $2\pi-\theta$ are equivalent; you can just mirror the full PDF back about $\pi$.

FYI, randn(Rotor{Float64}) already works to give you a uniform distribution. The reason is that randn(4) gives you a point in 4-D with a spherically symmetric distribution (Gaussian in the radial direction), so randn(Quaternion{Float64}) does the same, and therefore randn(Rotor{Float64}) normalizes the result which gives you a spherically symmetric distribution.

using Random, Quaternionic, Plots

quats = randn(Rotor{Float64}, 1_000_000)

theta = angle.(quats)
x = range(0, 2pi, 200)
bins = range(0, 2pi, 40)
pl = Plots.histogram(theta, bins=bins, normalize=:pdf, label="hist rot angles", size=(400, 200))
plot!(pl, x, (1 .-cos.(x))/2pi, lw=2, label="rot angles pdf")
title!(pl, "Original angle in [0, 2π]")

theta = [ang ≤ π ? ang : 2π - ang for ang in theta]
x = range(0, pi, 100)
bins = range(0, pi, 20)
pl = Plots.histogram(theta, bins=bins, normalize=:pdf, label="hist rot angles", size=(400, 200))
plot!(pl, x, (1 .-cos.(x))/pi, lw=2, label="rot angles pdf")
title!(pl, "Mapped back to [0, π]")