Conversation
leburgel
marked this pull request as draft
August 31, 2026 14:18
leburgel
changed the title
expectation_value implementationexpectation_value implementations
This was referenced Sep 2, 2026
…sion through reduced density matrix
…reduced density operators
- Reorganize file structure - Refactor in terms of generic expression generators that can be easily overloaded
Member
|
I'll try coming up with a source tree of expectation-value-related functions to better discuss where each function should be placed. |
Yue-Zhengyuan
left a comment
Yue-Zhengyuan
left a comment
Member
There was a problem hiding this comment.
First-round comments focusing on docstring inconsistencies.
Member
|
Some files put too many things together in my opinion. I would like to suggest the following source tree: Detailssrc/
└── algorithms/
├── expectation_value.jl
│ ├── local_expectation_value(inds, bra, operator::AbstractTensorMap, ket, env)
│ │ local_expectation_value(inds, state, operator::AbstractTensorMap, env)
│ │ Select the evaluation strategy by operator type; evaluate the current dense-operator implementation through a reduced density matrix.
│ │
│ └── MPSKit.expectation_value(bra::S, O::LocalOperator, ket::S, env) where {S<:InfiniteState}
│ MPSKit.expectation_value(peps::InfinitePEPS, O::LocalOperator, env)
│ MPSKit.expectation_value(state::InfinitePEPO, O::LocalOperator, env)
│ MPSKit.expectation_value(pf::InfinitePartitionFunction, op::Pair{CartesianIndex{2},<:AbstractTensorMap{T,S,2,2}}, env) where {T,S}
│ MPSKit.expectation_value(pf::InfinitePartitionFunction, op::Pair{Tuple{Int,Int}}, env)
│ Delegate each LocalOperator term to local_expectation_value and sum the results, or evaluate a local tensor insertion in a partition function.
│
├── reduced_densitymatrix.jl
│ └── reduced_densitymatrix(inds::Vector{CartesianIndex{2}}, ket::InfinitePEPS, bra::InfinitePEPS, env)
│ reduced_densitymatrix(inds, ket::InfinitePEPS, env)
│ reduced_densitymatrix(inds::Vector{CartesianIndex{2}}, state::InfinitePEPO, env)
│ reduced_densitymatrix(inds::Vector{CartesianIndex{2}}, ket::InfinitePEPO, bra::InfinitePEPO, env)
│ reduced_densitymatrix(inds::NTuple{N,CartesianIndex{2}}, args...) where {N} [deprecated]
│ reduced_densitymatrix(inds::NTuple{N,Tuple{Int,Int}}, args...) where {N} [deprecated]
│ Select an optimized density-matrix contraction when available, otherwise construct a normalized density matrix with _contract_densitymatrix.
│
├── contractions/
│ ├── tensor_traces.jl
│ │ ├── _str(::Bosonic, t::AbstractTensorMap)
│ │ │ _str(::Fermionic, t::AbstractTensorMap{<:Any,<:Any,N,N}) where {N}
│ │ │ Dispatch the trace calculation on bosonic or fermionic braiding style.
│ │ │
│ │ ├── str(t::AbstractTensorMap)
│ │ │ Compute the ordinary trace for bosonic tensors and the supertrace for fermionic tensors.
│ │ │
│ │ └── trmul(H::AbstractTensorMap{<:Any,S,N,N}, ρ::AbstractTensorMap{<:Any,S,N,N}) where {S,N}
│ │ Contract an operator with a density matrix without materializing their product.
│ │
│ ├── absorb.jl
│ │ ├── absorb_left(A::AbstractTensorMap{<:Any,S}, C::AbstractTensorMap{<:Any,S,1,1}) where {S}
│ │ │ absorb_left(P::AbstractTensorMap{<:Any,S,1,N}, C::AbstractTensorMap{<:Any,S,1,1}) where {S,N}
│ │ │ Contract a matrix into the leftmost leg of a tensor.
│ │ │
│ │ ├── absorb_right(A::AbstractTensorMap{<:Any,S}, C::AbstractTensorMap{<:Any,S,1,1}) where {S}
│ │ │ absorb_right(E::AbstractTensorMap{<:Any,S,N,1}, C::AbstractTensorMap{<:Any,S,1,1}) where {S,N}
│ │ │ Contract a matrix into the rightmost leg of a tensor.
│ │ │
│ │ └── absorb_left_right(T::AbstractTensorMap{<:Any,S}, CL::AbstractTensorMap{<:Any,S,1,1}, CR::AbstractTensorMap{<:Any,S,1,1}) where {S}
│ │ Contract matrices into both outer legs of a tensor.
│ │
│ ├── bp_messages.jl
│ │ ├── absorb_north_message(A::PEPSTensor, M::PEPSMessage)
│ │ │ Absorb a north BP message into a PEPS tensor.
│ │ │
│ │ ├── absorb_east_message(A::PEPSTensor, M::PEPSMessage)
│ │ │ Absorb an east BP message into a PEPS tensor.
│ │ │
│ │ ├── absorb_south_message(A::PEPSTensor, M::PEPSMessage)
│ │ │ Absorb a south BP message into a PEPS tensor.
│ │ │
│ │ ├── absorb_west_message(A::PEPSTensor, M::PEPSMessage)
│ │ │ Absorb a west BP message into a PEPS tensor.
│ │ │
│ │ ├── contract_north_message(A::PEPSSandwich, M_west::PEPSMessage, M_north::PEPSMessage, M_east::PEPSMessage)
│ │ │ Update the BP message leaving a site toward the north.
│ │ │
│ │ ├── contract_east_message(A::PEPSSandwich, M_north::PEPSMessage, M_east::PEPSMessage, M_south::PEPSMessage)
│ │ │ Update the BP message leaving a site toward the east.
│ │ │
│ │ ├── contract_south_message(A::PEPSSandwich, M_east::PEPSMessage, M_south::PEPSMessage, M_west::PEPSMessage)
│ │ │ Update the BP message leaving a site toward the south.
│ │ │
│ │ └── contract_west_message(A::PEPSSandwich, M_south::PEPSMessage, M_west::PEPSMessage, M_north::PEPSMessage)
│ │ Update the BP message leaving a site toward the west.
│ │
│ ├── local_patch/
│ │ ├── expr_utils.jl
│ │ │ ├── tensorlabel(args...)
│ │ │ │ Join label components into a tensor-contraction symbol.
│ │ │ │
│ │ │ ├── envlabel(args...)
│ │ │ │ Construct an environment-leg label.
│ │ │ │
│ │ │ ├── virtuallabel(args...)
│ │ │ │ Construct a state virtual-leg label.
│ │ │ │
│ │ │ ├── physicallabel(args...)
│ │ │ │ Construct a physical-leg label.
│ │ │ │
│ │ │ ├── _open_slot(open, r, c)
│ │ │ │ Return the operator slot assigned to a patch site.
│ │ │ │
│ │ │ ├── _bulk_virtuallabels(i, j, layer, gridsize)
│ │ │ │ Return the north, east, south, and west labels of one bulk tensor.
│ │ │ │
│ │ │ ├── _patch_inds(inds::Type)
│ │ │ │ _patch_inds(inds::Tuple{Vararg{Val}})
│ │ │ │ Recover and validate patch coordinates encoded in Val parameters.
│ │ │ │
│ │ │ ├── _patch_ranges(sites)
│ │ │ │ Return the row and column ranges spanned by patch sites.
│ │ │ │
│ │ │ ├── _patch_gridsize(sites)
│ │ │ │ Return the rectangular dimensions spanned by patch sites.
│ │ │ │
│ │ │ └── _patch_shape_string(sites)
│ │ │ Format the rectangular patch dimensions for diagnostics.
│ │ │
│ │ ├── network_expr.jl
│ │ │ ├── contractcheck(state::Type)
│ │ │ │ contractcheck(::Type{<:InfinitePEPO})
│ │ │ │ contractcheck(::Type{<:Tuple{Vararg{InfinitePEPO}}})
│ │ │ │ Select whether tensor-space compatibility is checked for a state representation.
│ │ │ │
│ │ │ ├── _tensor_expr(prod, lhs, check::Bool)
│ │ │ │ Assemble indexed tensor expressions into an optimized `@tensor` contraction.
│ │ │ │
│ │ │ ├── boundary_contraction_expr(env::Type, rowrange, colrange)
│ │ │ │ boundary_contraction_expr(::Type{<:CTMRGEnv{C,T}}, rowrange, colrange) where {C,T}
│ │ │ │ Generate indexed CTMRG boundary tensor expressions for an `@tensor` contraction, or report that an environment implementation is unavailable.
│ │ │ │
│ │ │ ├── bulk_contraction_expr(state::Type, rowrange, colrange, open)
│ │ │ │ bulk_contraction_expr(::Type{<:Tuple{InfinitePEPS,InfinitePEPS}}, rowrange, colrange, open)
│ │ │ │ bulk_contraction_expr(::Type{<:InfinitePEPO}, rowrange, colrange, open)
│ │ │ │ bulk_contraction_expr(::Type{<:Tuple{InfinitePEPO,InfinitePEPO}}, rowrange, colrange, open)
│ │ │ │ bulk_contraction_expr(state::Type{<:Tuple{Vararg{InfinitePEPO}}}, rowrange, colrange, open)
│ │ │ │ Generate indexed PEPS or PEPO tensor expressions for the patch interior, or report that a state implementation is unavailable.
│ │ │ │
│ │ │ └── operator_contraction_expr(operator::Type, nsites)
│ │ │ operator_contraction_expr(::Type{<:AbstractTensorMap}, nsites)
│ │ │ Generate an indexed dense-operator expression for an `@tensor` contraction, or report that an operator implementation is unavailable.
│ │ │
│ │ ├── patch_contractions.jl
│ │ │ ├── _contract_local_operator(inds::NTuple{N,Val}, operator, state, env) where {N}
│ │ │ │ Assemble and execute the unnormalized operator-inserted patch contraction for direct evaluation.
│ │ │ │
│ │ │ ├── contract_local_operator(inds::Vector{CartesianIndex{2}}, O, ket::InfinitePEPS, bra::InfinitePEPS, env)
│ │ │ │ contract_local_operator(inds::Vector{CartesianIndex{2}}, O, state::InfinitePEPO, env)
│ │ │ │ contract_local_operator(inds::Vector{CartesianIndex{2}}, O, ket::InfinitePEPO, bra::InfinitePEPO, env)
│ │ │ │ contract_local_operator(inds::Vector{Tuple{Int,Int}}, O, args...)
│ │ │ │ contract_local_operator(inds::NTuple, args...) [deprecated]
│ │ │ │ Validate the inputs and invoke the generated direct contraction for an operator insertion.
│ │ │ │
│ │ │ ├── _contract_local_norm(inds::NTuple{N,Val}, state, env) where {N}
│ │ │ │ Assemble and execute the corresponding patch-normalization contraction with closed physical legs.
│ │ │ │
│ │ │ └── contract_local_norm(inds::Vector{CartesianIndex{2}}, ket::InfinitePEPS, bra::InfinitePEPS, env)
│ │ │ contract_local_norm(inds::Vector{CartesianIndex{2}}, state::InfinitePEPO, env)
│ │ │ contract_local_norm(inds::Vector{CartesianIndex{2}}, ket::InfinitePEPO, bra::InfinitePEPO, env)
│ │ │ contract_local_norm(inds::Vector{Tuple{Int,Int}}, args...)
│ │ │ contract_local_norm(inds::NTuple, ket::InfinitePEPS, bra::InfinitePEPS, env) [deprecated]
│ │ │ Validate the inputs and invoke the generated direct contraction used to normalize an operator insertion.
│ │ │
│ │ └── densitymatrix/
│ │ ├── generic.jl
│ │ │ └── _contract_densitymatrix(inds::NTuple{N,Val}, state, env) where {N}
│ │ │ Assemble and execute a generated patch contraction with open physical legs.
│ │ │
│ │ ├── ctmrg.jl
│ │ │ ├── reduced_densitymatrix1x1(ind::CartesianIndex{2}, ket::InfinitePEPS, bra::InfinitePEPS, env::CTMRGEnv)
│ │ │ │ Contract an optimized one-site PEPS density matrix using a CTMRG environment.
│ │ │ │
│ │ │ ├── reduced_densitymatrix2x1(ind::CartesianIndex, ket::InfinitePEPS, bra::InfinitePEPS, env::CTMRGEnv)
│ │ │ │ Contract an optimized vertical two-site PEPS density matrix using a CTMRG environment.
│ │ │ │
│ │ │ └── reduced_densitymatrix1x2(ind::CartesianIndex, ket::InfinitePEPS, bra::InfinitePEPS, env::CTMRGEnv)
│ │ │ Contract an optimized horizontal two-site PEPS density matrix using a CTMRG environment.
│ │ │
│ │ └── bp.jl
│ │ ├── _contract_densitymatrix(inds::NTuple{N,Val}, state, env::BPEnv) where {N}
│ │ │ Reject patch geometries that cannot be represented by local BP messages.
│ │ │
│ │ ├── reduced_densitymatrix1x1(ind::CartesianIndex{2}, ket::InfinitePEPS, bra::InfinitePEPS, env::BPEnv)
│ │ │ Contract a one-site PEPS density matrix using BP messages.
│ │ │
│ │ ├── reduced_densitymatrix2x1(coord::CartesianIndex{2}, ket::InfinitePEPS, bra::InfinitePEPS, env::BPEnv)
│ │ │ Contract a vertical two-site PEPS density matrix using BP messages.
│ │ │
│ │ └── reduced_densitymatrix1x2(coord::CartesianIndex{2}, ket::InfinitePEPS, bra::InfinitePEPS, env::BPEnv)
│ │ Contract a horizontal two-site PEPS density matrix using BP messages.
│ │
│ └── ctmrg/
│ └── network_value.jl
│ ├── _contract_site(ind::Tuple{Int,Int}, network, env::CTMRGEnv)
│ │ _contract_site(C_northwest, C_northeast, C_southeast, C_southwest, E_north::CTMRG_PEPS_EdgeTensor, E_east::CTMRG_PEPS_EdgeTensor, E_south::CTMRG_PEPS_EdgeTensor, E_west::CTMRG_PEPS_EdgeTensor, O::PEPSSandwich)
│ │ _contract_site(C_northwest, C_northeast, C_southeast, C_southwest, E_north::CTMRG_PF_EdgeTensor, E_east::CTMRG_PF_EdgeTensor, E_south::CTMRG_PF_EdgeTensor, E_west::CTMRG_PF_EdgeTensor, O::PFTensor)
│ │ _contract_site(C_northwest, C_northeast, C_southeast, C_southwest, E_north::TE, E_east::TE, E_south::TE, E_west::TE, O::PEPOSandwich{H}) where {TE<:CTMRGEdgeTensor,H}
│ │ Contract one network site with its surrounding CTMRG corners and edges.
│ │
│ ├── _contract_corners(ind::Tuple{Int,Int}, env::CTMRGEnv)
│ │ _contract_corners(C_northwest::CTMRGCornerTensor, C_northeast::CTMRGCornerTensor, C_southeast::CTMRGCornerTensor, C_southwest::CTMRGCornerTensor)
│ │ Contract four CTMRG corners for network-value normalization.
│ │
│ ├── _contract_vertical_edges(ind::Tuple{Int,Int}, env::CTMRGEnv)
│ │ _contract_vertical_edges(C_northwest::CTMRGCornerTensor, C_northeast::CTMRGCornerTensor, C_southeast::CTMRGCornerTensor, C_southwest::CTMRGCornerTensor, E_east::CTMRGEdgeTensor{T,S,N}, E_west::CTMRGEdgeTensor{T,S,N}) where {T,S,N}
│ │ Contract two vertical edges and four corners for network-value normalization.
│ │
│ ├── _contract_horizontal_edges(ind::Tuple{Int,Int}, env::CTMRGEnv)
│ │ _contract_horizontal_edges(C_northwest::CTMRGCornerTensor, C_northeast::CTMRGCornerTensor, C_southeast::CTMRGCornerTensor, C_southwest::CTMRGCornerTensor, E_north::CTMRGEdgeTensor{T,S,N}, E_south::CTMRGEdgeTensor{T,S,N}) where {T,S,N}
│ │ Contract two horizontal edges and four corners for network-value normalization.
│ │
│ ├── network_value(network::InfiniteSquareNetwork, env::CTMRGEnv)
│ │ network_value(state, env::CTMRGEnv)
│ │ Evaluate the normalized value per unit cell of an infinite square network.
│ │
│ └── LinearAlgebra.norm(peps::InfinitePEPS, env::CTMRGEnv)
│ Evaluate the CTMRG norm of an infinite PEPS.
│
└── optimization/
└── peps_optimization.jl
└── cost_function(peps::InfinitePEPS, env, O::LocalOperator)
Return the real part of an expectation value as the PEPS optimization cost. |
lkdvos
reviewed
Sep 9, 2026
Member
Author
I did the reorganization mostly as suggested: Updated file treeThe only notable differences are that:
Happy to reorganize further, or more thoroughly if we no longer like the use of the |
Yue-Zhengyuan
left a comment
Yue-Zhengyuan
left a comment
Member
There was a problem hiding this comment.
Some code extensibility issues involving custom environment types discovered by Codex. Again, we need to explain why supertrace instead of trace occurs in expectation values.
I'm in favor of putting the low-level contractions beside the algorithm that uses it, instead of collecting them all together. But this can be deferred to a follow up.
| Contract a local norm corresponding to the overlap `ket` and `bra` states, computing a patch | ||
| of `⟨bra|ket⟩`, where `ket` and `bra` correspond to either a PEPS or a PEPO representing a | ||
| PEPS with ancillary legs. | ||
| Alternatively, contract a local norm patch of a density matrix PEPO `state`, computing a patch of `tr(state)`. |
Member
There was a problem hiding this comment.
I changed this back to ordinary trace. The RDM is using str only because we manually added twist on the 2nd codomain index of each iPEPO tensor.
Yue-Zhengyuan
approved these changes
Sep 21, 2026
Yue-Zhengyuan
left a comment
Yue-Zhengyuan
left a comment
Member
There was a problem hiding this comment.
Ready for merge after #429 and updating to the new test format.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Some refactoring and reorganization related to the evaluation of expectation values. The main motivation for this refactor is making it easier to add support for computing expectation values of different kinds of operators, and evaluate these using different kinds of environments. Some examples of this are given in #425 and #426, which are built on top of this refactor.
Short summary:
local_expectation_valuemethod to catch local expectation values for different kinds of operators. This goes through thereduced_densitymatrixapproach forAbstractTensorMaplocal terms, but can follow a different path for different kinds of local terms (see for example [WIP] Add support for local expectation values of tensor product and MPO terms #425).BPEnvexpectation values via reduced density matrix contraction along the genericAbstractTensorMappath, by specializing the appropriate methods.boundary_contraction_expr,bulk_contraction_exproroperator_contraction_expr.