[mtfishman]

Summary

Consolidate the edge-mutation and edge-factorization API surface of AbstractITensorNetwork around two primitives — add_edges (graph-edge + link-Index threading) and qr / qr! (absorbing-into-dst factorization) — and delete the legacy paths that used to do the same things in incompatible ways.

Edge-mutation / link-threading

• Delete insert_linkinds(::AbstractITensorNetwork, edges; link_space). Migrate add(tn1, tn2) and tebd initial-state setup to NamedGraphs.GraphsExtensions.add_edges(tn, edges).
• Strengthen add_edge! on AbstractITensorNetwork to fill in missing link inds when the graph edge already exists (and conversely add the graph edge when only a shared Index is present), so it's a single primitive that ensures both pieces. Return value follows the Graphs.add_edge! convention (true only when a new graph edge was added).
• Delete insert_linkinds(::AbstractIndsNetwork, edges; link_space). Its only caller — the dense-ITensor TTN constructor — is rewritten to build the vertex-tensor Dict directly during the post-order DFS instead of scaffolding a placeholder ITensorNetwork first; the scaffold's link inds (filled by insert_linkinds) never participated in the factorization and were overwritten immediately by tn[src(e)] = a_l.
• Move the two consumer sites that used to rely on set_vertex_data!'s fix_edges! auto-reconciliation — the tensors-only ITensorNetwork{V}(tensors) constructor and the _add_edge! helper in test/utils.jl — to maintain the graph-edge ↔ shared-Index invariant explicitly via @preserve_graph plus a direct add_edge! on the underlying graph. fix_edges! itself stays in place for now as the safety net for plain tn[v] = ... writes; it'll be dropped once the invariant becomes structural (e.g. via a reverse Index map on ITensorNetwork).

Edge factorization

• Replace the vertex-splitting qr(tn, edge) / svd(tn, edge) / factorize(tn, edge) and the internal gauge_edge + factorize_edge! helpers with a single absorbing-into-dst pair: qr!(tn, edge) (mutating) and qr(tn, edge) = qr!(copy(tn), edge) (non-mutating). Vertex set unchanged; the bond on edge is re-gauged with the orthogonal factor on src(edge) and the residual absorbed into tn[dst(edge)].
• Drop the dispatch on alg::Algorithm from gauge_walk, tree_gauge, and gauge. There was only ever one implementation (Algorithm"orthogonalize"), so the parameter was vestigial. Public orthogonalize / tree_orthogonalize signatures are unchanged.

Multi-edge collapse

• Delete combine_linkinds, linkinds_combiners, and is_multi_edge. The only caller — the multi-edge collapse step in add(tn1, tn2) — is replaced by an inline loop calling qr!(tn, e) on multi-edges. qr! produces the same single-shared-Index end state as combine_linkinds, plus a free rank truncation to the actual rank of tn[src] on the (left-inds | multi-link) bipartition.

Dense-ITensor TTN constructor

• Delete TreeTensorNetwork(::ITensor, ::IndsNetwork) outright. It had no in-src callers and its two test-only callers (test/test_ttns.jl's 'Construct TTN from ITensor or Array' and test/test_ttno.jl's 'Construct TTN operator from ITensor or Array') only verified contract(ttn) ≈ original_dense. Tracing the algorithm showed it was producing factorizations that round-trip correctly but do not lay out site indices on their designated vertices — the first vertex processed in post-order absorbed every site index that wasn't dst(e)'s, leaving later vertices without their own site indices. Drop the constructor and its two test callers; a clean replacement algorithm is written up in the development plan if a real use case appears.

Docs

• Drop the "From a dense ITensor" section in docs/src/tree_tensor_networks.md (its @example block would have crashed the doc build), the insert_linkinds, combine_linkinds, and linkinds_combiners entries in docs/src/experimental_methods.md, and the svd(tn, edge) / factorize(tn, edge) entries in docs/src/interface_methods.md. Update the remaining qr(tn, edge) entry to describe the new absorbing semantics. Update the gauge entry in docs/src/experimental_methods.md to drop the alg::Algorithm positional and kwargs....

Targeting the 0.22.0-DEV accumulator (already a breaking release line).

[codecov]

Codecov Report

❌ Patch coverage is 89.36170% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.92%. Comparing base (c8103d0) to head (a9205b4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/abstractitensornetwork.jl	86.66%	4 Missing ⚠️
...rc/treetensornetworks/abstracttreetensornetwork.jl	80.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #363       +/-   ##
===========================================
+ Coverage   49.96%   74.92%   +24.96%     
===========================================
  Files          61       63        +2     
  Lines        2852     2820       -32     
===========================================
+ Hits         1425     2113      +688     
+ Misses       1427      707      -720     

Flag	Coverage Δ
docs	49.92% <65.95%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.