Add exact periodic neighborhood queries and measured scan baseline
This commit is contained in:
@@ -100,6 +100,9 @@ format cannot be used for World 0 without a migration ADR.
|
||||
|
||||
## Extension seams and failure tests
|
||||
|
||||
Read-only proximity queries follow [SPATIAL_CONTRACT.md](SPATIAL_CONTRACT.md).
|
||||
They inspect current rows without cached state or changes to simulation rules.
|
||||
|
||||
Future commands carry tick, entity identity, sequence and validated intention;
|
||||
duplicate/reordered input handling belongs to the host protocol boundary.
|
||||
Biology introduces separate immutable genomes, development and phenotypes before
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# Local spatial contract
|
||||
|
||||
M1.7 implements [ADR-0023](../adr/0023-local-neighborhood-queries.md).
|
||||
|
||||
```cpp
|
||||
// include/evo/simulation/spatial.hpp
|
||||
auto ids = evo::query_neighbors(world, center, evo::Millimetres{16});
|
||||
```
|
||||
|
||||
| Input/result | Contract |
|
||||
|---|---|
|
||||
| Frame | Existing synthetic 2D torus, coordinates 0 through 1023 mm per axis |
|
||||
| Center | Out-of-domain coordinates return `Error::invalid_position`, even for an empty world |
|
||||
| Radius | Unsigned millimetres, zero through UINT32_MAX; no silent clamp or rejected large radius |
|
||||
| Geometry | Shortest periodic Euclidean distance; equality with radius is included |
|
||||
| Identity | Ascending unique IDs; coincident entities all included; caller explicitly excludes self if needed |
|
||||
| Lifetime | Returned vector owns IDs, not entity references; later removal may invalidate an identity |
|
||||
| Mutation | No state, tick, PRNG, snapshot or input changes; no clock/I/O/dependency |
|
||||
| Concurrency | Owner provides a stable world for the duration of the call |
|
||||
|
||||
For each axis, `d = min(abs(a-b), 1024-abs(a-b))`; membership is
|
||||
`dx*dx + dy*dy <= radius*radius`, evaluated in u64. Maximum squared distance is
|
||||
524,288. Thus radius 725 includes the entire domain; radius 724 can exclude the
|
||||
diagonal antipode. Exactly opposite points have an ambiguous direction but a
|
||||
unique distance; this API deliberately does not return displacement vectors.
|
||||
|
||||
The scan observes current rows on each call, so scheduled creates/removals,
|
||||
movement and restored state need no invalidation hook. Snapshots serialize only
|
||||
authoritative state. Future indexes must preserve this query contract and measure
|
||||
update/rebuild costs, not just warm query timings. Cross-region ghosts and senses
|
||||
require separate ownership/perception contracts before integration.
|
||||
|
||||
`evo-spatial-benchmark` reports seeded uniform and clustered worlds, 1k/10k/100k
|
||||
entities, 128 queries, radii 0/16/128/725, one warmup and three measured samples.
|
||||
Every result contributes to a checksum. Timing includes allocation/destruction,
|
||||
excludes world/query construction, and has no portable pass/fail threshold.
|
||||
Timing also includes result checksumming. This is a baseline measurement, not an
|
||||
index comparison or an MMO capacity claim.
|
||||
|
||||
Windows MSVC 19.44 Release on Ryzen 7 9800X3D (uncontrolled desktop, 2026-09-19):
|
||||
median milliseconds for 128 queries over 100,000 entities:
|
||||
|
||||
| Radius (mm) | Uniform | Clustered |
|
||||
|---|---:|---:|
|
||||
| 0 | 13.60 | 14.18 |
|
||||
| 16 | 17.73 | 59.31 |
|
||||
| 128 | 19.48 | 48.53 |
|
||||
| 725 | 53.35 | 48.36 |
|
||||
|
||||
Raw three-sample results and compiler metadata are in
|
||||
[spatial-msvc1944.jsonl](../engineering/results/spatial-msvc1944.jsonl).
|
||||
Clustered query centers are inside the same 32 mm patch as the entities; uniform
|
||||
centers span the entire domain. Dense result allocation/checksumming matters as
|
||||
well as scanning. This does not justify querying all 100,000 entities every tick;
|
||||
measure an index against this baseline when interaction frequency is known.
|
||||
Reference in New Issue
Block a user