Namespaces | |
| namespace | math |
Classes | |
| struct | Grid |
| Rectangular, evenly spaced local map grid. More... | |
| struct | PlannerOptions |
| Search, utility, and optimizer controls for the reference planner. More... | |
Typedefs | |
| using | Matrix = math::Matrix |
| Dense row-major covariance layout chosen for contiguous row updates. | |
| using | Vector = math::Vector |
| Dynamic GP mean, measurement, or per-cell variance vector. | |
| using | Point = math::Point |
| Three-dimensional local east/north/altitude point, in metres. | |
| using | Sensor = dipla::aigenlib::Sensor |
| Sparse block-averaging observation operator. | |
Functions | |
| std::vector< Point > | refine (const Grid &grid, const Vector &mean, const Matrix &covariance, const Point &start, const std::vector< Point > &initial, const PlannerOptions &options) |
| Refine a greedy route with bounded CMA-ES while retaining its best candidate. | |
| std::vector< Point > | plan (const Grid &grid, const Vector &mean, const Matrix &covariance, const Point &start, const PlannerOptions &options) |
| Run greedy route selection followed by optional CMA-ES refinement. | |
| double | fov_radius (double altitude, double angle=60.0) |
| Compute the ground-plane footprint radius from altitude and full FOV angle. | |
| int | resolution_block_size (double altitude) |
| Select the research sensor's altitude-dependent aggregation block size. | |
| double | noise_model (double altitude, double minimum_altitude=10.0) |
| Compute modeled observation variance at an altitude. | |
| Matrix | initialize_covariance (const Grid &grid, double sigma2, double lengthscale) |
| Initialize a dense Matérn-3/2 GP covariance matrix. | |
| Sensor | build_sensor (const Grid &grid, const Point &pose, double angle=60.0, double observation_variance=-1.0) |
| Build one block-averaged sensor footprint at a pose. | |
| Sensor | future_sensor (const Grid &grid, const std::vector< Point > &path, double angle=60.0, int stride=lookahead_stride, int max_measurements=lookahead_measurement_budget, double observation_variance=-1.0) |
| Approximate future measurements along a path under a bounded budget. | |
| Vector | observe (const Sensor &sensor, const Vector &field) |
| Apply the sensor's block averages to a full-grid field. | |
| Vector | sample_sensor_noise (const Sensor &sensor, std::mt19937_64 &generator) |
| Draw independent zero-mean noise using each sensor row's variance. | |
| std::vector< bool > | importance_mask (const Vector &mean, const Matrix &covariance, const PlannerOptions &options) |
| Select cells whose confidence bounds satisfy the utility threshold. | |
| double | expected_reduction (const Matrix &covariance, const std::vector< bool > &mask, const Sensor &sensor) |
| Sum expected marginal-variance reduction over important cells. | |
| void | condition (Matrix &covariance, Vector *mean, const Sensor &sensor, const Vector *measurement) |
| Apply a Gaussian linear-observation update in place. | |
| Point | clip_point (const Grid &grid, const Point &point, const PlannerOptions &options) |
| Clamp a candidate to the map safety inset and altitude interval. | |
| std::vector< Point > | lattice (const Grid &grid, const PlannerOptions &options) |
| Generate the deduplicated coarse-to-fine candidate lattice. | |
| std::vector< Point > | spline (const Point &start, const std::vector< Point > &waypoints, int samples_per_segment=spline_samples_per_segment) |
| Interpolate controls with a natural cubic spline parameterized by distance. | |
| double | trajectory_objective (const Grid &grid, const Matrix &covariance, const std::vector< bool > &mask, const Point &start, const std::vector< Point > &raw_waypoints, const PlannerOptions &options) |
| Score a trajectory by safety violation and distance-normalized information gain. | |
| std::vector< Point > | grid_search (const Grid &grid, const Vector &mean, const Matrix &covariance, const Point &start, const PlannerOptions &options) |
| Greedily select a bounded route by information gain per travel cost. | |
Variables | |
| constexpr int | lookahead_stride = 4 |
| Default route-pose sampling interval for look-ahead scoring. | |
| constexpr int | lookahead_measurement_budget = 64 |
| Innovation-system row budget, independent of worker FIFO capacity. | |
| constexpr int | spline_samples_per_segment = 5 |
| Default emitted spline samples per control segment. | |
Typedef Documentation
◆ Matrix
| using aipp::Matrix = math::Matrix |
Dense row-major covariance layout chosen for contiguous row updates.
◆ Point
| using aipp::Point = math::Point |
Three-dimensional local east/north/altitude point, in metres.
◆ Sensor
| using aipp::Sensor = dipla::aigenlib::Sensor |
Sparse block-averaging observation operator.
Each row lists grid-cell indices averaged into one measurement; variances stores the independent observation variance for each row.
◆ Vector
| using aipp::Vector = math::Vector |
Dynamic GP mean, measurement, or per-cell variance vector.
Function Documentation
◆ build_sensor()
| Sensor aipp::build_sensor | ( | const Grid & | grid, |
| const Point & | pose, | ||
| double | angle, | ||
| double | observation_variance ) |
Build one block-averaged sensor footprint at a pose.
Use the square bounding the FOV, then group included cells by globally anchored resolution blocks. Blocks stay anchored to grid row/column zero, not to the moving footprint edge; otherwise tiny pose changes would redefine the measurement operator even over the same physical cells.
- Note
- Edge blocks average only their included cells. Do not normalize them by the nominal block area or add a circular-distance rejection: either would describe a different observation model from this reference implementation.
- Precondition
- Geometry and pose are finite, altitude/FOV are valid, and the chosen fixed or altitude-derived observation variance is finite and nonnegative.
- See also
- observe The same row-average weights must be used when generating measurements.
Grid cells inside the square bounding the circular FOV are grouped by altitude-dependent resolution blocks, matching the reference sensor's coarse measurement behavior.
- Parameters
-
grid Map grid. pose Sensor east/north/altitude in metres. angle Full field-of-view angle in degrees. observation_variance Fixed variance, or negative to use the altitude model.
- Returns
- Sparse sensor rows and their independent variances.
◆ clip_point()
| Point aipp::clip_point | ( | const Grid & | grid, |
| const Point & | point, | ||
| const PlannerOptions & | options ) |
Clamp a candidate to the map safety inset and altitude interval.
Apply the comparison planner's two-grid-step XY inset and declared Z interval. This constrains a control point, not every point of a cubic spline between controls; trajectory_objective() separately scores spline overshoot.
- Precondition
- Coordinates and altitude bounds are finite, with options.zmin <= options.zmax.
- Warning
- A geometric target inset is not an aircraft geofence or an arrival test.
Horizontal margins are two grid steps, independent of optimizer penalty settings, so downstream routes retain a geometric boundary buffer.
- Parameters
-
grid Map geometry and horizontal inset. point Candidate east/north/altitude point. options Permitted altitude interval.
- Returns
- Bounded point.
◆ condition()
| void aipp::condition | ( | Matrix & | covariance, |
| Vector * | mean, | ||
| const Sensor & | sensor, | ||
| const Vector * | measurement ) |
Apply a Gaussian linear-observation update in place.
Compute P and solve S * B = P once, then reuse B for both posterior mean and covariance. Never form a general explicit inverse merely to multiply it away again; the measurement-space solve is the smaller numerical problem.
- Precondition
- Supply mean and measurement together with compatible finite dimensions, or pass both as nullptr for hypothetical covariance-only conditioning.
- Covariance and sensor describe the same valid finite grid domain.
- Warning
- The update mutates storage in place; it is not a transactional operation with rollback after an arithmetic or allocation failure. Symmetry restoration fixes triangle disagreement, not arbitrary loss of definiteness.
- See also
- expected_reduction Same covariance algebra without materializing its update.
Solves the innovation system rather than forming an inverse, updates the posterior mean only when both optional pointers are supplied, then updates covariance in row blocks to limit temporary allocations and restores symmetry.
- Parameters
-
covariance Prior covariance, replaced by the posterior covariance. mean Optional prior mean; used only when measurement is non-null. sensor Observation operator. measurement Optional observed vector paired with mean.
◆ expected_reduction()
| double aipp::expected_reduction | ( | const Matrix & | covariance, |
| const std::vector< bool > & | mask, | ||
| const Sensor & | sensor ) |
Sum expected marginal-variance reduction over important cells.
For each selected cell, the corresponding column of P and B yields the diagonal reduction in Sigma - P^T * B. Sum only those diagonals rather than allocating a full posterior just to obtain one candidate's utility. Future measurement values are unnecessary: linear-Gaussian covariance updates depend on the observation operator and noise, not the unknown observed value.
- Note
- Clamp each computed reduction to [0, prior marginal variance] to contain round-off. This is a trace-reduction utility, not entropy or a field-value reward.
- Precondition
- Covariance is finite and symmetric; mask has N entries and sensor rows and variances are valid for the same N-cell domain.
Uses the sensor innovation covariance and clamps numerical roundoff to each cell's prior marginal variance.
- Parameters
-
covariance Prior covariance. mask Cells contributing to utility. sensor Candidate observation operator.
- Returns
- Sum of marginal-variance reduction over selected cells.
◆ fov_radius()
| double aipp::fov_radius | ( | double | altitude, |
| double | angle ) |
Compute the ground-plane footprint radius from altitude and full FOV angle.
The angle is the full FOV in degrees. Dividing by 360 both halves it and converts to radians; using 180 here would double the angular footprint.
- Precondition
- altitude is finite and nonnegative; angle is finite and between 0 and 180 degrees.
- Note
- This ground-plane geometry assumes a level footprint. build_sensor() selects its square bounds, not a ray-traced or circular visibility mask.
Uses the tangent of the half-angle because the input is the full FOV.
- Parameters
-
altitude Sensor altitude above ground in metres. angle Full field-of-view angle in degrees.
- Returns
- Ground-plane footprint radius in metres.
◆ future_sensor()
| Sensor aipp::future_sensor | ( | const Grid & | grid, |
| const std::vector< Point > & | path, | ||
| double | angle, | ||
| int | stride, | ||
| int | max_measurements, | ||
| double | observation_variance ) |
Approximate future measurements along a path under a bounded budget.
Approximate a route's future observations without querying truth. Snap each sampled XY pose to the research grid before constructing its H; the supplied altitude still controls footprint, resolution, and default noise.
- Note
- Endpoint inclusion happens before row limiting. The final bounded operator evenly retains rows, not entire footprints, so a small budget may omit some cells or rows from any particular pose, including the endpoint.
- Warning
- max_measurements bounds the returned innovation dimension, not peak construction storage: the combined operator is built before subsampling.
- Precondition
- Path values, sensor geometry, and selected variances satisfy build_sensor()'s preconditions.
Samples path poses by stride, always includes the final waypoint, and evenly subsamples sensor rows if their total exceeds max_measurements. This trades a compact innovation matrix for some spatial detail.
- Parameters
-
grid Map grid. path Ordered trajectory in metres. angle Full field-of-view angle in degrees. stride Path-pose interval used for sampling. max_measurements Maximum number of returned measurement rows. observation_variance Fixed variance, or negative to use the altitude model.
- Returns
- Combined sensor operator within the requested measurement budget.
- Exceptions
-
std::invalid_argument If stride or the measurement budget is nonpositive.
◆ grid_search()
| std::vector< Point > aipp::grid_search | ( | const Grid & | grid, |
| const Vector & | mean, | ||
| const Matrix & | covariance, | ||
| const Point & | start, | ||
| const PlannerOptions & | options ) |
Greedily select a bounded route by information gain per travel cost.
Choose a gain-per-distance winner, condition a private hypothetical covariance, then score the next choice against reduced uncertainty. Reusing the original covariance every round would repeatedly reward already-covered regions instead of planning complementary observations.
- Note
- The mean remains the observed mean throughout look-ahead: future sensor values are unknown. Importance masks can still change as simulated uncertainty shrinks. One extra dense covariance is the principal storage cost of this search.
- Warning
- Cancellation returns an empty vector, not the partial prefix already selected. A short nonempty route can still result from exhausted candidates; the application must enforce its required eight-point publication contract.
- Precondition
- Geometry, posterior, utility, and sensor settings satisfy the called helpers.
- See also
- PlannerOptions::keep_planning Cooperative polling, not preemptive interruption.
Each chosen sensor conditions a private covariance copy before the next selection, giving cheap sequential look-ahead without mutating observed belief state. Cancellation returns an empty/incomplete route.
- Parameters
-
grid Candidate world grid. mean Current posterior mean. covariance Current posterior covariance. start Initial position. options Horizon, utility, sensor, and cancellation settings.
- Returns
- Ordered greedy controls, possibly empty when interrupted.
◆ importance_mask()
| std::vector< bool > aipp::importance_mask | ( | const Vector & | mean, |
| const Matrix & | covariance, | ||
| const PlannerOptions & | options ) |
Select cells whose confidence bounds satisfy the utility threshold.
Select utility using mean plus/minus beta times marginal standard deviation. The lower-bound mode asks whether a cell could lie below threshold; the upper-bound mode asks whether it could lie above. Preserve the inequality directions when adapting a task: swapping them changes what exploration values.
- Note
- If every cell fails, score the whole field instead of handing search a flat zero-gain objective. This is an explicit exploration policy, not a claim that every cell now meets the requested confidence-bound test.
- Precondition
- Mean, covariance, and utility settings are finite and dimensionally compatible.
If no cell meets the requested bound, all cells are selected so the optimizer does not receive a degenerate zero-utility objective.
- Parameters
-
mean Posterior mean. covariance Posterior covariance. options Confidence-bound direction, beta, and threshold.
- Returns
- Boolean importance mask in grid order.
◆ initialize_covariance()
Initialize a dense Matérn-3/2 GP covariance matrix.
The Matern-3/2 kernel is sigma2 * (1 + q) * exp(-q), with q = sqrt(3) * distance / lengthscale. sigma2 is already the marginal variance; squaring it again would change both uncertainty scale and inferred utility. At zero distance the diagonal is sigma2; nearby cells share information according to lengthscale measured in the same metres as the grid.
- Note
- This initializes covariance only. The application owns the prior mean; do not infer its value from a bare GP initializer in another caller.
Kernel values are cached by displacement on the uniform grid; the dense matrix then supports the block updates used by conditioning.
- Parameters
-
grid Grid defining the covariance coordinates. sigma2 Kernel marginal variance. lengthscale Matérn spatial length scale in metres.
- Returns
- Symmetric dense prior covariance.
- Exceptions
-
std::invalid_argument If kernel amplitude or length scale is invalid.
◆ lattice()
| std::vector< Point > aipp::lattice | ( | const Grid & | grid, |
| const PlannerOptions & | options ) |
Generate the deduplicated coarse-to-fine candidate lattice.
Combine three nested XY layers at progressively higher requested altitudes. Snap XY and Z to their respective grid-step lattices, then remove exact duplicate points so a shared location cannot consume two greedy slots. Fixed-height settings collapse Z layers naturally without inventing a Z search.
- Note
- Enumeration order breaks equal-score ties in grid_search(). Changing it can change a deterministic route even when the candidate set is unchanged.
- Precondition
- Altitude bounds are finite, ordered, and their step count fits int.
Nested layers trade uniform resolution for broad coverage and progressively finer central choices.
- Parameters
-
grid Map geometry and spacing. options Altitude range for lattice layers.
- Returns
- Unique candidate positions.
◆ noise_model()
| double aipp::noise_model | ( | double | altitude, |
| double | minimum_altitude ) |
Compute modeled observation variance at an altitude.
Return variance, not standard deviation: 0.01 at minimum_altitude, approaching 0.04 from below at increasing height. The exponential preserves that saturation rather than making high-altitude noise grow without limit.
- Warning
- This formula is not clamped below its reference altitude and can become negative there. The 2 m application explicitly supplies variance 0.01; do not extrapolate this law to low flight or take sqrt of a negative result.
- See also
- build_sensor Fixed-variance override for a separately declared sensor experiment.
Exponentially approaches the reference high-altitude variance rather than increasing without bound.
- Parameters
-
altitude Sensor altitude in metres. minimum_altitude Reference altitude for the minimum variance.
- Returns
- Modeled measurement variance.
◆ observe()
Apply the sensor's block averages to a full-grid field.
Apply H identically to hidden truth and predicted mean; the latter gives the expected measurement used by the GP residual. Noise is deliberately separate so scoring can use the operator without drawing synthetic evidence.
- Precondition
- Rows are nonempty and indices address finite entries in field.
- See also
- sample_sensor_noise Independent noise is added by the observation owner.
Each sparse row is treated as a uniform averaging operator.
- Parameters
-
sensor Sparse sensor operator. field One value per grid cell.
- Returns
- One averaged value per sensor row.
◆ plan()
| std::vector< Point > aipp::plan | ( | const Grid & | grid, |
| const Vector & | mean, | ||
| const Matrix & | covariance, | ||
| const Point & | start, | ||
| const PlannerOptions & | options ) |
Run greedy route selection followed by optional CMA-ES refinement.
Greedy search provides a feasible incumbent; refinement is skipped when options.refine is false.
- Parameters
-
grid Map geometry. mean Current posterior mean. covariance Current posterior covariance. start Initial position. options Search and optimizer settings.
- Returns
- Ordered control points, or an empty route if cancelled during greedy search.
◆ refine()
| std::vector< Point > aipp::refine | ( | const Grid & | grid, |
| const Vector & | mean, | ||
| const Matrix & | covariance, | ||
| const Point & | start, | ||
| const std::vector< Point > & | initial, | ||
| const PlannerOptions & | options ) |
Refine a greedy route with bounded CMA-ES while retaining its best candidate.
Fixed-altitude problems omit Z from the search dimension; boundary transforms keep the optimizer's latent Gaussian unconstrained while all evaluated waypoints remain inside flight bounds.
- Parameters
-
grid Map geometry and safety bounds. mean Current posterior mean. covariance Current posterior covariance. start Initial position. initial Greedy route used as the warm start and incumbent. options Optimizer budget, seed, bounds, and cancellation predicate.
- Returns
- Best route found, or the unchanged initial route if refinement cannot start.
◆ resolution_block_size()
| int aipp::resolution_block_size | ( | double | altitude | ) |
Select the research sensor's altitude-dependent aggregation block size.
Higher altitude coarsens one measurement into averages of wider grid blocks. These thresholds belong to the research observation model, not the ONNX tensor resolution; changing them changes the experiment's H.
Piecewise aggregation preserves the reference sensor's coarser effective resolution at higher altitude.
- Parameters
-
altitude Sensor altitude in metres.
- Returns
- Aggregation block width in cells.
◆ sample_sensor_noise()
Draw independent zero-mean noise using each sensor row's variance.
Scale a standard normal by sqrt(variance), not variance itself. Using the same per-row variance in innovation() makes sampled measurements and GP likelihood describe one experiment rather than two incompatible sensors.
- Precondition
- Each sensor row has one finite, nonnegative variance.
- Note
- The caller owns random-stream lifetime. Even a zero-variance row draws a normal here; changing row order or draw count changes later noise samples. Equal seeds alone do not promise NumPy or cross-library bitwise equivalence.
Uses one standard-normal draw per row and scales by that row's standard deviation; the caller owns the generator to control reproducibility.
- Parameters
-
sensor Per-row variances define Gaussian scales. generator Caller-owned random engine for reproducibility.
- Returns
- One independent noise value per sensor row.
◆ spline()
| std::vector< Point > aipp::spline | ( | const Point & | start, |
| const std::vector< Point > & | waypoints, | ||
| int | samples_per_segment ) |
Interpolate controls with a natural cubic spline parameterized by distance.
Parameterize by 3-D chord length rather than control index so unequal waypoint spacing affects interpolation geometrically. Natural endpoint conditions set endpoint second derivatives to zero; an in-place tridiagonal solve obtains the interior derivatives for all three coordinates together.
- Note
- Consecutive chords no longer than 1e-9 m are omitted. This avoids a singular system but intentionally differs from retaining coincident controls with an artificial minimum chord length in another reference implementation.
- Warning
- This is a sampled scoring path, not the flight controller's path implementation, a constant-speed parameterization, or a bound on continuous spline overshoot between emitted samples.
- Precondition
- Input coordinates are finite and the requested sample storage is practical.
Coincident consecutive knots are removed because their zero chord lengths make the spline system singular; an all-coincident path is returned as its single unique point.
- Parameters
-
start Initial path point. waypoints Ordered spline controls. samples_per_segment Number of emitted samples per chord.
- Returns
- Interpolated path including the final knot.
- Exceptions
-
std::invalid_argument If samples per segment is not positive.
◆ trajectory_objective()
| double aipp::trajectory_objective | ( | const Grid & | grid, |
| const Matrix & | covariance, | ||
| const std::vector< bool > & | mask, | ||
| const Point & | start, | ||
| const std::vector< Point > & | raw_waypoints, | ||
| const PlannerOptions & | options ) |
Score a trajectory by safety violation and distance-normalized information gain.
Minimize boundary violation minus information gain per travel cost. Raw controls contribute a penalty even though scoring uses clipped controls; otherwise many out-of-bounds proposals would become the same cheap clipped path. Sampled spline overshoot adds a penalty of its own.
- Note
- Travel cost is the clipped control polyline's length, not spline arc length. Its grid-step floor prevents division by zero and infinite reward for hovering on coincident controls. Sensor stride and the 64-row budget bound the scoring solve at the cost of an approximate future-observation operator.
- Warning
- Soft penalties do not certify continuous-path containment. Changing samples_per_segment, stride, or row budget changes the objective, not just speed.
- Precondition
- Inputs satisfy spline(), clip_point(), and expected_reduction() contracts.
Controls are clipped for geometric evaluation, while raw-control and spline overshoot is retained as a penalty so the optimizer cannot hide an unsafe proposal by clipping it before scoring.
- Parameters
-
grid Map geometry and safety bounds. covariance Current covariance. mask Cells included in information gain. start Current position. raw_waypoints Candidate controls before clipping. options Sensor geometry and distance-cost settings.
- Returns
- Scalar objective; lower values are preferred.
Variable Documentation
◆ lookahead_measurement_budget
|
inlineconstexpr |
Innovation-system row budget, independent of worker FIFO capacity.
◆ lookahead_stride
|
inlineconstexpr |
Default route-pose sampling interval for look-ahead scoring.
◆ spline_samples_per_segment
|
inlineconstexpr |
Default emitted spline samples per control segment.