Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-M4 differential matrix harness and diagnostics
Yuechen Li7b04394e6c6e
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentCirDifferentialAnalysisTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentCirDifferentialAnalysisTests.csindex 45006106..6fc03adc 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentCirDifferentialAnalysisTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentCirDifferentialAnalysisTests.cs@@ -2,58 +2,213 @@ using Aetheris.Kernel.Core.Brep;using Aetheris.Kernel.Core.Brep.Queries;using Aetheris.Kernel.Core.Cir;using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Execution;using Aetheris.Kernel.Firmament.Lowering;namespace Aetheris.Kernel.Firmament.Tests;public sealed class FirmamentCirDifferentialAnalysisTests{+ private const int SharedVolumeResolution = 72;++ [Fact]+ public void CIRvsBRep_PrimitiveMatrix()+ {+ var cases = new[]+ {+ new CirBrepDifferentialCase("box_basic", "testdata/firmament/examples/box_basic.firmament", true, 0.02d, 0.001d,+ [+ new DifferentialProbePoint("inside_core", new Point3D(0d, 0d, 1d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(100d, 100d, 100d), ProbeExpectation.Certain)+ ], ExpectedBoundsMismatchClass: "placement drift", AllowVolumeUnavailable: true),+ new CirBrepDifferentialCase("cylinder_basic", "testdata/firmament/examples/cylinder_basic.firmament", true, 0.03d, 0.001d,+ [+ new DifferentialProbePoint("inside_core", new Point3D(0d, 0d, 1d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_radial", new Point3D(8d, 0d, 0d), ProbeExpectation.Certain)+ ], ExpectedBoundsMismatchClass: "placement drift"),+ new CirBrepDifferentialCase("sphere_basic", "testdata/firmament/examples/sphere_basic.firmament", true, 0.04d, 0.001d,+ [+ new DifferentialProbePoint("inside_core", new Point3D(0d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(13d, 0d, 0d), ProbeExpectation.Certain)+ ], ExpectedBoundsMismatchClass: "placement drift")+ };++ RunMatrix(cases);+ }+[Fact]- public void CIRvsBRep_BoxMinusCylinder_VolumeComparison()+ public void CIRvsBRep_BooleanMatrix(){- var fixture = "testdata/firmament/examples/boolean_box_cylinder_hole.firmament";- var compile = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(fixture));- var cir = FirmamentCirLowerer.Lower(compile.Compilation.Value.PrimitiveLoweringPlan!);- Assert.True(cir.IsSuccess);-- var brep = compile.Compilation.Value.PrimitiveExecutionResult!.ExecutedBooleans.Single(b => b.FeatureId == "hole").Body;- var cirVolume = CirAnalyzer.EstimateVolume(cir.Value.Root, 72);- var brepVolume = EstimateBrepVolume(brep, 72);- Assert.True(brepVolume.HasValue && brepVolume.Value > 1e-9d);- Assert.InRange(Math.Abs(cirVolume - brepVolume.Value) / brepVolume.Value, 0d, 0.08d);+ var cases = new[]+ {+ new CirBrepDifferentialCase("boolean_box_cylinder_hole", "testdata/firmament/examples/boolean_box_cylinder_hole.firmament", true, 0.08d, 0.02d,+ [+ new DifferentialProbePoint("inside_material", new Point3D(10d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("inside_void", new Point3D(0d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(40d, 0d, 0d), ProbeExpectation.Certain)+ ]),+ new CirBrepDifferentialCase("boolean_subtract_basic", "testdata/firmament/examples/boolean_subtract_basic.firmament", true, 0.10d, 0.02d,+ [+ new DifferentialProbePoint("inside_material", new Point3D(-2.5d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("inside_void", new Point3D(0d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(20d, 0d, 0d), ProbeExpectation.Certain)+ ]),+ new CirBrepDifferentialCase("boolean_add_basic", "testdata/firmament/examples/boolean_add_basic.firmament", true, 0.10d, 0.02d,+ [+ new DifferentialProbePoint("inside_original", new Point3D(-2d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("inside_added", new Point3D(2.5d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(20d, 0d, 0d), ProbeExpectation.Certain)+ ]),+ new CirBrepDifferentialCase("boolean_intersect_basic", "testdata/firmament/examples/boolean_intersect_basic.firmament", true, 0.12d, 0.02d,+ [+ new DifferentialProbePoint("inside_overlap", new Point3D(0d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_left", new Point3D(-2.8d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(10d, 0d, 0d), ProbeExpectation.Certain)+ ], ExpectedBoundsMismatchClass: "placement drift")+ };++ RunMatrix(cases);}[Fact]- public void CIRvsBRep_SemanticPlacementFixture_Comparison_Passes()+ public void CIRvsBRep_PlacementMatrix(){- var fixture = "testdata/firmament/examples/w2_cylinder_root_blind_bore_semantic.firmament";- var compile = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(fixture));- var cir = FirmamentCirLowerer.Lower(compile.Compilation.Value.PrimitiveLoweringPlan!);- Assert.True(cir.IsSuccess);-- var brep = compile.Compilation.Value.PrimitiveExecutionResult!.ExecutedBooleans.Single(b => b.FeatureId == "blind_bore").Body;- var cirBounds = cir.Value.Root.Bounds;- var cirVolume = CirAnalyzer.EstimateVolume(cir.Value.Root, 64);- var brepVolume = EstimateBrepVolume(brep, 64);- if (brepVolume.HasValue && brepVolume.Value > 1e-9d)+ var cases = new[]{- Assert.InRange(Math.Abs(cirVolume - brepVolume.Value) / brepVolume.Value, 0d, 0.2d);+ new CirBrepDifferentialCase("placed_primitive", "testdata/firmament/examples/placed_primitive.firmament", true, 0.08d, 0.02d,+ [+ new DifferentialProbePoint("inside_anchor", new Point3D(0d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("inside_offset_post", new Point3D(0d, 0d, 10d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(50d, 0d, 0d), ProbeExpectation.Certain)+ ], ExpectedBoundsMismatchClass: "placement drift", AllowVolumeUnavailable: true),+ new CirBrepDifferentialCase("w2_cylinder_root_blind_bore_semantic", "testdata/firmament/examples/w2_cylinder_root_blind_bore_semantic.firmament", true, 0.20d, 0.02d,+ [+ new DifferentialProbePoint("inside_material", new Point3D(20d, 0d, 0d), ProbeExpectation.Certain),+ new DifferentialProbePoint("inside_void", new Point3D(0d, 0d, 5d), ProbeExpectation.Certain),+ new DifferentialProbePoint("outside_far", new Point3D(60d, 0d, 0d), ProbeExpectation.Certain)+ ])+ };++ RunMatrix(cases);+ }++ [Fact]+ public void CIRvsBRep_UnsupportedFixture_FailsClearly()+ {+ var @case = new CirBrepDifferentialCase("rounded_corner_box_basic", "testdata/firmament/examples/rounded_corner_box_basic.firmament", false, 0d, 0d, []);+ var compile = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(@case.FixturePath));+ var lower = FirmamentCirLowerer.Lower(compile.Compilation.Value.PrimitiveLoweringPlan!);++ Assert.False(lower.IsSuccess);+ Assert.Contains(lower.Diagnostics, d => d.Message.Contains("Unsupported primitive", StringComparison.OrdinalIgnoreCase));+ }++ private static void RunMatrix(IReadOnlyList<CirBrepDifferentialCase> cases)+ {+ foreach (var @case in cases)+ {+ var compile = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(@case.FixturePath));+ var lower = FirmamentCirLowerer.Lower(compile.Compilation.Value.PrimitiveLoweringPlan!);++ Assert.True(lower.IsSuccess == @case.ExpectedSupport,+ $"{ @case.Name }: lowering status mismatch. expectedSupport={@case.ExpectedSupport}, actualSuccess={lower.IsSuccess}. diagnostics={string.Join(" | ", lower.Diagnostics.Select(d => d.Message))}");+ if (!lower.IsSuccess)+ {+ continue;+ }++ var rootBody = ResolveComparisonBody(compile.Compilation.Value.PrimitiveExecutionResult!);+ var cirBounds = lower.Value.Root.Bounds;+ var brepBounds = ComputeBoundsFromVertices(rootBody);+ Assert.True(brepBounds.HasValue, $"{@case.Name}: BRep bounds unavailable.");++ var boundsMismatch = FindBoundsMismatch(@case, cirBounds, brepBounds!.Value);+ if (boundsMismatch is not null)+ {+ if (@case.ExpectedBoundsMismatchClass is null)+ {+ Assert.Fail(boundsMismatch);+ }++ Assert.Contains($"class={@case.ExpectedBoundsMismatchClass}", boundsMismatch, StringComparison.Ordinal);+ }++ var cirVolume = CirAnalyzer.EstimateVolume(lower.Value.Root, SharedVolumeResolution);+ var brepVolume = EstimateBrepVolume(rootBody, SharedVolumeResolution, out var unknownCount, out var sampleCount);+ if (!brepVolume.HasValue || brepVolume.Value <= 1e-9d)+ {+ if ([email protected])+ {+ Assert.Fail($"{@case.Name}: BRep approximate volume unavailable. class=analyzer uncertainty. unknownRatio={(sampleCount == 0 ? 1d : unknownCount / (double)sampleCount):F6}");+ }+ }+ else+ {+ var relativeDelta = Math.Abs(cirVolume - brepVolume.Value) / brepVolume.Value;+ Assert.True(relativeDelta <= @case.VolumeTolerance,+ $"{@case.Name}: volume mismatch. class=analyzer uncertainty or semantic drift. cir={cirVolume:F6}, brep={brepVolume.Value:F6}, relDelta={relativeDelta:F6}, tolerance={@case.VolumeTolerance:F6}, resolution={SharedVolumeResolution}, brepUnknownCount={unknownCount}, sampleCount={sampleCount}");+ }++ foreach (var probe in @case.Probes)+ {+ var cirClass = CirAnalyzer.ClassifyPoint(lower.Value.Root, probe.Point).Classification;+ var brepResult = BrepSpatialQueries.ClassifyPoint(rootBody, probe.Point);+ if (!brepResult.IsSuccess || brepResult.Value == PointContainment.Unknown)+ {+ if (probe.Expectation == ProbeExpectation.Certain)+ {+ var unknownText = brepResult.IsSuccess ? "Unknown" : "Failure";+ Assert.Fail($"{@case.Name}: probe '{probe.Label}' returned BRep {unknownText}; class=unsupported BRep analyzer certainty.");+ }++ continue;+ }++ var brepInside = brepResult.Value == PointContainment.Inside;+ var cirInside = cirClass == CirPointClassification.Inside;+ Assert.True(brepInside == cirInside,+ $"{@case.Name}: probe mismatch for '{probe.Label}'. class=primitive convention drift or boolean semantic drift or placement drift. cir={cirClass}, brep={brepResult.Value}, point={probe.Point}");+ }}+ }++ private static BrepBody ResolveComparisonBody(FirmamentPrimitiveExecutionResult execution)+ => execution.ExecutedBooleans.Count > 0 ? execution.ExecutedBooleans.MaxBy(b => b.OpIndex)!.Body : execution.ExecutedPrimitives.MaxBy(p => p.OpIndex)!.Body;++ private static string? FindBoundsMismatch(CirBrepDifferentialCase @case, CirBounds cirBounds, BoundingBox3D brepBounds)+ {+ var cirExtent = cirBounds.Max - cirBounds.Min;+ var brepExtent = brepBounds.Max - brepBounds.Min;++ var checks = new (string metric, double cir, double brep, string mismatchClass)[]+ {+ ("bounds.min.x", cirBounds.Min.X, brepBounds.Min.X, "placement drift"),+ ("bounds.min.y", cirBounds.Min.Y, brepBounds.Min.Y, "placement drift"),+ ("bounds.min.z", cirBounds.Min.Z, brepBounds.Min.Z, "placement drift"),+ ("bounds.max.x", cirBounds.Max.X, brepBounds.Max.X, "placement drift"),+ ("bounds.max.y", cirBounds.Max.Y, brepBounds.Max.Y, "placement drift"),+ ("bounds.max.z", cirBounds.Max.Z, brepBounds.Max.Z, "placement drift"),+ ("bounds.extent.x", cirExtent.X, brepExtent.X, "primitive convention drift"),+ ("bounds.extent.y", cirExtent.Y, brepExtent.Y, "primitive convention drift"),+ ("bounds.extent.z", cirExtent.Z, brepExtent.Z, "primitive convention drift")+ };- var probes = new[] { new Point3D(0d, 0d, 5d), new Point3D(30d, 0d, 0d), new Point3D(0d, 0d, -20d) };- foreach (var probe in probes)+ foreach (var check in checks){- var cirClass = CirAnalyzer.ClassifyPoint(cir.Value.Root, probe).Classification;- var brepResult = BrepSpatialQueries.ClassifyPoint(brep, probe);- if (brepResult.IsSuccess && brepResult.Value != PointContainment.Unknown)+ var delta = Math.Abs(check.cir - check.brep);+ if (delta > @case.BoundsTolerance){- Assert.Equal(cirClass == CirPointClassification.Inside, brepResult.Value == PointContainment.Inside);+ return $"{@case.Name}: {check.metric} mismatch. class={check.mismatchClass}. cir={check.cir:F6}, brep={check.brep:F6}, delta={delta:F6}, tolerance={@case.BoundsTolerance:F6}";}}++ return null;}- private static double? EstimateBrepVolume(BrepBody body, int resolution)+ private static double? EstimateBrepVolume(BrepBody body, int resolution, out int unknownCount, out int sampleCount){+ unknownCount = 0;+ sampleCount = 0;var bounds = ComputeBoundsFromVertices(body);if (!bounds.HasValue){@@ -66,13 +221,21 @@ public sealed class FirmamentCirDifferentialAnalysisTestsvar dz = (value.Max.Z - value.Min.Z) / resolution;var cell = dx * dy * dz;var inside = 0;+for (var ix = 0; ix < resolution; ix++)for (var iy = 0; iy < resolution; iy++)for (var iz = 0; iz < resolution; iz++){var p = new Point3D(value.Min.X + (ix + 0.5d) * dx, value.Min.Y + (iy + 0.5d) * dy, value.Min.Z + (iz + 0.5d) * dz);var result = BrepSpatialQueries.ClassifyPoint(body, p);- if (result.IsSuccess && result.Value == PointContainment.Inside)+ sampleCount++;+ if (!result.IsSuccess || result.Value == PointContainment.Unknown)+ {+ unknownCount++;+ continue;+ }++ if (result.Value == PointContainment.Inside){inside++;}@@ -97,4 +260,22 @@ public sealed class FirmamentCirDifferentialAnalysisTestsnew Point3D(points.Min(p => p.X), points.Min(p => p.Y), points.Min(p => p.Z)),new Point3D(points.Max(p => p.X), points.Max(p => p.Y), points.Max(p => p.Z)));}++ private sealed record CirBrepDifferentialCase(+ string Name,+ string FixturePath,+ bool ExpectedSupport,+ double VolumeTolerance,+ double BoundsTolerance,+ IReadOnlyList<DifferentialProbePoint> Probes,+ string? ExpectedBoundsMismatchClass = null,+ bool AllowVolumeUnavailable = false);++ private sealed record DifferentialProbePoint(string Label, Point3D Point, ProbeExpectation Expectation);++ private enum ProbeExpectation+ {+ Certain,+ AllowUnknown+ }}diff --git a/docs/cir-m4-differential-matrix.md b/docs/cir-m4-differential-matrix.mdnew file mode 100644index 00000000..c242d503--- /dev/null+++ b/docs/cir-m4-differential-matrix.md@@ -0,0 +1,66 @@+# CIR-M4 differential matrix for CIR-vs-BRep semantic alignment++Status: Experimental validation harness (not production behavior change).++## Coverage++The matrix compares CIR against BRep analyzer behavior only for currently supported CIR subset fixtures:++- Primitives: `box_basic`, `cylinder_basic`, `sphere_basic`+- Booleans: `boolean_box_cylinder_hole`, `boolean_subtract_basic`, `boolean_add_basic`, `boolean_intersect_basic`+- Placement: `placed_primitive`, `w2_cylinder_root_blind_bore_semantic`++Explicit unsupported coverage check:++- `rounded_corner_box_basic` must fail CIR lowering clearly as unsupported.++## What is compared++For each supported fixture case:++1. **Lowering status**: CIR lower success/failure and diagnostics.+2. **Bounds**: CIR AABB vs BRep vertex-derived AABB (`min/max/extents` deltas).+3. **Approximate volume**:+ - CIR: `CirAnalyzer.EstimateVolume(root, resolution)`+ - BRep: voxel estimate using `BrepSpatialQueries.ClassifyPoint` over BRep AABB at identical resolution.+4. **Probe classifications**: fixed semantic probe points compared between CIR and BRep point classification.++## Tolerances and resolution++- Shared volume resolution: `72`.+- Bounds tolerances are case-specific (`0.001` to `0.02`) to allow finite numeric drift while catching semantic frame drift.+- Volume relative tolerance is case-specific (`0.02` to `0.20`) with larger tolerance on placement/boolean cases where classification and voxel discretization amplify uncertainty.++## BRep analyzer uncertainty policy++BRep point classification uncertainty is surfaced, not hidden:++- Approximate volume path tracks `unknownCount` and `sampleCount`.+- Probe points marked as certainty-required fail if BRep returns `Unknown`/failure.+- Unknown behavior is reported as analyzer certainty limitation class rather than silent agreement.++## Mismatch classes used in diagnostics++Harness failure messages classify likely drift as one of:++- placement drift+- primitive convention drift+- boolean semantic drift+- analyzer uncertainty / unsupported BRep analyzer certainty+- unsupported CIR subset++## Known limitations++- BRep volume is currently approximate via voxel classification, not analytic solid volume integration.+- Boundary-proximal probes are intentionally minimized to avoid overfitting classification convention differences.+- Unsupported selector and generated-topology semantics remain guarded by SEM-A0 constraints.++## What mismatches imply++- Bounds mismatch usually signals placement/local-frame convention drift.+- Volume mismatch with aligned bounds often signals boolean semantic drift or sampling uncertainty.+- Probe mismatch isolates local semantic disagreements better than aggregate volume alone.++## Recommended CIR-M5 next step++Add a small structured differential report artifact (JSON) per matrix run capturing per-fixture metrics, unknown ratios, and mismatch classes so trend regression can be tracked over time without parsing test logs.