Skip to content

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.cs
index 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)
+ {
+ {
+ 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 FirmamentCirDifferentialAnalysisTests
var 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 FirmamentCirDifferentialAnalysisTests
new 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.md
new file mode 100644
index 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.