Consolidate edge factorization API on add_edges / qr / qr!

docs/src/experimental_methods.md

@@ -4,15 +4,6 @@ Methods which still need to be discussed, modified, or deprecated.
 
 ## ITensorNetwork Methods
 
-* Combine (fuse) every link index of a tensor network, or a chosen set of edges, into
-  a single index per edge using `combiner` tensors. (`abstractitensornetwork.jl`).
-  Comment: it may be better to fold this into a more general interface `gauge_transform(f, tn::AbstractITensorNetwork)` that applies a gauge transformation $X\_e$ $X\_e^{-1}$ on each edge $e$.
-  ```julia
-  linkinds_combiners(tn::AbstractITensorNetwork; edges = edges(tn))
-  combine_linkinds(tn::AbstractITensorNetwork, combiners)
-  combine_linkinds(tn::AbstractITensorNetwork; edges = edges(tn))
-  ```
-
 * Extract the `IndsNetwork` of a tensor network — site indices per vertex and link
   indices per edge (`abstractitensornetwork.jl`):
   ```julia
@@ -62,10 +53,10 @@ Methods which still need to be discussed, modified, or deprecated.
   tree-traversal QRs; `orthogonalize` is the user-facing wrapper, with `tree_orthogonalize`
   as an alias (`treetensornetworks/abstracttreetensornetwork.jl`):
   ```julia
-  gauge(alg::Algorithm, ttn::AbstractTTN, region::Vector; kwargs...)
-  gauge(alg::Algorithm, ttn::AbstractTTN, region; kwargs...)
-  orthogonalize(ttn::AbstractTTN, region; kwargs...)
-  tree_orthogonalize(ttn::AbstractTTN, args...; kwargs...)
+  gauge(ttn::AbstractTTN, region::Vector)
+  gauge(ttn::AbstractTTN, region)
+  orthogonalize(ttn::AbstractTTN, region)
+  tree_orthogonalize(ttn::AbstractTTN, args...)
   ```
 
 * Sweep-based truncation. The whole-TTN form orthogonalizes towards `src(e)` before
@@ -224,12 +215,6 @@ Methods which still need to be discussed, modified, or deprecated.
   union_all_inds(is_in::AbstractIndsNetwork...)
   ```
 
-* Insert a default link index on every edge of `indsnetwork` that doesn't already
-  have one — `link_space` controls the default bond dimension (`abstractindsnetwork.jl`):
-  ```julia
-  insert_linkinds(indsnetwork::AbstractIndsNetwork, edges = edges(indsnetwork); link_space = trivial_space(indsnetwork))
-  ```
-
 #### IndsNetwork
 
 * Type-parameter accessors and graph-type metadata (`indsnetwork.jl`):

docs/src/interface_methods.md

@@ -48,21 +48,14 @@ These ITensorNetwork constructor interfaces are foundational to other constructo
   contract(tn::AbstractITensorNetwork, edge::Pair; kws...)
   ```
 
-* Factorize the bond on `edge` using the default factorization (`abstractitensornetwork.jl`):
-  ```julia
-  factorize(tn::AbstractITensorNetwork, edge::AbstractEdge; kws...)
-  factorize(tn::AbstractITensorNetwork, edge::Pair; kws...)
-  ```
-
-* QR-factorize across `edge`, placing the orthogonal factor on `src(edge)` and the remainder
-  on `dst(edge)` (`abstractitensornetwork.jl`):
-  ```julia
-  qr(tn::AbstractITensorNetwork, edge::AbstractEdge; kws...)
-  ```
-
-* SVD-factorize across `edge` (`abstractitensornetwork.jl`):
-  ```julia
-  svd(tn::AbstractITensorNetwork, edge::AbstractEdge; kws...)
+* QR-factorize across `edge`: keep the orthogonal factor on `src(edge)` and absorb
+  the residual into `tn[dst(edge)]`. Vertex set unchanged; the bond between
+  `src(edge)` and `dst(edge)` is re-gauged (`abstractitensornetwork.jl`):
+  ```julia
+  qr(tn::AbstractITensorNetwork, edge::AbstractEdge)
+  qr(tn::AbstractITensorNetwork, edge::Pair)
+  qr!(tn::AbstractITensorNetwork, edge::AbstractEdge)
+  qr!(tn::AbstractITensorNetwork, edge::Pair)
   ```
 
 * Truncate the bond on `edge` via SVD; forwards `cutoff`, `maxdim`, `mindim` kwargs (`abstractitensornetwork.jl`):

docs/src/tree_tensor_networks.md

@@ -68,25 +68,6 @@ ITensorNetworks.TreeTensorNetwork
 ITensorNetworks.ITensorNetwork(::ITensorNetworks.TreeTensorNetwork)
 ```
 
-### From a dense `ITensor`
-
-A dense tensor can be decomposed into a TTN by successive QR/SVD factorisations along the
-tree edges. Truncation parameters (e.g. `cutoff`, `maxdim`) are forwarded to the
-factorisation step.
-
-```@example main
-g_small = named_comb_tree((3, 1))
-sites_small = siteinds("S=1/2", g_small)
-A = ITensors.random_itensor(
-    only(sites_small[(1, 1)]), only(sites_small[(2, 1)]), only(sites_small[(3, 1)])
-)
-ttn_A = TreeTensorNetwork(A, sites_small)
-```
-
-```@docs; canonical=false
-ITensorNetworks.TreeTensorNetwork(::ITensors.ITensor, ::ITensorNetworks.IndsNetwork)
-```
-
 ## Orthogonal Gauge
 
 One of the most powerful features of tree tensor networks is the ability to bring the

src/abstractindsnetwork.jl

@@ -93,24 +93,3 @@ function union_all_inds(is_in::AbstractIndsNetwork...)
     end
     return is_out
 end
-
-function insert_linkinds(
-        indsnetwork::AbstractIndsNetwork,
-        edges = edges(indsnetwork);
-        link_space = trivial_space(indsnetwork)
-    )
-    indsnetwork = copy(indsnetwork)
-    for e in edges
-        # TODO: Change to check if it is empty.
-        if !isassigned(indsnetwork, e)
-            if !isnothing(link_space)
-                iₑ = Index(link_space, edge_tag(e))
-                # TODO: Allow setting with just `Index`.
-                indsnetwork[e] = [iₑ]
-            else
-                indsnetwork[e] = []
-            end
-        end
-    end
-    return indsnetwork
-end