qmatmul 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. qmatmul-1.0.0/PKG-INFO +203 -0
  2. qmatmul-1.0.0/README.md +183 -0
  3. qmatmul-1.0.0/pyproject.toml +35 -0
  4. qmatmul-1.0.0/setup.cfg +4 -0
  5. qmatmul-1.0.0/src/qmatmul.egg-info/PKG-INFO +203 -0
  6. qmatmul-1.0.0/src/qmatmul.egg-info/SOURCES.txt +7 -0
  7. qmatmul-1.0.0/src/qmatmul.egg-info/dependency_links.txt +1 -0
  8. qmatmul-1.0.0/src/qmatmul.egg-info/requires.txt +4 -0
  9. qmatmul-1.0.0/src/qmatmul.egg-info/top_level.txt +1 -0
qmatmul-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,203 @@
1
+ Metadata-Version: 2.4
2
+ Name: qmatmul
3
+ Version: 1.0.0
4
+ Summary: Fast multiplications of quaternion-valued matrices.
5
+ Author-email: Przemysław Klęsk <pklesk@zut.edu.pl>, Aleksandr Cariov <alexandr.tariov@zut.edu.pl>
6
+ Project-URL: Homepage, https://github.com/pklesk/quaternions
7
+ Project-URL: Bug Tracker, https://github.com/pklesk/quaternions/issues
8
+ Project-URL: Documentation, https://pklesk.github.io/quaternions/
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: POSIX :: Linux
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
14
+ Requires-Python: >=3.12
15
+ Description-Content-Type: text/markdown
16
+ Requires-Dist: numpy>=2.3
17
+ Requires-Dist: numba>=0.62
18
+ Requires-Dist: numba-cuda[cu13]>=0.30
19
+ Requires-Dist: threadpoolctl>=3.6
20
+
21
+ # qmatmul: Fast multiplication of quaternion-valued matrices - algorithm and its implementations for sequential and CUDA computations
22
+ We present an algorithm for fast multiplication of matrices whose elements are *quaternions* - hypercomplex numbers consisting of one real and three imaginary parts.
23
+ The number of elementary floating-point multiplications involved in the algorithm is reduced *twice* with respect to the definition-based formula,
24
+ regardless of the input matrices. This is owed to a suitable representation and decomposition into two products, one of which takes advantage of certain
25
+ diagonal symmetry properties, the other of sparsity.
26
+
27
+ The `qmatmul` package is suitable for Python's ecosystem.
28
+ Altogether, we provide 8 implementation variants of matrix-matrix multiplication for quaternion-valued inputs.
29
+ The variants cover several approaches based on [NumPy](https://numpy.org), thus supported by BLAS,
30
+ but also several approaches employing [Numba](https://numba.pydata.org) - a just-in-time compiler targeting both CPU and GPU (CUDA).
31
+ Our design of CUDA computations for the proposed algorithm involves: 6 kernel functions with 11 invocations, tiling and shared memory,
32
+ and few host-device memory transfers.
33
+
34
+ ## Selected kernels - flows of CUDA computations
35
+ <table>
36
+ <tr>
37
+ <td valign="top"><img width="1150" height="1496" alt="had4_flow" src="https://github.com/user-attachments/assets/091bb888-3c58-421a-8165-dff3643dcdbf"/></td>
38
+ <td valign="top"><img width="1492" height="2046" alt="matmuldiag_flow" src="https://github.com/user-attachments/assets/302b37ce-58d9-46d5-9b0f-c9d7bf1ab001"/></td>
39
+ </tr>
40
+ </table>
41
+
42
+ ## Speed-ups
43
+ <table>
44
+ <tr>
45
+ <td valign="top"><img src="extras/speedups_float32_5090.png"/></td>
46
+ <td valign="top"><img src="extras/speedups_float64_5090.png"/></td>
47
+ </tr>
48
+ </table>
49
+
50
+ ## Installation
51
+ ```bash
52
+ pip install TODO
53
+ ```
54
+ Note: for further usage, NVIDIA CUDA drivers must be present in the operating system.
55
+
56
+ ## Usage example 1
57
+ Suppose one would like to multiply the following matrices of quaternions:
58
+
59
+ <!-- -->
60
+ $$
61
+ \begin{aligned}
62
+ {\tiny
63
+ \begin{pmatrix}
64
+ 2i +j & -1 +i -j + 4k & 5 -i +3j \\
65
+ 1 +4i -4j -4k & -5 +3i +3j +4k & 5 +3i +3k \\
66
+ -4 +i -4j + 4k & -i -2j +3k & i -5j +k \\
67
+ 1 +i +4j + 2k& -1 -i +2j -4k & 2 +2i -3j -4k \\
68
+ -2 -i +j -k & 5 -4i -3j -3k & 2 -2i -3k
69
+ \end{pmatrix}
70
+ }
71
+ {\cdot}
72
+ {\tiny
73
+ \begin{pmatrix}
74
+ -3 -4i + 2j -4k & -3 -i +3j -4k \\
75
+ 3 - 4i +5j & 5 +i +2j -5k\\
76
+ -2 -4i -2j -4k & -2 -i -4j +2k
77
+ \end{pmatrix}
78
+ }
79
+ {\tiny =}
80
+ {\tiny
81
+ \begin{pmatrix}
82
+ 4 -53i -39j +15k & 16 -6i -17j +52k \\
83
+ 1 -3i +4j +7k & -30 +3i +30j +56k \\
84
+ 44 +23i -16j -38k & 40 -4i -5j +7k \\
85
+ -34 -14i +29j -17k & -40 -62i -10j -21k \\
86
+ -14 -18i +21j -26k & 18 -41j -18k
87
+ \end{pmatrix}.
88
+ }
89
+ \end{aligned}
90
+ $$
91
+ <!-- -->
92
+
93
+ With `qmatmul` module installed, one can write:
94
+ ```python
95
+ import qmatmul as qmm
96
+ import numpy as np
97
+ import time
98
+
99
+ print("QMATMUL EXAMPLE...")
100
+ A = np.array([
101
+ [[ 0, 2, 1, 0], [-1, 1, -1, 4], [ 5, -1, 3, 0]],
102
+ [[ 1, 4, -4, -4], [-5, 3, 3, 4], [ 5, 3, 0, 3]],
103
+ [[-4, 1, -4, 4], [ 0, -1, -2, -3], [ 0, 1, -5, 1]],
104
+ [[ 1, 1, 4, 2], [-1, -1, 2, -4], [ 2, 2, -3, -4]],
105
+ [[-2, -1, 1, -1], [ 5, -4, -3, -3], [ 2, -2, 0, -3]]
106
+ ])
107
+ B = np.array([
108
+ [[-3, -4, 2, -4], [-3, -1, 3, -4]],
109
+ [[ 3, -4, 5, 0], [ 5, 1, 2, -5]],
110
+ [[-2, -4, -2, -4], [-2, -1, -4, 2]]
111
+ ])
112
+ t1 = time.time()
113
+ C = qmm.dot(A, B)
114
+ t2 = time.time()
115
+ print(f"RESULT -> C:")
116
+ print(C)
117
+ print(f"QMATMUL EXAMPLE DONE. TIME OF qmm.dot: {t2 - t1:.6f} s.")
118
+ ```
119
+ Running the code above produces the following output:
120
+ ```bash
121
+ QMATMUL EXAMPLE...
122
+ RESULT -> C:
123
+ [[[ 4. -53. -39. 15.]
124
+ [ 16. -6. -17. 52.]]
125
+
126
+ [[ 1. -3. 4. 7.]
127
+ [-30. 3. 30. 56.]]
128
+
129
+ [[ 44. 53. 8. -56.]
130
+ [ 10. 8. -11. -23.]]
131
+
132
+ [[-34. -14. 29. -17.]
133
+ [-40. -62. -10. -21.]]
134
+
135
+ [[-14. -18. 21. -26.]
136
+ [ 18. 0. -41. -18.]]]
137
+ QMATMUL EXAMPLE DONE. TIME OF qmm.dot: 0.001703 s.
138
+ ```
139
+
140
+ ## Usage example 2 (large arguments)
141
+ In the example below, two large random matrices with quaternions are multiplied.
142
+ ```python
143
+ import qmatmul as qmm
144
+ import numpy as np
145
+ import time
146
+
147
+ print("QMATMUL EXAMPLE (LARGE ARGUMENTS)...")
148
+ M, N, P = 1000, 3000, 2000
149
+ np.random.seed(0)
150
+ A = np.random.rand(M, N, 4) # M x N matrix of quaternions
151
+ B = np.random.rand(N, P, 4) # N x P matrix of quaternions
152
+ t1 = time.time()
153
+ C = qmm.dot(A, B)
154
+ t2 = time.time()
155
+ print(f"RESULT FRAGMENT -> C[:3, :3]:")
156
+ print(C[:3, :3])
157
+ print(f"QMATMUL EXAMPLE (LARGE ARGUMENTS) DONE. TIME OF qmm.dot: {t2 - t1:.6f} s.")
158
+ ```
159
+ The result is computed fast:
160
+ ```bash
161
+ QMATMUL EXAMPLE (LARGE ARGUMENTS)...
162
+ RESULT FRAGMENT -> C[:3, :3]:
163
+ [[[-1528.6768062 1482.01579334 1482.64352966 1469.29588132]
164
+ [-1474.39555984 1485.26884228 1485.81638515 1486.03433938]
165
+ [-1459.21558118 1487.12054919 1468.20437822 1461.65795584]]
166
+
167
+ [[-1502.50516591 1465.24326325 1494.5907814 1503.74503685]
168
+ [-1472.32677282 1493.41728185 1487.01751106 1506.41597882]
169
+ [-1460.42240679 1488.1077977 1474.34164258 1504.36179871]]
170
+
171
+ [[-1558.07311493 1475.34714296 1475.731701 1495.41197899]
172
+ [-1528.83559572 1476.28138065 1474.62854662 1504.35168932]
173
+ [-1508.66904595 1501.06439708 1459.07714887 1471.97545486]]]
174
+ QMATMUL EXAMPLE (LARGE ARGUMENTS) DONE. TIME OF qmm.dot: 0.151431 s.
175
+ ```
176
+
177
+ ## Choice of approach
178
+
179
+ An additional optional argument `approach`, e.g., `qmm.dot(A, B, approach="...")`, allows
180
+ the user to select one of the following eight computational approaches:
181
+
182
+ | approach | target, mode | description |
183
+ |:-------------------------------|:---------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
184
+ | `"naive_numba_st"` | CPU, single-threaded | naive single-threaded implementation of definition-based formula consisting of three nested loops, low-level compiled via Numba and LLVM |
185
+ | `"naive_numba_parallel"` | CPU, multi-threaded | as above, but parallelized over CPU cores |
186
+ | `"direct_numpy_st"` | CPU, single-threaded | direct implementation of formula based on the transformation matrix and stacked representation (followed by unstack), using NumPy/BLAS |
187
+ | `"direct_numpy_parallel"` | CPU, multi-threaded | as above, but allowing for CPU parallelization supported by NumPy/BLAS |
188
+ | `"direct_numba_cuda"` | GPU, multi-threaded | direct implementation of formula based on the transformation matrix and stacked representation (followed by unstack), using CUDA, compiled via Numba and LLVM to PTX/SASS |
189
+ | `"algo_numpy_st"` | CPU, single-threaded | implementation of the proposed fast algorithm, using NumPy/BLAS |
190
+ | `"algo_numpy_parallel"` | CPU, multi-threaded | as above, but allowing for CPU parallelization supported by NumPy/BLAS |
191
+ | `"algo_numba_cuda"` | GPU, multi-threaded | implementation of the proposed fast algorithm, using CUDA, compiled via Numba and LLVM to PTX/SASS |
192
+
193
+ The default setting is `"algo_numba_cuda"`.
194
+
195
+ ## Documentation
196
+ Developer documentation of the project is accessible at: [https://pklesk.github.io/quaternions](https://pklesk.github.io/quaternions). <br/>
197
+
198
+ ## License
199
+ This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
200
+
201
+ ## Acknowledgments and credits
202
+ - [NumPy](https://numpy.org): the fundamental package for scientific computing with Python.
203
+ - [Numba](https://numba.pydata.org): a high-performance just-in-time Python compiler.
qmatmul-1.0.0/README.md ADDED
@@ -0,0 +1,183 @@
1
+ # qmatmul: Fast multiplication of quaternion-valued matrices - algorithm and its implementations for sequential and CUDA computations
2
+ We present an algorithm for fast multiplication of matrices whose elements are *quaternions* - hypercomplex numbers consisting of one real and three imaginary parts.
3
+ The number of elementary floating-point multiplications involved in the algorithm is reduced *twice* with respect to the definition-based formula,
4
+ regardless of the input matrices. This is owed to a suitable representation and decomposition into two products, one of which takes advantage of certain
5
+ diagonal symmetry properties, the other of sparsity.
6
+
7
+ The `qmatmul` package is suitable for Python's ecosystem.
8
+ Altogether, we provide 8 implementation variants of matrix-matrix multiplication for quaternion-valued inputs.
9
+ The variants cover several approaches based on [NumPy](https://numpy.org), thus supported by BLAS,
10
+ but also several approaches employing [Numba](https://numba.pydata.org) - a just-in-time compiler targeting both CPU and GPU (CUDA).
11
+ Our design of CUDA computations for the proposed algorithm involves: 6 kernel functions with 11 invocations, tiling and shared memory,
12
+ and few host-device memory transfers.
13
+
14
+ ## Selected kernels - flows of CUDA computations
15
+ <table>
16
+ <tr>
17
+ <td valign="top"><img width="1150" height="1496" alt="had4_flow" src="https://github.com/user-attachments/assets/091bb888-3c58-421a-8165-dff3643dcdbf"/></td>
18
+ <td valign="top"><img width="1492" height="2046" alt="matmuldiag_flow" src="https://github.com/user-attachments/assets/302b37ce-58d9-46d5-9b0f-c9d7bf1ab001"/></td>
19
+ </tr>
20
+ </table>
21
+
22
+ ## Speed-ups
23
+ <table>
24
+ <tr>
25
+ <td valign="top"><img src="extras/speedups_float32_5090.png"/></td>
26
+ <td valign="top"><img src="extras/speedups_float64_5090.png"/></td>
27
+ </tr>
28
+ </table>
29
+
30
+ ## Installation
31
+ ```bash
32
+ pip install TODO
33
+ ```
34
+ Note: for further usage, NVIDIA CUDA drivers must be present in the operating system.
35
+
36
+ ## Usage example 1
37
+ Suppose one would like to multiply the following matrices of quaternions:
38
+
39
+ <!-- -->
40
+ $$
41
+ \begin{aligned}
42
+ {\tiny
43
+ \begin{pmatrix}
44
+ 2i +j & -1 +i -j + 4k & 5 -i +3j \\
45
+ 1 +4i -4j -4k & -5 +3i +3j +4k & 5 +3i +3k \\
46
+ -4 +i -4j + 4k & -i -2j +3k & i -5j +k \\
47
+ 1 +i +4j + 2k& -1 -i +2j -4k & 2 +2i -3j -4k \\
48
+ -2 -i +j -k & 5 -4i -3j -3k & 2 -2i -3k
49
+ \end{pmatrix}
50
+ }
51
+ {\cdot}
52
+ {\tiny
53
+ \begin{pmatrix}
54
+ -3 -4i + 2j -4k & -3 -i +3j -4k \\
55
+ 3 - 4i +5j & 5 +i +2j -5k\\
56
+ -2 -4i -2j -4k & -2 -i -4j +2k
57
+ \end{pmatrix}
58
+ }
59
+ {\tiny =}
60
+ {\tiny
61
+ \begin{pmatrix}
62
+ 4 -53i -39j +15k & 16 -6i -17j +52k \\
63
+ 1 -3i +4j +7k & -30 +3i +30j +56k \\
64
+ 44 +23i -16j -38k & 40 -4i -5j +7k \\
65
+ -34 -14i +29j -17k & -40 -62i -10j -21k \\
66
+ -14 -18i +21j -26k & 18 -41j -18k
67
+ \end{pmatrix}.
68
+ }
69
+ \end{aligned}
70
+ $$
71
+ <!-- -->
72
+
73
+ With `qmatmul` module installed, one can write:
74
+ ```python
75
+ import qmatmul as qmm
76
+ import numpy as np
77
+ import time
78
+
79
+ print("QMATMUL EXAMPLE...")
80
+ A = np.array([
81
+ [[ 0, 2, 1, 0], [-1, 1, -1, 4], [ 5, -1, 3, 0]],
82
+ [[ 1, 4, -4, -4], [-5, 3, 3, 4], [ 5, 3, 0, 3]],
83
+ [[-4, 1, -4, 4], [ 0, -1, -2, -3], [ 0, 1, -5, 1]],
84
+ [[ 1, 1, 4, 2], [-1, -1, 2, -4], [ 2, 2, -3, -4]],
85
+ [[-2, -1, 1, -1], [ 5, -4, -3, -3], [ 2, -2, 0, -3]]
86
+ ])
87
+ B = np.array([
88
+ [[-3, -4, 2, -4], [-3, -1, 3, -4]],
89
+ [[ 3, -4, 5, 0], [ 5, 1, 2, -5]],
90
+ [[-2, -4, -2, -4], [-2, -1, -4, 2]]
91
+ ])
92
+ t1 = time.time()
93
+ C = qmm.dot(A, B)
94
+ t2 = time.time()
95
+ print(f"RESULT -> C:")
96
+ print(C)
97
+ print(f"QMATMUL EXAMPLE DONE. TIME OF qmm.dot: {t2 - t1:.6f} s.")
98
+ ```
99
+ Running the code above produces the following output:
100
+ ```bash
101
+ QMATMUL EXAMPLE...
102
+ RESULT -> C:
103
+ [[[ 4. -53. -39. 15.]
104
+ [ 16. -6. -17. 52.]]
105
+
106
+ [[ 1. -3. 4. 7.]
107
+ [-30. 3. 30. 56.]]
108
+
109
+ [[ 44. 53. 8. -56.]
110
+ [ 10. 8. -11. -23.]]
111
+
112
+ [[-34. -14. 29. -17.]
113
+ [-40. -62. -10. -21.]]
114
+
115
+ [[-14. -18. 21. -26.]
116
+ [ 18. 0. -41. -18.]]]
117
+ QMATMUL EXAMPLE DONE. TIME OF qmm.dot: 0.001703 s.
118
+ ```
119
+
120
+ ## Usage example 2 (large arguments)
121
+ In the example below, two large random matrices with quaternions are multiplied.
122
+ ```python
123
+ import qmatmul as qmm
124
+ import numpy as np
125
+ import time
126
+
127
+ print("QMATMUL EXAMPLE (LARGE ARGUMENTS)...")
128
+ M, N, P = 1000, 3000, 2000
129
+ np.random.seed(0)
130
+ A = np.random.rand(M, N, 4) # M x N matrix of quaternions
131
+ B = np.random.rand(N, P, 4) # N x P matrix of quaternions
132
+ t1 = time.time()
133
+ C = qmm.dot(A, B)
134
+ t2 = time.time()
135
+ print(f"RESULT FRAGMENT -> C[:3, :3]:")
136
+ print(C[:3, :3])
137
+ print(f"QMATMUL EXAMPLE (LARGE ARGUMENTS) DONE. TIME OF qmm.dot: {t2 - t1:.6f} s.")
138
+ ```
139
+ The result is computed fast:
140
+ ```bash
141
+ QMATMUL EXAMPLE (LARGE ARGUMENTS)...
142
+ RESULT FRAGMENT -> C[:3, :3]:
143
+ [[[-1528.6768062 1482.01579334 1482.64352966 1469.29588132]
144
+ [-1474.39555984 1485.26884228 1485.81638515 1486.03433938]
145
+ [-1459.21558118 1487.12054919 1468.20437822 1461.65795584]]
146
+
147
+ [[-1502.50516591 1465.24326325 1494.5907814 1503.74503685]
148
+ [-1472.32677282 1493.41728185 1487.01751106 1506.41597882]
149
+ [-1460.42240679 1488.1077977 1474.34164258 1504.36179871]]
150
+
151
+ [[-1558.07311493 1475.34714296 1475.731701 1495.41197899]
152
+ [-1528.83559572 1476.28138065 1474.62854662 1504.35168932]
153
+ [-1508.66904595 1501.06439708 1459.07714887 1471.97545486]]]
154
+ QMATMUL EXAMPLE (LARGE ARGUMENTS) DONE. TIME OF qmm.dot: 0.151431 s.
155
+ ```
156
+
157
+ ## Choice of approach
158
+
159
+ An additional optional argument `approach`, e.g., `qmm.dot(A, B, approach="...")`, allows
160
+ the user to select one of the following eight computational approaches:
161
+
162
+ | approach | target, mode | description |
163
+ |:-------------------------------|:---------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
164
+ | `"naive_numba_st"` | CPU, single-threaded | naive single-threaded implementation of definition-based formula consisting of three nested loops, low-level compiled via Numba and LLVM |
165
+ | `"naive_numba_parallel"` | CPU, multi-threaded | as above, but parallelized over CPU cores |
166
+ | `"direct_numpy_st"` | CPU, single-threaded | direct implementation of formula based on the transformation matrix and stacked representation (followed by unstack), using NumPy/BLAS |
167
+ | `"direct_numpy_parallel"` | CPU, multi-threaded | as above, but allowing for CPU parallelization supported by NumPy/BLAS |
168
+ | `"direct_numba_cuda"` | GPU, multi-threaded | direct implementation of formula based on the transformation matrix and stacked representation (followed by unstack), using CUDA, compiled via Numba and LLVM to PTX/SASS |
169
+ | `"algo_numpy_st"` | CPU, single-threaded | implementation of the proposed fast algorithm, using NumPy/BLAS |
170
+ | `"algo_numpy_parallel"` | CPU, multi-threaded | as above, but allowing for CPU parallelization supported by NumPy/BLAS |
171
+ | `"algo_numba_cuda"` | GPU, multi-threaded | implementation of the proposed fast algorithm, using CUDA, compiled via Numba and LLVM to PTX/SASS |
172
+
173
+ The default setting is `"algo_numba_cuda"`.
174
+
175
+ ## Documentation
176
+ Developer documentation of the project is accessible at: [https://pklesk.github.io/quaternions](https://pklesk.github.io/quaternions). <br/>
177
+
178
+ ## License
179
+ This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
180
+
181
+ ## Acknowledgments and credits
182
+ - [NumPy](https://numpy.org): the fundamental package for scientific computing with Python.
183
+ - [Numba](https://numba.pydata.org): a high-performance just-in-time Python compiler.
qmatmul-1.0.0/pyproject.toml ADDED
@@ -0,0 +1,35 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "qmatmul"
7
+ version = "1.0.0"
8
+ authors = [
9
+ { name = "Przemysław Klęsk", email = "pklesk@zut.edu.pl" },
10
+ { name = "Aleksandr Cariov", email = "alexandr.tariov@zut.edu.pl" }
11
+ ]
12
+ description = "Fast multiplications of quaternion-valued matrices."
13
+ readme = "README.md"
14
+ requires-python = ">=3.12"
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Operating System :: POSIX :: Linux",
19
+ "Operating System :: Microsoft :: Windows",
20
+ "Topic :: Scientific/Engineering :: Mathematics",
21
+ ]
22
+ dependencies = [
23
+ "numpy>=2.3",
24
+ "numba>=0.62",
25
+ "numba-cuda[cu13]>=0.30",
26
+ "threadpoolctl>=3.6"
27
+ ]
28
+
29
+ [project.urls]
30
+ "Homepage" = "https://github.com/pklesk/quaternions"
31
+ "Bug Tracker" = "https://github.com/pklesk/quaternions/issues"
32
+ "Documentation" = "https://pklesk.github.io/quaternions/"
33
+
34
+ [tool.setuptools.packages.find]
35
+ where = ["src"]
qmatmul-1.0.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
qmatmul-1.0.0/src/qmatmul.egg-info/PKG-INFO ADDED
@@ -0,0 +1,203 @@
1
+ Metadata-Version: 2.4
2
+ Name: qmatmul
3
+ Version: 1.0.0
4
+ Summary: Fast multiplications of quaternion-valued matrices.
5
+ Author-email: Przemysław Klęsk <pklesk@zut.edu.pl>, Aleksandr Cariov <alexandr.tariov@zut.edu.pl>
6
+ Project-URL: Homepage, https://github.com/pklesk/quaternions
7
+ Project-URL: Bug Tracker, https://github.com/pklesk/quaternions/issues
8
+ Project-URL: Documentation, https://pklesk.github.io/quaternions/
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: POSIX :: Linux
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
14
+ Requires-Python: >=3.12
15
+ Description-Content-Type: text/markdown
16
+ Requires-Dist: numpy>=2.3
17
+ Requires-Dist: numba>=0.62
18
+ Requires-Dist: numba-cuda[cu13]>=0.30
19
+ Requires-Dist: threadpoolctl>=3.6
20
+
21
+ # qmatmul: Fast multiplication of quaternion-valued matrices - algorithm and its implementations for sequential and CUDA computations
22
+ We present an algorithm for fast multiplication of matrices whose elements are *quaternions* - hypercomplex numbers consisting of one real and three imaginary parts.
23
+ The number of elementary floating-point multiplications involved in the algorithm is reduced *twice* with respect to the definition-based formula,
24
+ regardless of the input matrices. This is owed to a suitable representation and decomposition into two products, one of which takes advantage of certain
25
+ diagonal symmetry properties, the other of sparsity.
26
+
27
+ The `qmatmul` package is suitable for Python's ecosystem.
28
+ Altogether, we provide 8 implementation variants of matrix-matrix multiplication for quaternion-valued inputs.
29
+ The variants cover several approaches based on [NumPy](https://numpy.org), thus supported by BLAS,
30
+ but also several approaches employing [Numba](https://numba.pydata.org) - a just-in-time compiler targeting both CPU and GPU (CUDA).
31
+ Our design of CUDA computations for the proposed algorithm involves: 6 kernel functions with 11 invocations, tiling and shared memory,
32
+ and few host-device memory transfers.
33
+
34
+ ## Selected kernels - flows of CUDA computations
35
+ <table>
36
+ <tr>
37
+ <td valign="top"><img width="1150" height="1496" alt="had4_flow" src="https://github.com/user-attachments/assets/091bb888-3c58-421a-8165-dff3643dcdbf"/></td>
38
+ <td valign="top"><img width="1492" height="2046" alt="matmuldiag_flow" src="https://github.com/user-attachments/assets/302b37ce-58d9-46d5-9b0f-c9d7bf1ab001"/></td>
39
+ </tr>
40
+ </table>
41
+
42
+ ## Speed-ups
43
+ <table>
44
+ <tr>
45
+ <td valign="top"><img src="extras/speedups_float32_5090.png"/></td>
46
+ <td valign="top"><img src="extras/speedups_float64_5090.png"/></td>
47
+ </tr>
48
+ </table>
49
+
50
+ ## Installation
51
+ ```bash
52
+ pip install TODO
53
+ ```
54
+ Note: for further usage, NVIDIA CUDA drivers must be present in the operating system.
55
+
56
+ ## Usage example 1
57
+ Suppose one would like to multiply the following matrices of quaternions:
58
+
59
+ <!-- -->
60
+ $$
61
+ \begin{aligned}
62
+ {\tiny
63
+ \begin{pmatrix}
64
+ 2i +j & -1 +i -j + 4k & 5 -i +3j \\
65
+ 1 +4i -4j -4k & -5 +3i +3j +4k & 5 +3i +3k \\
66
+ -4 +i -4j + 4k & -i -2j +3k & i -5j +k \\
67
+ 1 +i +4j + 2k& -1 -i +2j -4k & 2 +2i -3j -4k \\
68
+ -2 -i +j -k & 5 -4i -3j -3k & 2 -2i -3k
69
+ \end{pmatrix}
70
+ }
71
+ {\cdot}
72
+ {\tiny
73
+ \begin{pmatrix}
74
+ -3 -4i + 2j -4k & -3 -i +3j -4k \\
75
+ 3 - 4i +5j & 5 +i +2j -5k\\
76
+ -2 -4i -2j -4k & -2 -i -4j +2k
77
+ \end{pmatrix}
78
+ }
79
+ {\tiny =}
80
+ {\tiny
81
+ \begin{pmatrix}
82
+ 4 -53i -39j +15k & 16 -6i -17j +52k \\
83
+ 1 -3i +4j +7k & -30 +3i +30j +56k \\
84
+ 44 +23i -16j -38k & 40 -4i -5j +7k \\
85
+ -34 -14i +29j -17k & -40 -62i -10j -21k \\
86
+ -14 -18i +21j -26k & 18 -41j -18k
87
+ \end{pmatrix}.
88
+ }
89
+ \end{aligned}
90
+ $$
91
+ <!-- -->
92
+
93
+ With `qmatmul` module installed, one can write:
94
+ ```python
95
+ import qmatmul as qmm
96
+ import numpy as np
97
+ import time
98
+
99
+ print("QMATMUL EXAMPLE...")
100
+ A = np.array([
101
+ [[ 0, 2, 1, 0], [-1, 1, -1, 4], [ 5, -1, 3, 0]],
102
+ [[ 1, 4, -4, -4], [-5, 3, 3, 4], [ 5, 3, 0, 3]],
103
+ [[-4, 1, -4, 4], [ 0, -1, -2, -3], [ 0, 1, -5, 1]],
104
+ [[ 1, 1, 4, 2], [-1, -1, 2, -4], [ 2, 2, -3, -4]],
105
+ [[-2, -1, 1, -1], [ 5, -4, -3, -3], [ 2, -2, 0, -3]]
106
+ ])
107
+ B = np.array([
108
+ [[-3, -4, 2, -4], [-3, -1, 3, -4]],
109
+ [[ 3, -4, 5, 0], [ 5, 1, 2, -5]],
110
+ [[-2, -4, -2, -4], [-2, -1, -4, 2]]
111
+ ])
112
+ t1 = time.time()
113
+ C = qmm.dot(A, B)
114
+ t2 = time.time()
115
+ print(f"RESULT -> C:")
116
+ print(C)
117
+ print(f"QMATMUL EXAMPLE DONE. TIME OF qmm.dot: {t2 - t1:.6f} s.")
118
+ ```
119
+ Running the code above produces the following output:
120
+ ```bash
121
+ QMATMUL EXAMPLE...
122
+ RESULT -> C:
123
+ [[[ 4. -53. -39. 15.]
124
+ [ 16. -6. -17. 52.]]
125
+
126
+ [[ 1. -3. 4. 7.]
127
+ [-30. 3. 30. 56.]]
128
+
129
+ [[ 44. 53. 8. -56.]
130
+ [ 10. 8. -11. -23.]]
131
+
132
+ [[-34. -14. 29. -17.]
133
+ [-40. -62. -10. -21.]]
134
+
135
+ [[-14. -18. 21. -26.]
136
+ [ 18. 0. -41. -18.]]]
137
+ QMATMUL EXAMPLE DONE. TIME OF qmm.dot: 0.001703 s.
138
+ ```
139
+
140
+ ## Usage example 2 (large arguments)
141
+ In the example below, two large random matrices with quaternions are multiplied.
142
+ ```python
143
+ import qmatmul as qmm
144
+ import numpy as np
145
+ import time
146
+
147
+ print("QMATMUL EXAMPLE (LARGE ARGUMENTS)...")
148
+ M, N, P = 1000, 3000, 2000
149
+ np.random.seed(0)
150
+ A = np.random.rand(M, N, 4) # M x N matrix of quaternions
151
+ B = np.random.rand(N, P, 4) # N x P matrix of quaternions
152
+ t1 = time.time()
153
+ C = qmm.dot(A, B)
154
+ t2 = time.time()
155
+ print(f"RESULT FRAGMENT -> C[:3, :3]:")
156
+ print(C[:3, :3])
157
+ print(f"QMATMUL EXAMPLE (LARGE ARGUMENTS) DONE. TIME OF qmm.dot: {t2 - t1:.6f} s.")
158
+ ```
159
+ The result is computed fast:
160
+ ```bash
161
+ QMATMUL EXAMPLE (LARGE ARGUMENTS)...
162
+ RESULT FRAGMENT -> C[:3, :3]:
163
+ [[[-1528.6768062 1482.01579334 1482.64352966 1469.29588132]
164
+ [-1474.39555984 1485.26884228 1485.81638515 1486.03433938]
165
+ [-1459.21558118 1487.12054919 1468.20437822 1461.65795584]]
166
+
167
+ [[-1502.50516591 1465.24326325 1494.5907814 1503.74503685]
168
+ [-1472.32677282 1493.41728185 1487.01751106 1506.41597882]
169
+ [-1460.42240679 1488.1077977 1474.34164258 1504.36179871]]
170
+
171
+ [[-1558.07311493 1475.34714296 1475.731701 1495.41197899]
172
+ [-1528.83559572 1476.28138065 1474.62854662 1504.35168932]
173
+ [-1508.66904595 1501.06439708 1459.07714887 1471.97545486]]]
174
+ QMATMUL EXAMPLE (LARGE ARGUMENTS) DONE. TIME OF qmm.dot: 0.151431 s.
175
+ ```
176
+
177
+ ## Choice of approach
178
+
179
+ An additional optional argument `approach`, e.g., `qmm.dot(A, B, approach="...")`, allows
180
+ the user to select one of the following eight computational approaches:
181
+
182
+ | approach | target, mode | description |
183
+ |:-------------------------------|:---------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
184
+ | `"naive_numba_st"` | CPU, single-threaded | naive single-threaded implementation of definition-based formula consisting of three nested loops, low-level compiled via Numba and LLVM |
185
+ | `"naive_numba_parallel"` | CPU, multi-threaded | as above, but parallelized over CPU cores |
186
+ | `"direct_numpy_st"` | CPU, single-threaded | direct implementation of formula based on the transformation matrix and stacked representation (followed by unstack), using NumPy/BLAS |
187
+ | `"direct_numpy_parallel"` | CPU, multi-threaded | as above, but allowing for CPU parallelization supported by NumPy/BLAS |
188
+ | `"direct_numba_cuda"` | GPU, multi-threaded | direct implementation of formula based on the transformation matrix and stacked representation (followed by unstack), using CUDA, compiled via Numba and LLVM to PTX/SASS |
189
+ | `"algo_numpy_st"` | CPU, single-threaded | implementation of the proposed fast algorithm, using NumPy/BLAS |
190
+ | `"algo_numpy_parallel"` | CPU, multi-threaded | as above, but allowing for CPU parallelization supported by NumPy/BLAS |
191
+ | `"algo_numba_cuda"` | GPU, multi-threaded | implementation of the proposed fast algorithm, using CUDA, compiled via Numba and LLVM to PTX/SASS |
192
+
193
+ The default setting is `"algo_numba_cuda"`.
194
+
195
+ ## Documentation
196
+ Developer documentation of the project is accessible at: [https://pklesk.github.io/quaternions](https://pklesk.github.io/quaternions). <br/>
197
+
198
+ ## License
199
+ This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
200
+
201
+ ## Acknowledgments and credits
202
+ - [NumPy](https://numpy.org): the fundamental package for scientific computing with Python.
203
+ - [Numba](https://numba.pydata.org): a high-performance just-in-time Python compiler.
qmatmul-1.0.0/src/qmatmul.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,7 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/qmatmul.egg-info/PKG-INFO
4
+ src/qmatmul.egg-info/SOURCES.txt
5
+ src/qmatmul.egg-info/dependency_links.txt
6
+ src/qmatmul.egg-info/requires.txt
7
+ src/qmatmul.egg-info/top_level.txt
qmatmul-1.0.0/src/qmatmul.egg-info/requires.txt ADDED
@@ -0,0 +1,4 @@
1
+ numpy>=2.3
2
+ numba>=0.62
3
+ numba-cuda[cu13]>=0.30
4
+ threadpoolctl>=3.6