Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add internal CIR native analysis service for Firmament plans and tape

Yuechen Li5cd73e43831f
diff --git a/Aetheris.Kernel.Firmament.Tests/CirAnalysisServiceTests.cs b/Aetheris.Kernel.Firmament.Tests/CirAnalysisServiceTests.cs
new file mode 100644
index 00000000..88339edd
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/CirAnalysisServiceTests.cs
@@ -0,0 +1,96 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Analysis;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class CirAnalysisServiceTests
+{
+ [Fact]
+ public void CirAnalysisService_TapeInput_VolumeAndPoints()
+ {
+ var node = new CirBoxNode(4d, 4d, 4d);
+ var tape = CirTapeLowerer.Lower(node);
+
+ var result = CirNativeAnalysisService.AnalyzeTape(
+ tape,
+ node.Bounds,
+ [new Point3D(0d, 0d, 0d), new Point3D(10d, 0d, 0d)],
+ denseResolution: 20);
+
+ Assert.True(result.Success);
+ Assert.Equal("cir", result.Backend);
+ Assert.Equal(CirNativeAnalysisInputKind.CirTape, result.InputKind);
+ Assert.Equal(CirNativeAnalysisResultKind.Approximate, result.ResultKind);
+ Assert.NotNull(result.Volume);
+ Assert.Equal(CirNativeEstimatorKind.Dense, result.Volume!.Estimator);
+ Assert.Equal(2, result.PointClassifications.Count);
+ Assert.Contains(result.PointClassifications, p => p.Classification == CirPointClassification.Inside);
+ Assert.Contains(result.PointClassifications, p => p.Classification == CirPointClassification.Outside);
+ }
+
+ [Fact]
+ public void CirAnalysisService_FirmamentPlan_BoxBasic_Succeeds()
+ {
+ var plan = CompilePlan("testdata/firmament/examples/box_basic.firmament");
+ var result = CirNativeAnalysisService.AnalyzeFirmamentPlan(plan, denseResolution: 30);
+
+ Assert.True(result.Success);
+ Assert.Equal(CirNativeAnalysisInputKind.Firmament, result.InputKind);
+ Assert.NotNull(result.Bounds);
+ Assert.NotNull(result.Volume);
+ Assert.True(result.Volume!.EstimatedVolume > 0d);
+ Assert.NotNull(result.Lowering);
+ Assert.True(result.Lowering!.Supported);
+ }
+
+ [Fact]
+ public void CirAnalysisService_FirmamentPlan_BoxMinusCylinder_Succeeds()
+ {
+ var plan = CompilePlan("testdata/firmament/examples/boolean_box_cylinder_hole.firmament");
+ var result = CirNativeAnalysisService.AnalyzeFirmamentPlan(plan, denseResolution: 32);
+
+ Assert.True(result.Success);
+ Assert.NotNull(result.Volume);
+ Assert.Equal(CirNativeEstimatorKind.Dense, result.Volume!.Estimator);
+ Assert.Empty(result.Diagnostics);
+ Assert.DoesNotContain(result.Notes, n => n.Contains("fallback", StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void CirAnalysisService_UnsupportedFirmamentPlan_FailsClearly()
+ {
+ var plan = CompilePlan("testdata/firmament/examples/rounded_corner_box_basic.firmament");
+ var result = CirNativeAnalysisService.AnalyzeFirmamentPlan(plan, denseResolution: 24);
+
+ Assert.False(result.Success);
+ Assert.NotEmpty(result.Diagnostics);
+ Assert.Contains(result.Notes, n => n.Contains("BRep backend may still support materialized analysis", StringComparison.Ordinal));
+ Assert.Null(result.Volume);
+ }
+
+ [Fact]
+ public void AdaptiveVolume_MetadataPresent()
+ {
+ var plan = CompilePlan("testdata/firmament/examples/boolean_box_cylinder_hole.firmament");
+ var options = new CirAdaptiveVolumeOptions(MaxDepth: 6, DirectSampleGrid: 2, MaxTraceEvents: 20);
+
+ var result = CirNativeAnalysisService.AnalyzeFirmamentPlan(plan, adaptiveOptions: options);
+
+ Assert.True(result.Success);
+ Assert.NotNull(result.Volume);
+ Assert.Equal(CirNativeEstimatorKind.Adaptive, result.Volume!.Estimator);
+ Assert.NotNull(result.Volume.AdaptiveOptions);
+ Assert.Equal(options.MaxDepth, result.Volume.AdaptiveOptions!.MaxDepth);
+ Assert.True(result.Volume.TotalRegionsVisited > 0);
+ Assert.True(result.Volume.TraceEventCount > 0);
+ Assert.True(result.Volume.RegionsSubdivided >= 0);
+ }
+
+ private static Lowering.FirmamentPrimitiveLoweringPlan CompilePlan(string fixture)
+ {
+ var compile = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(fixture));
+ Assert.True(compile.Compilation.IsSuccess);
+ return compile.Compilation.Value.PrimitiveLoweringPlan!;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Analysis/CirNativeAnalysisService.cs b/Aetheris.Kernel.Firmament/Analysis/CirNativeAnalysisService.cs
new file mode 100644
index 00000000..48b7c4c9
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Analysis/CirNativeAnalysisService.cs
@@ -0,0 +1,79 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Firmament.Lowering;
+
+namespace Aetheris.Kernel.Firmament.Analysis;
+
+public enum CirNativeAnalysisInputKind { Firmament, CirTape, CirNode }
+public enum CirNativeAnalysisResultKind { Approximate, ClassifierDerived }
+public enum CirNativeEstimatorKind { Dense, Adaptive }
+public sealed record CirNativeLoweringDiagnostic(int? OpIndex, string? FeatureId, string Message);
+public sealed record CirNativeLoweringSummary(bool Supported, int SupportedOpCount, int UnsupportedOpCount, IReadOnlyList<CirNativeLoweringDiagnostic> Diagnostics);
+public sealed record CirNativeBounds(Point3D Min, Point3D Max);
+public sealed record CirNativePointClassification(Point3D Point, CirPointClassification Classification, double SignedDistance);
+public sealed record CirNativeVolumeResult(CirNativeEstimatorKind Estimator, double EstimatedVolume, int? Resolution, CirAdaptiveVolumeOptions? AdaptiveOptions, int? SampledPointCount, int? TotalRegionsVisited, int? RegionsClassifiedInside, int? RegionsClassifiedOutside, int? RegionsSubdivided, int? RegionsSampledDirectly, int? UnknownOrRejectedRegions, int? MaxDepthReached, int TraceEventCount, IReadOnlyList<CirAdaptiveTraceEvent> TraceHead, bool Approximate);
+public sealed record CirNativeAnalysisResult(bool Success, string Backend, CirNativeAnalysisInputKind InputKind, CirNativeAnalysisResultKind ResultKind, IReadOnlyList<string> Notes, IReadOnlyList<CirNativeLoweringDiagnostic> Diagnostics, CirNativeLoweringSummary? Lowering, CirNativeBounds? Bounds, CirNativeVolumeResult? Volume, IReadOnlyList<CirNativePointClassification> PointClassifications);
+
+public static class CirNativeAnalysisService
+{
+ public static CirNativeAnalysisResult AnalyzeTape(CirTape tape, CirBounds bounds, IEnumerable<Point3D>? points = null, int? denseResolution = null, CirAdaptiveVolumeOptions? adaptiveOptions = null)
+ => AnalyzeCore(tape, bounds, CirNativeAnalysisInputKind.CirTape, points, denseResolution, adaptiveOptions, null);
+
+ public static CirNativeAnalysisResult AnalyzeNode(CirNode node, IEnumerable<Point3D>? points = null, int? denseResolution = null, CirAdaptiveVolumeOptions? adaptiveOptions = null)
+ => AnalyzeCore(CirTapeLowerer.Lower(node), node.Bounds, CirNativeAnalysisInputKind.CirNode, points, denseResolution, adaptiveOptions, null);
+
+ public static CirNativeAnalysisResult AnalyzeFirmamentPlan(FirmamentPrimitiveLoweringPlan plan, IEnumerable<Point3D>? points = null, int? denseResolution = null, CirAdaptiveVolumeOptions? adaptiveOptions = null)
+ {
+ var lowering = FirmamentCirLowerer.Lower(plan);
+ var diagnostics = lowering.Diagnostics.Select(d => new CirNativeLoweringDiagnostic(null, d.Source, d.Message)).ToArray();
+ var loweringSummary = new CirNativeLoweringSummary(lowering.IsSuccess, plan.Primitives.Count + plan.Booleans.Count, diagnostics.Length, diagnostics);
+
+ if (!lowering.IsSuccess)
+ {
+ return new CirNativeAnalysisResult(false, "cir", CirNativeAnalysisInputKind.Firmament, CirNativeAnalysisResultKind.ClassifierDerived,
+ ["BRep backend may still support materialized analysis; CIR lowering is unsupported for this model."], diagnostics, loweringSummary, null, null, []);
+ }
+
+ return AnalyzeCore(CirTapeLowerer.Lower(lowering.Value.Root), lowering.Value.Root.Bounds, CirNativeAnalysisInputKind.Firmament, points, denseResolution, adaptiveOptions, loweringSummary);
+ }
+
+ private static CirNativeAnalysisResult AnalyzeCore(CirTape tape, CirBounds bounds, CirNativeAnalysisInputKind inputKind, IEnumerable<Point3D>? points, int? denseResolution, CirAdaptiveVolumeOptions? adaptiveOptions, CirNativeLoweringSummary? lowering)
+ {
+ var classifications = (points ?? []).Select(point =>
+ {
+ var value = tape.Evaluate(point);
+ var kind = double.Abs(value) <= 1e-6d ? CirPointClassification.Boundary : (value < 0d ? CirPointClassification.Inside : CirPointClassification.Outside);
+ return new CirNativePointClassification(point, kind, value);
+ }).ToArray();
+
+ var notes = new List<string>();
+ CirNativeAnalysisResultKind resultKind = CirNativeAnalysisResultKind.ClassifierDerived;
+ CirNativeVolumeResult? volume = null;
+
+ if (adaptiveOptions is not null)
+ {
+ var adaptive = CirAdaptiveVolumeEstimator.EstimateVolume(tape, bounds, adaptiveOptions);
+ volume = new CirNativeVolumeResult(CirNativeEstimatorKind.Adaptive, adaptive.EstimatedVolume, null, adaptive.Options, null, adaptive.TotalRegionsVisited, adaptive.RegionsClassifiedInside, adaptive.RegionsClassifiedOutside, adaptive.RegionsSubdivided, adaptive.RegionsSampledDirectly, adaptive.UnknownOrRejectedRegions, adaptive.MaxDepthReached, adaptive.TraceEvents.Count, adaptive.TraceEvents, true);
+ notes.AddRange(adaptive.Notes);
+ resultKind = CirNativeAnalysisResultKind.Approximate;
+ }
+ else if (denseResolution.HasValue)
+ {
+ var resolution = int.Max(1, denseResolution.Value);
+ var volumeNode = new CirTapeVolumeNode(tape, bounds);
+ volume = new CirNativeVolumeResult(CirNativeEstimatorKind.Dense, CirVolumeEstimator.EstimateVolume(volumeNode, resolution), resolution, null, resolution * resolution * resolution, null, null, null, null, null, 0, null, 0, [], true);
+ notes.Add("Dense CIR volume estimation uses regular grid center-point sampling and is approximate.");
+ resultKind = CirNativeAnalysisResultKind.Approximate;
+ }
+
+ return new CirNativeAnalysisResult(true, "cir", inputKind, resultKind, notes, [], lowering, new CirNativeBounds(bounds.Min, bounds.Max), volume, classifications);
+ }
+
+ private sealed record CirTapeVolumeNode(CirTape Tape, CirBounds TapeBounds) : CirNode(CirNodeKind.Transform)
+ {
+ public override CirBounds Bounds => TapeBounds;
+ public override double Evaluate(Point3D point) => Tape.Evaluate(point);
+ }
+}
diff --git a/docs/cir-a1-native-analysis-service.md b/docs/cir-a1-native-analysis-service.md
new file mode 100644
index 00000000..31416cf4
--- /dev/null
+++ b/docs/cir-a1-native-analysis-service.md
@@ -0,0 +1,40 @@
+# CIR-A1: Native Internal CIR Analysis Service
+
+`CirNativeAnalysisService` introduces an internal/test-facing API for CIR-backed native analysis without changing public CLI behavior.
+
+## Purpose
+
+- Analyze CIR-supported Firmament lowering plans without materializing BRep.
+- Provide a stable structured result contract for CIR-A2 hidden CLI wiring.
+- Surface uncertainty and lowering coverage explicitly.
+
+## Supported inputs
+
+- `FirmamentPrimitiveLoweringPlan` via `AnalyzeFirmamentPlan`.
+- `CirTape` + bounds via `AnalyzeTape`.
+- `CirNode` via `AnalyzeNode` (lowered to tape internally).
+
+## Result contract overview
+
+Top-level result includes:
+
+- `Success`, `Backend` (`cir`), `InputKind`, `ResultKind`.
+- `Notes` and `Diagnostics`.
+- `Lowering` coverage summary (supported flag, supported/unsupported op counters, diagnostics).
+- `Bounds`.
+- `Volume` metadata (dense/adaptive estimator, estimate, sampling/region counters, adaptive trace count/head).
+- point classification entries (point, classification, signed-distance value).
+
+## No-fallback policy
+
+When Firmament-to-CIR lowering is unsupported, the service returns `Success=false` with lowering diagnostics and does **not** fall back to BRep.
+
+Returned note:
+
+- `BRep backend may still support materialized analysis; CIR lowering is unsupported for this model.`
+
+## Status and next step
+
+This is internal/experimental only and intentionally not public CLI surface.
+
+Next step (CIR-A2): wire hidden/experimental CLI entry to this service with explicit backend selection and unchanged production defaults.