From 06ee3131290c6a3513bd8abda9e84e7de43841b9 Mon Sep 17 00:00:00 2001
From: Matthew Fishman <mfishman@flatironinstitute.org>
Date: Wed, 22 Jul 2026 17:31:21 -0400
Subject: [PATCH] Add a twist! interface with a no-op default for non-graded
 arrays

Adds twist!(a, dims) as a TensorAlgebra interface verb with a no-op AbstractArray default. A plain array has no sector data and no braiding, so twisting is the identity. Graded-array backends override the method to apply the sector twists of the given axes. This gives graded backends and named-tensor wrappers a shared twist! to extend, matching how the other array operations here are dispatched.
---
 Project.toml         |  2 +-
 src/TensorAlgebra.jl |  2 +-
 src/inplace.jl       |  9 +++++++++
 test/test_exports.jl |  2 +-
 test/test_inplace.jl | 11 +++++++++++
 5 files changed, 23 insertions(+), 3 deletions(-)
 create mode 100644 test/test_inplace.jl

diff --git a/Project.toml b/Project.toml
index 4f88083..d0c784f 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,6 +1,6 @@
 name = "TensorAlgebra"
 uuid = "68bd88dc-f39d-4e12-b2ca-f046b68fcc6a"
-version = "0.17.7"
+version = "0.17.8"
 authors = ["ITensor developers <support@itensor.org> and contributors"]
 
 [workspace]
diff --git a/src/TensorAlgebra.jl b/src/TensorAlgebra.jl
index ef3e19e..04d3ebf 100644
--- a/src/TensorAlgebra.jl
+++ b/src/TensorAlgebra.jl
@@ -9,7 +9,7 @@ export contract, contract!, eig_full, eig_trunc, eig_vals, eigh_full, eigh_trunc
 if VERSION >= v"1.11.0-DEV.469"
     eval(
         Meta.parse(
-            "public biperm, bipartition, cat_similar, concatenate, concatenate!, ContractAlgorithm, contractopadd!, data, datatype, directsum, flattenlinear, label_type, matricizeopperm, permutedims, permutedims!, scalar, similar_map, TensorOperationsAlgorithm, to_range, tr, tryflattenlinear, ungrade, zero!, scale!, permuteddims, PermutedDims"
+            "public biperm, bipartition, cat_similar, concatenate, concatenate!, ContractAlgorithm, contractopadd!, data, datatype, directsum, flattenlinear, label_type, matricizeopperm, permutedims, permutedims!, scalar, similar_map, TensorOperationsAlgorithm, to_range, tr, tryflattenlinear, ungrade, zero!, scale!, twist!, permuteddims, PermutedDims"
         )
     )
 end
diff --git a/src/inplace.jl b/src/inplace.jl
index 429bc73..fc567b1 100644
--- a/src/inplace.jl
+++ b/src/inplace.jl
@@ -11,3 +11,12 @@ zero!(a::AbstractArray) = (fill!(a, zero(eltype(a))); a)
 In-place scaling: multiply every entry of `a` by `β`.
 """
 scale!(a::AbstractArray, β::Number) = (a .*= β; a)
+
+"""
+    twist!(a::AbstractArray, dims) -> a
+
+In-place ribbon twist over the axes in `dims`. A plain array carries no sector data and has no
+braiding, so this is a no-op; graded-array backends override it to scale `a` by the product of
+the sector twists of those axes (`-1` for odd-parity fermionic charges, `+1` otherwise).
+"""
+twist!(a::AbstractArray, dims) = a
diff --git a/test/test_exports.jl b/test/test_exports.jl
index b45c40c..e84f8f6 100644
--- a/test/test_exports.jl
+++ b/test/test_exports.jl
@@ -44,7 +44,7 @@ using Test: @test, @testset
                 :flattenlinear, :label_type,
                 :matricizeopperm, :permutedims, :permutedims!, :scalar, :similar_map,
                 :TensorOperationsAlgorithm,
-                :to_range, :tr, :tryflattenlinear, :ungrade, :zero!, :scale!,
+                :to_range, :tr, :tryflattenlinear, :ungrade, :zero!, :scale!, :twist!,
                 :permuteddims, :PermutedDims,
             ]
         )
diff --git a/test/test_inplace.jl b/test/test_inplace.jl
new file mode 100644
index 0000000..837fc1e
--- /dev/null
+++ b/test/test_inplace.jl
@@ -0,0 +1,11 @@
+using LinearAlgebra: Diagonal
+using TensorAlgebra: twist!
+using Test: @test, @testset
+
+@testset "twist! is a no-op on non-graded arrays" begin
+    a = randn(2, 2)
+    @test twist!(copy(a), (1,)) == a
+    @test twist!(copy(a), (1, 2)) == a
+    d = Diagonal(randn(3))
+    @test twist!(copy(d), (1,)) == d
+end