Add C4v CTMRG #321

pbrehmer · 2026-01-21T19:11:53Z

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.

github-actions · 2026-01-22T17:18:02Z

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

codecov · 2026-01-22T18:17:18Z

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 · 2026-01-23T01:56:42Z

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 · 2026-01-23T09:57:16Z

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 · 2026-01-23T10:58:21Z

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 · 2026-01-23T14:32:25Z

Codecov Report

❌ Patch coverage is 87.94788% with 37 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/utility/eigh.jl	84.96%	20 Missing ⚠️
src/algorithms/ctmrg/c4v.jl	79.71%	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/algorithms/truncation/truncationschemes.jl	`75.00% <ø> (ø)`
src/environments/ctmrg_environments.jl	`81.50% <100.00%> (ø)`
src/environments/vumps_environments.jl	`100.00% <ø> (ø)`
... and 5 more

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

src/algorithms/ctmrg/gaugefix.jl

src/algorithms/ctmrg/ctmrg.jl

src/algorithms/ctmrg/gaugefix.jl

src/algorithms/ctmrg/projectors.jl

src/algorithms/ctmrg/simultaneous.jl

Co-authored-by: Yue Zhengyuan <yuezy1997@icloud.com>

src/algorithms/ctmrg/projectors.jl

Co-authored-by: Lukas Devos <ldevos98@gmail.com>

…4v-ctmrg

pbrehmer · 2026-02-02T16:14:05Z

This is good to go for me now, let me know what you think!

Yue-Zhengyuan · 2026-02-03T09:02:30Z

I'll unlink issue #258 until we also implement the QR-CTMRG.

…4v-ctmrg

Yue-Zhengyuan · 2026-02-03T13:29:36Z

src/algorithms/ctmrg/c4v.jl

+function c4v_renormalize(network, env, projector)
+    new_edge = renormalize_north_edge(env.edges[1], projector, projector', network[1, 1])
+    return new_edge / norm(new_edge)
+end


Do we need to further project_hermitian the updated edge with respect to the two environment indices to eliminate numerical errors?

See also the QR-CTM code which does this step.

BTW, I would add a leading underscore (_project_hermitian) to avoid conflict with MAK. But it's just my opinion...

In addition, do we have tests with fermions to see if project_hermitian for edges is correctly defined? I'm not quite confident on the usage of flip there unless it's proven correct.

Good point, thanks! Probably doesn't make too much of a difference but it should stabilize the method.

In addition, do we have tests with fermions to see if project_hermitian for edges is correctly defined? I'm not quite confident on the usage of flip there unless it's proven correct.

Good point, I'm also not sure if flip and _dag work for fermions right away. Would you have an idea for a quick test? (I wouldn't want to add too much more to this PR.)

Let's leave the fermions for a follow up, it will be easier to review what is going on that way.

The test idea is simple: create a random fermionic state with C4v, converge the environment with both C4v and asymmetric CTMRG, and evaluate the expectation value of a random operator, which should be the same for both cases. But frankly, I'm not even sure if the current symmetrize! plays nicely with permutation signs from FermionParity.

lkdvos

Left some small final comments, but otherwise good to go!

lkdvos · 2026-02-03T21:37:46Z

src/algorithms/ctmrg/c4v.jl

+function c4v_renormalize(network, env, projector)
+    new_edge = renormalize_north_edge(env.edges[1], projector, projector', network[1, 1])
+    return new_edge / norm(new_edge)
+end


Let's leave the fermions for a follow up, it will be easier to review what is going on that way.

src/algorithms/ctmrg/c4v.jl

src/algorithms/ctmrg/gaugefix.jl

Co-authored-by: Lukas Devos <ldevos98@gmail.com>

pbrehmer · 2026-02-04T13:22:22Z

Should be mergeable now!

pbrehmer added 3 commits January 21, 2026 20:00

Generalize environment gauge fixing

61a88c1

Add C4v CTMRG algorithm

0ec910b

Add C4v CTMRG rrules and defaults

7256f3f

pbrehmer self-assigned this Jan 21, 2026

pbrehmer marked this pull request as draft January 21, 2026 19:12

pbrehmer added 3 commits January 22, 2026 18:11

Fix tensor decompositions

1a326b9

Fix parameter selection

23c1610

Make some tests runnable

0a475fe

Fix some more stuff and add fixed_iterscheme C4v test

094af8c

Comment out QR things for now

a6ce108

Add gauge fixing and partition function C4v tests

97760e8

pbrehmer and others added 5 commits January 23, 2026 16:14

Fix differentiability and add C4v Heisenberg test

6effabe

Automatically symmetrize optimization when alg=:c4v

089a005

Fix unitcell test imports

f3d89e1

Add eigh_wrapper test and fix IterEigh

fcdea38

Fix eigh_wrapper test imports

7905570

Yue-Zhengyuan reviewed Jan 24, 2026

View reviewed changes

src/algorithms/ctmrg/gaugefix.jl Outdated Show resolved Hide resolved

Yue-Zhengyuan reviewed Jan 24, 2026

View reviewed changes

src/algorithms/ctmrg/ctmrg.jl Show resolved Hide resolved

src/algorithms/ctmrg/gaugefix.jl Outdated Show resolved Hide resolved

src/algorithms/ctmrg/projectors.jl Outdated Show resolved Hide resolved

src/algorithms/ctmrg/simultaneous.jl Show resolved Hide resolved

pbrehmer and others added 2 commits January 26, 2026 11:32

Update src/algorithms/ctmrg/gaugefix.jl

30f484f

Co-authored-by: Yue Zhengyuan <yuezy1997@icloud.com>

Rename to decomposition algorithm to decomp_alg

ee0b5e2

Yue-Zhengyuan reviewed Jan 26, 2026

View reviewed changes

src/algorithms/ctmrg/projectors.jl Outdated Show resolved Hide resolved

pbrehmer added 3 commits January 26, 2026 13:20

Fix partition function test import

f4df969

Update docstrings to decomp_alg

0968a4c

Fix flavors test import

7651853

pbrehmer and others added 5 commits February 2, 2026 16:36

Rename U to V in eigendecomposition (consistent with MAK)

0f6b5c0

Omit docstring type annotation

b182d90

Co-authored-by: Lukas Devos <ldevos98@gmail.com>

Move all imports to src/PEPSKit.jl

09b98c4

Fix U->V relabeling

f07d268

Merge branch 'c4v-ctmrg' of github.com:quantumghent/PEPSKit.jl into c…

71371e5

…4v-ctmrg

pbrehmer added 2 commits February 2, 2026 17:35

Fix SVD test

c094446

Move KrylovKitCRCExt to SVD file

f7d1111

pbrehmer requested a review from lkdvos February 2, 2026 16:41

pbrehmer and others added 2 commits February 2, 2026 18:27

Fix IterEigh fixed_iterscheme test

f262a48

Fix fixed_iterscheme test imports

fbbdaa0

pbrehmer added 4 commits February 3, 2026 10:36

Update fixed_iterscheme test

3f22fc4

Merge branch 'c4v-ctmrg' of github.com:quantumghent/PEPSKit.jl into c…

ea6e601

…4v-ctmrg

Remove redundant import

fd46a73

Update fixed_iterscheme test for the 10000th time

defc782

Yue-Zhengyuan reviewed Feb 3, 2026

View reviewed changes

pbrehmer added 2 commits February 3, 2026 16:27

Add Hermitian projection to c4v_renormalize

483742b

Rename hermitian_project to _project_hermitian

e580451

lkdvos reviewed Feb 3, 2026

View reviewed changes

pbrehmer and others added 5 commits February 4, 2026 13:15

Use north_virtualspace instead of domain

cef1161

Co-authored-by: Lukas Devos <ldevos98@gmail.com>

Add TODO

cdd8aa2

Adjust signature of fix_global_phases

6960981

Fix north_virtualspace adjointness

c00129f

Change function argument order of gauge_fix(env, ...)

76954b8

lkdvos approved these changes Feb 4, 2026

View reviewed changes

pbrehmer enabled auto-merge (squash) February 4, 2026 15:21

pbrehmer merged commit 81be8c0 into master Feb 4, 2026
63 checks passed

pbrehmer deleted the c4v-ctmrg branch February 4, 2026 17:12

Add C4v CTMRG #321

Add C4v CTMRG #321

Uh oh!

Conversation

pbrehmer commented Jan 21, 2026 • edited by Yue-Zhengyuan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Yue-Zhengyuan commented Jan 23, 2026

Uh oh!

pbrehmer commented Jan 23, 2026

Uh oh!

Yue-Zhengyuan commented Jan 23, 2026

Uh oh!

codecov bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pbrehmer commented Feb 2, 2026

Uh oh!

Yue-Zhengyuan commented Feb 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lkdvos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pbrehmer commented Feb 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pbrehmer commented Jan 21, 2026 •

edited by Yue-Zhengyuan

Loading

github-actions bot commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 23, 2026 •

edited

Loading