Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 9 additions & 2 deletions initiatives/repository-modernisation/decisions/README.md
Original file line number Diff line number Diff line change
@@ -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 |
|---|---|---|---|
Expand All @@ -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

Expand All @@ -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.
5 changes: 4 additions & 1 deletion initiatives/repository-modernisation/proposal.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.