From 0a424ff9ee317fb326804aa0aea06aef9cb6bd3c Mon Sep 17 00:00:00 2001 From: GiggleLiu Date: Sun, 24 Sep 2023 01:33:14 +0800 Subject: [PATCH] update README and improve complexity printing --- CITATION.bib | 51 ++++++++++++++++ README.md | 147 +++++++++++++--------------------------------- src/complexity.jl | 6 +- 3 files changed, 96 insertions(+), 108 deletions(-) create mode 100644 CITATION.bib diff --git a/CITATION.bib b/CITATION.bib new file mode 100644 index 0000000..c4f0027 --- /dev/null +++ b/CITATION.bib @@ -0,0 +1,51 @@ +@misc{Liu2022, + doi = {10.48550/ARXIV.2205.03718}, + url = {https://arxiv.org/abs/2205.03718}, + author = {Liu, Jin-Guo and Gao, Xun and Cain, Madelyn and Lukin, Mikhail D. and Wang, Sheng-Tao}, + keywords = {Statistical Mechanics (cond-mat.stat-mech), FOS: Physical sciences, FOS: Physical sciences}, + title = {Computing solution space properties of combinatorial optimization problems via generic tensor networks}, + publisher = {arXiv}, + year = {2022}, + copyright = {Creative Commons Attribution 4.0 International} +} +@misc{Pan2021, + title={Simulating the Sycamore quantum supremacy circuits}, + author={Feng Pan and Pan Zhang}, + year={2021}, + eprint={2103.03074}, + archivePrefix={arXiv}, + primaryClass={quant-ph} +} +@Article{10.21468/SciPostPhys.7.5.060, + title={{Fast counting with tensor networks}}, + author={Stefanos Kourtis and Claudio Chamon and Eduardo R. Mucciolo and Andrei E. Ruckenstein}, + journal={SciPost Phys.}, + volume={7}, + issue={5}, + pages={60}, + year={2019}, + publisher={SciPost}, + doi={10.21468/SciPostPhys.7.5.060}, + url={https://scipost.org/10.21468/SciPostPhys.7.5.060}, +} +@article{Gray2021, + title={Hyper-optimized tensor network contraction}, + volume={5}, + ISSN={2521-327X}, + url={http://dx.doi.org/10.22331/q-2021-03-15-410}, + DOI={10.22331/q-2021-03-15-410}, + journal={Quantum}, + publisher={Verein zur Forderung des Open Access Publizierens in den Quantenwissenschaften}, + author={Gray, Johnnie and Kourtis, Stefanos}, + year={2021}, + month={Mar}, + pages={410} +} +@misc{kalachev2021recursive, + title={Recursive Multi-Tensor Contraction for XEB Verification of Quantum Circuits}, + author={Gleb Kalachev and Pavel Panteleev and Man-Hong Yung}, + year={2021}, + eprint={2108.05665}, + archivePrefix={arXiv}, + primaryClass={quant-ph} +} diff --git a/README.md b/README.md index 5687411..1b51d51 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,22 @@ # OMEinsumContractionOrders -This package provides `optimize_code` function for finding tensor network contraction orders. + +OMEinsumContractionOrders is a Julia package that provides an `optimize_code` function for finding optimal contraction orders for tensor networks. It is designed to work with multiple tensor network packages, such as: [OMEinsum.jl](https://github.com/under-Peter/OMEinsum.jl/issues) package and [ITensorNetworks.jl](https://github.com/mtfishman/ITensorNetworks.jl). [![Build Status](https://github.com/TensorBFS/OMEinsumContractionOrders.jl/workflows/CI/badge.svg)](https://github.com/TensorBFS/OMEinsumContractionOrders.jl/actions) [![codecov](https://codecov.io/gh/TensorBFS/OMEinsumContractionOrders.jl/branch/master/graph/badge.svg?token=BwaF0cV6q1)](https://codecov.io/gh/TensorBFS/OMEinsumContractionOrders.jl) ## Installation -

-OMEinsumContractionOrders is a Julia Language package. To install OMEinsumContractionOrders, - please open - Julia's interactive session (known as REPL) and press ] key in the REPL to use the package mode, then type the following command -

-For stable release +To install OMEinsumContractionOrders, please follow these steps: -```julia -pkg> add OMEinsumContractionOrders -pkg> add KaHyPar -``` -The `KaHyPar` package (used in `KaHyParBipartite` optimizer) is optional because some one may have the binary issue, check [this](https://github.com/kahypar/KaHyPar.jl/issues/12) and [this](https://github.com/kahypar/KaHyPar.jl/issues/19). +1. Open Julia's interactive session (known as [REPL](https://docs.julialang.org/en/v1/manual/getting-started/)) by typing `julia` in your terminal. +2. Press the ] key in the REPL to enter the package mode. +3. Type `add OMEinsumContractionOrders` to install the stable release of the package. +4. (Optional) If you want to use the `KaHyParBipartite` optimizer, which is based on the KaHyPar library, type `add KaHyPar`. Note that this step is optional because some users may have issues with the binary dependencies of KaHyPar (please check issues: [this](https://github.com/kahypar/KaHyPar.jl/issues/12) and [this](https://github.com/kahypar/KaHyPar.jl/issues/19)). + +## Example 1: Use it directly +The contraction order optimizer is implemented in the `optimize_code` function. It takes three arguments: `code`, `size`, and `optimizer`. The `code` argument is the [einsum notation](https://numpy.org/doc/stable/reference/generated/numpy.einsum.html) to be optimized. The `size` argument is the size of the variables in the einsum notation. The `optimizer` argument is the optimizer to be used. The `optimize_code` function returns the optimized contraction order. One can use `contraction_complexity` function to get the time, space and rewrite complexity of returned contraction order. -## Example -Optimize a contraction order ```julia julia> using OMEinsumContractionOrders, Graphs, KaHyPar @@ -44,23 +40,35 @@ julia> optcode_kahypar = optimize_code(code, uniformsize(code, 2), julia> optcode_sa = optimize_code(code, uniformsize(code, 2), SABipartite(sc_target=30, max_group_size=50)); -julia> timespace_complexity(code, uniformsize(code, 2)) -(200.0, 0.0) - -julia> timespace_complexity(optcode_kahypar, uniformsize(code, 2)) -(39.00774639886569, 28.0) - -julia> timespace_complexity(optcode_sa, uniformsize(code, 2)) -(39.09524927371961, 28.0) - -julia> timespace_complexity(optcode_tree, uniformsize(code, 2)) -(31.13883492534964, 27.0) - -julia> timespace_complexity(optcode_tree_with_slice, uniformsize(code, 2)) -(31.292828948918775, 22.0) +julia> contraction_complexity(code, uniformsize(code, 2)) +Time complexity: 2^200.0 +Space complexity: 2^0.0 +Read-write complexity: 2^10.644757592516257 + +julia> contraction_complexity(optcode_kahypar, uniformsize(code, 2)) +Time complexity: 2^39.5938886486877 +Space complexity: 2^28.0 +Read-write complexity: 2^30.39890775966298 + +julia> contraction_complexity(optcode_sa, uniformsize(code, 2)) +Time complexity: 2^41.17129641027078 +Space complexity: 2^29.0 +Read-write complexity: 2^31.493976190321106 + +julia> contraction_complexity(optcode_tree, uniformsize(code, 2)) +Time complexity: 2^35.06468305863757 +Space complexity: 2^28.0 +Read-write complexity: 2^30.351552349259258 + +julia> contraction_complexity(optcode_tree_with_slice, uniformsize(code, 2)) +Time complexity: 2^33.70760100663681 +Space complexity: 2^24.0 +Read-write complexity: 2^32.17575935629581 ``` -It is already a part of [`OMEinsum`](https://github.com/under-Peter/OMEinsum.jl): +## Example 2: Use it in `OMEinsum` + +`OMEinsumContractionOrders` is shipped with [`OMEinsum`](https://github.com/under-Peter/OMEinsum.jl) package. You can use it to optimize the contraction order of an `OMEinsum` expression. ```julia julia> using OMEinsum @@ -68,7 +76,7 @@ julia> using OMEinsum julia> code = ein"ij, jk, kl, il->" ij, jk, kl, il -> -julia> optimize_code(code, uniformsize(code, 2), TreeSA()) +julia> optimized_code = optimize_code(code, uniformsize(code, 2), TreeSA()) SlicedEinsum{Char, NestedEinsum{DynamicEinCode{Char}}}(Char[], ki, ki -> ├─ jk, ij -> ki │ ├─ jk @@ -79,86 +87,15 @@ SlicedEinsum{Char, NestedEinsum{DynamicEinCode{Char}}}(Char[], ki, ki -> ) ``` -## Acknowledge OMEinsum/OMEinsumContractionOrders -Since we do not have a paper to cite, we wish anyone who finds this package useful in his research can post a comment under this issue: -https://github.com/TensorBFS/OMEinsumContractionOrders.jl/issues/21 - ## References -If you find this package useful in your research, please cite the following papers -``` -@misc{Liu2022, - doi = {10.48550/ARXIV.2205.03718}, - url = {https://arxiv.org/abs/2205.03718}, - author = {Liu, Jin-Guo and Gao, Xun and Cain, Madelyn and Lukin, Mikhail D. and Wang, Sheng-Tao}, - keywords = {Statistical Mechanics (cond-mat.stat-mech), FOS: Physical sciences, FOS: Physical sciences}, - title = {Computing solution space properties of combinatorial optimization problems via generic tensor networks}, - publisher = {arXiv}, - year = {2022}, - copyright = {Creative Commons Attribution 4.0 International} -} -``` - -To credit the `KaHyParBipartite` and `SABipartite` method, -``` -@misc{Pan2021, - title={Simulating the Sycamore quantum supremacy circuits}, - author={Feng Pan and Pan Zhang}, - year={2021}, - eprint={2103.03074}, - archivePrefix={arXiv}, - primaryClass={quant-ph} -} -``` - -To credit the `KaHyParBipartite` method, -``` -@Article{10.21468/SciPostPhys.7.5.060, - title={{Fast counting with tensor networks}}, - author={Stefanos Kourtis and Claudio Chamon and Eduardo R. Mucciolo and Andrei E. Ruckenstein}, - journal={SciPost Phys.}, - volume={7}, - issue={5}, - pages={60}, - year={2019}, - publisher={SciPost}, - doi={10.21468/SciPostPhys.7.5.060}, - url={https://scipost.org/10.21468/SciPostPhys.7.5.060}, -} -``` - -``` -@article{Gray2021, - title={Hyper-optimized tensor network contraction}, - volume={5}, - ISSN={2521-327X}, - url={http://dx.doi.org/10.22331/q-2021-03-15-410}, - DOI={10.22331/q-2021-03-15-410}, - journal={Quantum}, - publisher={Verein zur Forderung des Open Access Publizierens in den Quantenwissenschaften}, - author={Gray, Johnnie and Kourtis, Stefanos}, - year={2021}, - month={Mar}, - pages={410} -} -``` - -To credit the `TreeSA` method, -``` -@misc{kalachev2021recursive, - title={Recursive Multi-Tensor Contraction for XEB Verification of Quantum Circuits}, - author={Gleb Kalachev and Pavel Panteleev and Man-Hong Yung}, - year={2021}, - eprint={2108.05665}, - archivePrefix={arXiv}, - primaryClass={quant-ph} -} -``` +If you find this package useful in your research, please cite the *relevant* papers in [CITATION.bib](CITATION.bib). ## Multi-GPU computation -Check this Gist: +Please check this Gist: https://gist.github.com/GiggleLiu/d5b66c9883f0c5df41a440589983ab99 ## Authors -Jin-Guo Liu and Pan Zhang + +OMEinsumContractionOrders was developed by Jin-Guo Liu and Pan Zhang. \ No newline at end of file diff --git a/src/complexity.jl b/src/complexity.jl index 36f8043..8411f14 100644 --- a/src/complexity.jl +++ b/src/complexity.jl @@ -172,9 +172,9 @@ struct ContractionComplexity end function Base.show(io::IO, cc::ContractionComplexity) - print(io, "Time complexity (number of element-wise multiplications) = 2^$(cc.tc) -Space complexity (number of elements in the largest intermediate tensor) = 2^$(cc.sc) -Read-write complexity (number of element-wise read and write) = 2^$(cc.rwc)") + print(io, "Time complexity: 2^$(cc.tc) +Space complexity: 2^$(cc.sc) +Read-write complexity: 2^$(cc.rwc)") end Base.iterate(cc::ContractionComplexity) = Base.iterate((cc.tc, cc.sc, cc.rwc)) Base.iterate(cc::ContractionComplexity, state) = Base.iterate((cc.tc, cc.sc, cc.rwc), state)