From 683ece4d3c08db34d6fee0852275c0ff04f1e0fb Mon Sep 17 00:00:00 2001 From: AJ Isaacs Date: Tue, 17 Nov 2026 22:09:20 -0500 Subject: [PATCH] perf(engine): run pair grid overlap checks only where the ranking needs them FillLinear.FillDeferred returns a grid whose final overlap check has not run; Resolve runs it and returns exactly what Fill returns, and Fill is FillDeferred(...).Resolve(). PairFiller sorts a candidate's grids with CompareByCount, which answers from the counts a pending grid can still have (its tiling or its bounding-box fallback) and runs the check only when they could order the pair differently; the early abort and the remnant pass resolve the grids they use. Every answer equals the checked comparison, so List.Sort makes the same moves, ties included, and layouts are bit-identical. A check that throws during the sort surfaces unwrapped. On the bracket fill this skips about 35% of the pair grids' final checks by work. Co-Authored-By: Claude Opus 5.5 --- OpenNest.Engine/Fill/FillLinear.cs | 145 ++++++++++--- OpenNest.Engine/Fill/PairFiller.cs | 92 ++++++++- OpenNest.Tests/Fill/DeferredGridCheckTests.cs | 195 ++++++++++++++++++ docs/performance/fill-verification.md | 6 + 4 files changed, 400 insertions(+), 38 deletions(-) create mode 100644 OpenNest.Tests/Fill/DeferredGridCheckTests.cs diff --git a/OpenNest.Engine/Fill/FillLinear.cs b/OpenNest.Engine/Fill/FillLinear.cs index 7d169e44..15e7b8c9 100644 --- a/OpenNest.Engine/Fill/FillLinear.cs +++ b/OpenNest.Engine/Fill/FillLinear.cs @@ -421,17 +421,35 @@ namespace OpenNest.Engine.Fill /// produces overlapping parts. /// private List TilePatternBbox(Pattern basePattern, NestDirection direction) + { + var copies = BboxCopies(basePattern, direction); + var copyDistance = GetDimension(basePattern.BoundingBox, direction) + PartSpacing; + var result = new List(); + + for (var count = 1; count <= copies; count++) + { + var offset = MakeOffset(direction, copyDistance * count); + + foreach (var part in basePattern.Parts) + result.Add(part.CloneAtOffset(offset)); + } + + return result; + } + + /// + /// The number of whole copies adds, found without cloning. + /// + private int BboxCopies(Pattern basePattern, NestDirection direction) { var copyDistance = GetDimension(basePattern.BoundingBox, direction) + PartSpacing; if (copyDistance <= 0) - return new List(); + return 0; var dim = GetDimension(basePattern.BoundingBox, direction); var start = GetStart(basePattern.BoundingBox, direction); var limit = GetLimit(direction); - - var result = new List(); var count = 1; while (true) @@ -441,15 +459,10 @@ namespace OpenNest.Engine.Fill if (nextPos + dim > limit + Tolerance.Epsilon) break; - var offset = MakeOffset(direction, copyDistance * count); - - foreach (var part in basePattern.Parts) - result.Add(part.CloneAtOffset(offset)); - count++; } - return result; + return count - 1; } private static bool HasOverlappingParts( @@ -521,7 +534,11 @@ namespace OpenNest.Engine.Fill /// a row, then tiling that row along the perpendicular axis to form a grid. /// After the grid is formed, fills the remaining strip with individual parts. /// - private List FillGrid(Pattern pattern, NestDirection direction, OffsetPerimeterCache cache) + /// + /// Step 1's check runs here, as it decides how the grid is built. The final check, on the + /// whole grid, is left to the returned grid's . + /// + private DeferredGrid FillGrid(Pattern pattern, NestDirection direction, OffsetPerimeterCache cache) { var perpAxis = PerpendicularAxis(direction); @@ -547,21 +564,16 @@ namespace OpenNest.Engine.Fill { row = Tile(pattern, perpAxis, cache, MaxParts); - if (pattern.Parts.Count > 1 && HasOverlappingParts(row, out var a2, out var b2)) - { - LogOverlap("Step1-PerpOnly", perpAxis, pattern, row, a2, b2); - row = new List(pattern.Parts); - row.AddRange(TilePatternBbox(pattern, perpAxis)); - } - - return row; + return pattern.Parts.Count > 1 + ? new DeferredGrid(this, row, "Step1-PerpOnly", perpAxis, pattern) + : new DeferredGrid(row); } // A capped fill whose first row already holds enough parts needs no more rows. // Step 2's check could only switch perpendicular tiling to the bbox fallback; it // never repairs the row itself, so returning the row loses no protection. if (MaxParts > 0 && row.Count >= MaxParts) - return row; + return new DeferredGrid(row); // Step 2: Build row pattern and tile along perpendicular axis var rowPattern = new Pattern(); @@ -573,15 +585,83 @@ namespace OpenNest.Engine.Fill // Only the unchanged row is covered by Step 1's clean verdict: skip Step 2 // only when the perpendicular tiling appended zero parts, so gridResult // still contains the same Part objects, in the same order and poses. - if ((!rowIsVerified || gridResult.Count != row.Count) - && HasOverlappingParts(gridResult, out var a3, out var b3)) + return !rowIsVerified || gridResult.Count != row.Count + ? new DeferredGrid(this, gridResult, "Step2-Perp", perpAxis, rowPattern) + : new DeferredGrid(gridResult); + } + + /// + /// A grid tiled by whose final overlap check may not have run yet. + /// Until runs it, the grid holds either its tiling, when no two + /// parts overlap, or the fallback that tiles the same pattern by bounding boxes + /// (); both part counts are known without the check. + /// returns exactly what the eager fill returned, so a caller may + /// skip the check only on a grid whose outcome it never uses. Not thread-safe. + /// + internal sealed class DeferredGrid + { + private readonly FillLinear owner; + private readonly string step; + private readonly NestDirection axis; + private Pattern basePattern; + private List parts; + private int? fallbackCount; + + /// A grid with no check left to run. + internal DeferredGrid(List parts) => this.parts = parts; + + /// + /// A grid whose tiling of along + /// still has to pass the overlap check. + /// + internal DeferredGrid( + FillLinear owner, + List parts, + string step, + NestDirection axis, + Pattern basePattern + ) { - LogOverlap("Step2-Perp", perpAxis, rowPattern, gridResult, a3, b3); - gridResult = new List(rowPattern.Parts); - gridResult.AddRange(TilePatternBbox(rowPattern, perpAxis)); + this.owner = owner; + this.parts = parts; + this.step = step; + this.axis = axis; + this.basePattern = basePattern; } - return gridResult; + /// True until has run the overlap check. + public bool IsPending => basePattern != null; + + /// + /// The part count of the grid as it stands: its tiling while the check is pending, the + /// checked parts once resolved. + /// + public int Count => parts.Count; + + /// + /// While , the part count of the bounding-box fallback, should + /// the check fail. + /// + public int FallbackCount => + fallbackCount ??= (1 + owner.BboxCopies(basePattern, axis)) * basePattern.Parts.Count; + + /// Runs the overlap check if it is pending and returns the grid's parts. + public List Resolve() + { + if (basePattern == null) + return parts; + + if (HasOverlappingParts(parts, out var a, out var b)) + { + owner.LogOverlap(step, axis, basePattern, parts, a, b); + var fallback = new List(basePattern.Parts); + fallback.AddRange(owner.TilePatternBbox(basePattern, axis)); + parts = fallback; + } + + basePattern = null; + return parts; + } } private void LogOverlap( @@ -672,11 +752,18 @@ namespace OpenNest.Engine.Fill /// /// Fills the work area by tiling a pre-built pattern along both axes. /// - public List Fill(Pattern pattern, NestDirection primaryAxis) + public List Fill(Pattern pattern, NestDirection primaryAxis) => + FillDeferred(pattern, primaryAxis).Resolve(); + + /// + /// with the grid's final overlap check left to + /// the caller: returns exactly what Fill returns. + /// + internal DeferredGrid FillDeferred(Pattern pattern, NestDirection primaryAxis) { var cache = new OffsetPerimeterCache(HalfSpacing); if (pattern.Parts.Count == 0) - return new List(); + return new DeferredGrid(new List()); var offset = WorkArea.Location - pattern.BoundingBox.Location; var basePattern = pattern.Clone(offset); @@ -685,7 +772,7 @@ namespace OpenNest.Engine.Fill basePattern.BoundingBox.Width > WorkArea.Width + Tolerance.Epsilon || basePattern.BoundingBox.Length > WorkArea.Length + Tolerance.Epsilon ) - return new List(); + return new DeferredGrid(new List()); return FillGrid(basePattern, primaryAxis, cache); } @@ -702,7 +789,7 @@ namespace OpenNest.Engine.Fill if (seed.Parts.Count == 0) return new List(); - return FillGrid(seed, primaryAxis, cache); + return FillGrid(seed, primaryAxis, cache).Resolve(); } } } diff --git a/OpenNest.Engine/Fill/PairFiller.cs b/OpenNest.Engine/Fill/PairFiller.cs index 5f88576f..ae14d01b 100644 --- a/OpenNest.Engine/Fill/PairFiller.cs +++ b/OpenNest.Engine/Fill/PairFiller.cs @@ -2,6 +2,7 @@ using System; using System.Collections.Generic; using System.Diagnostics; using System.Linq; +using System.Runtime.ExceptionServices; using System.Threading; using System.Threading.Tasks; using OpenNest.Engine; @@ -554,30 +555,34 @@ namespace OpenNest.Engine.Fill CancellationToken token ) { - // Phase 1: evaluate all grids (fast) - var grids = new List<(List Parts, NestDirection Dir)>(); + // Phase 1: tile all grids (fast). Each grid's final overlap check, the bulk of the + // work, waits until the ranking or Phase 2 needs its outcome (see CompareByCount). + var grids = new List(); var engine = new FillLinear(workArea, partSpacing) { Label = "Pairs" }; foreach (var (pattern, dir) in claimed) { token.ThrowIfCancellationRequested(); - var gridParts = engine.Fill(pattern, dir); - if (gridParts != null && gridParts.Count > 0) - grids.Add((gridParts, dir)); + var grid = engine.FillDeferred(pattern, dir); + if (grid.IsPending && (grid.Count == 0 || grid.FallbackCount == 0)) + grid.Resolve(); + if (grid.IsPending || grid.Count > 0) + grids.Add(grid); } if (grids.Count == 0) return null; // Sort by count descending so we try the best grids first - grids.Sort((a, b) => b.Parts.Count.CompareTo(a.Parts.Count)); + SortByCount(grids); // Early abort: if the best grid + optimistic remnant can't beat the global best, skip Phase 2 if (minCountToBeat > 0) { - var topCount = grids[0].Parts.Count; + var topParts = grids[0].Resolve(); + var topCount = topParts.Count; var optimisticRemnant = remnantFiller.EstimateUpperBound( - grids[0].Parts, + topParts, workArea, maxUtilization, partArea @@ -594,10 +599,12 @@ namespace OpenNest.Engine.Fill // Phase 2: try remnant for each grid, skip if grid is too far behind List best = null; - foreach (var (gridParts, dir) in grids) + foreach (var grid in grids) { token.ThrowIfCancellationRequested(); + var gridParts = grid.Resolve(); + // If this grid + max possible remnant can't beat current best, skip if (best != null) { @@ -631,6 +638,73 @@ namespace OpenNest.Engine.Fill return best; } + /// + /// Sorts grids with . A check that throws during the sort + /// surfaces as itself, as it did when every grid was checked before sorting, rather than + /// wrapped by . + /// + internal static void SortByCount(List grids) + { + ExceptionDispatchInfo failure = null; + grids.Sort((a, b) => + { + if (failure != null) + return 0; + + try + { + return CompareByCount(a, b); + } + catch (Exception ex) + { + failure = ExceptionDispatchInfo.Capture(ex); + return 0; + } + }); + failure?.Throw(); + } + + /// + /// Orders grids by part count, descending, as b.Count.CompareTo(a.Count) on their + /// checked parts. A grid whose check is pending may keep its tiling or fall back to its + /// bounding-box tiling; when those counts could order the pair differently, the check + /// runs. Every answer is the one the checked counts give, so the sort makes the same + /// moves, ties included, as on grids checked up front, and the checks it skips are of + /// grids it never needed to tell apart. + /// + internal static int CompareByCount(FillLinear.DeferredGrid a, FillLinear.DeferredGrid b) + { + if (ReferenceEquals(a, b)) + return 0; + + while (true) + { + if (TryCompareByCount(a, b, out var order)) + return order; + + if (a.IsPending) + a.Resolve(); + else + b.Resolve(); + } + } + + /// + /// The order of and when every count either + /// grid can still have gives the same one. + /// + private static bool TryCompareByCount( + FillLinear.DeferredGrid a, + FillLinear.DeferredGrid b, + out int order + ) + { + order = b.Count.CompareTo(a.Count); + return (!a.IsPending || b.Count.CompareTo(a.FallbackCount) == order) + && (!b.IsPending || b.FallbackCount.CompareTo(a.Count) == order) + && (!a.IsPending || !b.IsPending || b.FallbackCount.CompareTo(a.FallbackCount) == order); + } + /// /// The BuildTilingAngles /// diff --git a/OpenNest.Tests/Fill/DeferredGridCheckTests.cs b/OpenNest.Tests/Fill/DeferredGridCheckTests.cs new file mode 100644 index 00000000..69783385 --- /dev/null +++ b/OpenNest.Tests/Fill/DeferredGridCheckTests.cs @@ -0,0 +1,195 @@ +using OpenNest.Engine; +using OpenNest.Engine.BestFit; +using OpenNest.Engine.Fill; +using OpenNest.Engine.Strategies; +using OpenNest.Geometry; +using OpenNest.Tests.BestFit; + +namespace OpenNest.Tests.Fill; + +/// +/// The pair filler ranks grids before their final overlap checks run and checks only those it +/// needs (); the stripe filler reuses convergences +/// (). Both must leave every layout exactly as computing +/// everything up front would. +/// +[Collection(nameof(FillCacheCollection))] +public class DeferredGridCheckTests +{ + private const double Spacing = 0.5; + + [Fact] + public void Resolve_ReturnsExactlyWhatFillReturns() + { + foreach (var (area, pattern, direction) in GridCases()) + { + var expected = new FillLinear(area, Spacing).Fill(pattern, direction); + var actual = new FillLinear(area, Spacing).FillDeferred(pattern, direction).Resolve(); + Assert.Equal(Poses(expected), Poses(actual)); + } + } + + [Fact] + public void CompareByCount_SortsLikeCheckedCounts_AndSkipsChecks() + { + var cases = GridCases(); + var expectedFallbacks = 0; + var skipped = 0; + + for (var seed = 0; seed < 25; seed++) + { + var order = Enumerable.Range(0, cases.Count).ToList(); + var random = new Random(seed); + for (var i = order.Count - 1; i > 0; i--) + { + var j = random.Next(i + 1); + (order[i], order[j]) = (order[j], order[i]); + } + + var eager = order + .Select(index => + { + var (area, pattern, direction) = cases[index]; + return (Index: index, Parts: new FillLinear(area, Spacing).Fill(pattern, direction)); + }) + .ToList(); + eager.Sort((a, b) => b.Parts.Count.CompareTo(a.Parts.Count)); + + var indexOf = new Dictionary(ReferenceEqualityComparer.Instance); + var lazy = new List(); + foreach (var index in order) + { + var (area, pattern, direction) = cases[index]; + var grid = new FillLinear(area, Spacing).FillDeferred(pattern, direction); + if (grid.IsPending && grid.Count != grid.FallbackCount) + { + var tiled = grid.Count; + var checkedCount = new FillLinear(area, Spacing).Fill(pattern, direction).Count; + if (checkedCount != tiled) + expectedFallbacks++; + } + indexOf.Add(grid, index); + lazy.Add(grid); + } + PairFiller.SortByCount(lazy); + + Assert.Equal(eager.Select(e => e.Index), lazy.Select(g => indexOf[g])); + skipped += lazy.Count(g => g.IsPending); + + for (var k = 0; k < lazy.Count; k++) + Assert.Equal(Poses(eager[k].Parts), Poses(lazy[k].Resolve())); + } + + // The fixture holds grids whose check fails and changes their count, and the ranking + // left some checks unrun. + Assert.True(expectedFallbacks > 0); + Assert.True(skipped > 0); + } + + [Fact] + public void StripeConvergenceCache_HitsReproduceTheConvergedLayouts() + { + var drawing = TestHelpers.MakeLShapeDrawing(); + var bestFits = new List + { + MakePair(drawing, 0, new Vector(10.5, 0)), + MakePair(drawing, System.Math.PI, new Vector(10.5, 10)), + }; + + List Run(StripeConvergenceCache cache, NestDirection axis, int maxQuantity) + { + var context = new FillContext + { + Item = new NestItem { Drawing = drawing, Quantity = maxQuantity }, + WorkArea = new Box(0, 0, 97.5, 47.25), + Plate = new Plate(47.25, 97.5) { PartSpacing = Spacing }, + MaxQuantity = maxQuantity, + }; + context.SharedState["BestFits"] = bestFits; + if (cache != null) + context.SharedState[StripeConvergenceCache.SharedStateKey] = cache; + return new StripeFiller(context, axis) { CompleteStripesOnly = true }.Fill(); + } + + foreach (var maxQuantity in new[] { 0, 30 }) + { + foreach (var axis in new[] { NestDirection.Horizontal, NestDirection.Vertical }) + { + var cold = Run(null, axis, maxQuantity); + var cache = new StripeConvergenceCache(); + var filling = Run(cache, axis, maxQuantity); + var entries = cache.Count; + var warm = Run(cache, axis, maxQuantity); + + Assert.NotEmpty(cold); + Assert.True(entries > 0); + Assert.Equal(entries, cache.Count); + Assert.Equal(Poses(cold), Poses(filling)); + Assert.Equal(Poses(cold), Poses(warm)); + } + } + } + + /// + /// Grids across work areas, both directions and three patterns: a single concave part, a + /// valid pair of it, and a pair of overlapping copies whose checks fail. At widths 16.75 and + /// 25.75 the overlapping pair's fallback holds fewer and more parts than its tiling. + /// + private static List<(Box Area, Pattern Pattern, NestDirection Direction)> GridCases() + { + var concave = FillExtentsTests.MakeFixture("concave"); + var single = new Pattern(); + single.Parts.Add(Part.CreateAtOrigin(concave)); + single.UpdateBounds(); + + var first = Part.CreateAtOrigin(concave); + var second = Part.CreateAtOrigin(concave, System.Math.PI); + second.Offset(new Vector(10.5, 0)); + var pair = new Pattern(); + pair.Parts.AddRange(new[] { first, second }); + pair.UpdateBounds(); + + var overlapping = new Pattern(); + overlapping.Parts.AddRange(new[] { first, first.CloneAtOffset(new Vector(0.25, 0.25)) }); + overlapping.UpdateBounds(); + Assert.True(FillHelpers.HasOverlappingParts(overlapping.Parts)); + + var cases = new List<(Box, Pattern, NestDirection)>(); + foreach (var length in new[] { 21.0, 30.0, 40.0 }) + foreach (var width in new[] { 12.0, 16.75, 25.75 }) + foreach (var pattern in new[] { single, pair, overlapping }) + foreach (var direction in new[] { NestDirection.Horizontal, NestDirection.Vertical }) + cases.Add((new Box(0, 0, length, width), pattern, direction)); + return cases; + } + + private static BestFitResult MakePair(Drawing drawing, double rotation, Vector offset) + { + var bounds = drawing.Program.BoundingBox(); + return new BestFitResult + { + Candidate = new PairCandidate + { + Drawing = drawing, + Part2Rotation = rotation, + Part2Offset = offset, + Spacing = Spacing, + }, + BoundingWidth = bounds.Length + offset.X, + BoundingHeight = bounds.Width + offset.Y, + OptimalRotation = 0, + Keep = true, + Reason = "Valid", + HullAngles = new List(), + }; + } + + private static List<(long X, long Y, long Rotation)> Poses(List parts) => + parts + .Select(p => ( + BitConverter.DoubleToInt64Bits(p.Location.X), + BitConverter.DoubleToInt64Bits(p.Location.Y), + BitConverter.DoubleToInt64Bits(p.Rotation) + )) + .ToList(); +} diff --git a/docs/performance/fill-verification.md b/docs/performance/fill-verification.md index e1cc381f..81e2ac8e 100644 --- a/docs/performance/fill-verification.md +++ b/docs/performance/fill-verification.md @@ -74,6 +74,12 @@ Predictor availability uses the same one-attempt session initialization as infer Whole-job before/after comparisons use `OpenNest.Benchmark` with a `*.manifest.json` corpus and `--parallel 1`. Retain input hashes, exact commands, raw results, validity, fulfillment and cost for both revisions outside source control. Record baseline failures rather than treating them as regressions or tuning the corpus around them; overlapping timing ranges are inconclusive, not proof of unchanged performance. +### Deferred grid checks and stripe convergence reuse + +Both leave every layout bit-identical; they only skip work whose outcome is never used or already known. `FillLinear.FillDeferred` returns a `DeferredGrid` whose final overlap check (Step 2, or the perpendicular-only row) has not run; `Resolve` runs it, and `Fill` is `FillDeferred(...).Resolve()`, so eager callers do the same work as before. Step 1's check stays eager because it decides how the grid is built. While pending, a grid's count is either its tiling's or its bounding-box fallback's (`FallbackCount`, which can be lower or higher). `PairFiller.EvaluateCandidate` sorts with `CompareByCount`, which answers each comparison from those counts and runs a check only when they could order the pair differently; the early abort and Phase 2 resolve the grids they use. Every answer equals the checked comparison, so `List.Sort` (unstable) makes the same moves, ties included. Other `FillLinear` callers stay eager: a stripe trajectory feeds every row's verdict into its next angle, and the Linear, remnant and pattern sweeps rank with a pluggable `IFillComparer` that offers no count bound. + +`StripeConvergenceCache` lives in the pipeline's `FillContext.SharedState` and reaches pair remnant strips through `PairFiller`. It keeps each stripe convergence by pair, drawing, axis, variant, span, spacing and row cap, the pair's turned bounds by angle, and each estimate row by angle (one thread tiles a row while others wait). Row and Column converge identical layouts, remnant strips along a full side repeat spans, and trajectories revisit angles; each value is a pure function of its key. `DeferredGridCheckTests` holds both to the eager results. + ## Entity identity and hot-test configuration Use `-c Release` for routine cross-platform test runs, matching CI. Continue running counter-based regressions explicitly in Debug; do not treat fewer Release test cases as lost coverage without checking the DEBUG-only methods and individual skipped outcomes.