[BREAKING] Drop ttn/mps name aliases and simplify test/utils.jl

Follow-up to the IndsNetwork/graph ctor removal in the same branch.

Drop the `ttn` / `mps` short-name surface entirely (rather than narrowing it):
the surviving constructors keep the canonical `TreeTensorNetwork` name. This
covers `ttn(::OpSum, ::IndsNetwork)` (and its `eltype`-leading variant) and
`ttn(::ITensor, ::IndsNetwork)`. `mpo` continues to dispatch through to
`TreeTensorNetwork(::OpSum, ::IndsNetwork)`.

Docs: drop `ttn` / `mps` from `using ITensorNetworks` in `docs/make.jl` and
the `mps`-specific section from `tree_tensor_networks.md`; rewrite the
constructor examples in `itensor_networks.md` and `tree_tensor_networks.md`
to build link inds explicitly with `random_itensor` so they don't fall back
to `EmptyNumber` placeholders that fail the downstream `add` / `qr` /
`directsum` examples; rename `ttn` callsites to `TreeTensorNetwork` in
`solvers.md` and `experimental_methods.md`. Fixes the docs build failure
on PR #356.

`src/abstractitensornetwork.jl`: `_siteinds` now `collect`s the inds before
iterating, so the return type is a `Vector{Index}` rather than a `Tuple`.
The `IndsNetwork` `vertex_data` setter expects a vector, and the previous
behaviour produced a `Tuple` whenever a vertex's tensor had no shared
neighbour inds. Also rename `truncate(ttn) → truncate(tn)` in a docstring.

`test/utils.jl`: substantial simplification (~261 → ~75 effective lines).
Drop `random_mps`, `random_ttn`, `Op`-handling, the `generic_state` machinery,
and the `@traitfn` indirection. Surviving surface: `random_tensornetwork`
(graph or `IndsNetwork` input, eltype + distribution variants), `productstate`
(renamed from `tensornetworkstate`, since it only builds product states;
routed through `insert_linkinds` so the default `link_space` follows
`trivial_space` and stays QN-aware), and the `ModelHamiltonians` submodule.
Test callsites updated: `ttn(state, s) → TreeTensorNetwork(productstate(state, s))`,
`ttn(os, s) → TreeTensorNetwork(os, s)`, `ttn(A, is; cutoff) → TreeTensorNetwork(A, is; cutoff)`,
and `tensornetworkstate → productstate`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mtfishman

docs/make.jl

@@ -14,7 +14,7 @@ DocMeta.setdocmeta!(
         using Graphs: dst, edges, src, vertices
         using ITensorNetworks
         using ITensorNetworks:
-            TreeTensorNetwork, expect, loginner, mps, orthogonalize, siteinds, truncate, ttn
+            TreeTensorNetwork, expect, loginner, orthogonalize, siteinds, truncate
         using ITensors: inner
         using LinearAlgebra: norm, normalize
         using OMEinsumContractionOrders

docs/src/experimental_methods.md

@@ -50,7 +50,7 @@ Methods which still need to be discussed, modified, or deprecated.
 
 * From an `OpSum`, using `opsum_to_ttn.jl` code:
   ```julia
-  ttn(os::OpSum, sites::IndsNetwork; kws...)
+  TreeTensorNetwork(os::OpSum, sites::IndsNetwork; kws...)
   ```
 
 * From `OpSum`, assuming path graph (`opsum_to_ttn.jl`):

docs/src/itensor_networks.md

@@ -32,22 +32,36 @@ tn = ITensorNetwork([A, B, C])  # integer vertices 1, 2, 3
 tn = ITensorNetwork(Dict("A" => A, "B" => B, "C" => C))  # named vertices via a Dict
 ```
 
-If you want to control edges directly — for example to build an empty network on a
+If you want to control edges directly — for example to build a structured network on a
 prescribed lattice and fill in tensors later — pass a `NamedGraph` along with a
-collection of `ITensor`s indexed by vertex:
+collection of `ITensor`s indexed by vertex. To create a tensor network with shared link
+indices on each edge, build the indices once per edge and reuse them at both endpoints:
 
 ```@example main
-g = named_grid((3, 3))
-s = siteinds("S=1/2", g)  # one spin-½ Index per vertex
+using ITensors: random_itensor
+using NamedGraphs: NamedGraph
+using NamedGraphs.GraphsExtensions: edgetype, incident_edges
+
+g = NamedGraph(named_grid((3, 3)))
+s = siteinds("S=1/2", g)  # one spin-½ site Index per vertex
+
+# One shared link Index per edge; bond dimension χ
+χ = 2
+links = Dict(e => Index(χ, "Link") for e in edges(g))
+
+# Per-vertex tensor: the site Index plus the link Index of every incident edge
+tensors = Dict(map(collect(vertices(g))) do v
+    site_v = s[v]
+    link_v = [haskey(links, e) ? links[e] : links[reverse(e)] for e in incident_edges(g, v)]
+    return v => random_itensor(site_v..., link_v...)
+end)
 
-# Build site tensors on the 3×3 lattice with one (placeholder) site index each
-tensors = Dict(v => ITensor(s[v]...) for v in vertices(g))
 ψ = ITensorNetwork(tensors, g)
 ```
 
 Higher-level construction routines (random networks, product states, OpSum-derived
-TTNs, etc.) are provided by sibling functions like `ttn(opsum, sites)` and the test-only
-helpers in `test/utils.jl`.
+TTNs, etc.) are provided by sibling functions like `TreeTensorNetwork(opsum, sites)`
+and the test-only helpers in `test/utils.jl`.
 
 ```@docs; canonical=false
 ITensorNetworks.ITensorNetwork
@@ -72,7 +86,7 @@ linkinds(ψ)  # IndsNetwork of bond (virtual) indices
 Two networks with the same graph and site indices can be added. The result represents the
 tensor network `ψ₁ + ψ₂` and has bond dimension equal to the **sum** of the two input bond
 dimensions. Individual bonds of the result can be recompressed with `truncate(tn, edge)`.
-For `TreeTensorNetwork`, the no-argument form `truncate(ttn; kwargs...)` sweeps and
+For `TreeTensorNetwork`, the no-argument form `truncate(tn; kwargs...)` sweeps and
 recompresses all bonds at once.
 
 ```@example main
@@ -96,7 +110,7 @@ edge = (1, 2) => (1, 3)
 ```
 
 Truncation parameters (`cutoff`, `maxdim`, `mindim`, …) are forwarded to `ITensors.svd`.
-For a `TreeTensorNetwork`, the sweep-based `truncate(ttn; kwargs...)` is usually more
+For a `TreeTensorNetwork`, the sweep-based `truncate(tn; kwargs...)` is usually more
 convenient because it recompresses the entire network at once with controlled errors;
 see the [Tree Tensor Networks](@ref) page.
 

docs/src/solvers.md

@@ -18,7 +18,7 @@ variational sweep algorithm.
 ```@example main
 using Graphs: vertices
 using ITensorNetworks:
-    ITensorNetwork, TreeTensorNetwork, dmrg, dst, edges, normalize, siteinds, src, ttn
+    ITensorNetwork, TreeTensorNetwork, dmrg, dst, edges, normalize, siteinds, src
 using ITensors: Index, OpSum, random_itensor
 using NamedGraphs.GraphsExtensions: incident_edges
 using NamedGraphs.NamedGraphGenerators: named_comb_tree
@@ -30,7 +30,7 @@ function random_state(g, s; link_space)
         v => random_itensor(only(s[v]), (l[e] for e in incident_edges(g, v))...)
             for v in vertices(g)
     )
-    return ITensorNetwork(ts)
+    return ITensorNetwork(ts, g)
 end
 
 # Build a Heisenberg Hamiltonian on a comb tree
@@ -42,7 +42,7 @@ H = let h = OpSum()
         h += 0.5, "S-", src(e), "S+", dst(e)
         h += "Sz", src(e), "Sz", dst(e)
     end
-    ttn(h, s)
+    TreeTensorNetwork(h, s)
 end
 
 # Random initial state (normalise first!)

docs/src/tree_tensor_networks.md

@@ -21,7 +21,7 @@ A common way to obtain a Hamiltonian-shaped TTN is to convert an `OpSum` over an
 `IndsNetwork` of site indices.
 
 ```@docs; canonical=false
-ITensorNetworks.ttn(::ITensors.Ops.OpSum, ::ITensorNetworks.IndsNetwork)
+ITensorNetworks.TreeTensorNetwork(::ITensors.Ops.OpSum, ::ITensorNetworks.IndsNetwork)
 ```
 
 ### From an existing `ITensorNetwork`
@@ -32,21 +32,28 @@ orthogonality region. Use the `TreeTensorNetwork` constructor to convert a plain
 gauge metadata when you need a plain network again.
 
 ```@example main
-using Graphs: vertices
+using Graphs: edges, vertices
 using ITensorNetworks: ITensorNetwork, TreeTensorNetwork, ortho_region, orthogonalize,
-    siteinds, ttn
-using ITensors: ITensors, ITensor
+    siteinds
+using ITensors: ITensors, Index, random_itensor
 using LinearAlgebra: norm
 using NamedGraphs: NamedGraph
+using NamedGraphs.GraphsExtensions: incident_edges
 using NamedGraphs.NamedGraphGenerators: named_comb_tree
 
 # Comb-tree TTN (a popular tree topology for 2D-like systems)
-g = named_comb_tree((3, 2))
+g = NamedGraph(named_comb_tree((3, 2)))
 sites = siteinds("S=1/2", g)
 
-# Build an `ITensorNetwork` from explicit per-vertex tensors and wrap as a TTN
-tensors = Dict(v => ITensor(sites[v]...) for v in vertices(g))
-itn = ITensorNetwork(tensors, NamedGraph(g))
+# Build a structured `ITensorNetwork` with shared link indices on each edge
+χ = 2
+links = Dict(e => Index(χ, "Link") for e in edges(g))
+tensors = Dict(map(collect(vertices(g))) do v
+    site_v = sites[v]
+    link_v = [haskey(links, e) ? links[e] : links[reverse(e)] for e in incident_edges(g, v)]
+    return v => random_itensor(site_v..., link_v...)
+end)
+itn = ITensorNetwork(tensors, g)
 psi = TreeTensorNetwork(itn)
 ```
 
@@ -68,14 +75,16 @@ tree edges. Truncation parameters (e.g. `cutoff`, `maxdim`) are forwarded to the
 factorisation step.
 
 ```@example main
-g = named_comb_tree((3, 1))
-sites = siteinds("S=1/2", g)
-A = ITensors.random_itensor(only(sites[(1, 1)]), only(sites[(2, 1)]), only(sites[(3, 1)]))
-ttn_A = ttn(A, sites)
+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.ttn(::ITensors.ITensor, ::ITensorNetworks.IndsNetwork)
+ITensorNetworks.TreeTensorNetwork(::ITensors.ITensor, ::ITensorNetworks.IndsNetwork)
 ```
 
 ## Orthogonal Gauge

src/abstractitensornetwork.jl

@@ -274,7 +274,7 @@ end
 #
 
 function _siteinds(tn::AbstractITensorNetwork, vertex)
-    s = inds(tn[vertex])
+    s = collect(inds(tn[vertex]))
     for v in neighbors(tn, vertex)
         s = setdiff(s, inds(tn[v]))
     end
@@ -681,7 +681,7 @@ Truncation parameters are passed as keyword arguments and forwarded to `ITensors
   - `mindim`: Minimum number of singular values to keep.
 
 This operates on a single bond. For `TreeTensorNetwork`, the no-argument form
-`truncate(ttn; kwargs...)` sweeps all bonds and is generally preferred for full
+`truncate(tn; kwargs...)` sweeps all bonds and is generally preferred for full
 recompression after addition or subspace expansion.
 
 See also: `Base.truncate(::AbstractTreeTensorNetwork)`.

src/itensornetwork.jl

@@ -38,7 +38,7 @@ julia> tn = ITensorNetwork([ITensor(i, j), ITensor(j, k)]);
 
 ```
 
-See also: `IndsNetwork`, [`ttn`](@ref ITensorNetworks.ttn), [`TreeTensorNetwork`](@ref ITensorNetworks.TreeTensorNetwork).
+See also: `IndsNetwork`, [`TreeTensorNetwork`](@ref ITensorNetworks.TreeTensorNetwork).
 """
 const _ITensorCollection = Union{
     AbstractVector{<:ITensor},

src/solvers/eigsolve.jl

@@ -70,7 +70,7 @@ DMRG-like sweep algorithm on a `TreeTensorNetwork`.
 # Arguments
 
   - `operator`: The operator to diagonalize, typically a `TreeTensorNetwork` representing a
-    Hamiltonian constructed from an `OpSum` (e.g. via `ttn(opsum, sites)`).
+    Hamiltonian constructed from an `OpSum` (e.g. via `TreeTensorNetwork(opsum, sites)`).
   - `init_state`: Initial guess for the eigenvector as a `TreeTensorNetwork`.
   - `nsweeps`: Number of sweeps over the network.
   - `nsites=1`: Number of sites optimized simultaneously per local update step (1 or 2).

src/treetensornetworks/opsum_to_ttn/opsum_to_ttn.jl

@@ -636,12 +636,12 @@ function sortmergeterms(os::OpSum{C}) where {C}
 end
 
 """
-    ttn(os::OpSum, sites::IndsNetwork{<:Index}; kwargs...)
-    ttn(eltype::Type{<:Number}, os::OpSum, sites::IndsNetwork{<:Index}; kwargs...)
+    TreeTensorNetwork(os::OpSum, sites::IndsNetwork{<:Index}; kwargs...)
+    TreeTensorNetwork(eltype::Type{<:Number}, os::OpSum, sites::IndsNetwork{<:Index}; kwargs...)
 
 Convert an OpSum object `os` to a TreeTensorNetwork, with indices given by `sites`.
 """
-function ttn(
+function TreeTensorNetwork(
         os::OpSum,
         sites::IndsNetwork;
         root_vertex = GraphsExtensions.default_root_vertex(sites),
@@ -658,16 +658,16 @@ function ttn(
 end
 
 function mpo(os::OpSum, external_inds::Vector; kwargs...)
-    return ttn(os, path_indsnetwork(external_inds); kwargs...)
+    return TreeTensorNetwork(os, path_indsnetwork(external_inds); kwargs...)
 end
 function mpo(os::OpSum, s::IndsNetwork; kwargs...)
     # TODO: Check it is a path graph.
-    return ttn(os, s; kwargs...)
+    return TreeTensorNetwork(os, s; kwargs...)
 end
 
 # Catch-all for leaf eltype specification
-function ttn(eltype::Type{<:Number}, os, sites::IndsNetwork; kwargs...)
-    return NDTensors.convert_scalartype(eltype, ttn(os, sites; kwargs...))
+function TreeTensorNetwork(eltype::Type{<:Number}, os, sites::IndsNetwork; kwargs...)
+    return NDTensors.convert_scalartype(eltype, TreeTensorNetwork(os, sites; kwargs...))
 end
 
 #

src/treetensornetworks/treetensornetwork.jl

@@ -1,9 +1,10 @@
+using DataGraphs: underlying_graph
 using Dictionaries: Indices
 using Graphs: path_graph
 using ITensors: ITensor
 using LinearAlgebra: factorize, normalize
 using NamedGraphs.GraphsExtensions: GraphsExtensions, vertextype
-using NamedGraphs: similar_graph
+using NamedGraphs: NamedGraph, similar_graph
 
 """
     TreeTensorNetwork{V} <: AbstractTreeTensorNetwork{V}
@@ -14,10 +15,10 @@ center of the network.
 
 `TTN` is an alias for `TreeTensorNetwork`.
 
-Use [`ttn`](@ref) or [`mps`](@ref) to construct instances, and [`orthogonalize`](@ref) to
-bring the network into a canonical gauge.
+Use the [`TreeTensorNetwork`](@ref) constructors to build instances, and
+[`orthogonalize`](@ref) to bring the network into a canonical gauge.
 
-See also: [`ITensorNetwork`](@ref), [`ttn`](@ref), [`mps`](@ref).
+See also: [`ITensorNetwork`](@ref).
 """
 struct TreeTensorNetwork{V} <: AbstractTreeTensorNetwork{V}
     tensornetwork::ITensorNetwork{V}
@@ -52,21 +53,25 @@ Throws an error if the underlying graph of `tn` is not a tree.
 ```jldoctest
 julia> using NamedGraphs.NamedGraphGenerators: named_comb_tree
 
+julia> using NamedGraphs: NamedGraph
+
 julia> using Graphs: vertices
 
+julia> using ITensors: ITensor
+
 julia> g = named_comb_tree((2, 2));
 
 julia> s = siteinds("S=1/2", g);
 
-julia> itn = ITensorNetwork(s; link_space = 2);
+julia> tensors = Dict(v => ITensor(s[v]...) for v in vertices(g));
 
-julia> root_vertex = first(vertices(itn));
+julia> itn = ITensorNetwork(tensors, NamedGraph(g));
 
-julia> ttn_state = TreeTensorNetwork(itn; ortho_region = [root_vertex]);
+julia> ttn_state = TreeTensorNetwork(itn; ortho_region = [first(vertices(itn))]);
 
 ```
 
-See also: [`ttn`](@ref), [`ITensorNetwork`](@ref), [`orthogonalize`](@ref).
+See also: [`ITensorNetwork`](@ref), [`orthogonalize`](@ref).
 """
 function TreeTensorNetwork(tn::ITensorNetwork; ortho_region = vertices(tn))
     return _TreeTensorNetwork(tn, ortho_region)
@@ -88,7 +93,7 @@ end
 Convert a `TreeTensorNetwork` to a plain `ITensorNetwork`, discarding orthogonality
 metadata. The returned network shares the same underlying tensor data.
 
-See also: [`TreeTensorNetwork`](@ref), [`ttn`](@ref).
+See also: [`TreeTensorNetwork`](@ref).
 """
 ITensorNetwork(tn::TTN) = copy(tn.tensornetwork)
 
@@ -123,33 +128,16 @@ function set_ortho_region(tn::TTN, ortho_region)
 end
 
 """
-    ttn(a::ITensor, is::IndsNetwork; ortho_region=..., kwargs...) -> TreeTensorNetwork
+    TreeTensorNetwork(a::ITensor, is::IndsNetwork; ortho_region=..., kwargs...) -> TreeTensorNetwork
 
 Decompose a dense `ITensor` `a` into a `TreeTensorNetwork` with the tree structure
 described by the `IndsNetwork` `is`.
 
 Successive QR/SVD factorizations are applied following a post-order DFS traversal from the
 root vertex, then the network is orthogonalized to `ortho_region` (defaults to the root).
 Extra `kwargs` (e.g. `cutoff`, `maxdim`) are forwarded to the factorization.
-
-# Example
-
-```jldoctest
-julia> using NamedGraphs.NamedGraphGenerators: named_comb_tree
-
-julia> using ITensors: ITensors
-
-julia> g = named_comb_tree((3, 1));
-
-julia> s = siteinds("S=1/2", g);
-
-julia> A = ITensors.random_itensor(only(s[(1, 1)]), only(s[(2, 1)]), only(s[(3, 1)]));
-
-julia> ttn_A = ttn(A, s);
-
-```
 """
-function ttn(
+function TreeTensorNetwork(
         a::ITensor,
         is::IndsNetwork;
         ortho_region = Indices([GraphsExtensions.default_root_vertex(is)]),
@@ -160,14 +148,15 @@ function ttn(
     end
     @assert ortho_region ⊆ vertices(is)
     is = insert_linkinds(is)
-    ts = Dict{vertextype(is), ITensor}()
-    for v in vertices(is)
+    g = NamedGraph(underlying_graph(is))
+    ts = Dict{vertextype(g), ITensor}()
+    for v in vertices(g)
         site_inds = get(is, v, Index[])
         edges_v = [edgetype(is)(v, nv) for nv in neighbors(is, v)]
         link_inds = reduce(vcat, (is[e] for e in edges_v); init = Index[])
         ts[v] = ITensor(site_inds..., link_inds...)
     end
-    tn = ITensorNetwork(ts)
+    tn = ITensorNetwork(ts, g)
     ortho_center = first(ortho_region)
     for e in post_order_dfs_edges(tn, ortho_center)
         left_inds = setdiff(inds(a), inds(tn[dst(e)]))