From 122a259665e59d05bc0bc0654d12412a2b9b6229 Mon Sep 17 00:00:00 2001 From: tomvanmele Date: Fri, 6 Nov 2026 12:50:56 +0100 Subject: [PATCH] Propose ShapeOp solver contract decisions --- ...shapeop-similarity-correspondence-flags.md | 110 ++++++++++++++++++ .../023-shapeop-point-buffer-lifecycle.md | 104 +++++++++++++++++ .../decisions/README.md | 11 +- .../repository-modernisation/proposal.md | 5 +- .../shapeop-modernisation-proposal.md | 40 +++++-- 5 files changed, 260 insertions(+), 10 deletions(-) create mode 100644 initiatives/repository-modernisation/decisions/022-shapeop-similarity-correspondence-flags.md create mode 100644 initiatives/repository-modernisation/decisions/023-shapeop-point-buffer-lifecycle.md diff --git a/initiatives/repository-modernisation/decisions/022-shapeop-similarity-correspondence-flags.md b/initiatives/repository-modernisation/decisions/022-shapeop-similarity-correspondence-flags.md new file mode 100644 index 0000000..e298d07 --- /dev/null +++ b/initiatives/repository-modernisation/decisions/022-shapeop-similarity-correspondence-flags.md @@ -0,0 +1,110 @@ +# ADR 022: ShapeOp Similarity Correspondence Flags + +**Status:** Proposed + +## Context + +`Solver.add_similarity_constraint(...)` and +`Solver.add_shape_constraint(...)` expose a Boolean named +`allow_translation`. Both wrappers pass it unchanged as the final Boolean to +ShapeOp's `SimilarityConstraint(indices, weight, positions, scaling, rotate, +flip)` constructor. + +The backend does not use this value to control translation. During projection, +ShapeOp always centers the input and target configurations before fitting them. +The final Boolean controls whether reversed vertex order is included among the +candidate correspondences. The backend implements this with its `flipMatrix_` +permutation. + +The neighboring `allow_rotation` Boolean also concerns correspondence rather +than a spatial transform: it enables cyclic permutations of the ordered +vertices. The existing Python documentation describing configurable +translation and spatial rotation is therefore false. + +ADR 019 requires ShapeOp modernization to preserve solver behavior unless a +separate public API decision is approved. Correcting these public names and +descriptions requires that decision. + +## Options + +1. **Preserve both existing names.** Correct their documentation so that + `allow_rotation` means cyclic rotation of correspondence order and + `allow_translation` means reversed order. This avoids keyword compatibility + breaks but leaves two names that appear to control spatial transformations. +2. **Rename both correspondence flags without aliases.** Replace + `allow_rotation` with `allow_cyclic_permutations` and + `allow_translation` with `allow_flip` consistently in both public methods, + the private native wrapper, and its stub. Preserve their positions, default + values, and native behavior. This introduces explicit keyword compatibility + breaks while giving each operation one accurate public name. +3. **Add the accurate names while retaining the old names as deprecated + aliases.** Define precedence or reject calls supplying both forms. This + temporarily preserves keyword calls but introduces overlapping names, + conflict handling, warnings, and compatibility paths without an approved + need. +4. **Rename only `allow_translation`.** This corrects the least defensible + name but knowingly retains `allow_rotation`, whose spatial interpretation + is also false. +5. **Implement actual spatial translation and rotation controls.** ShapeOp + currently removes translation unconditionally. This would change the + numerical algorithm rather than correct the wrapper contract and is outside + repository modernization. + +## Recommendation + +Choose option 2. + +Use this public correspondence contract on both +`add_similarity_constraint(...)` and `add_shape_constraint(...)`: + +- `allow_scaling` controls whether the fitted similarity may include scale; +- `allow_cyclic_permutations` controls whether cyclic shifts of ordered vertex + correspondence are considered; and +- `allow_flip` controls whether reversed vertex order, and its cyclic shifts + when `allow_cyclic_permutations=True`, are considered. + +Keep both correspondence defaults `True`, preserving the current positional +runtime behavior. Do not retain `allow_rotation` or `allow_translation` as +aliases. Spatial translation remains removed unconditionally and spatial +rotation remains part of the ordinary Umeyama fit; neither is presented as a +separately configurable operation. + +For `add_shape_constraint(...)`, these correspondence options apply only to +the `"similarity"` and `"custom"` paths. The `"regular_polygon"` path +continues to use its dedicated constraint and ignores them; this must be +documented rather than represented as configurable behavior. + +## Consequences + +Calls using the old keywords `allow_rotation=` or `allow_translation=` fail +and must migrate to `allow_cyclic_permutations=` or `allow_flip=` +respectively. Positional calls retain the same value ordering and numerical +behavior. Both defaults remain unchanged. + +The Python signatures, NumPy-style docstrings, C++ wrapper names and comments, +private `_shapeop.pyi`, typing fixtures, examples, and changelog all use the +same terminology. No compatibility alias or new numerical feature is added. + +## Verification + +- Inspect both public signatures and the packaged private stub to prove + `allow_cyclic_permutations` and `allow_flip` are present and the two old + names are absent. +- Add a strict Pyright fixture using both accurate keywords on both methods. +- Use an asymmetric custom target with cyclic correspondence disabled to prove + that `allow_flip=False` excludes reversed order and `allow_flip=True` + considers it. +- Verify cyclic permutations are excluded or considered according to + `allow_cyclic_permutations` using an asymmetric ordered target. +- Verify both defaults remain `True` and positional calls preserve existing + behavior. +- Verify translated copies remain translation-invariant independently of the + correspondence flags. +- Verify and document that the regular-polygon path does not consume the + correspondence flags. +- Run focused solver tests, Ruff, Pyright, strict MkDocs, installed-wheel + typing consumer, and wheel/sdist checks. + +## Dependencies + +ADR 019. diff --git a/initiatives/repository-modernisation/decisions/023-shapeop-point-buffer-lifecycle.md b/initiatives/repository-modernisation/decisions/023-shapeop-point-buffer-lifecycle.md new file mode 100644 index 0000000..b04577f --- /dev/null +++ b/initiatives/repository-modernisation/decisions/023-shapeop-point-buffer-lifecycle.md @@ -0,0 +1,104 @@ +# ADR 023: ShapeOp Point-Buffer Reassignment Lifecycle + +**Status:** Proposed + +## Context + +After `Solver.init()`, `Solver.points` is a writable NumPy view into the native +solver's Eigen point matrix. Constraints, forces, factorization state, and +that exported view are owned by or tied to the same native solver. + +Replacing the native wrapper while an exported array still references its +matrix can leave that array pointing at released memory. The modernization +candidate avoids this by storing every prior native wrapper in +`_retired_solvers`. Repeated reassignment therefore retains every prior point +matrix, constraint set, force set, and solver allocation until the Python +`Solver` is destroyed. + +No current requirement establishes repeated post-initialization reuse of one +solver object. Retaining an unbounded native history is not an acceptable +implicit ownership contract. + +## Options + +1. **Reject point reassignment after initialization.** Keep the initialized + point array writable in place. Require a new `Solver` or `MeshSolver` for a + different point set. +2. **Attach native ownership to each exported zero-copy array.** Rebuild the + wrapper on reassignment and arrange for every old array view to keep exactly + its originating native solver alive until the last dependent view is + collected. This preserves reassignment without permanent history but + requires a new native lifetime contract across NumPy base objects, slices, + and nanobind/Eigen return handling. +3. **Return owned copies instead of a native view.** Rebuilding becomes safe, + but in-place updates no longer affect the solver and an explicit + synchronization API would be required. +4. **Retain every previous native solver.** This preserves old exported views + but creates unbounded, invisible memory retention. + +## Recommendation + +Choose option 1. + +A solver accepts point assignment while it is uninitialized. A +pre-initialization reassignment starts a fresh configuration and clears +constraints and forces associated with the replaced point set. Once `init()` +succeeds, assignment to `solver.points` raises `RuntimeError` before conversion +or native mutation. + +The initialized array remains a live writable view. Updating coordinates +through `solver.points[...]` is supported and remains distinct from assigning a +new array to the property. The view is valid only while its owning `Solver` +remains alive; callers must copy it if the result must outlive the solver. A +caller that needs another point set creates a new solver instance. + +`MeshSolver` additionally binds its point rows to the mesh vertex-key mapping +established during construction. Before initialization, reassignment is +allowed only with exactly the same number of point rows; it replaces +coordinates without replacing mesh topology or the key-to-row mapping. A +different mesh or vertex count requires a new `MeshSolver`. + +Do not add a reset method, copied-buffer mode, ownership wrapper, or retained- +solver compatibility layer without a demonstrated use case and a separate +decision. + +## Consequences + +The `_retired_solvers` history is removed and each Python solver retains only +its current native solver. Merely retaining a NumPy view is not promised to +keep native storage alive; the existing copy-to-outlive rule remains part of +the public ownership contract. + +Code that assigns a new point array after initialization receives a clear +failure instead of an implicit reset. Its migration is to instantiate a new +solver. Code that updates the current native positions in place continues to +work without copying. + +`MeshSolver` follows the same post-initialization lifecycle and additionally +rejects a pre-initialization point count that differs from its bound mesh. + +## Verification + +- Initialize a solver, retain its point view, and verify that assigning another + point array raises `RuntimeError` with guidance to create a new solver. +- Verify the failed assignment is atomic: initialization state, native points, + constraints, forces, and the existing view remain unchanged. +- Verify in-place writes through the initialized point view still update the + native state used by `solve()`. +- Verify pre-initialization reassignment uses the latest points and begins a + fresh constraint/force configuration. +- Verify `MeshSolver` accepts pre-initialization coordinate replacement with + the same row count, preserves the vertex-key mapping, and rejects a different + row count atomically. +- Verify repeated rejected assignments do not retain native solvers or grow a + history collection. +- Retain an initialized view, copy it, destroy the owning solver, and verify + only the owned copy is documented and tested for use afterward. +- Update the public NumPy-style docstring, tutorial, examples, changelog, and + installed-wheel typing consumer. +- Run focused solver tests, Ruff, Pyright, strict MkDocs, artifact checks, and + memory/lifetime regression tests. + +## Dependencies + +ADR 019. diff --git a/initiatives/repository-modernisation/decisions/README.md b/initiatives/repository-modernisation/decisions/README.md index 9f284de..f711f4d 100644 --- a/initiatives/repository-modernisation/decisions/README.md +++ b/initiatives/repository-modernisation/decisions/README.md @@ -1,7 +1,9 @@ # Repository Modernisation Decisions -ADRs 001–021 are **Accepted**. All implementation remains subject to the -repository-setting, publishing, deployment, and merge approval boundaries. +ADRs 001–021 are **Accepted**. ShapeOp follow-up ADRs 022–023 are +**Proposed** and block only the corresponding public-contract changes. All +implementation remains subject to the repository-setting, publishing, +deployment, and merge approval boundaries. | ADR | Decision | Status | Depends on | |---|---|---|---| @@ -26,6 +28,8 @@ repository-setting, publishing, deployment, and merge approval boundaries. | [019](019-shapeop-distribution-and-quality-contract.md) | ShapeOp distribution and quality contract | Accepted | 002–006, 008, 010, 011, 013, 017, 018 | | [020](020-framework-host-extras.md) | `compas_framework` host extras during the COMPAS 3 transition | Accepted | 001, 002, 003, 009, 011, 013 | | [021](021-cross-repository-candidate-artifacts.md) | Cross-repository candidate artifact provenance | Accepted | 008, 010, 012, 013 | +| [022](022-shapeop-similarity-correspondence-flags.md) | ShapeOp similarity correspondence flags | Proposed | 019 | +| [023](023-shapeop-point-buffer-lifecycle.md) | ShapeOp point-buffer reassignment lifecycle | Proposed | 019 | ## Recommended review order @@ -50,3 +54,6 @@ repository-setting, publishing, deployment, and merge approval boundaries. 12. ADR 021: implement the accepted candidate-artifact provenance and credential boundary before enabling the native integration and release-order gate. +13. ADRs 022–023: decide the two newly exposed ShapeOp public contracts before + renaming the misleading correspondence flag or changing post-init point + reassignment. diff --git a/initiatives/repository-modernisation/proposal.md b/initiatives/repository-modernisation/proposal.md index 0658e22..84435a0 100644 --- a/initiatives/repository-modernisation/proposal.md +++ b/initiatives/repository-modernisation/proposal.md @@ -221,6 +221,8 @@ tasks that only sequence the documented direct commands. before its metadata and wheel matrix can be aligned. The approved package proposal and Accepted ADRs 017–019 are in [`shapeop-modernisation-proposal.md`](shapeop-modernisation-proposal.md). + Newly exposed public correspondence-flag and point-buffer lifecycle changes + remain blocked on Proposed ADRs 022–023. - `compas_gmsh` needs a meaningful test baseline and evidence-based support matrix before workflow modernization can make tests authoritative. The approved package proposal and Accepted ADRs 014–016 are in @@ -268,7 +270,8 @@ For each repository: ## Approval boundary Implementation may proceed only under Accepted ADRs. Gmsh ADRs 014–016 and -ShapeOp ADRs 017–019 authorize their scoped source work. +ShapeOp ADRs 017–019 authorize their scoped source work. Proposed ShapeOp ADRs +022–023 do not authorize the corresponding public-contract changes. Repository settings, trusted-publisher configuration, deployment, publishing, merging, and removal of active environment paths require explicit execution approval in their implementation phase. diff --git a/initiatives/repository-modernisation/shapeop-modernisation-proposal.md b/initiatives/repository-modernisation/shapeop-modernisation-proposal.md index c4e1a78..8782f9c 100644 --- a/initiatives/repository-modernisation/shapeop-modernisation-proposal.md +++ b/initiatives/repository-modernisation/shapeop-modernisation-proposal.md @@ -1,15 +1,24 @@ # `compas_shapeop` Modernisation Proposal -**Status:** Approved; source implementation is authorized by ADRs 017–019 +**Status:** Approved for ADRs 017–019; two follow-up contracts await ADRs +022–023 ## Purpose -Apply the approved native-wheel repository profile to `compas_shapeop` without -changing its solver API. The migration must first resolve the repository's +Apply the approved native-wheel repository profile to `compas_shapeop`. The +migration must first resolve the repository's Python/stable-ABI contradiction, make the native build reproducible and portable, and establish installed-artifact evidence strong enough to make its quality gates authoritative. +Implementation exposed two pre-existing public-contract defects that the +approved packaging work could not resolve without changing or constraining the +solver API: the `allow_translation` flag actually controls reversed +correspondence, and post-initialization point-buffer replacement has no bounded +safe ownership contract. Proposed ADRs 022–023 isolate those decisions; their +source changes remain blocked while all independent ADR 017–019 work may +continue. + This package proposal refines the accepted framework-wide decisions. It does not reopen the common uv, Ruff, MkDocs, workflow-security, or release-artifact policies. @@ -128,6 +137,18 @@ ADR 018 records this decision. ADR 019 records this decision. +### Follow-up public contracts + +- Proposed ADR 022 recommends replacing the misleading + `allow_rotation` and `allow_translation` keywords with the accurate + `allow_cyclic_permutations` and `allow_flip` correspondence flags on both + equivalent public constraint methods, without aliases. +- Proposed ADR 023 recommends rejecting assignment of a different point array + after solver initialization while preserving writable in-place updates of + the live native point view. + +Neither change is authorized until its ADR is explicitly accepted. + ## Alternatives and tradeoffs ### Build one wheel for every CPython minor @@ -175,7 +196,10 @@ useful, but installed-artifact tests are required for completion. temporary artifact directories, and one tested release artifact set. 7. Run an independent review and the full platform matrix. Record unavailable targets as unverified. -8. Push an initiative branch and open a draft PR only when authorized. Do not +8. After explicit ADR 022–023 approval, implement only the accepted flag and + point-buffer lifecycle contracts and their focused tests. Until then, leave + those source changes blocked. +9. Push an initiative branch and open a draft PR only when authorized. Do not merge or publish. ## Completion evidence @@ -202,6 +226,8 @@ The repository is not modernized until all applicable checks pass: ## Approval record ADRs 017–019 are accepted and authorize the bounded ShapeOp implementation -described above. This approval does not authorize merging, publishing, -repository-setting changes, or removal of a currently advertised platform -without evidence and explicit follow-up approval. +described above. ADRs 022–023 are Proposed and do not yet authorize the +correspondence-flag rename or post-initialization point-reassignment contract. +No approval authorizes merging, publishing, repository-setting changes, or +removal of a currently advertised platform without evidence and explicit +follow-up approval.