[BREAKING] Drop IndsNetwork/graph ITensorNetwork ctors and ttn/mps generic ctors

Remove the IndsNetwork-, AbstractNamedGraph-, and AbstractSimpleGraph-based
ITensorNetwork constructor families (state/value, function-callback, undef,
plain-graph variants), the broken-stub ITensorNetwork{V}(g::NamedGraph), and
the generic ttn(args...)/mps(args...)/mps(f, ::Vector{<:Index})/
mps(::Vector{<:Index}) wrappers that delegated to them. Also remove
visualize(::IndsNetwork).

Internal callers that built `ITensorNetwork(::IndsNetwork)`-style placeholders
now build `ITensorNetwork(tensors, graph::NamedGraph)` directly: bilinearform-
network, the directsum branch in abstracttreetensornetwork, opsum_to_ttn, and
ttn(::ITensor, ::IndsNetwork). set_ortho_region and the QR/SVD-decomposition
ttn use TreeTensorNetwork(tn) instead of ttn(tn::ITensorNetwork).

Bug fix: trivial_space was used in abstractindsnetwork.jl and
abstractitensornetwork.jl without being imported from ITensorsExtensions —
imports added.

test/utils.jl: rename state_tensornetwork → tensornetworkstate, drop
default_tensornetwork (callers use random_tensornetwork for structural
setups), and switch tensornetworkstate / random_tensornetwork to construct
via ITensorNetwork(tensors, graph) so graph edge order is preserved.

Test files rewritten to use the new helpers and the surviving ctor surface;
the exhaustive parameterised "Product state constructors" testset (which
covered the deleted state-arg ctor surface) is dropped.

Docs updated: itensor_networks.md and tree_tensor_networks.md show the
canonical (tensors, graph) construction; deprecated_methods.md entries for
the removed ctors are removed.

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

Author: mtfishman

Project.toml

@@ -1,6 +1,6 @@
 name = "ITensorNetworks"
 uuid = "2919e153-833c-4bdc-8836-1ea460a35fc7"
-version = "0.21.0"
+version = "0.22.0"
 authors = ["Matthew Fishman <mfishman@flatironinstitute.org>, Joseph Tindall <jtindall@flatironinstitute.org> and contributors"]
 
 [workspace]

docs/Project.toml

@@ -16,7 +16,7 @@ path = ".."
 Documenter = "1.10"
 Graphs = "1"
 ITensorFormatter = "0.2.27"
-ITensorNetworks = "0.21"
+ITensorNetworks = "0.22"
 ITensors = "0.9"
 Literate = "2.20.1"
 NamedGraphs = "0.11"

docs/src/computing_properties.md

@@ -2,7 +2,8 @@
 
 ```@setup main
 using Graphs: edges, vertices
-using ITensorNetworks: ITensorNetwork, expect, inner, loginner, normalize, siteinds, ttn
+using ITensorNetworks:
+    ITensorNetwork, TreeTensorNetwork, expect, inner, loginner, normalize, siteinds
 using ITensors: Index, random_itensor
 using LinearAlgebra: norm
 using NamedGraphs.GraphsExtensions: incident_edges
@@ -20,10 +21,10 @@ end
 
 g = named_grid((4,))
 s = siteinds("S=1/2", g)
-phi = normalize(ttn(random_state(g, s; link_space = 2)))
-psi = normalize(ttn(random_state(g, s; link_space = 2)))
-x = normalize(ttn(random_state(g, s; link_space = 2)))
-y = normalize(ttn(random_state(g, s; link_space = 2)))
+phi = normalize(TreeTensorNetwork(random_state(g, s; link_space = 2)))
+psi = normalize(TreeTensorNetwork(random_state(g, s; link_space = 2)))
+x = normalize(TreeTensorNetwork(random_state(g, s; link_space = 2)))
+y = normalize(TreeTensorNetwork(random_state(g, s; link_space = 2)))
 v = first(vertices(psi))
 ```
 

docs/src/deprecated_methods.md

@@ -2,43 +2,6 @@
 
 Suggestions of methods which could be deleted.
 
-## ITensorNetwork Methods
-
-#### ITensorNetwork Constructors
-
-* From a named graph, forwards to construction from `IndsNetwork` (`itensornetwork.jl`):
-  ```julia
-  ITensorNetwork{V}(g::NamedGraph)
-  ITensorNetwork(eltype::Type, undef::UndefInitializer, graph::AbstractNamedGraph; kws...)
-  ITensorNetwork(f, graph::AbstractNamedGraph; kwargs...)
-  ITensorNetwork(graph::AbstractNamedGraph; kwargs...)
-  ```
-
-* From a simple graph, forwards to construction from `IndsNetwork` (`itensornetwork.jl`):
-  ```julia
-  ITensorNetwork(eltype::Type, undef::UndefInitializer, graph::AbstractSimpleGraph; kws...)
-  ITensorNetwork(f, graph::AbstractSimpleGraph; kwargs...)
-  ITensorNetwork(graph::AbstractSimpleGraph; kwargs...)
-  ```
-
-* From a function over vertices or from a "value" (e.g. a string like `"Up"`,
-  an `Op`, an array, or a per-vertex dict/array) that is converted to a callable and used
-  to initialize each vertex tensor (`itensornetwork.jl`):
-  ```julia
-  ITensorNetwork(value, is::IndsNetwork; kwargs...)
-  ITensorNetwork(elt::Type, f, is::IndsNetwork; link_space = trivial_space(is), kws...)
-  ITensorNetwork(itensor_constructor::Function, is::IndsNetwork; link_space = trivial_space(is), kwargs...)
-  ```
-
-* Construct an `ITensorNetwork` from an `IndsNetwork`. Initializes ITensors with `undef` storage on each vertex
-  of the `IndsNetwork` with the corresponding indices (`itensornetwork.jl`):
-  ```julia
-  ITensorNetwork(eltype::Type, undef::UndefInitializer, is::IndsNetwork; kwargs...)
-  ITensorNetwork(eltype::Type, is::IndsNetwork; kwargs...)
-  ITensorNetwork(undef::UndefInitializer, is::IndsNetwork; kwargs...)
-  ITensorNetwork(is::IndsNetwork; kwargs...)
-  ```
-
 ## Global Operations on ITensorNetworks
 
 

docs/src/interface_methods.md

@@ -6,20 +6,20 @@ Recommended methods for building applications on top of ITensorNetworks.
 
 These ITensorNetwork constructor interfaces are foundational to other constructors:
 
-* From dictionary-like objects, including other `ITensorNetwork` objects, or a `Dict`
-  from vertices to `ITensor`. The `tensors` can be a collection of `ITensor`s in which case
-  the vertex labels are auto-assigned to `eachindex(tensors)` and edges are inferred
-  from shared indices between the `ITensor`s.
+* From a collection of `ITensor`s indexed by vertex (a `Dict`, `Dictionary`, or
+  `Vector{ITensor}` with linear-index vertex labels). Edges are inferred from shared
+  `Index` objects between the tensors.
   ```julia
   # `keys(tensors)` are vertices, `values(tensors)` are tensors on those vertices
   ITensorNetwork(tensors)
   ITensorNetwork{V}(tensors)
   ```
 
-* From collections of vertices and tensors. E.g. a `Vector{Int}` and a `Vector{ITensor}`.
+* From a collection of `ITensor`s placed at the vertices of a given `NamedGraph`. No
+  edge inference; the graph's edges are used as-is.
   ```julia
-  ITensorNetwork(vertices, tensors)
-  ITensorNetwork{V}(vertices, tensors)
+  ITensorNetwork(tensors, graph::NamedGraph)
+  ITensorNetwork{V}(tensors, graph::NamedGraph)
   ```
 
 

docs/src/itensor_networks.md

@@ -11,49 +11,44 @@ Key facts:
 - The underlying graph is a [`NamedGraph`](https://github.com/ITensor/NamedGraphs.jl), so
   vertices can be any hashable Julia value: integers, tuples, strings, etc.
 - Each vertex holds exactly one `ITensor`.
-- Edges and link indices are either inferred from shared `Index` objects (when constructing
-  from a collection of `ITensor`s) or inserted automatically (when constructing from an
-  `IndsNetwork`).
+- Edges are either inferred from shared `Index` objects (when constructing from a
+  collection of `ITensor`s) or taken from a graph passed explicitly alongside the tensors.
 
 ## Construction
 
-The most common entry point is an `IndsNetwork` — a graph whose vertices and edges carry
-`Index` objects.  Generate site indices with the `siteinds` function which takes a site
-type string (such as "S=1/2" or "Electron") and a NamedGraph. The NamedGraph can be 
-generated from functions such as `named_grid`, `named_comb_tree`, etc. from the NamedGraphs.jl
-`NamedGraphGenerators` module:
+When you already have `ITensor`s in hand, edges are inferred automatically from shared
+indices:
 
 ```@example main
 using Graphs: edges, ne, neighbors, nv, vertices
 using ITensorNetworks: ITensorNetwork, add, linkinds, siteinds
 using ITensors: Index, ITensor
 using NamedGraphs.NamedGraphGenerators: named_grid
 
-# 3×3 square-lattice tensor network
-g = named_grid((3, 3))
-s = siteinds("S=1/2", g)  # one spin-½ Index per vertex
-
-# Zero-initialized, bond dimension 2
-ψ = ITensorNetwork(s; link_space = 2)
-
-# Product state — every site in the |↑⟩ state
-ψ = ITensorNetwork("Up", s)
+i, j, k = Index(2, "i"), Index(2, "j"), Index(2, "k")
+A, B, C = ITensor(i, j), ITensor(j, k), ITensor(k)
 
-# Staggered initialization with a vertex-dependent function
-ψ = ITensorNetwork(v -> isodd(sum(v)) ? "Up" : "Dn", s)
+tn = ITensorNetwork([A, B, C])  # integer vertices 1, 2, 3
+tn = ITensorNetwork(Dict("A" => A, "B" => B, "C" => C))  # named vertices via a Dict
 ```
 
-When you already have `ITensor`s in hand, edges are inferred automatically from shared
-indices:
+If you want to control edges directly — for example to build an empty network on a
+prescribed lattice and fill in tensors later — pass a `NamedGraph` along with a
+collection of `ITensor`s indexed by vertex:
 
 ```@example main
-i, j, k = Index(2, "i"), Index(2, "j"), Index(2, "k")
-A, B, C = ITensor(i, j), ITensor(j, k), ITensor(k)
+g = named_grid((3, 3))
+s = siteinds("S=1/2", g)  # one spin-½ Index per vertex
 
-tn = ITensorNetwork([A, B, C])  # integer vertices 1, 2, 3
-tn = ITensorNetwork(Dict("A" => A, "B" => B, "C" => C))  # named vertices via a Dict
+# 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`.
+
 ```@docs; canonical=false
 ITensorNetworks.ITensorNetwork
 ```

docs/src/solvers.md

@@ -17,7 +17,8 @@ variational sweep algorithm.
 
 ```@example main
 using Graphs: vertices
-using ITensorNetworks: ITensorNetwork, dmrg, dst, edges, normalize, siteinds, src, ttn
+using ITensorNetworks:
+    ITensorNetwork, TreeTensorNetwork, dmrg, dst, edges, normalize, siteinds, src, ttn
 using ITensors: Index, OpSum, random_itensor
 using NamedGraphs.GraphsExtensions: incident_edges
 using NamedGraphs.NamedGraphGenerators: named_comb_tree
@@ -45,7 +46,7 @@ H = let h = OpSum()
 end
 
 # Random initial state (normalise first!)
-psi0 = normalize(ttn(random_state(g, s; link_space = 2)))
+psi0 = normalize(TreeTensorNetwork(random_state(g, s; link_space = 2)))
 
 # Run DMRG
 energy, psi = dmrg(H, psi0;

docs/src/tree_tensor_networks.md

@@ -11,48 +11,49 @@ records which vertices currently form the orthogonality center of the network. A
 update this field as the gauge changes.
 
 **MPS** (matrix product states) are the special case of a `TreeTensorNetwork` on a
-1D path graph. The [`mps`](@ref ITensorNetworks.mps) constructor enforces this topology
-and provides a convenient interface for 1D calculations.
+1D path graph.
 
 ## Construction
 
-### From an `IndsNetwork` or graph
+### From an `OpSum` (Hamiltonian)
+
+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)
+```
+
+### From an existing `ITensorNetwork`
+
+The `TreeTensorNetwork` struct wraps an `ITensorNetwork` and records the current
+orthogonality region. Use the `TreeTensorNetwork` constructor to convert a plain
+`ITensorNetwork` with tree topology into a `TTN`, and `ITensorNetwork` to strip the
+gauge metadata when you need a plain network again.
 
 ```@example main
 using Graphs: vertices
-using ITensorNetworks: ITensorNetwork, TreeTensorNetwork, mps, ortho_region, orthogonalize,
+using ITensorNetworks: ITensorNetwork, TreeTensorNetwork, ortho_region, orthogonalize,
     siteinds, ttn
-using ITensors: ITensors
+using ITensors: ITensors, ITensor
 using LinearAlgebra: norm
+using NamedGraphs: NamedGraph
 using NamedGraphs.NamedGraphGenerators: named_comb_tree
 
 # Comb-tree TTN (a popular tree topology for 2D-like systems)
 g = named_comb_tree((3, 2))
 sites = siteinds("S=1/2", g)
 
-psi = ttn(sites)  # zero-initialised
-psi = ttn(v -> "Up", sites)  # product state
-
-# 1D MPS
-s1d = siteinds("S=1/2", 6)
-mps_state = mps(v -> "Up", s1d)  # product MPS
+# 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))
+psi = TreeTensorNetwork(itn)
 ```
 
-```@docs; canonical=false
-ITensorNetworks.ttn
-ITensorNetworks.mps
-```
-
-### The `TreeTensorNetwork` type and conversion
-
-The `TreeTensorNetwork` struct wraps an `ITensorNetwork` and records the current
-orthogonality region. Use the `TreeTensorNetwork` constructor to convert a plain
-`ITensorNetwork` with tree topology into a `TTN`, and `ITensorNetwork` to strip the
-gauge metadata when you need a plain network again.
+To strip the gauge metadata back to a plain `ITensorNetwork`:
 
 ```@example main
-itn = ITensorNetwork(psi)  # TTN → ITensorNetwork
-psi = TreeTensorNetwork(itn)  # ITensorNetwork → TTN
+itn_again = ITensorNetwork(psi)  # TTN → ITensorNetwork
 ```
 
 ```@docs; canonical=false

examples/Project.toml

@@ -5,4 +5,4 @@ ITensorNetworks = "2919e153-833c-4bdc-8836-1ea460a35fc7"
 path = ".."
 
 [compat]
-ITensorNetworks = "0.21"
+ITensorNetworks = "0.22"

src/abstractindsnetwork.jl

@@ -1,4 +1,4 @@
-using .ITensorsExtensions: ITensorsExtensions, promote_indtype
+using .ITensorsExtensions: ITensorsExtensions, promote_indtype, trivial_space
 using DataGraphs: DataGraphs, AbstractDataGraph, DataGraph, IsUnderlyingGraph, edge_data,
     get_edge_data, get_vertex_data, is_edge_assigned, is_vertex_assigned, map_data,
     set_edge_data!, set_vertex_data!, underlying_graph_type, vertex_data