murk-space 0.1.7

Spatial data structures and field storage for Murk simulations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

//! Space trait compliance test helpers.
//!
//! These functions verify that a Space implementation satisfies the
//! invariants required by the trait contract. Reused across all backend
//! test modules (Line1D, Ring1D, Square4, Square8, Hex2D, ProductSpace).

use crate::region::RegionSpec;
use crate::space::Space;
use indexmap::IndexSet;

/// Assert that `distance(a, a) == 0.0` for all cells.
pub fn assert_distance_reflexive(space: &dyn Space) {
    for coord in space.canonical_ordering() {
        let d = space.distance(&coord, &coord);
        assert!(
            (d - 0.0).abs() < f64::EPSILON,
            "distance({coord:?}, {coord:?}) = {d}, expected 0.0"
        );
    }
}

/// Assert that `distance(a, b) == distance(b, a)` for all cell pairs.
pub fn assert_distance_symmetric(space: &dyn Space) {
    let cells = space.canonical_ordering();
    for a in &cells {
        for b in &cells {
            let dab = space.distance(a, b);
            let dba = space.distance(b, a);
            assert!(
                (dab - dba).abs() < f64::EPSILON,
                "distance({a:?}, {b:?}) = {dab} != distance({b:?}, {a:?}) = {dba}"
            );
        }
    }
}

/// Assert triangle inequality: `d(a, c) <= d(a, b) + d(b, c)` for all triples.
pub fn assert_distance_triangle_inequality(space: &dyn Space) {
    let cells = space.canonical_ordering();
    for a in &cells {
        for b in &cells {
            for c in &cells {
                let dac = space.distance(a, c);
                let dab = space.distance(a, b);
                let dbc = space.distance(b, c);
                assert!(
                    dac <= dab + dbc + f64::EPSILON,
                    "triangle inequality violated: d({a:?},{c:?})={dac} > d({a:?},{b:?})={dab} + d({b:?},{c:?})={dbc}"
                );
            }
        }
    }
}

/// Assert that `b in neighbours(a)` implies `a in neighbours(b)`.
pub fn assert_neighbours_symmetric(space: &dyn Space) {
    for coord in space.canonical_ordering() {
        for nb in space.neighbours(&coord) {
            let nb_neighbours = space.neighbours(&nb);
            assert!(
                nb_neighbours.contains(&coord),
                "neighbour symmetry violated: {nb:?} in N({coord:?}) but {coord:?} not in N({nb:?})"
            );
        }
    }
}

/// Assert that two calls to `canonical_ordering` return the same result.
pub fn assert_canonical_ordering_deterministic(space: &dyn Space) {
    let a = space.canonical_ordering();
    let b = space.canonical_ordering();
    assert_eq!(a, b, "canonical_ordering is non-deterministic");
}

/// Assert that `canonical_ordering` returns exactly `cell_count` unique coords
/// and that those coords match `compile_region(All)`.
pub fn assert_canonical_ordering_complete(space: &dyn Space) {
    let ordering = space.canonical_ordering();
    assert_eq!(
        ordering.len(),
        space.cell_count(),
        "canonical_ordering length ({}) != cell_count ({})",
        ordering.len(),
        space.cell_count()
    );
    let ordering_set: IndexSet<_> = ordering.iter().collect();
    assert_eq!(
        ordering_set.len(),
        space.cell_count(),
        "canonical_ordering has duplicates"
    );

    // Cross-validate: canonical_ordering coords must equal compile_region(All) coords.
    let all_plan = space
        .compile_region(&RegionSpec::All)
        .expect("compile_region(All) should succeed");
    let region_set: IndexSet<_> = all_plan.coords.iter().collect();
    assert_eq!(
        ordering_set, region_set,
        "canonical_ordering and compile_region(All) must cover the same cells"
    );
}

/// Assert that `compile_region(All)` produces `valid_ratio == 1.0`.
pub fn assert_compile_region_all_valid_ratio(space: &dyn Space) {
    let plan = space
        .compile_region(&RegionSpec::All)
        .expect("compile_region(All) should succeed");
    let ratio = plan.valid_ratio();
    assert!(
        (ratio - 1.0).abs() < f64::EPSILON,
        "valid_ratio for All region = {ratio}, expected 1.0"
    );
}

/// Assert that `compile_region(All)` covers all cells with matching coordinates.
pub fn assert_compile_region_all_covers_all(space: &dyn Space) {
    let plan = space
        .compile_region(&RegionSpec::All)
        .expect("compile_region(All) should succeed");
    assert_eq!(
        plan.cell_count(),
        space.cell_count(),
        "compile_region(All).cell_count ({}) != space.cell_count ({})",
        plan.cell_count(),
        space.cell_count()
    );
    // Verify coordinate content, not just cardinality.
    let region_set: IndexSet<_> = plan.coords.iter().collect();
    assert_eq!(
        region_set.len(),
        space.cell_count(),
        "compile_region(All) has duplicate coordinates"
    );
}

/// Run all 8 compliance checks on a space.
pub fn run_full_compliance(space: &dyn Space) {
    assert_distance_reflexive(space);
    assert_distance_symmetric(space);
    assert_distance_triangle_inequality(space);
    assert_neighbours_symmetric(space);
    assert_canonical_ordering_deterministic(space);
    assert_canonical_ordering_complete(space);
    assert_compile_region_all_valid_ratio(space);
    assert_compile_region_all_covers_all(space);
}