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.csnew file mode 100644index 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.