From 7bfb49bfbfef57b2ae83e62e59081778656b18a8 Mon Sep 17 00:00:00 2001 From: lkdvos Date: Mon, 3 Aug 2026 13:08:44 -0400 Subject: [PATCH 1/8] docs: add contributing guide and issue/PR templates `CONTRIBUTING.md` is the canonical guide, rendered as a page through the thin `docs/src/contributing.md` include so it is reachable from the site as well as from GitHub. Issue templates split bug reports from questions, since the two need very different information, and the PR template asks for the things review kept having to ask for. Also refreshes `README.md` with a short positioning statement, brings `CITATION.cff` up to the v0.13.13 release, and records in the docstring style guide that unverified physics claims get a REVIEW marker for the maintainer. Co-Authored-By: Claude Opus 5 (1M context) update contributing.md simplify readme --- .github/ISSUE_TEMPLATE/bug_report.md | 49 ++++++++++ .github/ISSUE_TEMPLATE/question.md | 27 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 10 ++ CITATION.cff | 4 +- CONTRIBUTING.md | 101 ++++++++++++++++++++ README.md | 135 +++++++++++---------------- docs/make.jl | 1 + docs/src/contributing.md | 87 +++++++++++++++++ 8 files changed, 331 insertions(+), 83 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/question.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/src/contributing.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..cc0720870 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,49 @@ +--- +name: Bug report +about: Something isn't working as expected +title: "" +labels: bug +--- + +## Description + +A clear and concise description of what went wrong, and what you expected to happen instead. + +## Minimal working example (MWE) + +Please include the smallest possible piece of code that reproduces the issue. +Trim away everything that is not needed to trigger the bug (unrelated setup, unused imports, etc). + +```julia +using MPSKit, TensorKit + +# ... +``` + +## Error / output + +Paste the full error message and stacktrace (or the incorrect output), if any. + +``` +paste here +``` + +## Version info + +Please include the versions of MPSKit and its main dependencies. +From the Julia REPL: + +```julia-repl +julia> using Pkg +julia> Pkg.status(["MPSKit", "TensorKit"]) +``` + +Also include the Julia version: + +```julia-repl +julia> versioninfo() +``` + +## Additional context + +Anything else that might help (OS, whether it also happens on the latest `main`, related issues, etc). diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 000000000..c7215fe11 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,27 @@ +--- +name: Question +about: Ask a question about using MPSKit +title: "" +labels: question +--- + +## What are you trying to do? + +Describe the physics or the workflow you are trying to set up. + +## What have you tried? + +If applicable, include the code you have so far, and what result you got (or expected but didn't get). + +```julia +using MPSKit, TensorKit + +# ... +``` + +## Version info (optional but helpful) + +```julia-repl +julia> using Pkg +julia> Pkg.status(["MPSKit", "TensorKit"]) +``` diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..d478b4737 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,10 @@ +## Description + +Briefly describe what this PR changes and why. + +## Checklist + +- [ ] Tests pass locally (`julia --project=test test/runtests.jl`, or the relevant subset) +- [ ] Documentation updated, if this PR changes public API (docstrings, `docs/src/`) +- [ ] Runic formatter is run +- [ ] Changelog entry added under `[Unreleased]` in `docs/src/changelog.md` diff --git a/CITATION.cff b/CITATION.cff index 8592b6a9a..62c16459b 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -12,7 +12,7 @@ authors: orcid: "https://orcid.org/0000-0002-0858-291X" title: "MPSKit" -version: 0.13.11 +version: 0.13.13 doi: 10.5281/zenodo.10654900 -date-released: 2026-05-04 +date-released: 2026-06-09 url: "https://github.com/QuantumKitHub/MPSKit.jl" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..8c4b86f13 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to MPSKit.jl + +Thanks for taking the time to contribute! +We are open to any and all suggestions and welcome new and advanced developers alike. +This document is a short, practical guide to reporting issues, asking questions, and submitting changes. + +## Asking questions and reporting bugs + +Use [GitHub issues](https://github.com/QuantumKitHub/MPSKit.jl/issues) for both. +There are two templates to help you: + +- **Bug report** — for something that doesn't work as expected. +- **Question** — for anything else, from "how do I model X" to "is Y possible". + +A good bug report is one we can act on immediately, and it typically needs two things: + +1. A minimal working example (MWE): the smallest snippet of code that reproduces the problem. + Strip away everything not needed to trigger the bug — unrelated setup, unused imports, alternative approaches you also tried. +2. Version information for MPSKit, TensorKit, and Julia, obtained with: + + ```julia-repl + julia> using Pkg + julia> Pkg.status(["MPSKit", "TensorKit"]) + ``` + + ```julia-repl + julia> versioninfo() + ``` + +Please also include the full error message and stacktrace, if there is one. + +## Contributing code + +We are very happy to take contributions, and will gladly make the time to review code. +Note that this might take a bit of time, so please be patient with us. + +For small issues, fixes and typos, feel free to open a PR directly. +For larger amounts of work, it might be beneficial to open an issue first, so we can discuss the solution strategy beforehand. +Often, it might be the case that there are other ideas, or partial solutions that already were in the make, and we want to avoid duplicate or wasted work as much as possible. + +There is no restriction for the use of AI-tooling to assist you, although we do ask that you take the time to review the code yourself. +Additionally, please do not just copy-pasted LLM generated responses to code reviews or discussions, as we take the time and effort to review your code and expect the same amount of effort from you. +Do note however, that this means that overly large PRs might not get reviewed, since the review proces for these is too resource-intensive. + +!!! hint + You can locally check out the main branch of the repository into your current Project.toml by using + ```julia-repl + pkg> dev --local MPSKit + ``` + + +### Running the tests + +The repository root is a Julia workspace (`Project.toml` lists `test`, `docs`, and `examples` as workspace projects), and `test/Project.toml` already points `MPSKit` back at the repo checkout. +From the repository root, you can therefore run the full suite with: + +``` +julia --project=test test/runtests.jl +``` + +The test suite is organized by topic under `test/` (`algorithms/`, `states/`, `operators/`, `misc/`, `gpu/`), with shared setup code in `test/setup/`. +GPU tests only run when a functional CUDA/cuTENSOR install is detected, so most contributors will only ever exercise the CPU tests. + +Additionally, a number of CLI flags can be added to run the tests selectively, as these will be filtered by folder and filename +A `--fast` flag is available for a quicker, reduced run while iterating. + +``` +julia --project=test test/runtests.jl states +julia --project=test test/runtests.jl operators algorithms/groundstate +julia --project=test test/runtests.jl misc --fast +``` + +### Building the documentation + +The docs use Documenter.jl with the DocumenterVitepress backend, so a full render needs Node.js in addition to Julia. +For routine verification of code examples (fast, no Node required), you can run the doctests directly: + +``` +julia --project=docs -e 'using Documenter, MPSKit; doctest(MPSKit)' +``` + +For a full local site build (slower, needs `npm`): + +``` +julia --project=docs docs/make.jl +``` + +### Code formatting + +This repository is formatted with [Runic](https://github.com/fredrikekre/Runic.jl). +Formatting is checked automatically on pull requests, and there is a [pre-commit](https://pre-commit.com/) hook (`.pre-commit-config.yaml`) that runs Runic locally if you use pre-commit. +Please format any Julia files you touch before opening a PR, and refrain from making any formatting changes to code that is not relevant to your PR. + +### Changelog + +If your change is user-facing (new feature, behavior change, bug fix, deprecation, or removal), add an entry under the `[Unreleased]` section of `docs/src/changelog.md`, in the category that matches your change. + +### Opening a pull request + +Small, focused pull requests are easiest to review. +Please describe what the change does and why, link any related issues, and make sure the checklist in the PR template is filled in before requesting review. diff --git a/README.md b/README.md index 215b4145a..8a0ee300a 100644 --- a/README.md +++ b/README.md @@ -2,119 +2,92 @@ # MPSKit.jl -Contains code for tackling one-dimensional quantum and two-dimensional statistical mechanics -problems using tensor network algorithms. The main focus is on matrix product states (MPS) -and matrix product operators (MPO), both finite and infinite. +[![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] [![DOI][doi-img]][doi-url] +[![CI][ci-img]][ci-url] [![PkgEval][pkgeval-img]][pkgeval-url] [![Codecov][codecov-img]][codecov-url] -| **Documentation** | **Digital Object Identifier** | -|:-----------------:|:-----------------------------:| -| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![DOI][doi-img]][doi-url] | +Tensor network algorithms based on matrix product states (MPS) and matrix product operators (MPO), for (quasi) one-dimensional quantum lattices and two-dimensional statistical mechanics models, as well as quantum circuit simulation or boundary-MPS methods. +This library highlights support for both finite systems and systems directly in the thermodynamic limit, and both have a large variety of implemented algorithms. -| **Build Status** | **PkgEval** | **Coverage** | -|:----------------:|:------------:|:------------:| -| [![CI][ci-img]][ci-url] | [![PkgEval][pkgeval-img]][pkgeval-url] | [![Codecov][codecov-img]][codecov-url] | +MPSKit builds on [TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) for its tensors, which makes abelian, non-abelian, fermionic and anyonic symmetries available throughout. +The toolbox covers ground states and leading boundary states, real and imaginary time evolution, excitation spectra, and more. -[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg -[docs-stable-url]: https://QuantumKitHub.github.io/MPSKit.jl/stable - -[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg -[docs-dev-url]: https://QuantumKitHub.github.io/MPSKit.jl/dev - -[doi-img]: https://zenodo.org/badge/DOI/10.5281/zenodo.10654900.svg -[doi-url]: https://doi.org/10.5281/zenodo.10654900 - -[codecov-img]: https://codecov.io/gh/QuantumKitHub/MPSKit.jl/branch/master/graph/badge.svg?token=rmp3bu7qn3 -[codecov-url]: https://codecov.io/gh/QuantumKitHub/MPSKit.jl - -[ci-img]: https://github.com/QuantumKitHub/MPSKit.jl/actions/workflows/Tests.yml/badge.svg -[ci-url]: https://github.com/QuantumKitHub/MPSKit.jl/actions/workflows/Tests.yml - -[pkgeval-img]: https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/M/MPSKit.svg -[pkgeval-url]: https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/M/MPSKit.html - -The framework is built upon -[TensorKit.jl](https://github.com/jutho/TensorKit.jl), which provides functionality for -generic symmetries. - -The toolbox contains different algorithms for finding MPS representations of groundstates or -leading boundary states, performing time evolution, finding excitations and much more. Check -out the [examples](https://QuantumKitHub.github.io/MPSKit.jl/dev/examples/) for concrete -use-cases. - -This package is under active development and new algorithms are added regularly. -Nevertheless, the documentation is quite terse, so feel free to open an issue if you have -any questions. +The [documentation](https://QuantumKitHub.github.io/MPSKit.jl/stable) contains the manual and the full API reference. +The [examples](https://QuantumKitHub.github.io/MPSKit.jl/dev/examples/) work through complete calculations, from ground states to dynamical correlators. ## Installation -The package can be installed through the Julia general registry, via the package manager: - -```julia-repl -pkg> add MPSKit -``` - -Because of the heavy use of [TensorKit.jl](https://github.com/jutho/TensorKit.jl), it is -recommended to install the latest version of this package as well. Additionally, several -extension packages exist that provide additional symmetries, which should all be compatible -with MPSKit. For example, to install the package with support for SU(N) symmetries, -[SUNRepresentations.jl](https://github.com/QuantumKitHub/SUNRepresentations.jl) can be used. +MPSKit is registered in the Julia general registry, and often is best combined with TensorKit.jl and MPSKitModels.jl. ```julia-repl -pkg> add TensorKit +pkg> add MPSKit TensorKit MPSKitModels ``` -Finally, several pre-defined operators, Hamiltonians and statistical mechanics models are available in [MPSKitModels.jl](https://github.com/QuantumKitHub/MPSKitModels.jl). It is recommended to install this package too. - -```julia-repl -pkg> add MPSKitModels -``` +[TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) provides the tensors and their symmetry sectors, and [MPSKitModels.jl](https://github.com/QuantumKitHub/MPSKitModels.jl) a library of common operators, Hamiltonians and statistical mechanics models. +Symmetries beyond the ones TensorKit itself ships with come from extension packages, such as [SUNRepresentations.jl](https://github.com/QuantumKitHub/SUNRepresentations.jl) for SU(N). ## Quickstart -After following the installation process, it should now be possible to load the packages and -start simulating. For example, to obtain the ground state of the 1D Ising model, we can use -the following code: +Sweeping the transverse field of the Ising model in the thermodynamic limit and measuring the magnetization: ```julia using MPSKit, MPSKitModels, TensorKit using ProgressMeter, Plots # for demonstration purposes -L = 16 # length of the chain D = 4 # bonddimension -init_state = FiniteMPS(L, ℂ^2, ℂ^D) +init_state = InfiniteMPS(ℂ^2, ℂ^D) -g_values = 0:0.1:2 +g_values = 0.1:0.1:2 M = @showprogress map(g_values) do g - H = periodic_boundary_conditions(transverse_field_ising(; g=g), L) - groundstate, environment, δ = find_groundstate(init_state, H; verbosity=0) - return abs(sum(expectation_value(groundstate, i => σᶻ()) for i in 1:L)) / L + H = transverse_field_ising(; g=g) + groundstate, environment, δ = find_groundstate(init_state, H, VUMPS(; verbosity=0)) + return abs(expectation_value(groundstate, 1 => σᶻ())) end scatter(g_values, M, xlabel="g", ylabel="M", label="D=$D", title="Magnetization") ``` -![Magnetization](docs/src/assets/README_ising_finite.png) +![Magnetization](docs/src/assets/README_ising_infinite.png) -Similarly, these simulations can be carried out directly in the thermodynamic limit, with -very minor code-changes: +The order parameter vanishes at `g = 1`, where the chain becomes critical. +Replacing the `InfiniteMPS` with a `FiniteMPS` runs the same sweep on a finite chain instead; the [examples](https://QuantumKitHub.github.io/MPSKit.jl/dev/examples/) cover that case along with time evolution, excitations and two-dimensional partition functions. -```julia -using MPSKit, MPSKitModels, TensorKit -using ProgressMeter, Plots # for demonstration purposes +## Getting help and contributing -D = 4 # bonddimension -init_state = InfiniteMPS(ℂ^2, ℂ^D) +MPSKit is under active development and new algorithms are added regularly. +Questions and general discussion belong on [GitHub Discussions](https://github.com/QuantumKitHub/MPSKit.jl/discussions), bug reports and feature requests in the [issue tracker](https://github.com/QuantumKitHub/MPSKit.jl/issues). +See [`CONTRIBUTING.md`](CONTRIBUTING.md) if you would like to contribute code or documentation. -g_values = 0.1:0.1:2 +## Citing -M = @showprogress map(g_values) do g - H = transverse_field_ising(; g=g) - groundstate, environment, δ = find_groundstate(init_state, H, VUMPS(; verbosity=0)) - return abs(expectation_value(groundstate, 1 => σᶻ())) -end +If you use MPSKit.jl in your research, please cite it. +See [`CITATION.cff`](CITATION.cff) for the up-to-date citation metadata, or use the BibTeX entry below. -scatter(g_values, M, xlabel="g", ylabel="M", label="D=$D", title="Magnetization") +```bibtex +@software{mpskitjl, + author = {Devos, Lukas and Van Damme, Maarten and Haegeman, Jutho}, + title = {{MPSKit.jl}}, + version = {v0.13.13}, + doi = {10.5281/zenodo.10654900}, + url = {https://github.com/QuantumKitHub/MPSKit.jl}, + year = {2026} +} ``` -![Magnetization](docs/src/assets/README_ising_infinite.png) +[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg +[docs-stable-url]: https://QuantumKitHub.github.io/MPSKit.jl/stable + +[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg +[docs-dev-url]: https://QuantumKitHub.github.io/MPSKit.jl/dev + +[doi-img]: https://zenodo.org/badge/DOI/10.5281/zenodo.10654900.svg +[doi-url]: https://doi.org/10.5281/zenodo.10654900 + +[codecov-img]: https://codecov.io/gh/QuantumKitHub/MPSKit.jl/branch/master/graph/badge.svg?token=rmp3bu7qn3 +[codecov-url]: https://codecov.io/gh/QuantumKitHub/MPSKit.jl + +[ci-img]: https://github.com/QuantumKitHub/MPSKit.jl/actions/workflows/Tests.yml/badge.svg +[ci-url]: https://github.com/QuantumKitHub/MPSKit.jl/actions/workflows/Tests.yml + +[pkgeval-img]: https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/M/MPSKit.svg +[pkgeval-url]: https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/M/MPSKit.html diff --git a/docs/make.jl b/docs/make.jl index 5922e4ee3..3b665078d 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -60,6 +60,7 @@ makedocs(; "Library" => "lib/lib.md", "References" => "references.md", "Changelog" => "changelog.md", + "Contributing" => "contributing.md", ], checkdocs = :exports, doctest = true, diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 000000000..3f8b76b0f --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1,87 @@ +# Contributing + +Contributions to MPSKit.jl are welcome, from bug reports and questions to documentation +fixes and new algorithms. +This page summarizes the practical workflow; the authoritative version is the +[`CONTRIBUTING.md`](https://github.com/QuantumKitHub/MPSKit.jl/blob/main/CONTRIBUTING.md) +file in the repository. + +## Asking questions and reporting bugs + +Questions and bug reports both go through +[GitHub issues](https://github.com/QuantumKitHub/MPSKit.jl/issues), which provides two +templates: a **bug report** for things that do not work as expected, and a **question** for +anything else. +General discussion is also welcome on +[GitHub Discussions](https://github.com/QuantumKitHub/MPSKit.jl/discussions). + +A good bug report includes a minimal working example (the smallest snippet that reproduces +the problem), the full error message and stacktrace, and version information for MPSKit, +TensorKit, and Julia: + +```julia-repl +julia> using Pkg +julia> Pkg.status(["MPSKit", "TensorKit"]) + +julia> versioninfo() +``` + +## Development setup + +Fork and clone the repository, then develop the package against your local checkout from the +Julia REPL: + +```julia-repl +pkg> dev /path/to/your/clone/MPSKit.jl +``` + +## Running the tests + +The repository root is a Julia workspace whose `Project.toml` lists `test`, `docs`, and +`examples` as workspace projects. +Run the full test suite from the repository root with: + +``` +julia --project=test test/runtests.jl +``` + +The tests are organized by topic under `test/` (`algorithms/`, `states/`, `operators/`, +`misc/`, `gpu/`). +GPU tests only run when a functional CUDA/cuTENSOR install is detected, so most contributors +exercise only the CPU tests. +A `--fast` flag is available for a quicker, reduced run while iterating. + +## Code formatting + +The repository is formatted with [Runic](https://github.com/fredrikekre/Runic.jl). +Formatting is checked automatically on pull requests, and a +[pre-commit](https://pre-commit.com/) hook (`.pre-commit-config.yaml`) runs Runic locally if +you use pre-commit. +Please format any Julia files you touch before opening a pull request. + +## Building the documentation + +The documentation uses [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) with the +[DocumenterVitepress](https://github.com/LuxDL/DocumenterVitepress.jl) backend, so a full site +render needs Node.js (with `npm`) in addition to Julia. +For routine verification of code examples, doctests run on the Documenter side and need no +Node: + +``` +julia --project=docs -e 'using Documenter, MPSKit; doctest(MPSKit)' +``` + +A full local site build is: + +``` +julia --project=docs docs/make.jl +``` + +## Opening a pull request + +Keep pull requests small and focused. +Describe what the change does and why, link any related issues, and fill in the checklist in +the PR template. +If your change is user-facing (a new feature, behavior change, bug fix, deprecation, or +removal), add an entry under the `[Unreleased]` section of the [Changelog](@ref) in the +category that matches your change. From 2c21ef3332108172842e22d8a8b1578fcf3442cf Mon Sep 17 00:00:00 2001 From: lkdvos Date: Tue, 4 Aug 2026 16:12:39 -0400 Subject: [PATCH 2/8] docs: single canonical contributing guide `docs/src/contributing.md` had been added as a hand-written second copy rather than the thin include it was described as, and the two had already drifted: the root file was missing the Discussions link and the development setup, the docs page was missing the AI-tooling policy and the selective-test invocations, while claiming the root file was authoritative. Keep `CONTRIBUTING.md` as the single source, since the repository root is where GitHub looks when it links contributing guidelines from the issue and pull request forms, and generate the manual page from it in `make.jl` with an `EditURL` pointing back at the real file. Along the way: the `!!! hint` admonition never rendered, as that file is read on GitHub rather than through Documenter, and the `dev --local MPSKit` it suggested does not check out `main` but clones into `./dev/`. Replaced with a Development setup section. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 3 ++ CONTRIBUTING.md | 25 ++++++++---- docs/make.jl | 14 +++++++ docs/src/contributing.md | 87 ---------------------------------------- 4 files changed, 35 insertions(+), 94 deletions(-) delete mode 100644 docs/src/contributing.md diff --git a/.gitignore b/.gitignore index 6d9656c0c..9afd56d56 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ benchmark/results **/.vitepress/cache/ **/.vitepress/dist/ package-lock.json + +# generated from CONTRIBUTING.md by docs/make.jl +docs/src/contributing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c4b86f13..fa1b2b710 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,8 @@ There are two templates to help you: - **Bug report** — for something that doesn't work as expected. - **Question** — for anything else, from "how do I model X" to "is Y possible". +Open-ended discussion that isn't really a question or a bug is also welcome on [GitHub Discussions](https://github.com/QuantumKitHub/MPSKit.jl/discussions). + A good bug report is one we can act on immediately, and it typically needs two things: 1. A minimal working example (MWE): the smallest snippet of code that reproduces the problem. @@ -39,15 +41,24 @@ For larger amounts of work, it might be beneficial to open an issue first, so we Often, it might be the case that there are other ideas, or partial solutions that already were in the make, and we want to avoid duplicate or wasted work as much as possible. There is no restriction for the use of AI-tooling to assist you, although we do ask that you take the time to review the code yourself. -Additionally, please do not just copy-pasted LLM generated responses to code reviews or discussions, as we take the time and effort to review your code and expect the same amount of effort from you. -Do note however, that this means that overly large PRs might not get reviewed, since the review proces for these is too resource-intensive. +Additionally, please do not just copy-paste LLM generated responses into code reviews or discussions, as we take the time and effort to review your code and expect the same amount of effort from you. +Do note however, that this means that overly large PRs might not get reviewed, since the review process for these is too resource-intensive. -!!! hint - You can locally check out the main branch of the repository into your current Project.toml by using - ```julia-repl - pkg> dev --local MPSKit - ``` +### Development setup + +Fork and clone the repository, then point Julia at your local checkout instead of the released version: + +```julia-repl +pkg> dev /path/to/your/clone/MPSKit.jl +``` + +Alternatively, you can tell Julia to clone the repository automatically, which will put it in a local `dev/` folder next to your Project.toml: + +``` +pkg> dev --local MPSKi +``` +If you just want to try out the current `main` without a fork, `pkg> add MPSKit#main` is enough. ### Running the tests diff --git a/docs/make.jl b/docs/make.jl index 3b665078d..2549e0060 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -21,6 +21,20 @@ quantum_pages = map(readdir(joinpath(example_dir, "quantum1d"))) do dir return joinpath("examples", "quantum1d", dir, "index.md") end +# contributing guide: `CONTRIBUTING.md` in the repository root is canonical, since that is the +# location GitHub links to from the issue and pull request forms. Copy it in as a page so it is +# reachable from the manual as well, with an `EditURL` pointing back at the real source file. +open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io + println( + io, """ + ```@meta + EditURL = "https://github.com/QuantumKitHub/MPSKit.jl/blob/main/CONTRIBUTING.md" + ``` + """ + ) + return write(io, read(joinpath(@__DIR__, "..", "CONTRIBUTING.md"), String)) +end + # bibliography bibpath = joinpath(@__DIR__, "src", "assets", "mpskit.bib") bib = CitationBibliography(bibpath; style = :authoryear) diff --git a/docs/src/contributing.md b/docs/src/contributing.md deleted file mode 100644 index 3f8b76b0f..000000000 --- a/docs/src/contributing.md +++ /dev/null @@ -1,87 +0,0 @@ -# Contributing - -Contributions to MPSKit.jl are welcome, from bug reports and questions to documentation -fixes and new algorithms. -This page summarizes the practical workflow; the authoritative version is the -[`CONTRIBUTING.md`](https://github.com/QuantumKitHub/MPSKit.jl/blob/main/CONTRIBUTING.md) -file in the repository. - -## Asking questions and reporting bugs - -Questions and bug reports both go through -[GitHub issues](https://github.com/QuantumKitHub/MPSKit.jl/issues), which provides two -templates: a **bug report** for things that do not work as expected, and a **question** for -anything else. -General discussion is also welcome on -[GitHub Discussions](https://github.com/QuantumKitHub/MPSKit.jl/discussions). - -A good bug report includes a minimal working example (the smallest snippet that reproduces -the problem), the full error message and stacktrace, and version information for MPSKit, -TensorKit, and Julia: - -```julia-repl -julia> using Pkg -julia> Pkg.status(["MPSKit", "TensorKit"]) - -julia> versioninfo() -``` - -## Development setup - -Fork and clone the repository, then develop the package against your local checkout from the -Julia REPL: - -```julia-repl -pkg> dev /path/to/your/clone/MPSKit.jl -``` - -## Running the tests - -The repository root is a Julia workspace whose `Project.toml` lists `test`, `docs`, and -`examples` as workspace projects. -Run the full test suite from the repository root with: - -``` -julia --project=test test/runtests.jl -``` - -The tests are organized by topic under `test/` (`algorithms/`, `states/`, `operators/`, -`misc/`, `gpu/`). -GPU tests only run when a functional CUDA/cuTENSOR install is detected, so most contributors -exercise only the CPU tests. -A `--fast` flag is available for a quicker, reduced run while iterating. - -## Code formatting - -The repository is formatted with [Runic](https://github.com/fredrikekre/Runic.jl). -Formatting is checked automatically on pull requests, and a -[pre-commit](https://pre-commit.com/) hook (`.pre-commit-config.yaml`) runs Runic locally if -you use pre-commit. -Please format any Julia files you touch before opening a pull request. - -## Building the documentation - -The documentation uses [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) with the -[DocumenterVitepress](https://github.com/LuxDL/DocumenterVitepress.jl) backend, so a full site -render needs Node.js (with `npm`) in addition to Julia. -For routine verification of code examples, doctests run on the Documenter side and need no -Node: - -``` -julia --project=docs -e 'using Documenter, MPSKit; doctest(MPSKit)' -``` - -A full local site build is: - -``` -julia --project=docs docs/make.jl -``` - -## Opening a pull request - -Keep pull requests small and focused. -Describe what the change does and why, link any related issues, and fill in the checklist in -the PR template. -If your change is user-facing (a new feature, behavior change, bug fix, deprecation, or -removal), add an entry under the `[Unreleased]` section of the [Changelog](@ref) in the -category that matches your change. From b1a92857ec20e8f1c9ac9a14db803b248407b8a0 Mon Sep 17 00:00:00 2001 From: lkdvos Date: Tue, 4 Aug 2026 16:13:04 -0400 Subject: [PATCH 3/8] docs: fix package name in dev --local example Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa1b2b710..3fc3dee36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,8 +54,8 @@ pkg> dev /path/to/your/clone/MPSKit.jl Alternatively, you can tell Julia to clone the repository automatically, which will put it in a local `dev/` folder next to your Project.toml: -``` -pkg> dev --local MPSKi +```julia-repl +pkg> dev --local MPSKit ``` If you just want to try out the current `main` without a fork, `pkg> add MPSKit#main` is enough. From b3c92d0d933c35ec579fc12d2d28fa6583adb2b7 Mon Sep 17 00:00:00 2001 From: lkdvos Date: Tue, 4 Aug 2026 16:15:35 -0400 Subject: [PATCH 4/8] docs: suggest citing TensorKit alongside MPSKit in README TensorKit provides the tensors every algorithm here runs on, and its `CITATION.cff` declares a `preferred-citation`, so the entry points at the paper (arXiv:2508.10076) rather than the software DOI. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 8a0ee300a..fc6295180 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,9 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) if you would like to contribute code or If you use MPSKit.jl in your research, please cite it. See [`CITATION.cff`](CITATION.cff) for the up-to-date citation metadata, or use the BibTeX entry below. +Please consider citing [TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) as well. +It provides the (symmetric) tensors that MPSKit is built on, and does much of the heavy lifting behind every algorithm here. + ```bibtex @software{mpskitjl, author = {Devos, Lukas and Van Damme, Maarten and Haegeman, Jutho}, @@ -72,6 +75,14 @@ See [`CITATION.cff`](CITATION.cff) for the up-to-date citation metadata, or use url = {https://github.com/QuantumKitHub/MPSKit.jl}, year = {2026} } + +@article{tensorkitjl, + author = {Devos, Lukas and Haegeman, Jutho}, + title = {{TensorKit.jl}: A Julia package for large-scale tensor computations, with a hint of category theory}, + journal = {arXiv preprint arXiv:2508.10076}, + doi = {10.48550/arXiv.2508.10076}, + year = {2025} +} ``` [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg From 6ff0902d8ce0f77b81952b7d75db760fffc6f085 Mon Sep 17 00:00:00 2001 From: lkdvos Date: Tue, 4 Aug 2026 16:19:21 -0400 Subject: [PATCH 5/8] docs: declare the TensorKit citation in CITATION.cff and the manual Adds a `references:` entry to `CITATION.cff` so citation tooling picks the dependency up rather than only human readers of the README, and a "Citing MPSKit" section on the references page with both works as proper bibliography entries. The TensorKit entry is the paper its own `CITATION.cff` marks as `preferred-citation` (arXiv:2508.10076), not the software DOI. Both bib entries use `@misc` rather than the biblatex-only `@software`, since the bibliography is parsed as BibTeX. Co-Authored-By: Claude Opus 5 (1M context) --- CITATION.cff | 16 ++++++++++++++++ docs/src/assets/mpskit.bib | 25 +++++++++++++++++++++++++ docs/src/references.md | 8 ++++++++ 3 files changed, 49 insertions(+) diff --git a/CITATION.cff b/CITATION.cff index 62c16459b..edb2b2ac9 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -16,3 +16,19 @@ version: 0.13.13 doi: 10.5281/zenodo.10654900 date-released: 2026-06-09 url: "https://github.com/QuantumKitHub/MPSKit.jl" + +references: +- type: article + authors: + - family-names: "Devos" + given-names: "Lukas" + orcid: "https://orcid.org/0000-0002-0256-4200" + - family-names: "Haegeman" + given-names: "Jutho" + orcid: "https://orcid.org/0000-0002-0858-291X" + title: "TensorKit.jl: A Julia package for large-scale tensor computations, with a hint of category theory" + journal: "arXiv" + year: 2025 + doi: "10.48550/arXiv.2508.10076" + url: "https://arxiv.org/abs/2508.10076" + notes: "MPSKit is built on TensorKit.jl; please consider citing it as well." diff --git a/docs/src/assets/mpskit.bib b/docs/src/assets/mpskit.bib index 76f9fc9fe..44e762933 100644 --- a/docs/src/assets/mpskit.bib +++ b/docs/src/assets/mpskit.bib @@ -144,6 +144,31 @@ @article{devos2022 abstract = {We calculate the Haldane gap of the SU⁡(3) spin [300] Heisenberg model using variational uniform fully symmetric SU⁡(3) matrix product states, and find that the minimal gap {$\Delta$}/{$J$}=0.0263 is obtained in the [210] sector at momentum 2⁢{$\pi$}/3. We also discuss the symmetry protected topological order of the ground state, and determine the full dispersion relation of the elementary excitations and the correlation lengths of the system.} } +@misc{devos2025tensorkit, + title = {{{TensorKit.jl}}: A {{Julia}} Package for Large-Scale Tensor Computations, with a Hint of Category Theory}, + author = {Devos, Lukas and Haegeman, Jutho}, + year = {2025}, + month = aug, + number = {arXiv:2508.10076}, + eprint = {2508.10076}, + primaryclass = {cs.MS}, + publisher = {arXiv}, + doi = {10.48550/arXiv.2508.10076}, + url = {https://arxiv.org/abs/2508.10076}, + archiveprefix = {arXiv} +} + +@misc{devos2026mpskit, + title = {{{MPSKit.jl}}}, + author = {Devos, Lukas and Van Damme, Maarten and Haegeman, Jutho}, + year = {2026}, + month = jun, + version = {0.13.13}, + publisher = {Zenodo}, + doi = {10.5281/zenodo.10654900}, + url = {https://github.com/QuantumKitHub/MPSKit.jl} +} + @article{gleis2023, title = {Controlled {{Bond Expansion}} for {{Density Matrix Renormalization Group Ground State Search}} at {{Single-Site Costs}}}, author = {Gleis, Andreas and Li, Jheng-Wei and {von Delft}, Jan}, diff --git a/docs/src/references.md b/docs/src/references.md index d092016fb..e857f9fdd 100644 --- a/docs/src/references.md +++ b/docs/src/references.md @@ -1,5 +1,13 @@ # References +## Citing MPSKit + +If you use MPSKit in your research, please cite it: [devos2026mpskit](@cite). +The [`CITATION.cff`](https://github.com/QuantumKitHub/MPSKit.jl/blob/main/CITATION.cff) file in the repository carries the up-to-date metadata, including the DOI of the specific release you used. + +Please consider citing [TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) as well: [devos2025tensorkit](@cite). +It provides the (symmetric) tensors that MPSKit is built on, and does much of the heavy lifting behind every algorithm here. + ## Publications using MPSKit Below you can find a list of publications that have made use of MPSKit. If you have used From 1c23bf031727752b7d7180c2c4140168cefb2252 Mon Sep 17 00:00:00 2001 From: lkdvos Date: Tue, 4 Aug 2026 16:41:52 -0400 Subject: [PATCH 6/8] docs: route discussions from the issue chooser, complete the home TOC The contributing guide and README both send open-ended discussion to GitHub Discussions, but the issue chooser did not offer it, so that pointer only reached people who read CONTRIBUTING first. An `ISSUE_TEMPLATE/config.yml` surfaces it at the point where someone is about to file, alongside a link to the manual. The link is named for open-ended discussion rather than questions, to keep the split the Question template already makes. Blank issues stay enabled. The changelog checkbox in the pull request template was unconditional while the guide asks for an entry only on user-facing changes, so a docs-only PR could not tick it honestly. Now conditional, with the same wording as the guide. The home page table of contents listed only the manual pages, leaving the contributing guide and the new citation section unreachable from it. Extended to the rest of the site, mirroring the structure of `pages` in `make.jl`. Co-Authored-By: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/config.yml | 8 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 2 +- docs/src/index.md | 18 ++++++++++++------ 3 files changed, 21 insertions(+), 7 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..e41ec019f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Open-ended discussion + url: https://github.com/QuantumKitHub/MPSKit.jl/discussions + about: Ideas, feature brainstorming, or anything that isn't a specific question or bug report. For a concrete question about using MPSKit, use the Question template above. + - name: Documentation + url: https://quantumkithub.github.io/MPSKit.jl/stable/ + about: The manual and examples, which may already cover what you are after. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d478b4737..7ebcdbbed 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,4 +7,4 @@ Briefly describe what this PR changes and why. - [ ] Tests pass locally (`julia --project=test test/runtests.jl`, or the relevant subset) - [ ] Documentation updated, if this PR changes public API (docstrings, `docs/src/`) - [ ] Runic formatter is run -- [ ] Changelog entry added under `[Unreleased]` in `docs/src/changelog.md` +- [ ] Changelog entry added under `[Unreleased]` in `docs/src/changelog.md`, if this PR is user-facing (new feature, behavior change, bug fix, deprecation, or removal) diff --git a/docs/src/index.md b/docs/src/index.md index dd86bb1ba..2b9265209 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -39,12 +39,18 @@ features: ## Table of contents -- [Prerequisites](@ref) -- [States](@ref um_states) -- [Operators](@ref um_operators) -- [Algorithms](@ref um_algorithms) -- [Parallelism in julia](@ref) -- [Lattices](@ref lattices) +- Manual + - [Prerequisites](@ref) + - [States](@ref um_states) + - [Operators](@ref um_operators) + - [Algorithms](@ref um_algorithms) + - [Parallelism in julia](@ref) + - [Lattices](@ref lattices) +- [Examples](@ref) +- [Library](@ref "Library documentation") +- [References](@ref) — how to cite MPSKit, and publications that have used it +- [Changelog](@ref) +- [Contributing](@ref "Contributing to MPSKit.jl") ## Installation From 657473dd82ff7b9f8b29597bbb8dc5844dc53d05 Mon Sep 17 00:00:00 2001 From: lkdvos Date: Tue, 4 Aug 2026 18:14:49 -0400 Subject: [PATCH 7/8] docs: fix ambiguous Changelog cross-reference Making `CONTRIBUTING.md` the rendered contributing page brought its `### Changelog` subsection into `docs/src/`, where it collides with the `# Changelog` heading of `changelog.md`. That was latent until the home page table of contents added a `[Changelog](@ref)`, at which point Documenter could no longer resolve the slug and the build failed at `[:cross_references]`. Renamed the subsection to `### Changelog entries`, rather than anchoring `changelog.md` with an `@id`: that file is read on GitHub by the contributors it is written for, and `# [Changelog](@id changelog)` renders there as a broken link. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fc3dee36..4e9b4f35f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -102,7 +102,7 @@ This repository is formatted with [Runic](https://github.com/fredrikekre/Runic.j Formatting is checked automatically on pull requests, and there is a [pre-commit](https://pre-commit.com/) hook (`.pre-commit-config.yaml`) that runs Runic locally if you use pre-commit. Please format any Julia files you touch before opening a PR, and refrain from making any formatting changes to code that is not relevant to your PR. -### Changelog +### Changelog entries If your change is user-facing (new feature, behavior change, bug fix, deprecation, or removal), add an entry under the `[Unreleased]` section of `docs/src/changelog.md`, in the category that matches your change. From a0d4c3c757c0c8ba985647757aa30697ec06e2fa Mon Sep 17 00:00:00 2001 From: Lukas Devos Date: Wed, 5 Aug 2026 09:22:37 -0400 Subject: [PATCH 8/8] Apply suggestions from code review [skip ci] Co-authored-by: Boris De Vos <143942306+borisdevos@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fc6295180..0543e08b8 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,8 @@ scatter(g_values, M, xlabel="g", ylabel="M", label="D=$D", title="Magnetization" ![Magnetization](docs/src/assets/README_ising_infinite.png) -The order parameter vanishes at `g = 1`, where the chain becomes critical. -Replacing the `InfiniteMPS` with a `FiniteMPS` runs the same sweep on a finite chain instead; the [examples](https://QuantumKitHub.github.io/MPSKit.jl/dev/examples/) cover that case along with time evolution, excitations and two-dimensional partition functions. +The order parameter vanishes at `g ≥ 1`, where the chain becomes critical and transitions to the disordered phase. +Replacing the `InfiniteMPS` with a `FiniteMPS` and the ground-state algorithm to `DMRG` runs the same sweep on a finite chain instead; the [examples](https://QuantumKitHub.github.io/MPSKit.jl/dev/examples/) cover that case along with time evolution, excitations and two-dimensional partition functions. ## Getting help and contributing