Move test-only helpers (random_tensornetwork, random_ttn, random_mps, ModelHamiltonians) out of src/ (#339)

## Summary

Pull non-basic constructors that are only used by tests out of `src/`
and into a new `test/utils.jl`. Each test that needs them does
`include("utils.jl")` inside its gensym module. The file is
intentionally named `utils.jl` so the `ITensorPkgSkeleton.runtests`
runner does not auto-pick it up (the runner only globs `test_*.jl`).

**What moved to `test/utils.jl`:**
- `random_tensornetwork` (12 method specializations, including the
`Distribution`- and `IsUnderlyingGraph`-based variants) — moved from
`src/specialitensornetworks.jl`.
- `random_ttn` and `random_mps` — moved from
`src/treetensornetworks/treetensornetwork.jl`. These thin wrappers
around `random_tensornetwork` had no real `src/` consumers (only
docstring examples) and a single test reference.
- `ModelHamiltonians.tight_binding`, `heisenberg`, `ising` plus the
internal helpers `to_callable`, `nth_nearest_neighbors`,
`next_nearest_neighbors` — moved from `src/lib/ModelHamiltonians/` into
a `ModelHamiltonians` submodule of `test/utils.jl`. Test sites continue
to call them as `ModelHamiltonians.ising(...)` etc.

**What was deleted entirely (no consumers):**
- `delta_network` (and the rest of `src/specialitensornetworks.jl`) —
only consumer was `ModelNetworks.ising_network`, which itself had no
consumers.
- `ModelHamiltonians.hubbard` — no consumers.
- `src/lib/ModelNetworks/` (`ising_network`, `ising_network_state`) — no
consumers; the lone `using ITensorNetworks.ModelNetworks: ModelNetworks`
in `test/test_belief_propagation.jl` was an unused import and was
dropped.
- `random_ttn` / `random_mps` jldoctest examples in `src/normalize.jl`,
`src/expect.jl`, `src/treetensornetworks/abstracttreetensornetwork.jl`,
plus `[ref]` links in `See also:` lists. Consistent with not having doc
examples that depend on functions being removed.

**Construction pattern**

The `random_tensornetwork` helpers in `test/utils.jl` are factored
through a private `_random_tensornetwork(s::IndsNetwork, build_tensor;
link_space)` that uses the explicit Dict-of-ITensor pattern: build a
`Dict{Edge, Index}` of fresh link indices over `edges(s)` (mirrored
under `reverse(e)`); for each vertex, gather the site indices from
`vertex_data(s)[v]` (or empty if `v` has no entry) plus the link indices
on incident edges; let the caller-supplied `build_tensor` produce the
per-vertex `ITensor`; wrap with the basic `ITensorNetwork(::Dict{V,
ITensor})` constructor. The 12 user-facing `random_tensornetwork` method
specializations and their `IsUnderlyingGraph` trait wrappers route
through this helper.

**Documentation**
- `docs/src/{computing_properties,solvers}.md` setup blocks now build a
small inline `random_state(g, s; link_space)` helper using the same
Dict-of-ITensor pattern, instead of calling `random_ttn`. `link_space`
is required (no default), passed explicitly at the call sites.
- `docs/src/tree_tensor_networks.md` drops the `random_ttn` /
`random_mps` constructor examples and autodoc entries.
- `docs/src/reference.md`'s `@autodocs` listing trimmed to just
`ITensorNetworks` (no longer pulling in the removed `ModelNetworks` /
`ModelHamiltonians` submodules).

**Incidental import cleanups**

A few imports were previously available inside `ITensorNetworks` as a
side effect of the deleted files' `using` clauses; now imported
directly:
- `ITensors: delta` — `src/formnetworks/bilinearformnetwork.jl`,
`src/caches/abstractbeliefpropagationcache.jl`

**Version + test deps**

- Bump to `0.19.0` (pre-1.0 minor bump = breaking, public API removed).
- Update pinned `ITensorNetworks` compat in `test/`, `docs/`,
`examples/` Project.toml.
- Add `SimpleTraits` to `test/Project.toml` so `test/utils.jl` can use
`@traitfn` / `IsUnderlyingGraph`.

---------

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.18.1"
+version = "0.19.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.18"
+ITensorNetworks = "0.19"
 ITensors = "0.9"
 Literate = "2.20.1"
 NamedGraphs = "0.8.2"

docs/src/computing_properties.md

@@ -1,17 +1,29 @@
 # Computing Properties
 
 ```@setup main
-using Graphs: vertices
-using ITensorNetworks: expect, inner, loginner, normalize, random_ttn, siteinds
+using Graphs: edges, vertices
+using ITensorNetworks: ITensorNetwork, expect, inner, loginner, normalize, siteinds, ttn
+using ITensors: Index, random_itensor
 using LinearAlgebra: norm
+using NamedGraphs.GraphsExtensions: incident_edges
 using NamedGraphs.NamedGraphGenerators: named_grid
 
+function random_state(g, s; link_space)
+    l = Dict(e => Index(link_space, "Link") for e in edges(g))
+    l = merge(l, Dict(reverse(e) => l[e] for e in edges(g)))
+    ts = Dict(
+        v => random_itensor(only(s[v]), (l[e] for e in incident_edges(g, v))...)
+            for v in vertices(g)
+    )
+    return ITensorNetwork(ts)
+end
+
 g = named_grid((4,))
 s = siteinds("S=1/2", g)
-phi = normalize(random_ttn(s; link_space = 2))
-psi = normalize(random_ttn(s; link_space = 2))
-x = normalize(random_ttn(s; link_space = 2))
-y = normalize(random_ttn(s; link_space = 2))
+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)))
 v = first(vertices(psi))
 ```
 

docs/src/reference.md

@@ -1,8 +1,7 @@
 # API Reference
 
-Complete listing of all documented public functions and types in ITensorNetworks.jl,
-ITensorNetworks.ModelNetworks, and ITensorNetworks.ModelHamiltonians.
+Complete listing of all documented public functions and types in ITensorNetworks.jl.
 
 ```@autodocs
-Modules = [ITensorNetworks, ITensorNetworks.ModelNetworks, ITensorNetworks.ModelHamiltonians]
+Modules = [ITensorNetworks]
 ```

docs/src/solvers.md

@@ -16,10 +16,22 @@ variational sweep algorithm.
 [`dmrg`](@ref ITensorNetworks.dmrg) is an alias for `eigsolve`.
 
 ```@example main
-using ITensorNetworks: dmrg, dst, edges, normalize, random_ttn, siteinds, src, ttn
-using ITensors: OpSum
+using Graphs: vertices
+using ITensorNetworks: ITensorNetwork, dmrg, dst, edges, normalize, siteinds, src, ttn
+using ITensors: Index, OpSum, random_itensor
+using NamedGraphs.GraphsExtensions: incident_edges
 using NamedGraphs.NamedGraphGenerators: named_comb_tree
 
+function random_state(g, s; link_space)
+    l = Dict(e => Index(link_space, "Link") for e in edges(g))
+    l = merge(l, Dict(reverse(e) => l[e] for e in edges(g)))
+    ts = Dict(
+        v => random_itensor(only(s[v]), (l[e] for e in incident_edges(g, v))...)
+            for v in vertices(g)
+    )
+    return ITensorNetwork(ts)
+end
+
 # Build a Heisenberg Hamiltonian on a comb tree
 g = named_comb_tree((3, 2))
 s = siteinds("S=1/2", g)
@@ -33,7 +45,7 @@ H = let h = OpSum()
 end
 
 # Random initial state (normalise first!)
-psi0 = normalize(random_ttn(s; link_space = 2))
+psi0 = normalize(ttn(random_state(g, s; link_space = 2)))
 
 # Run DMRG
 energy, psi = dmrg(H, psi0;

docs/src/tree_tensor_networks.md

@@ -21,7 +21,7 @@ and provides a convenient interface for 1D calculations.
 ```@example main
 using Graphs: vertices
 using ITensorNetworks: ITensorNetwork, TreeTensorNetwork, mps, ortho_region, orthogonalize,
-    random_mps, random_ttn, siteinds, ttn
+    siteinds, ttn
 using ITensors: ITensors
 using LinearAlgebra: norm
 using NamedGraphs.NamedGraphGenerators: named_comb_tree
@@ -33,20 +33,14 @@ sites = siteinds("S=1/2", g)
 psi = ttn(sites)  # zero-initialised
 psi = ttn(v -> "Up", sites)  # product state
 
-# Random TTN
-psi = random_ttn(sites; link_space = 2)
-
 # 1D MPS
 s1d = siteinds("S=1/2", 6)
 mps_state = mps(v -> "Up", s1d)  # product MPS
-mps_state = random_mps(s1d; link_space = 2)
 ```
 
 ```@docs; canonical=false
 ITensorNetworks.ttn
 ITensorNetworks.mps
-ITensorNetworks.random_ttn
-ITensorNetworks.random_mps
 ```
 
 ### The `TreeTensorNetwork` type and conversion

examples/Project.toml

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

src/ITensorNetworks.jl

@@ -14,7 +14,6 @@ include("contraction_sequences.jl")
 include("tebd.jl")
 include("itensornetwork.jl")
 include("contract.jl")
-include("specialitensornetworks.jl")
 include("partitioneditensornetwork.jl")
 include("edge_sequences.jl")
 include("caches/abstractbeliefpropagationcache.jl")
@@ -63,7 +62,5 @@ include("normalize.jl")
 include("expect.jl")
 include("environment.jl")
 include("exports.jl")
-include("lib/ModelHamiltonians/src/ModelHamiltonians.jl")
-include("lib/ModelNetworks/src/ModelNetworks.jl")
 
 end

src/caches/abstractbeliefpropagationcache.jl

@@ -1,6 +1,6 @@
 using Adapt: Adapt, adapt, adapt_structure
 using Graphs: Graphs, IsDirected
-using ITensors: dir
+using ITensors: delta, dir
 using LinearAlgebra: diag, dot
 using NDTensors: NDTensors
 using NamedGraphs.PartitionedGraphs: PartitionedGraph, PartitionedGraphs, QuotientVertex,

src/expect.jl

@@ -97,23 +97,6 @@ vertex of `ψ`.
 
 A `Dictionary` mapping each vertex of `ψ` to its expectation value.
 
-# Example
-
-```jldoctest
-julia> using NamedGraphs.NamedGraphGenerators: named_grid
-
-julia> g = named_grid((4,));
-
-julia> s = siteinds("S=1/2", g);
-
-julia> psi = random_ttn(s; link_space = 2);
-
-julia> sz = expect(psi, "Sz");
-
-julia> sz_exact = expect(psi, "Sz"; alg = "exact");
-
-```
-
 See also: [`expect(ψ, op::String, vertices)`](@ref),
 [`expect(operator, state::AbstractTreeTensorNetwork)`](@ref).
 """