Complete the single-index set-operation helpers

Project.toml

@@ -1,6 +1,6 @@
 name = "ITensorBase"
 uuid = "4795dd04-0d67-49bb-8f44-b89c448a1dc7"
-version = "0.12.1"
+version = "0.12.2"
 authors = ["ITensor developers <support@itensor.org> and contributors"]
 
 [workspace]

src/ITensorBase.jl

@@ -3,8 +3,10 @@ module ITensorBase
 export AbstractNamedTensor, NamedTensor, AbstractITensor, ITensor, Index,
     NamedUnitRange, aligndims, aligneddims, apply, codomainnames, commonind, commoninds,
     dimnames, dimnametype, domainnames, hascommoninds, id, inds, mapinds, named, nameddims,
-    noncommoninds, noprime, operator, prime, replaceinds, sim, similar_operator, state,
-    trycommonind, trynoncommonind, uniqueind, uniqueinds, unioninds, uniquename
+    noncommonind, noncommoninds, noprime, operator, prime, replaceinds, sim,
+    similar_operator, state,
+    trycommonind, trynoncommonind, tryuniqueind, uniqueind, uniqueinds, unioninds,
+    uniquename
 if VERSION >= v"1.11.0-DEV.469"
     eval(
         Meta.parse(

src/abstractnamedtensor.jl

@@ -738,7 +738,7 @@ commonind(a::AbstractNamedTensor, b::AbstractNamedTensor) = only(commoninds(a, b
     uniqueind(a::AbstractNamedTensor, b::AbstractNamedTensor)
 
 The single index of `a` that does not appear by name in `b`. Errors unless there is exactly
-one such index. Use [`trynoncommonind`](@ref) to get `nothing` instead of an error.
+one such index. Use [`tryuniqueind`](@ref) to get `nothing` instead of an error.
 
 # Examples
 
@@ -755,6 +755,28 @@ See also [`uniqueinds`](@ref), [`commonind`](@ref).
 """
 uniqueind(a::AbstractNamedTensor, b::AbstractNamedTensor) = only(uniqueinds(a, b))
 
+"""
+    noncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
+
+The single index not shared by name between `a` and `b` (the symmetric difference). Errors
+unless there is exactly one such index. Use [`trynoncommonind`](@ref) to get `nothing` instead
+of an error.
+
+# Examples
+
+```jldoctest
+julia> i, j, k = Index.((2, 3, 2));
+
+julia> a, b = randn(i, j), randn(i, j, k);
+
+julia> noncommonind(a, b) == k
+true
+```
+
+See also [`noncommoninds`](@ref), [`uniqueind`](@ref).
+"""
+noncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor) = only(noncommoninds(a, b))
+
 """
     trycommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
 
@@ -781,7 +803,7 @@ function trycommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
 end
 
 """
-    trynoncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
+    tryuniqueind(a::AbstractNamedTensor, b::AbstractNamedTensor)
 
 The single index of `a` that does not appear by name in `b`, or `nothing` if there is no such
 index or more than one. The non-erroring counterpart of [`uniqueind`](@ref).
@@ -793,15 +815,41 @@ julia> i, j, k = Index.((2, 3, 2));
 
 julia> a, b = randn(i, j), randn(j, k);
 
-julia> trynoncommonind(a, b) == i
+julia> tryuniqueind(a, b) == i
 true
 ```
 """
-function trynoncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
+function tryuniqueind(a::AbstractNamedTensor, b::AbstractNamedTensor)
     us = uniqueinds(a, b)
     return length(us) == 1 ? only(us) : nothing
 end
 
+"""
+    trynoncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
+
+The single index not shared by name between `a` and `b` (the symmetric difference), or
+`nothing` if there is no such index or more than one. The non-erroring counterpart of
+[`noncommonind`](@ref).
+
+# Examples
+
+```jldoctest
+julia> i, j, k = Index.((2, 3, 2));
+
+julia> a, b = randn(i, j), randn(i, j, k);
+
+julia> trynoncommonind(a, b) == k
+true
+
+julia> isnothing(trynoncommonind(randn(i, j), randn(j, k)))
+true
+```
+"""
+function trynoncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)
+    ncs = noncommoninds(a, b)
+    return length(ncs) == 1 ? only(ncs) : nothing
+end
+
 # `Base.isempty(a::AbstractArray)` is defined as `length(a) == 0`,
 # which involves comparing a named integer to an unnamed integer
 # which isn't well defined.

test/test_basics.jl

@@ -1,8 +1,8 @@
 using ITensorBase: ITensorBase, AbstractNamedTensor, ITensor, Index, IndexName, NamedTensor,
     commonind, commoninds, dimnametype, gettag, hascommoninds, hastag, id, inds, mapinds,
-    name, named, noncommoninds, noprime, plev, prime, replaceinds, setplev, settag, sim,
-    tags, trycommonind, trynoncommonind, unioninds, uniqueind, uniqueinds, uniquename,
-    unname, unnamed, unsettag, uuid
+    name, named, noncommonind, noncommoninds, noprime, plev, prime, replaceinds, setplev,
+    settag, sim, tags, trycommonind, trynoncommonind, tryuniqueind, unioninds, uniqueind,
+    uniqueinds, uniquename, unname, unnamed, unsettag, uuid
 using Test: @test, @test_broken, @test_throws, @testset
 using UUIDs: UUID
 
@@ -250,7 +250,12 @@ using UUIDs: UUID
         @test name(commonind(a, b)) == name(j)
         @test name(uniqueind(a, b)) == name(i)
         @test name(trycommonind(a, b)) == name(j)
-        @test name(trynoncommonind(a, b)) == name(i)
+        @test name(tryuniqueind(a, b)) == name(i)
+
+        # The symmetric-difference single: the one index not shared across both tensors.
+        e = randn(elt, i, j, k)
+        @test name(noncommonind(a, e)) == name(k)
+        @test name(trynoncommonind(a, e)) == name(k)
 
         # No shared index.
         c = randn(elt, k)
@@ -265,6 +270,13 @@ using UUIDs: UUID
         @test isnothing(trycommonind(a, d))
         @test_throws ArgumentError commonind(a, c)
         @test_throws ArgumentError uniqueind(a, c)
-        @test isnothing(trynoncommonind(a, c))
+        @test isnothing(tryuniqueind(a, c))
+
+        # `noncommonind` errors / `trynoncommonind` is `nothing` unless there is exactly one
+        # non-shared index: two here (symdiff is `[i, k]`), zero for identical index sets.
+        @test_throws ArgumentError noncommonind(a, b)
+        @test isnothing(trynoncommonind(a, b))
+        @test_throws ArgumentError noncommonind(a, d)
+        @test isnothing(trynoncommonind(a, d))
     end
 end

test/test_exports.jl

@@ -6,10 +6,11 @@ using Test: @test, @testset
         :Index, :NamedUnitRange,
         :aligndims, :aligneddims, :apply, :codomainnames, :commonind, :commoninds,
         :dimnames, :dimnametype, :domainnames, :hascommoninds, :id,
-        :inds, :mapinds, :named, :nameddims, :noncommoninds, :noprime, :operator,
+        :inds, :mapinds, :named, :nameddims, :noncommonind, :noncommoninds, :noprime,
+        :operator,
         :prime,
         :replaceinds, :sim, :similar_operator, :state, :trycommonind, :trynoncommonind,
-        :uniqueind, :uniqueinds, :unioninds, :uniquename,
+        :tryuniqueind, :uniqueind, :uniqueinds, :unioninds, :uniquename,
     ]
     publics = [
         :IndexName, :name, :nametype, :replacedimnames, :setname, :space, :unnamed,