Documentation update

[leburgel]

To do

• Standardize docstrings using DocStringExtensions
• Add a section explaining the use of PrecompileTools to cut down on long precompilation times, see also Add PrecompileTools precompilation setup #129
• Use DocumenterCitations to organize literature references
• Add Pluto notebook generation infracstructure for examples that showcase the full PEPSKit feature set on a few different models

Examples

• A simple Heisenberg example that can serve as a "getting started" example which shows basics of optimization, CTMRG contraction, computing the correlation length and observables
• Example showing how to use fermionic tensors and that optimizing them might require different settings
• Example showcasing $\mathbb{Z}_2$ or $U(1)$ symmetric optimization
• Example or part of an example which shows how to use gradient_alg=nothing (POSTPONED)
• Boundary MPS example using VUMPS to contract a PEPS
• Example with PEPS-PEPO-PEPS contraction
• Example for contracting a partition function
• A simple update (and in the future NTU/full update) example

https://quantumkithub.github.io/PEPSKit.jl/previews/PR161/

[codecov]

Codecov Report

Attention: Patch coverage is 84.44444% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/operators/localoperator.jl	62.50%	3 Missing ⚠️
src/algorithms/ctmrg/sparse_environments.jl	0.00%	2 Missing ⚠️
src/states/infiniteweightpeps.jl	0.00%	2 Missing ⚠️

Files with missing lines	Coverage Δ
src/Defaults.jl	85.71% <ø> (ø)
src/PEPSKit.jl	100.00% <ø> (ø)
src/algorithms/contractions/bondenv/als_solve.jl	100.00% <ø> (ø)
src/algorithms/contractions/ctmrg_contractions.jl	58.09% <ø> (ø)
src/algorithms/contractions/localoperator.jl	94.94% <ø> (ø)
src/algorithms/ctmrg/ctmrg.jl	90.47% <ø> (ø)
src/algorithms/ctmrg/gaugefix.jl	97.19% <ø> (ø)
src/algorithms/ctmrg/projectors.jl	82.69% <ø> (ø)
src/algorithms/ctmrg/sequential.jl	98.36% <ø> (ø)
src/algorithms/ctmrg/simultaneous.jl	98.27% <ø> (ø)
... and 24 more

🚀 New features to boost your workflow:

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

[pbrehmer]

Here are some TODOs for the documentation update from our last meeting but also things that came to my mind recently:

• Standardize docstrings using DocStringExtensions
• Add a section explaining the use of PrecompileTools to cut down on long precompilation times, see also Add PrecompileTools precompilation setup #129
• Use DocumenterCitations to organize literature references
• Agree on a unicode TN diagram convention and standardize diagrams in docstrings
• Add examples in Pluto notebook format that (try to) showcase the full PEPSKit feature set on a few different models

In terms of examples that we want to add to the docs, I think we suggested the following (noting that most of these already exist in the examples folder and only need to be converted to a notebook with some additional explanations):

• A simple Heisenberg example that can serve as a "getting started" example which shows basics of optimization, CTMRG contraction, computing the correlation length and observables
• Example showing how to use fermionic tensors and that optimizing them might require different settings
• Example showcasing $\mathbb{Z}_2$ or $U(1)$ symmetric optimization
• Example or part of an example which shows how to use gradient_alg=nothing
• Boundary MPS example using VUMPS to contract a PEPS
• Example with PEPS-PEPO-PEPS contraction
• A simple update (and in the future NTU/full update) example

Feel free to add suggestions and ideas to the above lists!

[lkdvos]

I added the list to the PR description, apologies if I'm putting words in @leburgel 's mouth but that seems a bit easier to track and less likely to get lost 😉

[leburgel]

https://quantumkithub.github.io/PEPSKit.jl/previews/PR161/

[github-actions]

After the build completes, the updated documentation will be available here

[lkdvos]

It would be great if we can all pretend I nailed that first attempt

[pbrehmer]

This is mostly done from my part. I will rerun the examples and update the cache fully once I get access to a more powerful computer again (I'm currently only on my laptop). But if someone else wants to do that, feel free to do so :-)

@leburgel perhaps you could finish the suggestions for the 3D Ising model? Otherwise this PR would be good to go for me! Thanks again for the comprehensive review.

[leburgel]

I addressed the remaining comments for the 3D classical Ising example I think. As far as I'm concerned, we can update the cache again and merge.

[pbrehmer]

I'm just rerunning the examples right now, so I'll push the updated rendered examples and cache, and then I'd be fine with merging as well.

[pbrehmer]

Alright, good to go for me once the tests run through :-) @lkdvos What do you think? Also, shall we tag a new release after merging this?

[lkdvos]

I'll have breakfast and quickly go through it one last time, but I think I gave my comments in the last round so should be good to go. Agreed with the version update as well, but let's keep that as a separate commit so I can also double check what changed.