Maintains a synthetic field, GP posterior, and planning comparisons. More...
#include <dipla_planner.hpp>
Classes | |
| struct | State |
| Private storage for the synthetic field and its GP posterior. More... | |
Public Member Functions | |
| Survey (const std::string &field, const ExperimentOptions &options={}) | |
| Load the complete finite-grid synthetic field. | |
| ~Survey () | |
| Releases field and covariance storage. | |
| bool | observe (double east, double north, std::uint32_t number, double height=DIPLA_DEMO_HEIGHT_MM/DIPLA_MM_PER_M) |
| Assimilate one synthetic observation at a local pose. | |
| std::optional< Waypoints > | compare (const std::array< double, 3 > &position, const CmaesOptions &options={}, const std::function< bool()> &cancelled={}) const |
| Run the explicitly requested native CMA-ES comparison planner. | |
| Belief | belief () const |
| Copy the current GP marginal mean and variance into fixed-size storage. | |
| double | total_variance () const |
| Return the sum of posterior marginal variances. | |
| std::uint64_t | field_digest () const |
| Return the FNV-1a digest of the input CSV bytes. | |
Private Attributes | |
| std::unique_ptr< State > | state_ |
| Exclusive ownership keeps private truth and dense GP state out of the API. | |
Detailed Description
Maintains a synthetic field, GP posterior, and planning comparisons.
Field truth is private to the observation source. Callers receive only posterior statistics; monotonically increasing observation numbers prevent replaying a shot from conditioning the belief twice.
Constructor & Destructor Documentation
◆ Survey()
|
explicit |
Load the complete finite-grid synthetic field.
The field is retained privately and the GP prior is initialized once; only observations and posterior summaries are exposed to callers.
- Parameters
-
field CSV containing one sample for each supported even-coordinate cell. options Startup GP, synthetic sensor, seed and flight-margin policy.
- Exceptions
-
std::exception If the file is malformed, oversized, or incomplete.
A new Survey starts a fresh belief and sensor random stream. Keep the same instance across route chunks; reconstruct only for a new survey, otherwise previously acquired knowledge disappears along with the covariance.
◆ ~Survey()
|
default |
Releases field and covariance storage.
The private pimpl owns the dense posterior and synthetic truth.
Release private truth and the dense posterior together through their owning State.
Member Function Documentation
◆ belief()
| Belief dipla::Survey::belief | ( | ) | const |
Copy the current GP marginal mean and variance into fixed-size storage.
Converts Eigen's internal vectors to the stable public row-major arrays.
- Returns
- Snapshot of posterior mean and nonnegative marginal variances.
Publish a value snapshot, not aliases into the mutable GP. The denoiser needs per-cell means and marginal variances, whereas conditioning needs the correlations in the full covariance; keep those responsibilities separate rather than expanding every model request into a matrix copy.
- Note
- Clamp negative diagonal round-off only in the exported summary. This does not repair the internal covariance or validate its positive semidefiniteness.
◆ compare()
| std::optional< Waypoints > dipla::Survey::compare | ( | const std::array< double, 3 > & | position, |
| const CmaesOptions & | options = {}, | ||
| const std::function< bool()> & | cancelled = {} ) const |
Run the explicitly requested native CMA-ES comparison planner.
Planning operates on a covariance copy and must not mutate the observation posterior. It returns no route if cancellation or the deadline prevents completion; a partial route is never published.
- Parameters
-
position Current local east, north, and altitude in metres. options Validated comparison search, utility, budget and seed policy. cancelled Optional cooperative cancellation predicate.
- Returns
- Complete eight-waypoint route, or std::nullopt on interruption.
- Exceptions
-
std::runtime_error If position or budget is invalid, or planning fails.
◆ field_digest()
| std::uint64_t dipla::Survey::field_digest | ( | ) | const |
Return the FNV-1a digest of the input CSV bytes.
This is diagnostic provenance, not cryptographic authentication.
- Returns
- 64-bit FNV-1a digest.
Identify the loaded data rows without exposing the hidden field. FNV-1a is a lightweight diagnostic fingerprint, not collision-resistant integrity checking or authentication. See State's loader for newline handling.
◆ observe()
| bool dipla::Survey::observe | ( | double | east, |
| double | north, | ||
| std::uint32_t | number, | ||
| double | height = DIPLA_DEMO_HEIGHT_MM / DIPLA_MM_PER_M ) |
Assimilate one synthetic observation at a local pose.
Builds the supplied-altitude footprint, adds independently seeded Gaussian sensor noise and applies one GP conditioning update. At the demo height both injected noise and likelihood use the configured positive variance, 0.01 in the default profile. Non-increasing shot numbers are discarded before any expensive matrix work. The full truth field never becomes a network input: only the footprint conditions the belief.
- Parameters
-
east Local east coordinate in metres. north Local north coordinate in metres. number Nonzero, strictly increasing shot number. height Model-domain sensor height; defaults to the original 2 m experiment.
- Returns
- True if the sensor footprint covered at least one grid cell; false for a duplicate, stale, zero, or otherwise non-increasing number.
- Exceptions
-
std::runtime_error If coordinates are nonfinite or outside the field.
- Note
- The low-height noise floor avoids extrapolating the reference law to a negative variance; this remains a synthetic sensor experiment.
Measurement generation and GP conditioning must describe the same sensor: observe the footprint, add Gaussian noise with its declared variance, and use that variance as the update's likelihood. Adding noise only to the belief, or conditioning on exact truth, would be a different experiment.
- Note
- The default remains the original 2 m experiment. Resized worker frames supply the same model-domain height used for network pose conditioning.
- Warning
- Updates are in place, not transactional. A GP arithmetic failure throws; the owner must treat that survey as failed, not retry as if untouched.
- See also
- Survey::belief
◆ total_variance()
| double dipla::Survey::total_variance | ( | ) | const |
Return the sum of posterior marginal variances.
Uses the covariance trace as a compact scalar uncertainty measure.
- Returns
- Sum of diagonal covariance entries.
The trace sums uncertainty over cells, not the uncertainty of their sum (which would include cross-covariances). Keep it consistent with the model's total-variance conditioning; it is not a calibrated route-quality score.
- Note
- This diagnostic reads the raw trace, unlike belief()'s clipped marginals.
Member Data Documentation
◆ state_
|
private |
Exclusive ownership keeps private truth and dense GP state out of the API.
The documentation for this class was generated from the following files: