0
# Core Quaternion Operations
1
2
Fundamental quaternion functionality including the quaternion type, predefined constants, arithmetic operations, and efficient array manipulation functions. These operations form the foundation for all quaternion computations.
3
4
## Capabilities
5
6
### Quaternion Construction
7
8
Create quaternions from individual components or arrays.
9
10
```python { .api }
11
def quaternion(w=0.0, x=0.0, y=0.0, z=0.0):
12
"""
13
Create a quaternion from scalar and vector components.
14
15
Args:
16
w (float): Scalar component (real part)
17
x (float): i component (first imaginary part)
18
y (float): j component (second imaginary part)
19
z (float): k component (third imaginary part)
20
21
Returns:
22
quaternion: New quaternion with specified components
23
"""
24
```
25
26
### Predefined Quaternion Constants
27
28
Standard quaternion constants for common operations.
29
30
```python { .api }
31
# Fundamental quaternion constants
32
zero = quaternion(0, 0, 0, 0) # Zero quaternion
33
one = quaternion(1, 0, 0, 0) # Identity quaternion
34
x = quaternion(0, 1, 0, 0) # Basis quaternion i
35
y = quaternion(0, 0, 1, 0) # Basis quaternion j
36
z = quaternion(0, 0, 0, 1) # Basis quaternion k
37
```
38
39
### Array Conversion Functions
40
41
Convert between quaternion arrays and float arrays for interoperability and performance.
42
43
```python { .api }
44
def as_float_array(a):
45
"""
46
View quaternion array as float array with shape (..., 4).
47
48
Args:
49
a (array_like): Quaternion array
50
51
Returns:
52
ndarray: Float array with components [w, x, y, z] in last dimension
53
54
Notes:
55
Fast view operation (no data copying). Output has one more dimension
56
than input, with size 4 representing [w, x, y, z] components.
57
"""
58
59
def as_quat_array(a):
60
"""
61
View float array as quaternion array.
62
63
Args:
64
a (array_like): Float array with last dimension divisible by 4
65
66
Returns:
67
quaternion array: Array interpreted as quaternions
68
69
Notes:
70
Input must have final dimension size divisible by 4. Components
71
interpreted as [w, x, y, z]. Fast view when input is C-contiguous.
72
"""
73
74
def from_float_array(a):
75
"""
76
Alias for as_quat_array.
77
78
Args:
79
a (array_like): Float array to convert
80
81
Returns:
82
quaternion array: Array interpreted as quaternions
83
"""
84
```
85
86
### Vector Part Operations
87
88
Work with the 3D vector components of quaternions (x, y, z parts).
89
90
```python { .api }
91
def as_vector_part(q):
92
"""
93
Extract vector parts from quaternions as float array.
94
95
Args:
96
q (quaternion array_like): Input quaternions
97
98
Returns:
99
ndarray: Float array of shape q.shape + (3,) containing [x, y, z] components
100
"""
101
102
def from_vector_part(v, vector_axis=-1):
103
"""
104
Create quaternions from vector parts (w=0).
105
106
Args:
107
v (array_like): Array of 3D vectors or quaternion array
108
vector_axis (int): Axis containing vector components (default: -1)
109
110
Returns:
111
quaternion array: Quaternions with w=0 and vector parts from input
112
113
Notes:
114
If input has quaternion dtype, returns unchanged. Otherwise, expects
115
dimension of size 3 or 4 along vector_axis. For size 4, sets w=0.
116
"""
117
```
118
119
### Spinor Representation
120
121
Convert quaternions to two-complex spinor representation.
122
123
```python { .api }
124
def as_spinor_array(a):
125
"""
126
View quaternion array as spinors in two-complex representation.
127
128
Args:
129
a (quaternion array_like): Input quaternion array
130
131
Returns:
132
ndarray: Complex array of shape a.shape + (2,)
133
134
Notes:
135
Slower operation involving memory copying due to column reordering.
136
Maps quaternion components to two complex numbers.
137
"""
138
```
139
140
### Mathematical Operations
141
142
Quaternions support all standard mathematical operations through NumPy's ufunc system:
143
144
#### Arithmetic Operations
145
- Addition: `q1 + q2`
146
- Subtraction: `q1 - q2`
147
- Multiplication: `q1 * q2` (quaternion product)
148
- Division: `q1 / q2` (multiply by reciprocal)
149
- Power: `q ** n` (quaternion exponentiation)
150
151
#### Mathematical Functions
152
- `np.conjugate(q)` or `q.conjugate()`: Quaternion conjugate
153
- `np.abs(q)` or `q.norm()`: Quaternion norm/magnitude
154
- `q.normalized()`: Unit quaternion (norm 1)
155
- `np.exp(q)`: Quaternion exponential
156
- `np.log(q)`: Quaternion logarithm
157
- `np.sqrt(q)`: Quaternion square root
158
- Trigonometric: `np.sin(q)`, `np.cos(q)`, `np.tan(q)`
159
- Inverse trigonometric: `np.arcsin(q)`, `np.arccos(q)`, `np.arctan(q)`
160
161
#### Comparison Operations
162
- Equality: `q1 == q2`
163
- Inequality: `q1 != q2`
164
- Ordering: `q1 < q2`, `q1 <= q2`, `q1 > q2`, `q1 >= q2` (lexicographic)
165
166
#### Utility Functions
167
- `np.isnan(q)`: Check for NaN components
168
- `np.isinf(q)`: Check for infinite components
169
- `np.isfinite(q)`: Check if all components are finite
170
- `q.nonzero()`: Check if quaternion is non-zero
171
172
## Usage Examples
173
174
```python
175
import quaternion
176
import numpy as np
177
178
# Create quaternions
179
q1 = quaternion.quaternion(1, 2, 3, 4)
180
q2 = quaternion.quaternion(0.5, -1, 0, 2)
181
182
# Array operations
183
q_array = np.array([q1, q2, quaternion.x, quaternion.y])
184
print(f"Array shape: {q_array.shape}")
185
186
# Convert to float representation
187
float_repr = quaternion.as_float_array(q_array)
188
print(f"Float array shape: {float_repr.shape}") # (..., 4)
189
190
# Extract vector parts
191
vectors = quaternion.as_vector_part(q_array)
192
print(f"Vector parts shape: {vectors.shape}") # (..., 3)
193
194
# Create from vectors (pure quaternions)
195
pure_quats = quaternion.from_vector_part(vectors)
196
197
# Mathematical operations
198
conjugates = np.conjugate(q_array)
199
norms = np.abs(q_array)
200
normalized = q_array / norms[..., np.newaxis]
201
202
# Check properties
203
finite_mask = np.isfinite(q_array)
204
nonzero_mask = np.array([q.nonzero() for q in q_array])
205
206
# Advanced comparison with tolerance
207
close_mask = quaternion.isclose(q_array, normalized, rtol=1e-10)
208
all_close = quaternion.allclose(q_array, normalized, verbose=True)
209
```
210
211
### Advanced Comparison Functions
212
213
Precise comparison functions with configurable tolerances for quaternion equality testing.
214
215
```python { .api }
216
def isclose(a, b, rtol=4*np.finfo(float).eps, atol=0.0, equal_nan=False):
217
"""
218
Element-wise test for close equality with tolerance.
219
220
Args:
221
a (array_like): First quaternion array
222
b (array_like): Second quaternion array
223
rtol (float): Relative tolerance (default: 4*machine epsilon)
224
atol (float): Absolute tolerance (default: 0.0)
225
equal_nan (bool): Consider NaN values as equal (default: False)
226
227
Returns:
228
ndarray: Boolean array indicating element-wise closeness
229
230
Notes:
231
Uses |a - b| <= atol + rtol * |b| comparison formula.
232
More stringent defaults than numpy.isclose for quaternion precision.
233
"""
234
235
def allclose(a, b, rtol=4*np.finfo(float).eps, atol=0.0, equal_nan=False, verbose=False):
236
"""
237
Test if all quaternions in arrays are close within tolerance.
238
239
Args:
240
a (array_like): First quaternion array
241
b (array_like): Second quaternion array
242
rtol (float): Relative tolerance (default: 4*machine epsilon)
243
atol (float): Absolute tolerance (default: 0.0)
244
equal_nan (bool): Consider NaN values as equal (default: False)
245
verbose (bool): Print non-close values if result is False (default: False)
246
247
Returns:
248
bool: True if all elements are close, False otherwise
249
250
Notes:
251
Wrapper around isclose() returning single boolean result.
252
Verbose mode prints mismatched values for debugging.
253
"""
254
```