Skip to content

Rework the matricize, contract, and factorization surfaces - #233

Merged
mtfishman merged 33 commits into
mainfrom
develop
Sep 24, 2026
Merged

mtfishman merged 33 commits into
mainfrom
develop

Conversation

@mtfishman

@mtfishman mtfishman commented Sep 15, 2026 •

Copy link
Copy Markdown
Member

Summary

Gives each operation one primitive that backends overload, with the convenience spellings derived on top, reworks the algorithm selection interface, and trims the factorization surface. The factorization names MatrixAlgebraKit also exports are no longer exported, to keep the bare names unambiguous in a session using both, and the hooks that downstream packages actually overload are now declared public rather than being an undeclared interface.

mtfishman and others added 5 commits September 15, 2026 18:30
Accumulates the contract and matricize interface redesign. The version
stays at 0.21.0-DEV until the release PR strips the suffix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It had no callers outside its own forwarding method, and its behaviour is
covered by the in-place form. Also raises the subproject compat bounds the
round-opening bump missed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The argument maps the destination's dimension order to the matrix's; it is
not intrinsically an inverse, so invperm_ described one caller's derivation
rather than the parameter.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The two shapes are disjoint at the trailing argument, a Val split spec
against a pair of permutation tuples, so one name carries both and the
perm marker stops earning its place.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The entry points collect trailing keywords and forward them to the
resolver, whose methods declared none, so any unrecognized keyword
surfaced as a MethodError on an internal function.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Sep 15, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 85.18519% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.67%. Comparing base (31e5602) to head (166063a).

Files with missing lines Patch % Lines
src/matricize.jl 70.90% 16 Missing ⚠️
src/factorizations.jl 86.66% 4 Missing ⚠️
src/algorithm.jl 71.42% 2 Missing ⚠️
src/contract/contract.jl 95.45% 1 Missing ⚠️
src/projectto.jl 0.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #233      +/-   ##
==========================================
+ Coverage   79.64%   81.67%   +2.03%     
==========================================
  Files          28       29       +1     
  Lines        1056     1004      -52     
==========================================
- Hits          841      820      -21     
+ Misses        215      184      -31     
Flag Coverage Δ
docs 23.98% <49.33%> (+1.91%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

mtfishman and others added 8 commits September 15, 2026 19:28
Nothing passed `..`, and supporting it cost a dependency plus a
typed/untyped method tier whose only job was normalizing it. Names the
joint predicate `isbiperm` and routes the three duplicate validations
through `check_biperm`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A hook dispatches on the array or the style, never on the permutation, so
annotating it narrowed what a backend may pass without buying any dispatch.
Base leaves `permutedims`' perm untyped and validates at runtime.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Both callers had a bipermutation in hand and were splatting it to reach
`isidentityperm`, the same shape problem `isbiperm` fixed. Also drops the
Ellipsis spellings from the matricize tests, which the removed normalizing
tier supported.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A style now implements four bipermutation hooks, `allocate_output`,
`matricizeop!`, `matricizeopview` and `is_output_view`, and the copy and
maybe-alias forms are derived. Allocation is a hook because only the style
knows its fused axes, and because it is what makes the copy path terminate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`identitybiperm` now matches `isidentitybiperm` and sits beside it. The
symmetry sense of `trivial` is a different concept, so the two never apply
to the same object.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Also migrates five Val-forwarding calls in the factorization wrappers that
a literal-only search had missed, and the second custom style in the
factorization tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Matricizing without permuting is worth a short spelling. Removing `Val` as
a dispatch tier was what mattered: a style implements the bipermutation
hooks and never these, so the copy path cannot recurse through the router.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The gram factorizations were only used by higher-level network code, so they belong in the package that needs them. `sqrth_invsqrth_safe` only saves an eigendecomposition over calling the two separately.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mtfishman mtfishman changed the title [WIP] Redesign the contract and matricize interfaces for v0.21 [WIP] Rework the matricize, contract, and factorization surfaces for v0.21 Sep 16, 2026
mtfishman and others added 8 commits September 15, 2026 22:56
A graded array already gets owned storage out of `permutedimsop`, whose stored matrix is the answer, so decomposing the copy into an allocation plus an in-place write would copy that storage a second time.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The labels forms keep the plain names and the bipermutation forms take a `perm` marker, freeing `contract` to become variadic over operands. `allocate_contract_output` is gone in favor of overloading `allocate_output`, and a generic `select_algorithm` sits above the per-operation resolvers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It was the one rung of the labels ladder that was neither exported nor public, though it is as much a user-facing entry point as the rest.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A contraction algorithm does not choose how the output is allocated, so these two entry points were a second way to contract that bypassed `allocate_output`. The algorithm stays a keyword above the in-place primitive.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Belief-propagation simple update needs both square roots of the same
Hermitian matrix, and taking them from one eigendecomposition rather
than two is worth the extra name.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The `contract` example asserted a tuple of labels, but the surviving
labels come back as a `Vector`, which is what makes the return type
concrete. The `contractalign` description is cut to the contract it
actually has.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Loading TensorAlgebra alongside MatrixAlgebraKit made 21 bare
factorization names ambiguous, so those move from `export` to `public`.
The declaration now also covers the permute ladder and the rest of what
GradedArrays and ITensorBase overload.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Takes the prerelease suffix off so merging the release PR registers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mtfishman mtfishman changed the title [WIP] Rework the matricize, contract, and factorization surfaces for v0.21 Rework the matricize, contract, and factorization surfaces Sep 23, 2026
@mtfishman
mtfishman marked this pull request as ready for review September 23, 2026 15:34
mtfishman and others added 5 commits September 23, 2026 14:35
Replaces the contract-specific algorithm selection with a generic layer keyed on the operation, so other operations can register defaults the same way. The algorithm types are renamed after the operation they implement.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The value and type domains of `select_algorithm` and `default_algorithm` overlapped when an argument was itself a type. Packing the selection-relevant arguments into a tuple keeps `(Float64, Int)` and `Tuple{Float64, Int}` distinct.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Takes the codomain rank and the total instead of an array, which was only ever read for its `ndims`, matching the shape `bipartition` already uses. The factorization and matrix-function forwarders open-coded the same tuples and now call it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Gives the bipermutation tier the same argument-form naming as the labels tier, with `contractpermalign` for the destination-specifying form. Also drops the variadic forms over three or more operands and shortens `AbstractContractAlgorithm` to `ContractAlgorithm`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A type that stores a codomain/domain split can now report both ranks through one pair of accessors. Only `ndims_codomain` needs overloading, since `ndims_domain` is whatever rank is left over.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mtfishman and others added 7 commits September 24, 2026 10:41
`TensorAlgebra.one` bottomed out on `MatrixAlgebraKit.one!`, which a `TensorMap` has no method for, so the TensorKit extension worked around it one level up and `one!` on a `TensorMap` never worked at all. The matrix-level fill is now its own entry in `MatrixAlgebra` for a backend to overload, which also lets `one!!` go.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The arity check looked at the operand bipermutations, which are identical for a `{1,1}` destination and for one that groups both free legs on the same side, so a `{2,0}` destination got a `Diagonal` it cannot represent.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`one` built its result from `matricizeopcopy`, whose dense allocation flattens a `Diagonal` into a `Matrix`. Filling a permuted copy through `one!` instead costs the same single copy and keeps the structure. Nothing asserted the returned type, so the tests now do.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The labels entry points only ever hand down the canonical destination split, so the unevenly split and permuted destinations the `perm` signatures accept had no coverage. That is where the `Diagonal` allocation bug lived.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`matricize` with `conj` threw a `SpaceMismatch` on every `TensorMap`. The destination was allocated over the permuted space rather than the conjugated one, and TensorKit conjugates by adjointing its source, so the two never lined up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`public` accepts a name that resolves to nothing, and the expected-name list is maintained alongside the declaration, so a typo gets edited into both and the set comparison still passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mtfishman
mtfishman merged commit efca686 into main Sep 24, 2026
21 checks passed
@mtfishman
mtfishman deleted the develop branch September 24, 2026 23:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant