Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
aigenlib.hpp
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file aigenlib.hpp
20 * @brief Bounded, owning numerical types and Gaussian-process operations.
21 * @details No expression templates, BLAS, LAPACK, Eigen, or OpenCV dependency.
22 * Operations allocate explicit bounded workspaces and throw on invalid input.
23 */
24#pragma once
25
26#include <array>
27#include <cstddef>
28#include <vector>
29
30namespace dipla::aigenlib {
31
32/** Maximum matrix extent, matching the current dense GP grid ceiling. */
33inline constexpr std::size_t max_extent = 2601;
34/** Relative spectral cutoff shared with the Eigen reference implementation. */
35inline constexpr double pseudoinverse_relative_cutoff = 1e-15;
36/** Owning scalar vector; size validation belongs to the consuming operation. */
37using Vector = std::vector<double>;
38
39/**
40 * @brief Three-dimensional value type for route arithmetic.
41 * @details Coordinates use metres; norm uses overflow-resistant hypot.
42 */
43struct Point {
44 std::array<double, 3> coordinates{}; /**< East, north, altitude. */
45 /** @brief Construct a point. @param east East. @param north North. @param altitude Height. */
46 Point(double east = 0.0, double north = 0.0, double altitude = 0.0);
47 /** @brief Access east. @return Mutable coordinate. */
48 double& x() noexcept;
49 /** @brief Access east. @return Coordinate. */
50 double x() const noexcept;
51 /** @brief Access north. @return Mutable coordinate. */
52 double& y() noexcept;
53 /** @brief Access north. @return Coordinate. */
54 double y() const noexcept;
55 /** @brief Access altitude. @return Mutable coordinate. */
56 double& z() noexcept;
57 /** @brief Access altitude. @return Coordinate. */
58 double z() const noexcept;
59 /** @brief Checked coordinate access. @param index Coordinate 0..2. @return Mutable value. */
60 double& operator[](std::size_t index);
61 /** @brief Checked coordinate access. @param index Coordinate 0..2. @return Value. */
62 double operator[](std::size_t index) const;
63 /** @brief Euclidean length. @return Nonnegative length. */
64 double norm() const noexcept;
65 /** @brief Check every coordinate. @return True if finite. */
66 bool finite() const noexcept;
67 /** @brief Add coordinates. @param other Addend. @return This point. */
68 Point& operator+=(const Point& other) noexcept;
69 /** @brief Subtract coordinates. @param other Subtrahend. @return This point. */
70 Point& operator-=(const Point& other) noexcept;
71};
72
73/** @brief Add points. @param left First. @param right Second. @return Sum. */
74Point operator+(Point left, const Point& right) noexcept;
75/** @brief Subtract points. @param left First. @param right Second. @return Difference. */
76Point operator-(Point left, const Point& right) noexcept;
77/** @brief Scale coordinates. @param point Input. @param scale Factor. @return Scaled point. */
78Point operator*(Point point, double scale) noexcept;
79/** @brief Scale coordinates. @param scale Factor. @param point Input. @return Scaled point. */
80Point operator*(double scale, Point point) noexcept;
81/** @brief Divide coordinates. @param point Input. @param divisor Finite nonzero divisor. @return Quotient. */
82Point operator/(Point point, double divisor);
83/** @brief Exact equality. @param left First. @param right Second. @return All coordinates equal. */
84bool operator==(const Point& left, const Point& right) noexcept;
85/** @brief Exact inequality. @param left First. @param right Second. @return Any coordinate differs. */
86bool operator!=(const Point& left, const Point& right) noexcept;
87
88/**
89 * @brief Owning, contiguous, row-major double matrix.
90 * @details Each extent is at most max_extent. Construction checks before
91 * multiplying dimensions. Element/row access is checked, including release
92 * builds. A borrowed row pointer is valid until assignment, move, or destruction;
93 * callers must bound column accesses. Moved-from matrices are empty 0-by-0.
94 */
95class Matrix {
96public:
97 /** @brief Construct an empty matrix. */
98 Matrix() = default;
99 /** @brief Allocate initialized storage. @param rows Row count. @param columns Column count. @param value Initial scalar. */
100 Matrix(std::size_t rows, std::size_t columns, double value = 0.0);
101 /** @brief Deep copy. @param other Source. */
102 Matrix(const Matrix& other) = default;
103 /** @brief Deep assignment with strong exception guarantee. @param other Source. @return This matrix. */
104 Matrix& operator=(const Matrix& other);
105 /** @brief Transfer storage. @param other Source, emptied afterwards. */
106 Matrix(Matrix&& other) noexcept;
107 /** @brief Transfer storage. @param other Source, emptied afterwards. @return This matrix. */
108 Matrix& operator=(Matrix&& other) noexcept;
109 /** @brief Row count. @return Rows. */
110 std::size_t rows() const noexcept;
111 /** @brief Column count. @return Columns. */
112 std::size_t cols() const noexcept;
113 /** @brief Allocated scalar count. @return Rows times columns. */
114 std::size_t size() const noexcept;
115 /** @brief Checked access. @param row Row. @param column Column. @return Mutable scalar. */
116 double& operator()(std::size_t row, std::size_t column);
117 /** @brief Checked access. @param row Row. @param column Column. @return Scalar. */
118 double operator()(std::size_t row, std::size_t column) const;
119 /** @brief Borrow a row. @param row Row. @return Pointer, null for zero columns. */
120 double* row_data(std::size_t row);
121 /** @brief Borrow a row. @param row Row. @return Pointer, null for zero columns. */
122 const double* row_data(std::size_t row) const;
123 /** @brief Validate all stored scalars. @return True if finite, including empty matrices. */
124 bool finite() const noexcept;
125 /** @brief Sum a square matrix's diagonal. @return Trace. */
126 double trace() const;
127
128private:
129 std::size_t rows_ = 0; /**< Row extent. */
130 std::size_t columns_ = 0; /**< Column extent. */
131 Vector values_; /**< Contiguous owning storage. */
132};
133
134/** Factorization selected for a solve. */
135enum class SolveMethod {
136 cholesky, /**< Positive-definite triangular factorization. */
137 pseudoinverse /**< Signed spectral inverse with null-mode truncation. */
138};
139/**
140 * @brief Solve a finite symmetric system with multiple right-hand sides.
141 * @details Cholesky is attempted first. On failure, bounded cyclic Jacobi sweeps
142 * compute a spectral pseudoinverse with abs(lambda) > 1e-15 * max(abs(lambda)).
143 * Negative eigenvalues retain their sign. Input is scaled before factoring;
144 * neither input is mutated. Symmetry is checked relative to matrix scale and
145 * the lower triangle defines the system within that tolerance. Zero systems
146 * produce zero solutions. Throws on invalid shape, nonfinite data, numerical
147 * overflow, or nonconvergence; never silently adds jitter. Not a general SVD.
148 * @param system Square coefficient matrix, including 0-by-0.
149 * @param right Matrix with system.rows() rows, possibly zero columns.
150 * @param method Optional output reporting the selected factorization.
151 * @return Owning solution with the same shape as right.
152 */
153Matrix solve_symmetric(const Matrix& system, const Matrix& right, SolveMethod* method = nullptr);
154
155/**
156 * @brief Sparse uniform-averaging measurement operator.
157 * @details Each row must be nonempty and contain valid cell indices. Repeated
158 * indices retain their averaging weight. Row count and individual row lengths
159 * are bounded by max_extent, not by the planner's 64-row look-ahead budget.
160 */
161struct Sensor {
162 std::vector<std::vector<int>> rows; /**< Cell indices in each measurement. */
163 Vector variances; /**< Finite nonnegative independent noise variances. */
164};
165
166/**
167 * @brief Construct a symmetric Matern-3/2 covariance over supplied positions.
168 * @details Kernel parameters are supplied by the caller, not selected by this
169 * library. Coordinate and length-scale units must agree. One triangle is
170 * evaluated and mirrored. Rejects nonfinite positions/parameters.
171 * @param positions Grid-cell coordinates, at most max_extent.
172 * @param sigma2 Positive marginal variance.
173 * @param lengthscale Positive correlation length in the coordinates' units.
174 * @return Dense symmetric prior.
175 */
176Matrix matern32(const std::vector<Point>& positions, double sigma2, double lengthscale);
177/**
178 * @brief Project covariance through sparse averaging rows: B = H P.
179 * @details Requires a square finite covariance. Checks shape/sensor before
180 * allocation and detects nonfinite projected values in the sensor's accessed
181 * rows, without rescanning the whole grid per candidate. Unused rows are not
182 * inspected; conditioning checks the complete covariance before mutation.
183 * @param sensor Averaging operator.
184 * @param covariance Square cell covariance.
185 * @return Measurement-by-cell cross covariance.
186 */
187Matrix project(const Sensor& sensor, const Matrix& covariance);
188/**
189 * @brief Construct innovation covariance S = H P H^T + R from B = H P.
190 * @details Validates rows and variances against the projected cell count.
191 * @param sensor Averaging operator.
192 * @param projected Measurement-by-cell cross covariance.
193 * @return Measurement-by-measurement innovation covariance.
194 */
195Matrix innovation(const Sensor& sensor, const Matrix& projected);
196/** @brief Average field values through a sensor. @param sensor Operator. @param field Finite cell values. @return Measurements. */
197Vector observe(const Sensor& sensor, const Vector& field);
198/**
199 * @brief Sum the masked posterior diagonal reduction without modifying belief.
200 * @details Solves S X = B and clamps each selected B-column dot X-column to
201 * [0, max(0, Pii)], matching the production utility calculation. Checks the
202 * accessed projection and selected diagonal, not unused covariance entries.
203 * @param covariance Square finite cell covariance.
204 * @param mask One selection bit per cell.
205 * @param sensor Averaging operator.
206 * @return Expected trace reduction.
207 */
208double expected_reduction(const Matrix& covariance, const std::vector<bool>& mask, const Sensor& sensor);
209/**
210 * @brief Condition a GP in place with optional measurement assimilation.
211 * @details Both mean and measurement must be supplied, or both null for
212 * look-ahead. All shapes, indices, noise and input finiteness are checked before
213 * mutation. Workspace is two m-by-n matrices, small solver storage and one
214 * 4 KiB scratch tile per active lane, never an n-by-n product temporary.
215 * Large multi-row updates use at most three lanes and join before symmetry
216 * restoration; a thread-creation failure falls back to remaining serial work.
217 * A single-row observation fuses updating and symmetry restoration without scratch;
218 * both triangle calculations and their averaging order are preserved exactly.
219 * Arithmetic overflow throws; after mutation begins it does
220 * not roll back the belief. Concurrent access requires caller synchronization.
221 * @param covariance Square finite covariance, updated in place.
222 * @param mean Optional finite cell mean, updated in place.
223 * @param sensor Averaging operator.
224 * @param measurement Optional finite measurement values.
225 */
226void condition(Matrix& covariance, Vector* mean, const Sensor& sensor, const Vector* measurement);
227
228}
Owning, contiguous, row-major double matrix.
Definition aigenlib.hpp:95
Matrix(const Matrix &other)=default
Deep copy.
std::size_t cols() const noexcept
Column count.
Definition aigenlib.cpp:241
Matrix & operator=(const Matrix &other)
Deep assignment with strong exception guarantee.
Definition aigenlib.cpp:223
std::size_t size() const noexcept
Allocated scalar count.
Definition aigenlib.cpp:242
double * row_data(std::size_t row)
Borrow a row.
Definition aigenlib.cpp:251
double trace() const
Sum a square matrix's diagonal.
Definition aigenlib.cpp:262
Matrix()=default
Construct an empty matrix.
bool finite() const noexcept
Validate all stored scalars.
Definition aigenlib.cpp:259
std::size_t rows() const noexcept
Row count.
Definition aigenlib.cpp:240
struct latest_measurement measurement
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
Vector observe(const Sensor &sensor, const Vector &field)
Average field values through a sensor.
Definition aigenlib.cpp:376
Matrix matern32(const std::vector< Point > &positions, double sigma2, double lengthscale)
Construct a symmetric Matern-3/2 covariance over supplied positions.
Definition aigenlib.cpp:324
double expected_reduction(const Matrix &covariance, const std::vector< bool > &mask, const Sensor &sensor)
Sum the masked posterior diagonal reduction without modifying belief.
Definition aigenlib.cpp:388
Matrix project(const Sensor &sensor, const Matrix &covariance)
Project covariance through sparse averaging rows: B = H P.
Definition aigenlib.cpp:342
std::vector< double > Vector
Definition aigenlib.hpp:37
Matrix solve_symmetric(const Matrix &system, const Matrix &right, SolveMethod *method)
Solve a finite symmetric system with multiple right-hand sides.
Definition aigenlib.cpp:269
constexpr double pseudoinverse_relative_cutoff
Definition aigenlib.hpp:35
void condition(Matrix &covariance, Vector *mean, const Sensor &sensor, const Vector *measurement)
Condition a GP in place with optional measurement assimilation.
Definition aigenlib.cpp:409
constexpr std::size_t max_extent
Definition aigenlib.hpp:33
Matrix innovation(const Sensor &sensor, const Matrix &projected)
Construct innovation covariance S = H P H^T + R from B = H P.
Definition aigenlib.cpp:359
Three-dimensional value type for route arithmetic.
Definition aigenlib.hpp:43
double & y() noexcept
Access north.
Definition aigenlib.cpp:190
std::array< double, 3 > coordinates
Definition aigenlib.hpp:44
bool finite() const noexcept
Check every coordinate.
Definition aigenlib.cpp:197
Point(double east=0.0, double north=0.0, double altitude=0.0)
Construct a point.
Definition aigenlib.cpp:187
double & x() noexcept
Access east.
Definition aigenlib.cpp:188
double & z() noexcept
Access altitude.
Definition aigenlib.cpp:192
double norm() const noexcept
Euclidean length.
Definition aigenlib.cpp:196
Sparse uniform-averaging measurement operator.
Definition aigenlib.hpp:161
std::vector< std::vector< int > > rows
Definition aigenlib.hpp:162
One timestamped geographic position for a replay annotation.