Add a twist! interface with a no-op default for non-graded arrays

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]

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

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

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,
             ]
         )

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