Rename *_norm_messagecache to *_norm_message_env; add norm_message_env

Reserve `messagecache` (and `MessageCache`) for the low-level data-structure
constructors; use `_message_env` for the domain-level environment builders.
Renames apply to all five constructors:

  similar_norm_messagecache  -> similar_norm_message_env
  identity_norm_messagecache -> identity_norm_message_env
  ones_norm_messagecache     -> ones_norm_message_env
  randn_norm_messagecache    -> randn_norm_message_env
  rand_norm_messagecache     -> rand_norm_message_env

Introduce norm_message_env(f, tn) as the shared filler: it allocates via
similar_norm_message_env, applies f to each entry, returns the cache. The
identity / ones / randn / rand variants are now one-liners delegating to
it. The eventual interface is `*_message_env(NormNetwork(tn))`; for now
the network is encoded in the `_norm_` infix until the NormNetwork type
lands. A parallel `*_norm_ctm_env` family is planned for CTMRG.

Test imports, in-test constructor list, and testset name updated.
beliefpropagation_normnetwork docstring cross-refs updated.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: mtfishman

src/beliefpropagation/normnetwork.jl

@@ -5,106 +5,101 @@ using NamedDimsArrays:
 using NamedGraphs.GraphsExtensions: all_edges, incident_edges
 using Random: Random
 
-# === MessageCache constructors keyed to the norm network ⟨tn|tn⟩ ===
+# === Norm-network environment constructors ===
+#
+# `*_norm_message_env(tn)` builds a `MessageCache` shaped to act as the BP environment
+# for the norm network ⟨tn|tn⟩, with each entry filled per the leading verb (`identity`,
+# `ones`, `randn`, `rand`). The `_env` suffix is reserved for the high-level
+# environment-builder interface; the low-level `MessageCache` / `messagecache(...)`
+# constructors are used internally. A parallel `*_norm_ctm_env` family is planned for
+# CTMRG environments.
 
 """
-    similar_norm_messagecache(tn) -> MessageCache
-
-Allocate a `MessageCache` of square operator messages with **undefined** data, one per
-directed edge of the undirected graph of `tn` (both directions on every undirected edge).
-Each message's codomain is the link axes on that edge in `tn`; the domain has dual axes
-with fresh `randname`-generated names. The element type and backend are inherited from
-the factor tensors of `tn` via `Base.similar`.
-
-This is the allocator that backs the filled-cache constructors
-(`identity_norm_messagecache`, `ones_norm_messagecache`, `randn_norm_messagecache`).
-Use it directly to construct caches with custom message data, e.g. by mutating each
-entry after allocation.
+    similar_norm_message_env(tn) -> MessageCache
+
+Allocate a BP environment for the norm network ⟨tn|tn⟩ with **undefined** message data:
+one square operator message per directed edge of `tn` (both directions on every
+undirected edge). Each message's codomain is the link axes on that edge in `tn`; the
+domain has dual axes with fresh `randname`-generated names. Element type and backend are
+inherited from the factor tensors of `tn` via `Base.similar`.
+
+Used internally by [`norm_message_env`](@ref) and the filled environment constructors
+([`identity_norm_message_env`](@ref), [`ones_norm_message_env`](@ref),
+[`randn_norm_message_env`](@ref), [`rand_norm_message_env`](@ref)). Use it directly to
+construct environments with custom message data, e.g. by mutating each entry after
+allocation.
 """
-function similar_norm_messagecache(tn)
+function similar_norm_message_env(tn)
     return messagecache(all_edges(tn)) do e
         return similar_operator(tn[src(e)], linkinds(tn, e))
     end
 end
 
 """
-    identity_norm_messagecache(tn) -> MessageCache
+    norm_message_env(f, tn) -> MessageCache
 
-Allocate a `MessageCache` of identity-operator messages, one per directed edge of `tn`.
-Each message acts as the identity map on the link axis for its edge — the
-"uncorrelated environment" starting point for belief-propagation simple-update gauging
-on the norm network ⟨tn|tn⟩.
-
-See also: [`ones_norm_messagecache`](@ref), [`randn_norm_messagecache`](@ref),
-[`rand_norm_messagecache`](@ref), [`similar_norm_messagecache`](@ref).
-"""
-function identity_norm_messagecache(tn)
-    m = similar_norm_messagecache(tn)
-    # `one_operator` is held locally in `tensoralgebra.jl` and would become
-    # `Base.one(::AbstractNamedDimsOperator)` once that lands upstream.
-    # TODO: replace with `map(one_operator, m)` once `map` is defined on `MessageCache`.
-    foreach(e -> m[e] = one_operator(m[e]), edges(m))
-    return m
+Allocate a norm-network BP environment via [`similar_norm_message_env`](@ref) and apply
+`f` to each operator-message entry. Shared building block for the filled-environment
+constructors.
+"""
+function norm_message_env(f, tn)
+    env = similar_norm_message_env(tn)
+    # TODO: replace with `map(f, env)` once `map` is defined on `MessageCache`.
+    foreach(e -> env[e] = f(env[e]), edges(env))
+    return env
 end
 
 """
-    ones_norm_messagecache(tn) -> MessageCache
+    identity_norm_message_env(tn) -> MessageCache
 
-Allocate a `MessageCache` whose per-edge messages have every entry equal to `1`. Each
-message is the rank-1 outer product of all-ones vectors on the (codomain, domain) link
-axes.
+Build a norm-network BP environment with identity-operator messages on every edge — the
+"uncorrelated environment" starting point for belief-propagation simple-update gauging
+on ⟨tn|tn⟩.
 
-See also: [`identity_norm_messagecache`](@ref), [`randn_norm_messagecache`](@ref),
-[`rand_norm_messagecache`](@ref).
+See also: [`ones_norm_message_env`](@ref), [`randn_norm_message_env`](@ref),
+[`rand_norm_message_env`](@ref), [`similar_norm_message_env`](@ref).
 """
-function ones_norm_messagecache(tn)
-    m = similar_norm_messagecache(tn)
-    # TODO: replace with `map(msg -> fill!(msg, one(eltype(msg))), m)` once `map`
-    # is defined on `MessageCache`.
-    foreach(e -> m[e] = fill!(m[e], one(eltype(m[e]))), edges(m))
-    return m
-end
+identity_norm_message_env(tn) = norm_message_env(one_operator, tn)
+
+"""
+    ones_norm_message_env(tn) -> MessageCache
+
+Build a norm-network BP environment whose per-edge messages have every entry equal to
+`1` — the rank-1 outer product of all-ones vectors on each (codomain, domain) pair.
+
+See also: [`identity_norm_message_env`](@ref), [`randn_norm_message_env`](@ref),
+[`rand_norm_message_env`](@ref).
+"""
+ones_norm_message_env(tn) = norm_message_env(msg -> fill!(msg, one(eltype(msg))), tn)
 
-randn_norm_messagecache(tn) = randn_norm_messagecache(Random.default_rng(), tn)
+randn_norm_message_env(tn) = randn_norm_message_env(Random.default_rng(), tn)
 
 """
-    randn_norm_messagecache([rng], tn) -> MessageCache
+    randn_norm_message_env([rng], tn) -> MessageCache
 
-Allocate a `MessageCache` whose per-edge messages have entries drawn from a standard
-normal distribution. `rng` defaults to `Random.default_rng()`.
+Build a norm-network BP environment whose per-edge messages have entries drawn from a
+standard normal distribution. `rng` defaults to `Random.default_rng()`.
 
-See also: [`rand_norm_messagecache`](@ref), [`identity_norm_messagecache`](@ref),
-[`ones_norm_messagecache`](@ref).
+See also: [`rand_norm_message_env`](@ref), [`identity_norm_message_env`](@ref),
+[`ones_norm_message_env`](@ref).
 """
-function randn_norm_messagecache(rng::Random.AbstractRNG, tn)
-    m = similar_norm_messagecache(tn)
-    # `randn_operator!` is held locally in `tensoralgebra.jl`; would become a
-    # method of `Random.randn!` once that lands upstream.
-    # TODO: replace with `map(msg -> randn_operator!(rng, msg), m)` once `map` is
-    # defined on `MessageCache`.
-    foreach(e -> randn_operator!(rng, m[e]), edges(m))
-    return m
+function randn_norm_message_env(rng::Random.AbstractRNG, tn)
+    return norm_message_env(msg -> randn_operator!(rng, msg), tn)
 end
 
-rand_norm_messagecache(tn) = rand_norm_messagecache(Random.default_rng(), tn)
+rand_norm_message_env(tn) = rand_norm_message_env(Random.default_rng(), tn)
 
 """
-    rand_norm_messagecache([rng], tn) -> MessageCache
+    rand_norm_message_env([rng], tn) -> MessageCache
 
-Allocate a `MessageCache` whose per-edge messages have entries drawn from a uniform
-distribution on `[0, 1)`. `rng` defaults to `Random.default_rng()`.
+Build a norm-network BP environment whose per-edge messages have entries drawn from a
+uniform distribution on `[0, 1)`. `rng` defaults to `Random.default_rng()`.
 
-See also: [`randn_norm_messagecache`](@ref), [`identity_norm_messagecache`](@ref),
-[`ones_norm_messagecache`](@ref).
+See also: [`randn_norm_message_env`](@ref), [`identity_norm_message_env`](@ref),
+[`ones_norm_message_env`](@ref).
 """
-function rand_norm_messagecache(rng::Random.AbstractRNG, tn)
-    m = similar_norm_messagecache(tn)
-    # `rand_operator!` is held locally in `tensoralgebra.jl`; would become a
-    # method of `Random.rand!` once that lands upstream.
-    # TODO: replace with `map(msg -> rand_operator!(rng, msg), m)` once `map` is
-    # defined on `MessageCache`.
-    foreach(e -> rand_operator!(rng, m[e]), edges(m))
-    return m
+function rand_norm_message_env(rng::Random.AbstractRNG, tn)
+    return norm_message_env(msg -> rand_operator!(rng, msg), tn)
 end
 
 # === Double-layer construction and BP wrapper ===
@@ -144,7 +139,7 @@ end
 
 Run belief propagation on the norm network `⟨tn|tn⟩` (treating `tn` as the ket),
 starting from a pre-built operator `MessageCache` `messages` (e.g. from
-[`identity_norm_messagecache`](@ref) or any of the other `*_norm_messagecache`
+[`identity_norm_message_env`](@ref) or any of the other `*_norm_message_env`
 constructors).
 
 The norm network built by [`normnetwork`](@ref) is the source of truth for bra-link

test/test_apply_operator.jl

@@ -3,8 +3,8 @@ import NamedDimsArrays as NDA
 import TensorAlgebra as TA
 using ITensorBase: Index
 using ITensorNetworksNext: TensorNetwork, apply_operator, apply_operators,
-    beliefpropagation_normnetwork, identity_norm_messagecache, ones_norm_messagecache,
-    rand_norm_messagecache, randn_norm_messagecache, similar_norm_messagecache
+    beliefpropagation_normnetwork, identity_norm_message_env, ones_norm_message_env,
+    rand_norm_message_env, randn_norm_message_env, similar_norm_message_env
 using MatrixAlgebraKit: truncrank
 using NamedDimsArrays: name, operator, randname, setname
 using NamedGraphs.GraphsExtensions: incident_edges
@@ -48,7 +48,7 @@ end
         site_axes = Dict(v => Index(d) for v in Graphs.vertices(g))
         state = random_tensornetwork(g, link_axes, site_axes)
         env = beliefpropagation_normnetwork(
-            state, ones_norm_messagecache(state);
+            state, ones_norm_message_env(state);
             stopping_criterion = (; maxiter = 100, tol = 1.0e-13)
         )
         # Without truncation the gate is applied exactly, so the gated network
@@ -67,7 +67,7 @@ end
         site_axes = Dict(v => Index(d) for v in Graphs.vertices(g))
         state = random_tensornetwork(g, link_axes, site_axes)
         env = beliefpropagation_normnetwork(
-            state, ones_norm_messagecache(state);
+            state, ones_norm_message_env(state);
             stopping_criterion = (; maxiter = 100, tol = 1.0e-13)
         )
         gate = randn_operator((site_axes[2], site_axes[3]))
@@ -85,7 +85,7 @@ end
         site_axes = Dict(v => Index(d) for v in Graphs.vertices(g))
         state = random_tensornetwork(g, link_axes, site_axes)
         env = beliefpropagation_normnetwork(
-            state, ones_norm_messagecache(state);
+            state, ones_norm_message_env(state);
             stopping_criterion = (; maxiter = 100, tol = 1.0e-13)
         )
         # Gates on neighboring edges sharing site 3, applied in sequence.
@@ -95,7 +95,7 @@ end
         @test prod(gated) ≈ NDA.apply(g2, NDA.apply(g1, prod(state)))
     end
 
-    @testset "norm-messagecache constructors" begin
+    @testset "norm-message-env constructors" begin
         link_axes = Dict(e => Index(χ) for e in Graphs.edges(g))
         site_axes = Dict(v => Index(d) for v in Graphs.vertices(g))
         state = random_tensornetwork(g, link_axes, site_axes)
@@ -104,9 +104,9 @@ end
         # undirected edge of the state.
         n_directed = 2 * length(collect(Graphs.edges(g)))
         for ctor in (
-                similar_norm_messagecache, identity_norm_messagecache,
-                ones_norm_messagecache, randn_norm_messagecache,
-                rand_norm_messagecache,
+                similar_norm_message_env, identity_norm_message_env,
+                ones_norm_message_env, randn_norm_message_env,
+                rand_norm_message_env,
             )
             cache = ctor(state)
             @test length(collect(Graphs.edges(cache))) == n_directed
@@ -115,7 +115,7 @@ end
         # Identity env reproduces the gauge-invariant exact-gate property: an
         # untruncated gate gives the exact result regardless of which valid env we
         # gauge against.
-        env = identity_norm_messagecache(state)
+        env = identity_norm_message_env(state)
         for gate in (
                 randn_operator((site_axes[2],)),
                 randn_operator((site_axes[2], site_axes[3])),