rename absorb and add out-of-place version

Author: lkdvos

src/TensorKit.jl

@@ -76,7 +76,7 @@ export leftorth, rightorth, leftnull, rightnull,
        isposdef, isposdef!, ishermitian, sylvester, rank, cond
 export braid, braid!, permute, permute!, transpose, transpose!, twist, twist!, repartition,
        repartition!
-export catdomain, catcodomain, embed!
+export catdomain, catcodomain, absorb, absorb!
 
 export OrthogonalFactorizationAlgorithm, QR, QRpos, QL, QLpos, LQ, LQpos, RQ, RQpos,
        SVD, SDD, Polar

src/tensors/linalg.jl

@@ -513,9 +513,10 @@ function catcodomain(t1::TT, t2::TT) where {S,N₂,TT<:AbstractTensorMap{<:Any,S
 end
 
 """
-    embed!(tdst::AbstactTensorMap, tsrc::AbstractTensorMap)
+    absorb(tdst::AbstractTensorMap, tsrc::AbstractTensorMap)
+    absorb!(tdst::AbstactTensorMap, tsrc::AbstractTensorMap)
 
-Embed the contents of `tsrc` into `tdst`, which may have different sizes of data.
+Absorb the contents of `tsrc` into `tdst`, which may have different sizes of data.
 This is equivalent to the following operation on dense arrays, but also works for symmetric
 tensors. Note also that this only overwrites the regions that are shared, and will do
 nothing on the ones that are not, so it is up to the user to properly initialize the
@@ -526,7 +527,8 @@ sub_axes = map((x, y) -> 1:min(x, y), size(tdst), size(tsrc))
 tdst[sub_axes...] .= tsrc[sub_axes...]
 ```
 """
-function embed!(tdst::AbstractTensorMap, tsrc::AbstractTensorMap)
+absorb(tdst::AbstractTensorMap, tsrc::AbstractTensorMap) = absorb!(copy(tdst), tsrc)
+function absorb!(tdst::AbstractTensorMap, tsrc::AbstractTensorMap)
     numin(tdst) == numin(tsrc) && numout(tdst) == numout(tsrc) ||
         throw(DimensionError("Incompatible number of indices for source and destination"))
     S = spacetype(tdst)

test/tensors.jl

@@ -739,17 +739,26 @@ for V in spacelist
                 @test t ≈ t′
             end
         end
-        @timedtestset "Tensor embedding" begin
-            t1 = rand(V1 ⊕ V1, V2 ⊗ V3)
+        @timedtestset "Tensor absorpsion" begin
+            # absorbing small into large
+            t1 = zeros(V1 ⊕ V1, V2 ⊗ V3)
             t2 = rand(V1, V2 ⊗ V3)
-
-            # embedding small into large
-            t3 = @constinferred embed!(zerovector(t1), t2)
+            t3 = @constinferred absorb(t1, t2)
             @test norm(t3) ≈ norm(t2)
+            @test norm(t1) == 0
+            t4 = @constinferred absorb!(t1, t2)
+            @test t1 === t4
+            @test t3 ≈ t4
 
-            # embedding large into small
-            t4 = @constinferred embed!(zerovector(t2), t1)
-            @test norm(t4) < norm(t1)
+            # absorbing large into small
+            t1 = rand(V1 ⊕ V1, V2 ⊗ V3)
+            t2 = zeros(V1, V2 ⊗ V3)
+            t3 = @constinferred absorb(t2, t1)
+            @test norm(t3) < norm(t1)
+            @test norm(t2) == 0
+            t4 = @constinferred absorb!(t2, t1)
+            @test t2 === t4
+            @test t3 ≈ t4
         end
     end
     TensorKit.empty_globalcaches!()