Skip to content

Conversation

@pbrehmer
Copy link
Collaborator

@pbrehmer pbrehmer commented Jan 21, 2026

In this PR we will finally add a dedicated C4v CTMRG algorithm. I started with the standard version using eigh projectors but we can easily also implement a QR version by making a C4vQRProjector algorithm and the corresponding c4v_projector method. (@Yue-Zhengyuan said he would be up for doing this :-)) This C4v routine is completely differentiable using naive AD, :diffgauge and :fixed mode.

Note that I needed to generalize the gauge_fix method for CTMRGEnvs to not have separate methods for all the C4v stuff. Same thing is true for environment initialization, where it would be nice to have an initialize_environment method where one can dispatch on an algorithm. Here we'll have to wait until we merge #264.

Let me also say that it would eventually be nicer to have a dedicated C4vCTMRGEnv since this would make things cleaner. However, this would entail a larger rewrite of quite a few things, so I propose that I postpone this rewriting and cleaning up process until I have more resources for that again. (In general I feel like we should clean up and refactor some stuff again since the codebase has been growing quite a bit.) Anyways, for now it would be nice to have a working C4v CTMRG that people can use.

This is still very much under construction but I'll finish up things and adjust the test suite tomorrow.

Closes #258.

@pbrehmer pbrehmer self-assigned this Jan 21, 2026
@pbrehmer pbrehmer marked this pull request as draft January 21, 2026 19:12
@github-actions
Copy link
Contributor

github-actions bot commented Jan 22, 2026

Your PR no longer requires formatting changes. Thank you for your contribution!

@codecov
Copy link

codecov bot commented Jan 22, 2026

Codecov Report

❌ Patch coverage is 5.01792% with 265 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/utility/eigh.jl 0.00% 127 Missing ⚠️
src/algorithms/ctmrg/c4v.jl 0.00% 54 Missing ⚠️
...rithms/optimization/fixed_point_differentiation.jl 0.00% 38 Missing ⚠️
src/algorithms/ctmrg/gaugefix.jl 0.00% 35 Missing ⚠️
src/algorithms/ctmrg/projectors.jl 61.11% 7 Missing ⚠️
src/algorithms/select_algorithm.jl 50.00% 2 Missing ⚠️
src/algorithms/ctmrg/ctmrg.jl 50.00% 1 Missing ⚠️
src/environments/ctmrg_environments.jl 0.00% 1 Missing ⚠️
Files with missing lines Coverage Δ
src/Defaults.jl 85.71% <ø> (ø)
src/PEPSKit.jl 100.00% <ø> (ø)
src/algorithms/ctmrg/sequential.jl 87.30% <ø> (-11.12%) ⬇️
src/algorithms/ctmrg/simultaneous.jl 82.35% <ø> (-17.65%) ⬇️
src/utility/svd.jl 82.99% <ø> (-4.51%) ⬇️
src/algorithms/ctmrg/ctmrg.jl 83.60% <50.00%> (-6.87%) ⬇️
src/environments/ctmrg_environments.jl 47.09% <0.00%> (-34.41%) ⬇️
src/algorithms/select_algorithm.jl 17.39% <50.00%> (-57.61%) ⬇️
src/algorithms/ctmrg/projectors.jl 50.84% <61.11%> (-32.18%) ⬇️
src/algorithms/ctmrg/gaugefix.jl 0.00% <0.00%> (-97.23%) ⬇️
... and 3 more

... and 28 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Yue-Zhengyuan
Copy link
Member

This PR already involves lots of things. For QR CTMRG, besides getting projectors from QR instead of SVD, the way to enlarge corners is also different. Maybe we focus on the eigh version here only, and handle QR CTMRG in a separate PR.

@pbrehmer
Copy link
Collaborator Author

This PR already involves lots of things. For QR CTMRG, besides getting projectors from QR instead of SVD, the way to enlarge corners is also different. Maybe we focus on the eigh version here only, and handle QR CTMRG in a separate PR.

Completely agree, I anyway assumed this would go into a separate PR. Also I apologize for making this PR so big, I found it somewhat hard to split up the changes needed to make the whole apparatus compatible with C4v CTMRG.

@Yue-Zhengyuan
Copy link
Member

it would eventually be nicer to have a dedicated C4vCTMRGEnv since this would make things cleaner. However, this would entail a larger rewrite of quite a few things

One approach is to make C4vCTMRGEnv (and associated functions) independent from general CTMRG routines (behave like a self-sufficient submodule) for now and just provide a C4vCTMRGEnv-to-CTMRGEnv converter. At least the forward pass should be concise enough. We can think about reusing or rewriting existing CTMRG functions in later PRs. Does this still need a large rewrite?

@codecov
Copy link

codecov bot commented Jan 23, 2026

Codecov Report

❌ Patch coverage is 87.01299% with 40 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/utility/eigh.jl 83.21% 23 Missing ⚠️
src/algorithms/ctmrg/c4v.jl 79.41% 14 Missing ⚠️
src/algorithms/select_algorithm.jl 71.42% 2 Missing ⚠️
src/algorithms/ctmrg/projectors.jl 94.73% 1 Missing ⚠️
Files with missing lines Coverage Δ
src/Defaults.jl 85.71% <ø> (ø)
src/PEPSKit.jl 100.00% <ø> (ø)
src/algorithms/ctmrg/ctmrg.jl 90.76% <100.00%> (+0.29%) ⬆️
src/algorithms/ctmrg/gaugefix.jl 97.87% <100.00%> (+0.65%) ⬆️
src/algorithms/ctmrg/sequential.jl 98.41% <ø> (ø)
src/algorithms/ctmrg/simultaneous.jl 100.00% <ø> (ø)
...rithms/optimization/fixed_point_differentiation.jl 93.18% <100.00%> (+1.45%) ⬆️
src/environments/ctmrg_environments.jl 81.50% <100.00%> (ø)
src/utility/svd.jl 87.50% <ø> (ø)
src/algorithms/ctmrg/projectors.jl 83.33% <94.73%> (+0.31%) ⬆️
... and 3 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@pbrehmer
Copy link
Collaborator Author

One approach is to make C4vCTMRGEnv (and associated functions) independent from general CTMRG routines (behave like a self-sufficient submodule) for now and just provide a C4vCTMRGEnv-to-CTMRGEnv converter. At least the forward pass should be concise enough. We can think about reusing or rewriting existing CTMRG functions in later PRs. Does this still need a large rewrite?

I have thought about this but this would be rather annoying as an intermediate stage I think since it would break a lot of the general CTMRG functions that I use now leading to a lot of code duplication and extra work (that I don't really have time for at the moment). I'd rather do it once but properly. I hope that's fine!

@pbrehmer pbrehmer marked this pull request as ready for review January 26, 2026 17:06
@pbrehmer
Copy link
Collaborator Author

I think in principle the tests should run through now. Once we have merged #264 and some details have been settled, I will add a small example to the docs on how to use C4v CTMRG.

@Yue-Zhengyuan
Copy link
Member

Yue-Zhengyuan commented Jan 27, 2026

Since we are going to also introduce CTMRG on triangular lattices in #324 (which also has a C6v specialization), it may be better to reorganize files into sub-folders under src/algorithms/ctmrg.

  • square: The generic Sequential & Simultaneous CTMRG on the square lattice for any unit cell sizes.
  • c4v: The specialization with C4v symmetry and 1x1 unit cell, with projectors found from eigh.
  • c4vqr (TODO): The specialization with C4v symmetry and 1x1 unit cell, with projectors found from qr.
  • triangle (add Triangular CTMRG #324): The generic Simultaneous CTMRG on the triangular lattice for any unit cell sizes.
  • c6v and c6vqr: The specialization with C6v symmetry (for triangular or honeycomb lattice), with projectors found from eigh or qr.

Similarly, the pure contraction functions in src/algorithms/contractions/ctmrg_contractions.jl (this file is already painfully long) may also be split into several files under src/algorithms/contractions/ctmrg. (This can be done in later refactoring PRs).

Copy link
Member

@lkdvos lkdvos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall I don't think I have too many comments on this.
I definitely share your view that it is a rather large PR and that it sucks a bit to take on this much code debt, but I also don't actually have any suggestions as to how to avoid this without having to really start rewriting everything so I guess we just have to deal with this.

I would maybe try and clean up a little more, I don't think the QR stuff is working already right? Can we just not deal with that just yet, and instead try to merge this first?

Otherwise I left a couple small nitpicking naming questions and comments, but I think overall this looks like great work, thanks!

function physical_flip(A::AbstractTensorMap{T, S, N, 1}) where {T, S, N}
return flip(A, 2:N)
end
function project_hermitian(E::AbstractTensorMap{T, S, N, 1}) where {T, S, N}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use a different name for this? I think MatrixAlgebraKit already exports this as well.

- `:truncspace` : Additionally supply truncation space `η`; truncate according to the supplied vector space
- `:trunctol` : Additionally supply singular value cutoff `η`; truncate such that every retained singular value is larger than `η`
* `svd_alg::Union{<:SVDAdjoint,NamedTuple}` : SVD algorithm for computing projectors. See also [`SVDAdjoint`](@ref). By default, a reverse-rule tolerance of `tol=1e1tol` where the `krylovdim` is adapted to the `env₀` environment dimension.
* `decomposition_alg::Union{<:DecompositionAdjoint,NamedTuple}` : Tensor decomposition algorithm for computing projectors. See e.g. [`SVDAdjoint`](@ref).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `decomposition_alg::Union{<:DecompositionAdjoint,NamedTuple}` : Tensor decomposition algorithm for computing projectors. See e.g. [`SVDAdjoint`](@ref).
* `decomposition_alg` : Tensor decomposition algorithm for computing projectors. See e.g. [`SVDAdjoint`](@ref).

I wonder if it really makes sense to have that type description in the docstring. I don't think most people would know what that type alias means?

function calc_elementwise_convergence(
envfinal::CTMRGEnv{C}, envfix::CTMRGEnv{C′}; atol::Real = 1.0e-6
) where {C, C′}
Cfinal = (C <: DiagonalTensorMap) ? convert.(TensorMap, envfinal.corners) : envfinal.corners
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QuantumKitHub/TensorKit.jl#361

please open issues for things like this ❤️

using KrylovKit: Lanczos, BlockLanczos
const KrylovKitCRCExt = Base.get_extension(KrylovKit, :KrylovKitChainRulesCoreExt)

"""
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we merge all the MatrixAlgebraKit pullbacks in one struct?
Would be nice to avoid some of this duplicated boilerplate/docstrings etc

end

# hacky way of computing the truncation error for current version of eigh_trunc!
# TODO: replace once TensorKit updates to new MatrixAlgebraKit which returns truncation error as well
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't this already the case?

Copy link
Member

@Yue-Zhengyuan Yue-Zhengyuan Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then it may be better to address #314 first, which still requires changes in MPSKit to be released.

Comment on lines +207 to +213
function isfulleig(alg::FixedEig)
if isnothing(alg.D_full) || isnothing(alg.U_full)
return false
else
return true
end
end
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
function isfulleig(alg::FixedEig)
if isnothing(alg.D_full) || isnothing(alg.U_full)
return false
else
return true
end
end
isfulleig(alg::FixedEig) = !isnothing(alg.D_full) && !isnothing(alg.U_full)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a specific reason to use U instead of V for the eigenvectors? It's slightly odd to me to change that convention here instead of just following the MatrixAlgebraKit one?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we remove this file for now?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pbrehmer I'm also OK with removing QR stuff now instead of just commenting it out.

Copy link
Member

@Yue-Zhengyuan Yue-Zhengyuan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My final comments.

Comment on lines +1 to +6
using MatrixAlgebraKit: TruncationStrategy, NoTruncation, LAPACK_EighAlgorithm, truncate
using MatrixAlgebraKit: eigh_pullback!, eigh_trunc_pullback!, findtruncated, diagview
using TensorKit: AdjointTensorMap, SectorDict, Factorizations.TruncationSpace,
throw_invalid_innerproduct, similarstoragetype
using TensorKit.Factorizations: _notrunc_ind
using KrylovKit: Lanczos, BlockLanczos
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we import modules only in src/PEPSKit.jl?

(BTW, there is a using MPSKit: InfiniteEnvironments in src/environments/vumps_environments.jl that I suggest to also be moved to src/PEPSKit.jl.)

E_ref = -0.6602310934799577

# Heisenberg model assuming C4v symmetric PEPS and environment, which only evaluates necessary term
function heisenberg_XYZ_c4v(lattice::InfiniteSquare; kwargs...)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about adding this directly to src/operators/models.jl so it can be accessed by users? (also asking for @lkdvos's opinion)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] C4v CTMRG

4 participants