Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

CIR-F7 pressure test: add torus CIR representation and explicit box-torus materializer rejection

Yuechen Li38b17c0ea807
diff --git a/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs b/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs
index 73aa2c6a..a519629a 100644
--- a/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs
+++ b/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs
@@ -79,11 +79,19 @@ public sealed class CirTapeEvaluationTests
Assert.Equal(first.BoxPayloads, second.BoxPayloads);
Assert.Equal(first.CylinderPayloads, second.CylinderPayloads);
Assert.Equal(first.SpherePayloads, second.SpherePayloads);
+ Assert.Equal(first.TorusPayloads, second.TorusPayloads);
var probe = new Point3D(1.25d, -0.5d, 2d);
Assert.Equal(first.Evaluate(probe), second.Evaluate(probe), 12);
}
+ [Fact]
+ public void Tape_Torus_MatchesRecursiveEvaluate()
+ {
+ var node = new CirTransformNode(new CirTorusNode(6d, 2d), Transform3D.CreateTranslation(new Vector3D(1d, 0d, 0.5d)));
+ AssertTapeMatches(node, new Point3D(7d, 0d, 0.5d), new Point3D(1d, 0d, 0.5d), new Point3D(1d, 0d, 2.5d));
+ }
+
private static void AssertTapeMatches(CirNode node, params Point3D[] points)
{
var tape = CirTapeLowerer.Lower(node);
diff --git a/Aetheris.Kernel.Core/Cir/CirNode.cs b/Aetheris.Kernel.Core/Cir/CirNode.cs
index 1c87ad0f..59f12727 100644
--- a/Aetheris.Kernel.Core/Cir/CirNode.cs
+++ b/Aetheris.Kernel.Core/Cir/CirNode.cs
@@ -7,6 +7,7 @@ public enum CirNodeKind
Box,
Cylinder,
Sphere,
+ Torus,
Union,
Subtract,
Intersect,
diff --git a/Aetheris.Kernel.Core/Cir/CirNodes.cs b/Aetheris.Kernel.Core/Cir/CirNodes.cs
index 878dfc6c..c5546cd5 100644
--- a/Aetheris.Kernel.Core/Cir/CirNodes.cs
+++ b/Aetheris.Kernel.Core/Cir/CirNodes.cs
@@ -48,6 +48,19 @@ public sealed record CirSphereNode(double Radius) : CirNode(CirNodeKind.Sphere)
public override double Evaluate(Point3D point) => double.Sqrt((point.X * point.X) + (point.Y * point.Y) + (point.Z * point.Z)) - Radius;
}
+public sealed record CirTorusNode(double MajorRadius, double MinorRadius) : CirNode(CirNodeKind.Torus)
+{
+ public override CirBounds Bounds => new(
+ new Point3D(-(MajorRadius + MinorRadius), -(MajorRadius + MinorRadius), -MinorRadius),
+ new Point3D(MajorRadius + MinorRadius, MajorRadius + MinorRadius, MinorRadius));
+
+ public override double Evaluate(Point3D point)
+ {
+ var qx = double.Sqrt((point.X * point.X) + (point.Y * point.Y)) - MajorRadius;
+ return double.Sqrt((qx * qx) + (point.Z * point.Z)) - MinorRadius;
+ }
+}
+
public sealed record CirUnionNode(CirNode Left, CirNode Right) : CirNode(CirNodeKind.Union)
{
public override CirBounds Bounds => CirBounds.Union(Left.Bounds, Right.Bounds);
diff --git a/Aetheris.Kernel.Core/Cir/CirTape.cs b/Aetheris.Kernel.Core/Cir/CirTape.cs
index f6426b7c..d5b1df27 100644
--- a/Aetheris.Kernel.Core/Cir/CirTape.cs
+++ b/Aetheris.Kernel.Core/Cir/CirTape.cs
@@ -8,6 +8,7 @@ public enum CirTapeOpCode
EvalBox,
EvalCylinder,
EvalSphere,
+ EvalTorus,
Min,
Max,
Neg,
@@ -25,6 +26,7 @@ public readonly record struct CirTapeInstruction(
public readonly record struct CirTapeBoxPayload(double Width, double Height, double Depth, Transform3D InverseTransform);
public readonly record struct CirTapeCylinderPayload(double Radius, double Height, Transform3D InverseTransform);
public readonly record struct CirTapeSpherePayload(double Radius, Transform3D InverseTransform);
+public readonly record struct CirTapeTorusPayload(double MajorRadius, double MinorRadius, Transform3D InverseTransform);
public readonly record struct FieldInterval(double MinValue, double MaxValue)
{
@@ -51,6 +53,7 @@ public sealed class CirTape
IReadOnlyList<CirTapeBoxPayload> boxes,
IReadOnlyList<CirTapeCylinderPayload> cylinders,
IReadOnlyList<CirTapeSpherePayload> spheres,
+ IReadOnlyList<CirTapeTorusPayload> toruses,
int outputSlot,
int slotCount)
{
@@ -58,6 +61,7 @@ public sealed class CirTape
BoxPayloads = boxes;
CylinderPayloads = cylinders;
SpherePayloads = spheres;
+ TorusPayloads = toruses;
OutputSlot = outputSlot;
SlotCount = slotCount;
}
@@ -66,6 +70,7 @@ public sealed class CirTape
public IReadOnlyList<CirTapeBoxPayload> BoxPayloads { get; }
public IReadOnlyList<CirTapeCylinderPayload> CylinderPayloads { get; }
public IReadOnlyList<CirTapeSpherePayload> SpherePayloads { get; }
+ public IReadOnlyList<CirTapeTorusPayload> TorusPayloads { get; }
public int OutputSlot { get; }
public int SlotCount { get; }
@@ -95,6 +100,12 @@ public sealed class CirTape
slots[instruction.DestSlot] = EvaluateSphere(point, payload);
break;
}
+ case CirTapeOpCode.EvalTorus:
+ {
+ var payload = TorusPayloads[instruction.PayloadIndex];
+ slots[instruction.DestSlot] = EvaluateTorus(point, payload);
+ break;
+ }
case CirTapeOpCode.Min:
slots[instruction.DestSlot] = double.Min(slots[instruction.InputA], slots[instruction.InputB]);
break;
@@ -129,6 +140,9 @@ public sealed class CirTape
case CirTapeOpCode.EvalSphere:
slots[instruction.DestSlot] = EvaluateSphereInterval(region, SpherePayloads[instruction.PayloadIndex]);
break;
+ case CirTapeOpCode.EvalTorus:
+ slots[instruction.DestSlot] = EvaluateTorusInterval(region, TorusPayloads[instruction.PayloadIndex]);
+ break;
case CirTapeOpCode.Min:
{
var a = slots[instruction.InputA];
@@ -209,6 +223,14 @@ public sealed class CirTape
return double.Sqrt((point.X * point.X) + (point.Y * point.Y) + (point.Z * point.Z)) - payload.Radius;
}
+ private static double EvaluateTorus(Point3D point, CirTapeTorusPayload payload)
+ {
+ point = payload.InverseTransform.Apply(point);
+ var radial = double.Sqrt((point.X * point.X) + (point.Y * point.Y));
+ var qx = radial - payload.MajorRadius;
+ return double.Sqrt((qx * qx) + (point.Z * point.Z)) - payload.MinorRadius;
+ }
+
private static FieldInterval EvaluateBoxInterval(CirBounds region, CirTapeBoxPayload payload)
{
var local = TransformBounds(region, payload.InverseTransform);
@@ -234,6 +256,19 @@ public sealed class CirTape
return new FieldInterval(distanceMin - payload.Radius, distanceMax - payload.Radius);
}
+ private static FieldInterval EvaluateTorusInterval(CirBounds region, CirTapeTorusPayload payload)
+ {
+ var local = TransformBounds(region, payload.InverseTransform);
+ var radial = RadiusInterval(local, payload.MajorRadius);
+ var qMin = MinAbsInInterval(radial.MinValue, radial.MaxValue);
+ var qMax = MaxAbsInInterval(radial.MinValue, radial.MaxValue);
+ var zMinAbs = MinAbsInInterval(local.Min.Z, local.Max.Z);
+ var zMaxAbs = MaxAbsInInterval(local.Min.Z, local.Max.Z);
+ var minD = double.Sqrt((qMin * qMin) + (zMinAbs * zMinAbs));
+ var maxD = double.Sqrt((qMax * qMax) + (zMaxAbs * zMaxAbs));
+ return new FieldInterval(minD - payload.MinorRadius, maxD - payload.MinorRadius);
+ }
+
private static CirBounds TransformBounds(CirBounds bounds, Transform3D transform)
{
var corners = GetCorners(bounds);
@@ -335,6 +370,7 @@ public static class CirTapeLowerer
state.BoxPayloads,
state.CylinderPayloads,
state.SpherePayloads,
+ state.TorusPayloads,
outputSlot,
state.NextSlot);
}
@@ -361,6 +397,12 @@ public static class CirTapeLowerer
state.SpherePayloads.Add(new CirTapeSpherePayload(sphere.Radius, accumulatedInverse));
return state.Emit(CirTapeOpCode.EvalSphere, -1, -1, payloadIndex, node.Kind);
}
+ case CirTorusNode torus:
+ {
+ var payloadIndex = state.TorusPayloads.Count;
+ state.TorusPayloads.Add(new CirTapeTorusPayload(torus.MajorRadius, torus.MinorRadius, accumulatedInverse));
+ return state.Emit(CirTapeOpCode.EvalTorus, -1, -1, payloadIndex, node.Kind);
+ }
case CirUnionNode union:
{
var left = LowerNode(union.Left, accumulatedInverse, state);
@@ -396,6 +438,7 @@ public static class CirTapeLowerer
public List<CirTapeBoxPayload> BoxPayloads { get; } = new();
public List<CirTapeCylinderPayload> CylinderPayloads { get; } = new();
public List<CirTapeSpherePayload> SpherePayloads { get; } = new();
+ public List<CirTapeTorusPayload> TorusPayloads { get; } = new();
public int NextSlot { get; private set; }
public int Emit(CirTapeOpCode opCode, int inputA, int inputB, int payloadIndex, CirNodeKind sourceKind)
diff --git a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs
index 703185e2..f5c2439a 100644
--- a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs
@@ -59,6 +59,18 @@ public sealed class CirBrepMaterializerTests
Assert.Contains("Replay/CIR mismatch", result.Message, StringComparison.Ordinal);
}
+ [Fact]
+ public void CirMaterializer_BoxMinusTorus_FailsWithPreciseUnsupported()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirTorusNode(8, 2));
+ var replay = BuildReplay("torus");
+ var result = CirBrepMaterializer.TryMaterialize(new CirBrepMaterializer.CirBrepMaterializerContext(root, replay));
+ Assert.False(result.IsSuccess);
+ Assert.Equal("subtract_box_torus", result.SelectedStrategy);
+ Assert.Equal("materialization-unsupported", result.UnsupportedReason);
+ Assert.Contains("recognized", result.Message, StringComparison.OrdinalIgnoreCase);
+ }
+
[Fact]
public void CirOnly_BoxMinusCylinder_RematerializesToBRepActive()
{
diff --git a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs
index b56f5aaa..03bb41ab 100644
--- a/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/NativeGeometryStateTests.cs
@@ -213,7 +213,7 @@ public sealed partial class NativeGeometryStateTests
}
[Fact]
- public void FallForward_UnsupportedCIRLowering_DoesNotTransition()
+ public void FallForward_BoxMinusTorus_DoesNotMaskUpstreamCompileFailure()
{
var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/fixtures/m10n-unsupported-box-subtract-torus.firmament"));
Assert.False(result.Compilation.IsSuccess);
diff --git a/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs b/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs
index 3e4b0c88..28092b58 100644
--- a/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs
+++ b/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs
@@ -11,8 +11,9 @@ internal static class CirBrepMaterializer
{
internal const string BoxMinusCylinderPattern = "subtract(box,cylinder)";
internal const string BoxMinusBoxPattern = "subtract(box,box)";
+ internal const string BoxMinusTorusPattern = "subtract(box,torus)";
private static readonly JudgmentEngine<CirBrepMaterializerContext> Engine = new();
- private static readonly ICirBrepMaterializerStrategy[] Registry = [new SubtractBoxCylinderStrategy(), new SubtractBoxBoxStrategy()];
+ private static readonly ICirBrepMaterializerStrategy[] Registry = [new SubtractBoxCylinderStrategy(), new SubtractBoxBoxStrategy(), new SubtractBoxTorusUnsupportedStrategy()];
internal static CirBrepMaterializationResult TryMaterialize(CirNode root) => TryMaterialize(new CirBrepMaterializerContext(root, null));
@@ -82,6 +83,19 @@ internal static class CirBrepMaterializer
}
}
+ private sealed class SubtractBoxTorusUnsupportedStrategy : ICirBrepMaterializerStrategy
+ {
+ public string Name => "subtract_box_torus";
+ public bool IsAdmissible(CirBrepMaterializerContext context) => TryMatchTorus(context, out _);
+ public string RejectionReason(CirBrepMaterializerContext context) => TryMatchTorus(context, out var reason) ? "admissible" : reason;
+ public double Score(CirBrepMaterializerContext context) => context.ReplayLog is null ? 0.5d : 3d;
+ public CirBrepMaterializationResult Materialize(CirBrepMaterializerContext context)
+ {
+ if (!TryMatchTorus(context, out var reason)) return new(false, null, BoxMinusTorusPattern, "strategy-no-longer-admissible", [], reason, Name, []);
+ return new(false, null, BoxMinusTorusPattern, "materialization-unsupported", [], "Replay-guided pattern subtract(box,torus) recognized, but no exact CIR→BRep torus subtract materializer exists yet.", Name, []);
+ }
+ }
+
private sealed record Match(CirBoxNode LeftBox, Vector3D LeftTranslation, Vector3D RightTranslation, CirCylinderNode? Cylinder, CirBoxNode? RightBox);
private static bool TryMatch(CirBrepMaterializerContext context, bool cylinder, out Match? match, out string reason)
{
@@ -106,6 +120,14 @@ internal static class CirBrepMaterializer
reason = "matched"; return true;
}
+ private static bool TryMatchTorus(CirBrepMaterializerContext context, out string reason)
+ {
+ if (context.Root is not CirSubtractNode s) { reason = "CIR root is not subtract."; return false; }
+ if (!TryUnwrapTranslation(s.Left, out var lnode, out _) || lnode is not CirBoxNode) { reason = "Subtract lhs must be translated/untranslated box with translation-only transforms."; return false; }
+ if (!TryUnwrapTranslation(s.Right, out var rnode, out _) || rnode is not CirTorusNode) { reason = "Subtract rhs must be translated/untranslated torus."; return false; }
+ return ReplayMatches(context, "torus", out reason);
+ }
+
private static CirBrepMaterializationResult Failed(string pattern, string message, IReadOnlyList<KernelDiagnostic> d) => new(false, null, pattern, "materialize-failed", d, message, null, []);
private static BrepBody TranslateBody(BrepBody body, Vector3D t) => t == Vector3D.Zero ? body : FirmamentPrimitiveExecutionTranslation.TranslateBody(body, t);
private static bool TryUnwrapTranslation(CirNode node, out CirNode unwrapped, out Vector3D translation) { var total = Vector3D.Zero; var cur = node; while (cur is CirTransformNode tr) { if (!TryExtractPureTranslation(tr.Transform, out var local)) { unwrapped = node; translation = Vector3D.Zero; return false; } total += local; cur = tr.Child; } unwrapped = cur; translation = total; return true; }
diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs
index 59512d44..ade0f98a 100644
--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs
+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs
@@ -102,6 +102,8 @@ internal static class FirmamentCirLowerer
"cylinder" when boolean.Tool.RawFields.TryGetValue("radius", out var radius) && boolean.Tool.RawFields.TryGetValue("height", out var height)
=> new CirCylinderNode(double.Parse(radius), double.Parse(height)),
"sphere" when boolean.Tool.RawFields.TryGetValue("radius", out var sr) => new CirSphereNode(double.Parse(sr)),
+ "torus" when boolean.Tool.RawFields.TryGetValue("major_radius", out var major) && boolean.Tool.RawFields.TryGetValue("minor_radius", out var minor)
+ => new CirTorusNode(double.Parse(major), double.Parse(minor)),
_ => UnsupportedTool(boolean, diagnostics)
};
}
@@ -117,6 +119,7 @@ internal static class FirmamentCirLowerer
{ Kind: FirmamentLoweredPrimitiveKind.Box, Parameters: FirmamentLoweredBoxParameters box } => new CirBoxNode(box.SizeX, box.SizeY, box.SizeZ),
{ Kind: FirmamentLoweredPrimitiveKind.Cylinder, Parameters: FirmamentLoweredCylinderParameters cylinder } => new CirCylinderNode(cylinder.Radius, cylinder.Height),
{ Kind: FirmamentLoweredPrimitiveKind.Sphere, Parameters: FirmamentLoweredSphereParameters sphere } => new CirSphereNode(sphere.Radius),
+ { Kind: FirmamentLoweredPrimitiveKind.Torus, Parameters: FirmamentLoweredTorusParameters torus } => new CirTorusNode(torus.MajorRadius, torus.MinorRadius),
_ => UnsupportedPrimitive(primitive, diagnostics)
};
diff --git a/docs/cir-f7-box-minus-torus-pressure-test.md b/docs/cir-f7-box-minus-torus-pressure-test.md
new file mode 100644
index 00000000..e4d91e05
--- /dev/null
+++ b/docs/cir-f7-box-minus-torus-pressure-test.md
@@ -0,0 +1,45 @@
+# CIR-F7: replay-guided pressure test for `subtract(box, torus)`
+
+## Outcome
+
+**Success (Path B: valid CIR intent + explicit unsupported CIR→BRep materializer).**
+
+`subtract(box, torus)` now lowers into CIR and can execute in `CirOnly` fall-forward when BRep subtract rejects the family. CIR analysis remains available. Rematerialization/STEP export remain blocked with explicit strategy-level diagnostics until an exact torus subtract materializer exists.
+
+## Layer audit
+
+- **Firmament:** torus primitive/tool support already existed in parsing, validation, lowering plan, selector contracts, and primitive execution paths.
+- **CIR (before F7):** torus was missing from `CirNode`/tape lowering and therefore blocked CIR fallback for torus families.
+- **CIR (F7):** added bounded `CirTorusNode` + tape opcode/payload lowering/evaluation so `subtract(box,torus)` is representable and analyzable in CIR.
+- **BRep primitives / STEP:** torus primitive and torus surface export already exist.
+- **Boolean subtract:** no safe exact `box - torus` path is currently available in the bounded subtract-family materializers.
+- **Replay-guided materializer registry (F6):** extended with named strategy `subtract_box_torus` that recognizes the replay/CIR family and emits precise unsupported diagnostics.
+
+## Chosen F7 path
+
+**Path B (CIR intent only, no exact materializer yet).**
+
+- `subtract(box,torus)` is accepted as valid intent.
+- BRep-first subtract failure can fall-forward into `CirOnly`.
+- CIR analysis works on that state.
+- Rematerialization/export report explicit unsupported materializer strategy.
+
+## Diagnostics shape
+
+The system now differentiates:
+
+- replay/CIR family recognition success (`subtract_box_torus` selected), and
+- exact materialization unsupported (`materialization-unsupported`) with message:
+ - replay-guided pattern recognized
+ - exact torus subtract materializer not implemented.
+
+## Intentional non-generalization
+
+- No generic F-Rep→BRep extractor.
+- No broad torus boolean kernel expansion.
+- No public CLI behavior change.
+- No topology naming generation (SEM-A0 preserved).
+
+## Recommended F8
+
+Implement a narrowly-scoped **exact** `subtract_box_torus` materializer only if it can be grounded in existing safe analytic subtract infrastructure (or add a dedicated safe-family validator + constructor first). Keep registry diagnostics as the fallback contract.