From 67947f40a5866ac0858c0dcb7508e3e89436d2fa Mon Sep 17 00:00:00 2001 From: Matthew Fishman Date: Sat, 25 Apr 2026 10:20:52 -0400 Subject: [PATCH 1/2] Port README content into examples/README.jl The previous examples/README.jl was the bare ITensorPkgSkeleton template stub (added in 7a79fb5 to unblock the docs build), so every itpkgfmt run regenerated README.md as the empty stub, wiping the actual usage prose and `@visualize` examples that lived in README.md on main. Move the description, the UnicodePlots contraction example, the GLMakie backend example, and the backend-switching session into examples/README.jl as runnable Literate input. The contraction setup and both `@visualize` calls are now bare Julia so they execute via the shared ITensorPkgSkeleton.runtests examples sweep; the ASCII output, GLMakie window snippet, and `julia>` prompt blocks remain wrapped in `#= ... =#` so they pass through as raw markdown without trying to run. Image references switch to absolute raw.githubusercontent.com URLs so the same source renders correctly in both README.md and docs/src/index.md. Co-Authored-By: Claude Opus 4.7 (1M context) --- Project.toml | 2 +- README.md | 115 +++++++++++++++++++++++++++------- examples/README.jl | 149 ++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 241 insertions(+), 25 deletions(-) diff --git a/Project.toml b/Project.toml index 3c35ea1..d7e5e2b 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "ITensorVisualizationBase" uuid = "cd2553d2-8bef-4d93-8a38-c62f17d5ad23" -version = "0.1.15" +version = "0.1.16" authors = ["Matthew Fishman and contributors"] [workspace] diff --git a/README.md b/README.md index 75e303b..7703ae4 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,69 @@ -# ITensorVisualizationBase +# ITensorVisualizationBase.jl -This is an internal package providing common code for defining backends for visualizing tensor network of ITensors. It is only an interface package, and does not provide concrete implementations of visualizing tensor network code (by default, it does nothing). You will need to load a visualization backend, such as `ITensorUnicodePlots` or `ITensorGLMakie`. The main purpose is to use it with the [ITensors.jl](https://github.com/ITensor/ITensors.jl) package to view and debug tensor network contractions, for example: +[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://itensor.github.io/ITensorVisualizationBase.jl/stable/) +[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://itensor.github.io/ITensorVisualizationBase.jl/dev/) +[![Build Status](https://github.com/ITensor/ITensorVisualizationBase.jl/actions/workflows/Tests.yml/badge.svg?branch=main)](https://github.com/ITensor/ITensorVisualizationBase.jl/actions/workflows/Tests.yml?query=branch%3Amain) +[![Coverage](https://codecov.io/gh/ITensor/ITensorVisualizationBase.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ITensor/ITensorVisualizationBase.jl) +[![Code Style](https://img.shields.io/badge/code_style-ITensor-purple)](https://github.com/ITensor/ITensorFormatter.jl) +[![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl) + +## Support + + + + Flatiron Center for Computational Quantum Physics logo. + + + +ITensorVisualizationBase.jl is supported by the Flatiron Institute, a division of the Simons Foundation. + +## Installation instructions + +This package resides in the `ITensor/ITensorRegistry` local registry. +In order to install, simply add that registry through your package manager. +This step is only required once. +```julia +julia> using Pkg: Pkg + +julia> Pkg.Registry.add(url = "https://github.com/ITensor/ITensorRegistry") +``` +or: ```julia -using ITensors +julia> Pkg.Registry.add(url = "git@github.com:ITensor/ITensorRegistry.git") +``` +if you want to use SSH credentials, which can make it so you don't have to enter your Github ursername and password when registering packages. + +Then, the package can be added as usual through the package manager: + +```julia +julia> Pkg.add("ITensorVisualizationBase") +``` -# Load a visualization backend, which will reexport the interface -# of ITensorVisualizationBase automatically +This is an internal package providing common code for defining backends for visualizing +tensor networks of ITensors. It is only an interface package, and does not provide +concrete implementations of visualizing tensor network code (by default, it does +nothing). You will need to load a visualization backend, such as `ITensorUnicodePlots` +or `ITensorGLMakie`. The main purpose is to use it with the +[ITensors.jl](https://github.com/ITensor/ITensors.jl) package to view and debug tensor +network contractions, for example: + +````julia +using ITensorVisualizationBase: ITensorVisualizationBase, @visualize +using ITensors: Index, random_itensor +```` + +Load a visualization backend, which will reexport the interface of +`ITensorVisualizationBase` automatically: +```julia using ITensorUnicodePlots +``` -# ITensorVisualizationBase handles the logic of switching -# between backends. +(we leave the `using ITensorUnicodePlots` line out of this example so it can run in +test environments that do not have the backend installed.) + +`ITensorVisualizationBase` handles the logic of switching between backends: + +````julia @show ITensorVisualizationBase.get_backend() i = Index(2, "i") @@ -21,8 +75,10 @@ A = random_itensor(i, j, k) B = random_itensor(i, j, l, m) C = random_itensor(k, l) ABC = @visualize A * B * C -``` -This will execute the contraction and output +```` + +With the `ITensorUnicodePlots` backend loaded, this outputs: + ```julia ITensorVisualizationBase.get_backend() = ITensorVisualizationBase.Backend{:UnicodePlots}()⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ @@ -47,10 +103,13 @@ ITensorVisualizationBase.get_backend() = ITensorVisualizationBase.Backend{:Unico ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ``` + You can show the visualization with tags with: -```julia -ABC = @visualize A * B * C edge_labels=(tags=true,) -``` + +````julia +ABC_tags = @visualize A * B * C edge_labels = (tags = true,) +```` + ```julia ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ @@ -76,15 +135,17 @@ ABC = @visualize A * B * C edge_labels=(tags=true,) ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ``` -In order to output a more sophisticated interactive visualization, -you can load a Makie-based backend called GLMakie: +In order to output a more sophisticated interactive visualization, you can load a +Makie-based backend called `ITensorGLMakie`: ```julia using ITensorGLMakie -ABC = @visualize A * B * C edge_labels=(tags=true,); +ABC = @visualize A * B * C edge_labels = (tags = true,); ``` + A window like the following should appear: -![alt text](assets/ITensorVisualization_A_B_C.png) + +![alt text](https://raw.githubusercontent.com/ITensor/ITensorVisualizationBase.jl/main/assets/ITensorVisualization_A_B_C.png) You can switch back to another backend like the following: ```julia @@ -93,10 +154,16 @@ julia> ITensorVisualizationBase.set_backend!("UnicodePlots"); julia> ITensorVisualizationBase.get_backend() ITensorVisualizationBase.Backend{:UnicodePlots}() -julia> ABC = @visualize A * B * C edge_labels=(tags=true,) # The visualization will now use the UnicodePlots backend +julia> ABC = @visualize A * B * C edge_labels = (tags = true,) # The visualization will now use the UnicodePlots backend [...] ``` -The visualization makes an initial guess for the locations of the tensors (using [NetworkLayout.jl](https://github.com/JuliaGraphs/NetworkLayout.jl)), and then allows users to interactively move the tensors to better locations. You can move the tensors and external indices (the square and circle nodes of the network) by left clicking on a node and dragging it to a new location. You can also right click and drag to translate the entire diagram, and scroll to zoom in and out. + +The visualization makes an initial guess for the locations of the tensors (using +[NetworkLayout.jl](https://github.com/JuliaGraphs/NetworkLayout.jl)), and then allows +users to interactively move the tensors to better locations. You can move the tensors +and external indices (the square and circle nodes of the network) by left clicking on a +node and dragging it to a new location. You can also right click and drag to translate +the entire diagram, and scroll to zoom in and out. In addition, you can visualize multiple steps of a contraction as follows: ```julia @@ -105,10 +172,16 @@ julia> ITensorVisualizationBase.set_backend!("Makie"); julia> ITensorVisualizationBase.get_backend() ITensorVisualizationBase.Backend{:Makie}() -julia> AB = @visualize fig A * B edge_labels=(tags=true,); +julia> AB = @visualize fig A * B edge_labels = (tags = true,); -julia> ABC = @visualize! fig[1, 2] AB * C edge_labels=(tags=true,); +julia> ABC = @visualize! fig[1, 2] AB * C edge_labels = (tags = true,); julia> fig ``` -![alt text](assets/ITensorVisualization_A_B_C_sequence.png) + +![alt text](https://raw.githubusercontent.com/ITensor/ITensorVisualizationBase.jl/main/assets/ITensorVisualization_A_B_C_sequence.png) + +--- + +*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).* + diff --git a/examples/README.jl b/examples/README.jl index 71d5846..f5ba6ba 100644 --- a/examples/README.jl +++ b/examples/README.jl @@ -41,7 +41,150 @@ julia> Pkg.add("ITensorVisualizationBase") ``` =# -# ## Examples +# This is an internal package providing common code for defining backends for visualizing +# tensor networks of ITensors. It is only an interface package, and does not provide +# concrete implementations of visualizing tensor network code (by default, it does +# nothing). You will need to load a visualization backend, such as `ITensorUnicodePlots` +# or `ITensorGLMakie`. The main purpose is to use it with the +# [ITensors.jl](https://github.com/ITensor/ITensors.jl) package to view and debug tensor +# network contractions, for example: -using ITensorVisualizationBase: ITensorVisualizationBase -# Examples go here. +using ITensorVisualizationBase: ITensorVisualizationBase, @visualize +using ITensors: Index, random_itensor + +# Load a visualization backend, which will reexport the interface of +# `ITensorVisualizationBase` automatically: +#= +```julia +using ITensorUnicodePlots +``` +=# + +# (we leave the `using ITensorUnicodePlots` line out of this example so it can run in +# test environments that do not have the backend installed.) + +# `ITensorVisualizationBase` handles the logic of switching between backends: + +@show ITensorVisualizationBase.get_backend() + +i = Index(2, "i") +j = Index(10, "j") +k = Index(40, "k") +l = Index(40, "l") +m = Index(40, "m") +A = random_itensor(i, j, k) +B = random_itensor(i, j, l, m) +C = random_itensor(k, l) +ABC = @visualize A * B * C + +# With the `ITensorUnicodePlots` backend loaded, this outputs: + +#= +```julia +ITensorVisualizationBase.get_backend() = ITensorVisualizationBase.Backend{:UnicodePlots}()⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀A⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⢱⠀⠀⠉⠉⠑⠒⠒⠤⠤⢄⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⢇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠑⠒⠒⠤⠤40⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠒⠒⠢⠤⠤⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⢱⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠒⠒⠢⠤⠤C⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⢇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⠤⠒⠉⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠒⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀2⊗10⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔40⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀B⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀40⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ +``` +=# + +# You can show the visualization with tags with: + +ABC_tags = @visualize A * B * C edge_labels = (tags = true,) + +#= +```julia + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀A⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⢱⠀⠀⠉⠉⠑⠒⠒⠤⠤⢄⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⢇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠑⠒(40|"k")⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠒⠒⠢⠤⠤⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⢱⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠒⠒⠢⠤⠤C⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⢇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⠤⠒⠉⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠒⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀(2|"i")⊗(10|"j")⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀(40|"l")⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⠀⠀⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆⢀⡠⠔⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀B⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀(40|"m")⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ + ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ +``` +=# + +# In order to output a more sophisticated interactive visualization, you can load a +# Makie-based backend called `ITensorGLMakie`: +#= +```julia +using ITensorGLMakie + +ABC = @visualize A * B * C edge_labels = (tags = true,); +``` + +A window like the following should appear: + +![alt text](https://raw.githubusercontent.com/ITensor/ITensorVisualizationBase.jl/main/assets/ITensorVisualization_A_B_C.png) +=# + +# You can switch back to another backend like the following: +#= +```julia +julia> ITensorVisualizationBase.set_backend!("UnicodePlots"); + +julia> ITensorVisualizationBase.get_backend() +ITensorVisualizationBase.Backend{:UnicodePlots}() + +julia> ABC = @visualize A * B * C edge_labels = (tags = true,) # The visualization will now use the UnicodePlots backend +[...] +``` +=# + +# The visualization makes an initial guess for the locations of the tensors (using +# [NetworkLayout.jl](https://github.com/JuliaGraphs/NetworkLayout.jl)), and then allows +# users to interactively move the tensors to better locations. You can move the tensors +# and external indices (the square and circle nodes of the network) by left clicking on a +# node and dragging it to a new location. You can also right click and drag to translate +# the entire diagram, and scroll to zoom in and out. + +# In addition, you can visualize multiple steps of a contraction as follows: +#= +```julia +julia> ITensorVisualizationBase.set_backend!("Makie"); + +julia> ITensorVisualizationBase.get_backend() +ITensorVisualizationBase.Backend{:Makie}() + +julia> AB = @visualize fig A * B edge_labels = (tags = true,); + +julia> ABC = @visualize! fig[1, 2] AB * C edge_labels = (tags = true,); + +julia> fig +``` + +![alt text](https://raw.githubusercontent.com/ITensor/ITensorVisualizationBase.jl/main/assets/ITensorVisualization_A_B_C_sequence.png) +=# From b595021b1cfe255b84de64fee50a4ddfa8640123 Mon Sep 17 00:00:00 2001 From: Matthew Fishman Date: Sat, 25 Apr 2026 10:23:57 -0400 Subject: [PATCH 2/2] Restore "## Examples" section header Dropped accidentally in the previous commit; the template structure expects it before the usage prose. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 2 ++ examples/README.jl | 2 ++ 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index 7703ae4..33f50a5 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,8 @@ Then, the package can be added as usual through the package manager: julia> Pkg.add("ITensorVisualizationBase") ``` +## Examples + This is an internal package providing common code for defining backends for visualizing tensor networks of ITensors. It is only an interface package, and does not provide concrete implementations of visualizing tensor network code (by default, it does diff --git a/examples/README.jl b/examples/README.jl index f5ba6ba..fd5e652 100644 --- a/examples/README.jl +++ b/examples/README.jl @@ -41,6 +41,8 @@ julia> Pkg.add("ITensorVisualizationBase") ``` =# +# ## Examples + # This is an internal package providing common code for defining backends for visualizing # tensor networks of ITensors. It is only an interface package, and does not provide # concrete implementations of visualizing tensor network code (by default, it does