├── .codecov.yml ├── .gitattributes ├── .github ├── CONTRIBUTING.md ├── ISSUE_TEMPLATE │ ├── bugreport.yml │ ├── config.yml │ ├── misc.yml │ └── newfeature.yml └── workflows │ ├── pypi-release.yml │ └── tests.yml ├── .gitignore ├── LICENSE.txt ├── README.md ├── bin └── quimb-mpi-python ├── ci └── requirements │ ├── py-base.yml │ ├── py-jax.yml │ ├── py-openblas.yml │ ├── py-slepc.yml │ ├── py-tensorflow.yml │ └── py-torch.yml ├── docs ├── Makefile ├── _pygments │ ├── _pygments_dark.py │ └── _pygments_light.py ├── _static │ ├── amplitude.png │ ├── basic-compress.png │ ├── branching.png │ ├── canonize-bond.png │ ├── compute_marginal.png │ ├── docset.css │ ├── isometric-tensor.png │ ├── kagome-contract-treeset-2.png │ ├── local_expectation.png │ ├── logo-banner.png │ ├── montage.png │ ├── my-styles.css │ ├── partial_trace.png │ ├── quimb.ico │ ├── quimb_logo.png │ ├── quimb_logo_small.png │ ├── quimb_logo_title.png │ ├── rand-herm-matrix.svg │ ├── rand-tensor.svg │ ├── sample.png │ ├── sample_chaotic.png │ ├── sample_gate_by_gate.png │ └── to_dense.png ├── _templates │ └── layout.html ├── basics.ipynb ├── calculating quantities.ipynb ├── changelog.md ├── conf.py ├── develop.md ├── distributed parallelism - mpi.md ├── dynamics and evolution.ipynb ├── examples │ ├── ex_2d.ipynb │ ├── ex_MERA.ipynb │ ├── ex_TEBD_evo.ipynb │ ├── ex_circuit_to_mpo.ipynb │ ├── ex_distributed_shift_invert.ipynb │ ├── ex_dmrg_periodic.ipynb │ ├── ex_htn_to_tn_2d.ipynb │ ├── ex_mpi_expm_evo.py │ ├── ex_quench.ipynb │ ├── ex_quimb_within_jax_flax_optax.ipynb │ ├── ex_quimb_within_torch.ipynb │ ├── ex_real_time_simple_update.ipynb │ ├── ex_tensorflow_optimize_pbc_mps.ipynb │ ├── ex_tn_TRG.ipynb │ ├── ex_tn_circuit_sample_explore.ipynb │ ├── ex_tn_qaoa_energy_bayesopt.ipynb │ ├── ex_tn_rand_uni_gate_graphs.ipynb │ ├── ex_tn_tensor_fitting.ipynb │ ├── ex_tn_train_circuit.ipynb │ ├── inst_7x7_31_0.txt │ ├── readme.md │ └── schematic-demo.ipynb ├── generate.md ├── index.md ├── index_examples.md ├── index_matrix.md ├── index_tn.md ├── installation.md ├── make.bat ├── solving systems.ipynb ├── tensor-1d.ipynb ├── tensor-2d.ipynb ├── tensor-basics.ipynb ├── tensor-circuit-mps.ipynb ├── tensor-circuit.ipynb ├── tensor-contraction.ipynb ├── tensor-design.ipynb ├── tensor-drawing.ipynb └── tensor-optimization.ipynb ├── paper ├── fig-TN-graph.png ├── paper.bib └── paper.md ├── pyproject.toml ├── quimb ├── __init__.py ├── calc.py ├── core.py ├── evo.py ├── experimental │ ├── __init__.py │ ├── autojittn.py │ ├── belief_propagation │ │ ├── __init__.py │ │ └── hd1gbp.py │ ├── cluster_update.py │ ├── merabuilder │ │ ├── __init__.py │ │ ├── merabuilder demo.ipynb │ │ └── merabuilder.py │ ├── misc │ │ ├── __init__.py │ │ ├── cp_decomp.py │ │ ├── misc.py │ │ ├── peps_dmrg.py │ │ ├── renormalization.ipynb │ │ ├── renormalization.py │ │ ├── tn_virtual_tree_gauge.ipynb │ │ └── tn_virtual_tree_gauge.py │ ├── operatorbuilder │ │ ├── __init__.py │ │ ├── builder.py │ │ ├── configcore.py │ │ ├── hilbertspace.py │ │ ├── models.py │ │ ├── operatorbuilder demo.ipynb │ │ └── pepobuilder.py │ ├── schematic.py │ ├── tensor_1d_gate │ │ └── tensor_1d_mpo_gate_methods.py │ ├── tn_marginals.py │ └── tnvmc │ │ ├── __init__.py │ │ ├── tnvmc demo.ipynb │ │ └── tnvmc.py ├── gates.py ├── gen │ ├── __init__.py │ ├── operators.py │ ├── rand.py │ └── states.py ├── linalg │ ├── __init__.py │ ├── approx_spectral.py │ ├── autoblock.py │ ├── base_linalg.py │ ├── mpi_launcher.py │ ├── numpy_linalg.py │ ├── rand_linalg.py │ ├── scipy_linalg.py │ └── slepc_linalg.py ├── schematic.py ├── tensor │ ├── __init__.py │ ├── array_ops.py │ ├── belief_propagation │ │ ├── __init__.py │ │ ├── bp_common.py │ │ ├── d1bp.py │ │ ├── d2bp.py │ │ ├── diis.py │ │ ├── hd1bp.py │ │ ├── hv1bp.py │ │ ├── l1bp.py │ │ ├── l2bp.py │ │ └── regions.py │ ├── circuit.py │ ├── circuit_gen.py │ ├── contraction.py │ ├── decomp.py │ ├── drawing.py │ ├── fitting.py │ ├── geometry.py │ ├── interface.py │ ├── networking.py │ ├── optimize.py │ ├── tensor_1d.py │ ├── tensor_1d_compress.py │ ├── tensor_1d_tebd.py │ ├── tensor_2d.py │ ├── tensor_2d_compress.py │ ├── tensor_2d_tebd.py │ ├── tensor_3d.py │ ├── tensor_3d_tebd.py │ ├── tensor_approx_spectral.py │ ├── tensor_arbgeom.py │ ├── tensor_arbgeom_compress.py │ ├── tensor_arbgeom_tebd.py │ ├── tensor_builder.py │ ├── tensor_core.py │ ├── tensor_dmrg.py │ └── tensor_mera.py ├── utils.py └── utils_plot.py ├── readthedocs.yml └── tests ├── __init__.py ├── test_matrix ├── __init__.py ├── test_accel.py ├── test_calc.py ├── test_core.py ├── test_evo.py ├── test_gen │ ├── __init__.py │ ├── test_operators.py │ ├── test_rand.py │ └── test_states.py └── test_linalg │ ├── __init__.py │ ├── test_approx_spectral.py │ ├── test_base_linalg.py │ ├── test_mpi_linalg.py │ ├── test_numpy_linalg.py │ ├── test_rand_linalg.py │ └── test_slepc_linalg.py ├── test_operator ├── __init__.py ├── test_builder.py └── test_models.py ├── test_tensor ├── __init__.py ├── test_belief_propagation │ ├── __init__.py │ ├── test_d1bp.py │ ├── test_d2bp.py │ ├── test_hd1bp.py │ ├── test_hv1bp.py │ ├── test_l1bp.py │ └── test_l2bp.py ├── test_circuit.py ├── test_contract.py ├── test_decomp.py ├── test_fitting.py ├── test_mera.py ├── test_optimizers.py ├── test_tensor_1d.py ├── test_tensor_2d.py ├── test_tensor_2d_tebd.py ├── test_tensor_3d.py ├── test_tensor_arbgeom.py ├── test_tensor_builder.py ├── test_tensor_core.py ├── test_tensor_dmrg.py ├── test_tensor_spectral_approx.py └── test_tensor_tebd.py └── test_utils.py /.codecov.yml: -------------------------------------------------------------------------------- 1 | codecov: 2 | require_ci_to_pass: yes 3 | 4 | coverage: 5 | range: 50..100 6 | status: 7 | project: 8 | default: 9 | informational: true 10 | patch: 11 | default: 12 | informational: true 13 | changes: false 14 | 15 | comment: off 16 | 17 | github_checks: 18 | annotations: false -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Auto detect text files and perform LF normalization 2 | * text=auto 3 | 4 | # Custom for Visual Studio 5 | *.cs diff=csharp 6 | 7 | # Standard to msysgit 8 | *.doc diff=astextplain 9 | *.DOC diff=astextplain 10 | *.docx diff=astextplain 11 | *.DOCX diff=astextplain 12 | *.dot diff=astextplain 13 | *.DOT diff=astextplain 14 | *.pdf diff=astextplain 15 | *.PDF diff=astextplain 16 | *.rtf diff=astextplain 17 | *.RTF diff=astextplain 18 | quimb/_version.py export-subst 19 | 20 | # ensure quimb appears as a python project on github 21 | *.ipynb linguist-language=Python 22 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Any contributions to ``quimb`` in the form of [pull requests](https://github.com/jcmgray/quimb/pulls) are very welcome! Consider also raising an [issue](https://github.com/jcmgray/quimb/issues) first. If this is the first time, the following might be useful introductions to github pull requests: 4 | 5 | * [Github - Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) 6 | * [Thinkful - Pull Request Tutorial](https://www.thinkful.com/learn/github-pull-request-tutorial/) 7 | 8 | Additionally, make sure any new code is properly accompanied by working through the following checklist: 9 | 10 | - [ ] Tests have been added for any new functionality in ``quimb/tests`` 11 | - [ ] All other tests still pass (when running ``pytest`` in the root directory) 12 | - [ ] Any functions added have [``numpy`` style docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html) 13 | - [ ] If suitable, funtionality is documented in ``quimb/docs`` or an example notebook added in ``quimb/docs/examples`` 14 | - [ ] The code is linted with PEP8 15 | 16 | Extra developer details can be found [here](http://quimb.readthedocs.io/en/latest/develop.html). 17 | 18 | 19 | # Contributor Covenant Code of Conduct 20 | 21 | ## Our Pledge 22 | 23 | In the interest of fostering an open and welcoming environment, we as 24 | contributors and maintainers pledge to making participation in our project and 25 | our community a harassment-free experience for everyone, regardless of age, body 26 | size, disability, ethnicity, gender identity and expression, level of experience, 27 | education, socio-economic status, nationality, personal appearance, race, 28 | religion, or sexual identity and orientation. 29 | 30 | ## Our Standards 31 | 32 | Examples of behavior that contributes to creating a positive environment 33 | include: 34 | 35 | * Using welcoming and inclusive language 36 | * Being respectful of differing viewpoints and experiences 37 | * Gracefully accepting constructive criticism 38 | * Focusing on what is best for the community 39 | * Showing empathy towards other community members 40 | 41 | Examples of unacceptable behavior by participants include: 42 | 43 | * The use of sexualized language or imagery and unwelcome sexual attention or 44 | advances 45 | * Trolling, insulting/derogatory comments, and personal or political attacks 46 | * Public or private harassment 47 | * Publishing others' private information, such as a physical or electronic 48 | address, without explicit permission 49 | * Other conduct which could reasonably be considered inappropriate in a 50 | professional setting 51 | 52 | ## Our Responsibilities 53 | 54 | Project maintainers are responsible for clarifying the standards of acceptable 55 | behavior and are expected to take appropriate and fair corrective action in 56 | response to any instances of unacceptable behavior. 57 | 58 | Project maintainers have the right and responsibility to remove, edit, or 59 | reject comments, commits, code, wiki edits, issues, and other contributions 60 | that are not aligned to this Code of Conduct, or to ban temporarily or 61 | permanently any contributor for other behaviors that they deem inappropriate, 62 | threatening, offensive, or harmful. 63 | 64 | ## Scope 65 | 66 | This Code of Conduct applies both within project spaces and in public spaces 67 | when an individual is representing the project or its community. Examples of 68 | representing a project or community include using an official project e-mail 69 | address, posting via an official social media account, or acting as an appointed 70 | representative at an online or offline event. Representation of a project may be 71 | further defined and clarified by project maintainers. 72 | 73 | ## Enforcement 74 | 75 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 76 | reported by contacting the project team at [INSERT EMAIL ADDRESS]. All 77 | complaints will be reviewed and investigated and will result in a response that 78 | is deemed necessary and appropriate to the circumstances. The project team is 79 | obligated to maintain confidentiality with regard to the reporter of an incident. 80 | Further details of specific enforcement policies may be posted separately. 81 | 82 | Project maintainers who do not follow or enforce the Code of Conduct in good 83 | faith may face temporary or permanent repercussions as determined by other 84 | members of the project's leadership. 85 | 86 | ## Attribution 87 | 88 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 89 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 90 | 91 | [homepage]: https://www.contributor-covenant.org 92 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bugreport.yml: -------------------------------------------------------------------------------- 1 | name: Bug Report 2 | description: File a bug report to help us improve 3 | labels: [bug] 4 | body: 5 | - type: textarea 6 | id: what-happened 7 | attributes: 8 | label: What happened? 9 | description: | 10 | Thanks for reporting a bug! Please describe what you were trying to get done. 11 | Tell us what happened, what went wrong. 12 | validations: 13 | required: true 14 | 15 | - type: textarea 16 | id: what-did-you-expect-to-happen 17 | attributes: 18 | label: What did you expect to happen? 19 | description: | 20 | Describe what you expected to happen. 21 | validations: 22 | required: false 23 | 24 | - type: textarea 25 | id: sample-code 26 | attributes: 27 | label: Minimal Complete Verifiable Example 28 | description: | 29 | Minimal, self-contained copy-pastable example that generates the issue if possible. Please be concise with code posted. See guidelines below on how to provide a good bug report: 30 | 31 | - [Minimal Complete Verifiable Examples](https://stackoverflow.com/help/mcve) 32 | - [Craft Minimal Bug Reports](http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) 33 | 34 | Bug reports that follow these guidelines are easier to diagnose, and so are often handled much more quickly. 35 | This will be automatically formatted into code, so no need for markdown backticks. 36 | render: Python 37 | 38 | - type: textarea 39 | id: log-output 40 | attributes: 41 | label: Relevant log output 42 | description: Please copy and paste any relevant output. This will be automatically formatted into code, so no need for markdown backticks. 43 | render: Python 44 | 45 | - type: textarea 46 | id: extra 47 | attributes: 48 | label: Anything else we need to know? 49 | description: | 50 | Please describe any other information you want to share. 51 | 52 | - type: textarea 53 | id: show-versions 54 | attributes: 55 | label: Environment 56 | description: | 57 | Is this with the latest version of `quimb` from github? 58 | validations: 59 | required: true 60 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: Usage question 4 | url: https://github.com/jcmgray/quimb/discussions 5 | about: | 6 | Ask questions and discuss with other community members here. 7 | If you have a question then please include a self-contained reproducible 8 | example if possible. 9 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/misc.yml: -------------------------------------------------------------------------------- 1 | name: Issue 2 | description: General Issue or discussion topic. For usage questions, please follow the "Usage question" link 3 | labels: [] 4 | body: 5 | - type: markdown 6 | attributes: 7 | value: | 8 | Please describe your issue here. 9 | - type: textarea 10 | id: issue-description 11 | attributes: 12 | label: What is your issue? 13 | description: | 14 | Thank you for filing an issue! Please give us further information on how we can help you. 15 | placeholder: Please describe your issue. 16 | validations: 17 | required: true 18 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/newfeature.yml: -------------------------------------------------------------------------------- 1 | name: Feature Request 2 | description: Suggest an idea for quimb 3 | labels: [enhancement] 4 | body: 5 | - type: textarea 6 | id: description 7 | attributes: 8 | label: Is your feature request related to a problem? 9 | description: | 10 | Please do a quick search of existing issues to make sure that this has not been asked before. 11 | Please provide a clear and concise description of what the problem is. 12 | validations: 13 | required: true 14 | - type: textarea 15 | id: solution 16 | attributes: 17 | label: Describe the solution you'd like 18 | description: | 19 | A clear and concise description of what you want to happen. 20 | - type: textarea 21 | id: alternatives 22 | attributes: 23 | label: Describe alternatives you've considered 24 | description: | 25 | A clear and concise description of any alternative solutions or features you've considered. 26 | validations: 27 | required: false 28 | - type: textarea 29 | id: additional-context 30 | attributes: 31 | label: Additional context 32 | description: | 33 | Add any other context about the feature request here. 34 | validations: 35 | required: false 36 | -------------------------------------------------------------------------------- /.github/workflows/pypi-release.yml: -------------------------------------------------------------------------------- 1 | name: Build and Upload quimb to PyPI 2 | on: 3 | workflow_dispatch: 4 | release: 5 | types: 6 | - published 7 | push: 8 | tags: 9 | - 'v*' 10 | 11 | jobs: 12 | build-artifacts: 13 | runs-on: ubuntu-latest 14 | if: github.repository == 'jcmgray/quimb' 15 | steps: 16 | - uses: actions/checkout@v4 17 | with: 18 | fetch-depth: 0 19 | - uses: actions/setup-python@v5 20 | name: Install Python 21 | with: 22 | python-version: "3.12" 23 | 24 | - name: Install dependencies 25 | run: | 26 | python -m pip install --upgrade pip 27 | python -m pip install build twine 28 | 29 | - name: Build tarball and wheels 30 | run: | 31 | git clean -xdf 32 | git restore -SW . 33 | python -m build 34 | 35 | - name: Check built artifacts 36 | run: | 37 | python -m twine check --strict dist/* 38 | pwd 39 | if [ -f dist/quimb-0.0.0.tar.gz ]; then 40 | echo "❌ INVALID VERSION NUMBER" 41 | exit 1 42 | else 43 | echo "✅ Looks good" 44 | fi 45 | - uses: actions/upload-artifact@v4 46 | with: 47 | name: releases 48 | path: dist 49 | 50 | test-built-dist: 51 | needs: build-artifacts 52 | runs-on: ubuntu-latest 53 | steps: 54 | - uses: actions/setup-python@v5 55 | name: Install Python 56 | with: 57 | python-version: "3.12" 58 | - uses: actions/download-artifact@v4 59 | with: 60 | name: releases 61 | path: dist 62 | - name: List contents of built dist 63 | run: | 64 | ls -ltrh 65 | ls -ltrh dist 66 | 67 | - name: Verify the built dist/wheel is valid 68 | if: github.event_name == 'push' 69 | run: | 70 | python -m pip install --upgrade pip 71 | python -m pip install dist/quimb*.whl 72 | 73 | upload-to-test-pypi: 74 | needs: test-built-dist 75 | if: github.event_name == 'push' 76 | runs-on: ubuntu-latest 77 | 78 | environment: 79 | name: pypi 80 | url: https://test.pypi.org/p/quimb 81 | permissions: 82 | id-token: write 83 | 84 | steps: 85 | - uses: actions/download-artifact@v4 86 | with: 87 | name: releases 88 | path: dist 89 | - name: Publish package to TestPyPI 90 | if: github.event_name == 'push' 91 | uses: pypa/gh-action-pypi-publish@v1.12.3 92 | with: 93 | repository-url: https://test.pypi.org/legacy/ 94 | verbose: true 95 | 96 | 97 | upload-to-pypi: 98 | needs: test-built-dist 99 | if: github.event_name == 'release' 100 | runs-on: ubuntu-latest 101 | 102 | environment: 103 | name: pypi 104 | url: https://pypi.org/p/quimb 105 | permissions: 106 | id-token: write 107 | 108 | steps: 109 | - uses: actions/download-artifact@v4 110 | with: 111 | name: releases 112 | path: dist 113 | - name: Publish package to PyPI 114 | uses: pypa/gh-action-pypi-publish@v1.12.3 115 | with: 116 | verbose: true -------------------------------------------------------------------------------- /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: Tests 2 | 3 | on: 4 | workflow_dispatch: 5 | push: 6 | pull_request: 7 | 8 | defaults: 9 | run: 10 | shell: bash -l {0} 11 | 12 | jobs: 13 | run-tests: 14 | runs-on: ${{ matrix.os }} 15 | continue-on-error: ${{ matrix.flaky }} 16 | strategy: 17 | matrix: 18 | testset: [matrix, tensor] 19 | conda-env: [base] 20 | os: [ubuntu-latest] 21 | python-version: ['3.9', '3.12'] 22 | flaky: [false] 23 | 24 | include: 25 | - os: macos-latest 26 | testset: matrix 27 | conda-env: base 28 | python-version: '3.11' 29 | flaky: true 30 | 31 | - os: macos-latest 32 | testset: tensor 33 | conda-env: base 34 | python-version: '3.11' 35 | flaky: false 36 | 37 | - os: windows-latest 38 | testset: matrix 39 | conda-env: openblas 40 | python-version: '3.11' 41 | flaky: false 42 | env: 43 | KMP_DUPLICATE_LIB_OK: "True" 44 | 45 | - os: windows-latest 46 | testset: tensor 47 | conda-env: openblas 48 | python-version: '3.11' 49 | flaky: false 50 | env: 51 | KMP_DUPLICATE_LIB_OK: "True" 52 | 53 | - conda-env: torch 54 | testset: tensor 55 | os: ubuntu-latest 56 | python-version: '3.11' 57 | flaky: false 58 | 59 | - conda-env: jax 60 | testset: tensor 61 | os: ubuntu-latest 62 | python-version: '3.11' 63 | flaky: false 64 | 65 | - conda-env: tensorflow 66 | testset: tensor 67 | os: ubuntu-latest 68 | python-version: '3.11' 69 | flaky: false 70 | 71 | - conda-env: slepc 72 | testset: matrix 73 | os: ubuntu-latest 74 | python-version: '3.11' 75 | flaky: false 76 | 77 | steps: 78 | - uses: actions/checkout@v4 79 | 80 | - name: Setup Miniconda 81 | uses: conda-incubator/setup-miniconda@v3 82 | with: 83 | miniforge-version: latest 84 | conda-remove-defaults: "true" 85 | python-version: ${{ matrix.python-version }} 86 | environment-file: ci/requirements/py-${{ matrix.conda-env }}.yml 87 | 88 | - name: Matrix submodule tests with pytest 89 | if: ${{ matrix.testset == 'matrix' }} 90 | run: pytest tests/ --cov=quimb --cov-report=xml --ignore=tests/test_tensor 91 | 92 | - name: Tensor tests with pytest 93 | if: ${{ matrix.testset == 'tensor' }} 94 | run: pytest tests/test_tensor --cov=quimb --cov-report=xml 95 | 96 | - name: Report to codecov 97 | uses: codecov/codecov-action@v4 98 | with: 99 | token: ${{ secrets.CODECOV_TOKEN }} 100 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | env/ 12 | build/ 13 | develop-eggs/ 14 | dist/ 15 | downloads/ 16 | eggs/ 17 | .eggs/ 18 | lib/ 19 | lib64/ 20 | parts/ 21 | sdist/ 22 | var/ 23 | *.egg-info/ 24 | .installed.cfg 25 | *.egg 26 | [.]venv 27 | .python-version 28 | __pypackages__ 29 | 30 | # PyInstaller 31 | # Usually these files are written by a python script from a template 32 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 33 | *.manifest 34 | *.spec 35 | 36 | # Installer logs 37 | pip-log.txt 38 | pip-delete-this-directory.txt 39 | 40 | # Unit test / coverage reports 41 | htmlcov/ 42 | .tox/ 43 | .coverage 44 | .coverage.* 45 | .cache 46 | nosetests.xml 47 | coverage.xml 48 | *,cover 49 | 50 | # Translations 51 | *.mo 52 | *.pot 53 | 54 | # Django stuff: 55 | *.log 56 | 57 | # Editors 58 | *.swp 59 | *.swo 60 | 61 | # Sphinx documentation 62 | docs/_build/ 63 | 64 | # PyBuilder 65 | target/ 66 | 67 | # ========================= 68 | # Operating System Files 69 | # ========================= 70 | 71 | # OSX 72 | # ========================= 73 | 74 | .DS_Store 75 | .AppleDouble 76 | .LSOverride 77 | 78 | # Thumbnails 79 | ._* 80 | 81 | # Files that might appear in the root of a volume 82 | .DocumentRevisions-V100 83 | .fseventsd 84 | .Spotlight-V100 85 | .TemporaryItems 86 | .Trashes 87 | .VolumeIcon.icns 88 | 89 | # Directories potentially created on remote AFP share 90 | .AppleDB 91 | .AppleDesktop 92 | Network Trash Folder 93 | Temporary Items 94 | .apdisk 95 | 96 | # Windows 97 | # ========================= 98 | 99 | # Windows image file caches 100 | Thumbs.db 101 | ehthumbs.db 102 | 103 | # Folder config file 104 | Desktop.ini 105 | 106 | # Recycle Bin used on file shares 107 | $RECYCLE.BIN/ 108 | 109 | # Windows Installer files 110 | *.cab 111 | *.msi 112 | *.msm 113 | *.msp 114 | 115 | # Windows shortcuts 116 | *.lnk 117 | 118 | docs/_autosummary/ 119 | docs/autoapi 120 | 121 | .fuse_hidden* 122 | 123 | \.pytest_cache/ 124 | \.vscode/ 125 | *.ipynb_checkpoints/ 126 | 127 | # quimb specific 128 | ctg_cache 129 | quimb/_version.py 130 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright 2015-2024 Johnnie Gray 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"); 4 | you may not use this file except in compliance with the License. 5 | You may obtain a copy of the License at 6 | 7 | http://www.apache.org/licenses/LICENSE-2.0 8 | 9 | Unless required by applicable law or agreed to in writing, software 10 | distributed under the License is distributed on an "AS IS" BASIS, 11 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | See the License for the specific language governing permissions and 13 | limitations under the License. 14 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![quimb logo](https://github.com/jcmgray/quimb/blob/HEAD/docs/_static/logo-banner.png?raw=true) 2 | 3 | [![Tests](https://github.com/jcmgray/quimb/actions/workflows/tests.yml/badge.svg)](https://github.com/jcmgray/quimb/actions/workflows/tests.yml) 4 | [![Code Coverage](https://codecov.io/gh/jcmgray/quimb/branch/main/graph/badge.svg)](https://codecov.io/gh/jcmgray/quimb) 5 | [![Code Quality](https://app.codacy.com/project/badge/Grade/3c7462a3c45f41fd9d8f0a746a65c37c)](https://www.codacy.com/gh/jcmgray/quimb/dashboard?utm_source=github.com&utm_medium=referral&utm_content=jcmgray/quimb&utm_campaign=Badge_Grade) 6 | [![Documentation Status](https://readthedocs.org/projects/quimb/badge/?version=latest)](http://quimb.readthedocs.io/en/latest/?badge=latest) 7 | [![JOSS Paper](http://joss.theoj.org/papers/10.21105/joss.00819/status.svg)](https://doi.org/10.21105/joss.00819) 8 | [![PyPI](https://img.shields.io/pypi/v/quimb?color=teal)](https://pypi.org/project/quimb/) 9 | [![Anaconda-Server Badge](https://anaconda.org/conda-forge/quimb/badges/version.svg)](https://anaconda.org/conda-forge/quimb) 10 | 11 | [`quimb`](https://github.com/jcmgray/quimb) is an easy but fast python library for *'quantum information many-body'* calculations, focusing primarily on **tensor networks**. The code is hosted on [github](https://github.com/jcmgray/quimb), and docs are hosted on [readthedocs](http://quimb.readthedocs.io/en/latest/). Functionality is split in two: 12 | 13 | --- 14 | 15 | The `quimb.tensor` module contains tools for working with **tensors and tensor networks**. It has a particular focus on automatically handling arbitrary geometry, e.g. beyond 1D and 2D lattices. With this you can: 16 | 17 | - construct and manipulate arbitrary (hyper) graphs of tensor networks 18 | - automatically [contract](https://cotengra.readthedocs.io), optimize and draw networks 19 | - use various backend array libraries such as [jax](https://jax.readthedocs.io) and [torch](https://pytorch.org/) via [autoray](https://github.com/jcmgray/autoray/) 20 | - run specific MPS, PEPS, MERA and quantum circuit algorithms, such as DMRG & TEBD 21 | 22 | ![tensor pic](https://github.com/jcmgray/quimb/blob/HEAD/docs/_static/rand-tensor.svg?raw=true) 23 | 24 | --- 25 | 26 | The core `quimb` module contains tools for reference **'exact'** quantum calculations, where the states and operator are represented as either `numpy.ndarray` or `scipy.sparse` **matrices**. With this you can: 27 | 28 | - construct operators in complicated tensor spaces 29 | - find groundstates, excited states and do time evolutions, including with [slepc](https://slepc.upv.es/) 30 | - compute various quantities including entanglement measures 31 | - take advantage of [numba](https://numba.pydata.org) accelerations 32 | - stochastically estimate $\mathrm{Tr}f(X)$ quantities 33 | 34 | ![matrix pic](https://github.com/jcmgray/quimb/blob/HEAD/docs/_static/rand-herm-matrix.svg?raw=true) 35 | 36 | --- 37 | 38 | The **full documentation** can be found at: [quimb.readthedocs.io](https://quimb.readthedocs.io). Contributions of any sort are very welcome - please see the [contributing guide](https://github.com/jcmgray/quimb/blob/main/.github/CONTRIBUTING.md). [Issues](https://github.com/jcmgray/quimb/issues) and [pull requests](https://github.com/jcmgray/quimb/pulls) are hosted on [github](https://github.com/jcmgray/quimb). For other questions and suggestions, please use the [discussions page](https://github.com/jcmgray/quimb/discussions). -------------------------------------------------------------------------------- /bin/quimb-mpi-python: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | 4 | POSITIONAL=() 5 | while [[ $# -gt 0 ]] 6 | do 7 | key="$1" 8 | 9 | case $key in 10 | -h|--help) 11 | echo "Run a python script that uses quimb, eagerly launching 12 | with mpi, rather than dynamically spawning MPI processes. 13 | 14 | Usage: 15 | quimb-mpi-python [OPTIONS]... [SCRIPT]... 16 | 17 | Options: 18 | -n, --np 19 | How many mpi processes to use, defaults to 20 | letting the MPI launcher decide. 21 | -l, --launcher 22 | How to launch the python process, defaults 23 | to 'mpiexec'. Can add mpi options here. 24 | -s, --syncro 25 | Launch in syncro mode, where all processes 26 | run the script, splitting work up only when 27 | a MPIPool is encountered. 28 | -h, --help 29 | Show this help. 30 | 31 | Note that in syncro mode, *all* functions called outside 32 | of the mpi pool must be pure to ensure syncronization. 33 | " 34 | exit 0 35 | ;; 36 | -n|--np) 37 | num_procs="$2" 38 | shift 39 | shift 40 | ;; 41 | -s|--syncro) 42 | export QUIMB_SYNCRO_MPI=YES 43 | shift 44 | ;; 45 | -l|--launcher) 46 | mpi_launcher="$2" 47 | shift 48 | shift 49 | ;; 50 | "-") 51 | shift 52 | break 53 | ;; 54 | *) # unknown option 55 | POSITIONAL+=("$1") # save it in an array for later 56 | shift # past argument 57 | ;; 58 | esac 59 | done 60 | set -- "${POSITIONAL[@]}" # restore positional parameters 61 | 62 | mpi_launcher=${mpi_launcher:-"mpiexec"} 63 | 64 | # set up environment 65 | export OMP_NUM_THREADS=1 66 | export _QUIMB_MPI_LAUNCHED="MANUAL" 67 | 68 | if [ $QUIMB_SYNCRO_MPI ]; then # use simplistic syncronized pool 69 | if [ $num_procs ]; then 70 | echo "Launching quimb in Syncro mode with ${mpi_launcher} and ${num_procs} processes." 71 | ${mpi_launcher} --np "${num_procs}" python "$@" 72 | else 73 | echo "Launching quimb in Syncro mode with ${mpi_launcher}". 74 | ${mpi_launcher} python "$@" 75 | fi 76 | else # run script with mpi through mpi4py module 77 | if [ $num_procs ]; then 78 | echo "Launching quimb in mpi4py.futures mode with ${mpi_launcher} and ${num_procs} processes." 79 | ${mpi_launcher} --np "${num_procs}" python -m mpi4py.futures "$@" 80 | else 81 | echo "Launching quimb in mpi4py.futures mode with ${mpi_launcher}." 82 | ${mpi_launcher} python -m mpi4py.futures "$@" 83 | fi 84 | fi 85 | -------------------------------------------------------------------------------- /ci/requirements/py-base.yml: -------------------------------------------------------------------------------- 1 | channels: 2 | - conda-forge 3 | dependencies: 4 | - autoray>=0.6.12 5 | - cotengra>=0.7.1 6 | - coverage 7 | - cytoolz 8 | - joblib 9 | - matplotlib 10 | - networkx 11 | - numba>=0.56 12 | - numpy 13 | - psutil 14 | - pytest 15 | - pytest-cov 16 | - scipy<1.15.0 17 | - tqdm 18 | -------------------------------------------------------------------------------- /ci/requirements/py-jax.yml: -------------------------------------------------------------------------------- 1 | channels: 2 | - conda-forge 3 | dependencies: 4 | - autoray>=0.6.12 5 | - cotengra>=0.7.1 6 | - coverage 7 | - cytoolz 8 | - joblib 9 | - matplotlib 10 | - networkx 11 | - numba>=0.56 12 | - numpy 13 | - psutil 14 | - pytest 15 | - pytest-cov 16 | - scipy<1.15.0 17 | - tqdm 18 | - pip 19 | - pip: 20 | - jax[cpu] 21 | -------------------------------------------------------------------------------- /ci/requirements/py-openblas.yml: -------------------------------------------------------------------------------- 1 | channels: 2 | - conda-forge 3 | dependencies: 4 | - autoray>=0.6.12 5 | - blas=*=openblas 6 | - cotengra>=0.7.1 7 | - coverage 8 | - cytoolz 9 | - joblib 10 | - matplotlib 11 | - networkx 12 | - numba>=0.56 13 | - numpy 14 | - psutil 15 | - pytest 16 | - pytest-cov 17 | - scipy<1.15.0 18 | - tqdm 19 | -------------------------------------------------------------------------------- /ci/requirements/py-slepc.yml: -------------------------------------------------------------------------------- 1 | channels: 2 | - conda-forge 3 | dependencies: 4 | - autoray>=0.6.12 5 | - cotengra>=0.7.1 6 | - coverage 7 | - cytoolz 8 | - joblib 9 | - matplotlib 10 | - mpi4py>=3.1 11 | - networkx 12 | - numba>=0.56 13 | - numpy 14 | - openmpi 15 | - petsc=*=*complex* 16 | - petsc4py 17 | - psutil 18 | - pytest 19 | - pytest-cov 20 | - scipy<1.15.0 21 | - slepc=*=*complex* 22 | - slepc4py<=3.21 23 | - tqdm -------------------------------------------------------------------------------- /ci/requirements/py-tensorflow.yml: -------------------------------------------------------------------------------- 1 | channels: 2 | - conda-forge 3 | dependencies: 4 | - autoray>=0.7.0 5 | - cotengra>=0.7.1 6 | - coverage 7 | - cytoolz 8 | - joblib 9 | - matplotlib 10 | - networkx 11 | - numba>=0.56 12 | - numpy 13 | - psutil 14 | - pytest 15 | - pytest-cov 16 | - scipy<1.15.0 17 | - tqdm 18 | - pip 19 | - pip: 20 | - tensorflow 21 | -------------------------------------------------------------------------------- /ci/requirements/py-torch.yml: -------------------------------------------------------------------------------- 1 | channels: 2 | - pytorch 3 | - conda-forge 4 | dependencies: 5 | - autoray>=0.6.12 6 | - cotengra>=0.7.1 7 | - coverage 8 | - cpuonly 9 | - cytoolz 10 | - joblib 11 | - matplotlib 12 | - networkx 13 | - numba>=0.56 14 | - numpy 15 | - psutil 16 | - pytest 17 | - pytest-cov 18 | - pytorch 19 | - scipy<1.15.0 20 | - tqdm -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /docs/_pygments/_pygments_dark.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | Pygments version of the sublime Mariana theme. 4 | 5 | Pygments template by Jan T. Sott (https://github.com/idleberg) 6 | """ 7 | 8 | from pygments.style import Style 9 | from pygments.token import Keyword, Name, Comment, String, Error, Text, \ 10 | Number, Operator, Generic, Whitespace, Punctuation, Other, Literal 11 | 12 | 13 | BACKGROUND = "#1a1c1e" 14 | CURRENT_LINE = "#4e5a65" 15 | SELECTION = "#343d46" 16 | FOREGROUND = "#d8dee9" 17 | COMMENT = "#5a6272" 18 | RED = "#ec5f66" 19 | ORANGE = "#f9ae58" 20 | YELLOW = "#fac761" 21 | GREEN = "#99c794" 22 | AQUA = "#70c2bb" 23 | BLUE = "#6699cc" 24 | PURPLE = "#c695c6" 25 | 26 | 27 | class MarianaDark(Style): 28 | 29 | default_style = '' 30 | 31 | background_color = BACKGROUND 32 | highlight_color = SELECTION 33 | 34 | background_color = BACKGROUND 35 | highlight_color = SELECTION 36 | 37 | styles = { 38 | # No corresponding class for the following: 39 | Text: FOREGROUND, # class: '' 40 | Whitespace: "", # class: 'w' 41 | Error: RED, # class: 'err' 42 | Other: "", # class 'x' 43 | 44 | Comment: COMMENT, # class: 'c' 45 | Comment.Multiline: "", # class: 'cm' 46 | Comment.Preproc: "", # class: 'cp' 47 | Comment.Single: "", # class: 'c1' 48 | Comment.Special: "", # class: 'cs' 49 | 50 | Keyword: PURPLE, # class: 'k' 51 | Keyword.Constant: RED, # class: 'kc' 52 | Keyword.Declaration: "", # class: 'kd' 53 | Keyword.Namespace: PURPLE, # class: 'kn' 54 | Keyword.Pseudo: RED, # class: 'kp' 55 | Keyword.Reserved: "", # class: 'kr' 56 | Keyword.Type: YELLOW, # class: 'kt' 57 | 58 | Operator: RED, # class: 'o' 59 | Operator.Word: "", # class: 'ow' - like keywords 60 | 61 | Punctuation: AQUA, # class: 'p' 62 | 63 | Name: FOREGROUND, # class: 'n' 64 | Name.Attribute: BLUE, # class: 'na' - to be revised 65 | Name.Builtin: BLUE, # class: 'nb' 66 | Name.Builtin.Pseudo: RED, # class: 'bp' 67 | Name.Class: ORANGE, # class: 'nc' - to be revised 68 | Name.Constant: RED, # class: 'no' - to be revised 69 | Name.Decorator: AQUA, # class: 'nd' - to be revised 70 | Name.Entity: BLUE, # class: 'ni' 71 | Name.Exception: RED, # class: 'ne' 72 | Name.Function: AQUA, # class: 'nf' 73 | Name.Function.Magic: BLUE, # class: 'nf' 74 | Name.Property: BLUE, # class: 'py' 75 | Name.Label: BLUE, # class: 'nl' 76 | Name.Namespace: BLUE, # class: 'nn' - to be revised 77 | Name.Other: BLUE, # class: 'nx' 78 | Name.Tag: AQUA, # class: 'nt' - like a keyword 79 | Name.Variable: RED, # class: 'nv' - to be revised 80 | Name.Variable.Class: "", # class: 'vc' - to be revised 81 | Name.Variable.Global: "", # class: 'vg' - to be revised 82 | Name.Variable.Instance: "", # class: 'vi' - to be revised 83 | 84 | Number: ORANGE, # class: 'm' 85 | Number.Float: "", # class: 'mf' 86 | Number.Hex: "", # class: 'mh' 87 | Number.Integer: "", # class: 'mi' 88 | Number.Integer.Long: "", # class: 'il' 89 | Number.Oct: "", # class: 'mo' 90 | 91 | Literal: ORANGE, # class: 'l' 92 | Literal.Date: GREEN, # class: 'ld' 93 | 94 | String: GREEN, # class: 's' 95 | String.Backtick: "", # class: 'sb' 96 | String.Char: FOREGROUND, # class: 'sc' 97 | String.Doc: COMMENT, # class: 'sd' - like a comment 98 | String.Double: "", # class: 's2' 99 | String.Escape: ORANGE, # class: 'se' 100 | String.Heredoc: "", # class: 'sh' 101 | String.Interpol: ORANGE, # class: 'si' 102 | String.Other: "", # class: 'sx' 103 | String.Regex: "", # class: 'sr' 104 | String.Single: "", # class: 's1' 105 | String.Symbol: "", # class: 'ss' 106 | 107 | Generic: "", # class: 'g' 108 | Generic.Deleted: RED, # class: 'gd', 109 | Generic.Emph: "italic", # class: 'ge' 110 | Generic.Error: "", # class: 'gr' 111 | Generic.Heading: "bold " + FOREGROUND, # class: 'gh' 112 | Generic.Inserted: GREEN, # class: 'gi' 113 | Generic.Output: "", # class: 'go' 114 | Generic.Prompt: "bold " + COMMENT, # class: 'gp' 115 | Generic.Strong: "bold", # class: 'gs' 116 | Generic.Subheading: "bold " + AQUA, # class: 'gu' 117 | Generic.Traceback: "", # class: 'gt' 118 | } 119 | -------------------------------------------------------------------------------- /docs/_pygments/_pygments_light.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | Pygments (light) version of the sublime Mariana theme. 4 | 5 | Pygments template by Jan T. Sott (https://github.com/idleberg) 6 | """ 7 | 8 | from pygments.style import Style 9 | from pygments.token import Keyword, Name, Comment, String, Error, Text, \ 10 | Number, Operator, Generic, Whitespace, Punctuation, Other, Literal 11 | 12 | 13 | BACKGROUND = "#f8f9fb" 14 | CURRENT_LINE = "#b7c0c8" 15 | SELECTION = "#d0d6dc" 16 | FOREGROUND = "#161c27" 17 | COMMENT = "#8d95a5" 18 | RED = "#e7323b" 19 | ORANGE = "#f79626" 20 | YELLOW = "#f9b52f" 21 | GREEN = "#70b069" 22 | AQUA = "#3d8f88" 23 | BLUE = "#407fbf" 24 | PURPLE = "#b474b4" 25 | 26 | 27 | class MarianaLight(Style): 28 | 29 | default_style = '' 30 | 31 | background_color = BACKGROUND 32 | highlight_color = SELECTION 33 | 34 | background_color = BACKGROUND 35 | highlight_color = SELECTION 36 | 37 | styles = { 38 | # No corresponding class for the following: 39 | Text: FOREGROUND, # class: '' 40 | Whitespace: "", # class: 'w' 41 | Error: RED, # class: 'err' 42 | Other: "", # class 'x' 43 | 44 | Comment: COMMENT, # class: 'c' 45 | Comment.Multiline: "", # class: 'cm' 46 | Comment.Preproc: "", # class: 'cp' 47 | Comment.Single: "", # class: 'c1' 48 | Comment.Special: "", # class: 'cs' 49 | 50 | Keyword: PURPLE, # class: 'k' 51 | Keyword.Constant: RED, # class: 'kc' 52 | Keyword.Declaration: "", # class: 'kd' 53 | Keyword.Namespace: PURPLE, # class: 'kn' 54 | Keyword.Pseudo: RED, # class: 'kp' 55 | Keyword.Reserved: "", # class: 'kr' 56 | Keyword.Type: YELLOW, # class: 'kt' 57 | 58 | Operator: RED, # class: 'o' 59 | Operator.Word: "", # class: 'ow' - like keywords 60 | 61 | Punctuation: AQUA, # class: 'p' 62 | 63 | Name: FOREGROUND, # class: 'n' 64 | Name.Attribute: BLUE, # class: 'na' - to be revised 65 | Name.Builtin: BLUE, # class: 'nb' 66 | Name.Builtin.Pseudo: RED, # class: 'bp' 67 | Name.Class: ORANGE, # class: 'nc' - to be revised 68 | Name.Constant: RED, # class: 'no' - to be revised 69 | Name.Decorator: AQUA, # class: 'nd' - to be revised 70 | Name.Entity: BLUE, # class: 'ni' 71 | Name.Exception: RED, # class: 'ne' 72 | Name.Function: AQUA, # class: 'nf' 73 | Name.Function.Magic: BLUE, # class: 'nf' 74 | Name.Property: BLUE, # class: 'py' 75 | Name.Label: BLUE, # class: 'nl' 76 | Name.Namespace: BLUE, # class: 'nn' - to be revised 77 | Name.Other: BLUE, # class: 'nx' 78 | Name.Tag: AQUA, # class: 'nt' - like a keyword 79 | Name.Variable: RED, # class: 'nv' - to be revised 80 | Name.Variable.Class: "", # class: 'vc' - to be revised 81 | Name.Variable.Global: "", # class: 'vg' - to be revised 82 | Name.Variable.Instance: "", # class: 'vi' - to be revised 83 | 84 | Number: ORANGE, # class: 'm' 85 | Number.Float: "", # class: 'mf' 86 | Number.Hex: "", # class: 'mh' 87 | Number.Integer: "", # class: 'mi' 88 | Number.Integer.Long: "", # class: 'il' 89 | Number.Oct: "", # class: 'mo' 90 | 91 | Literal: ORANGE, # class: 'l' 92 | Literal.Date: GREEN, # class: 'ld' 93 | 94 | String: GREEN, # class: 's' 95 | String.Backtick: "", # class: 'sb' 96 | String.Char: FOREGROUND, # class: 'sc' 97 | String.Doc: COMMENT, # class: 'sd' - like a comment 98 | String.Double: "", # class: 's2' 99 | String.Escape: ORANGE, # class: 'se' 100 | String.Heredoc: "", # class: 'sh' 101 | String.Interpol: ORANGE, # class: 'si' 102 | String.Other: "", # class: 'sx' 103 | String.Regex: "", # class: 'sr' 104 | String.Single: "", # class: 's1' 105 | String.Symbol: "", # class: 'ss' 106 | 107 | Generic: "", # class: 'g' 108 | Generic.Deleted: RED, # class: 'gd', 109 | Generic.Emph: "italic", # class: 'ge' 110 | Generic.Error: "", # class: 'gr' 111 | Generic.Heading: "bold " + FOREGROUND, # class: 'gh' 112 | Generic.Inserted: GREEN, # class: 'gi' 113 | Generic.Output: "", # class: 'go' 114 | Generic.Prompt: "bold " + COMMENT, # class: 'gp' 115 | Generic.Strong: "bold", # class: 'gs' 116 | Generic.Subheading: "bold " + AQUA, # class: 'gu' 117 | Generic.Traceback: "", # class: 'gt' 118 | } 119 | -------------------------------------------------------------------------------- /docs/_static/amplitude.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/amplitude.png -------------------------------------------------------------------------------- /docs/_static/basic-compress.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/basic-compress.png -------------------------------------------------------------------------------- /docs/_static/branching.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/branching.png -------------------------------------------------------------------------------- /docs/_static/canonize-bond.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/canonize-bond.png -------------------------------------------------------------------------------- /docs/_static/compute_marginal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/compute_marginal.png -------------------------------------------------------------------------------- /docs/_static/docset.css: -------------------------------------------------------------------------------- 1 | #site-navigation, .topbar { 2 | display: none; 3 | } 4 | 5 | .container-xl { 6 | max-width: max-content; 7 | } 8 | 9 | .col-md-9 { 10 | max-width: 100%; 11 | flex: 0 0 100%; 12 | } -------------------------------------------------------------------------------- /docs/_static/isometric-tensor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/isometric-tensor.png -------------------------------------------------------------------------------- /docs/_static/kagome-contract-treeset-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/kagome-contract-treeset-2.png -------------------------------------------------------------------------------- /docs/_static/local_expectation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/local_expectation.png -------------------------------------------------------------------------------- /docs/_static/logo-banner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/logo-banner.png -------------------------------------------------------------------------------- /docs/_static/montage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/montage.png -------------------------------------------------------------------------------- /docs/_static/my-styles.css: -------------------------------------------------------------------------------- 1 | @import url('https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400;1,700&family=Spline+Sans+Mono:ital,wght@0,300..700;1,300..700&display=swap'); 2 | 3 | h1 { 4 | font-size: 2.0rem; 5 | } 6 | 7 | h2 { 8 | font-size: 1.75rem; 9 | } 10 | 11 | h3 { 12 | font-size: 1.5rem; 13 | } 14 | 15 | .toctree-l2 { 16 | font-size: 0.85rem; 17 | } 18 | 19 | article { 20 | font-size: 0.9rem; 21 | } 22 | 23 | div.cell div.cell_input { 24 | padding-left: 0em; 25 | padding-right: 0em; 26 | border: 1px rgba(127, 127, 127, 0.1) solid; 27 | background-color: rgba(127, 127, 127, 0.1); 28 | border-left-color: hsl(126, 25%, 45%); 29 | border-left-width: medium; 30 | } 31 | 32 | .cell_output .output.text_plain, .cell_output .output.traceback, .cell_output .output.stream { 33 | border: 1px solid rgba(127, 127, 127, 0.0); 34 | background: rgba(127, 127, 127, 0.0); 35 | margin-top: 0em; 36 | margin-bottom: 0em; 37 | margin-left: 0.5em; 38 | box-shadow: none; 39 | } 40 | 41 | .cell_output .output.stderr { 42 | border: 1px solid rgba(127, 127, 127, 0.0); 43 | background: rgba(127, 127, 127, 0.0); 44 | margin-top: 0em; 45 | margin-bottom: 0em; 46 | margin-left: 0.25em; 47 | box-shadow: none; 48 | border-left-color: #cc7766; 49 | border-left-width: medium; 50 | } 51 | 52 | .cell_output { 53 | padding-left: 1em; 54 | padding-right: 0em; 55 | margin-top: 0em; 56 | } 57 | 58 | code.literal { 59 | color: hsl(32, 85%, 50%); 60 | } -------------------------------------------------------------------------------- /docs/_static/partial_trace.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/partial_trace.png -------------------------------------------------------------------------------- /docs/_static/quimb.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/quimb.ico -------------------------------------------------------------------------------- /docs/_static/quimb_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/quimb_logo.png -------------------------------------------------------------------------------- /docs/_static/quimb_logo_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/quimb_logo_small.png -------------------------------------------------------------------------------- /docs/_static/quimb_logo_title.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/quimb_logo_title.png -------------------------------------------------------------------------------- /docs/_static/sample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/sample.png -------------------------------------------------------------------------------- /docs/_static/sample_chaotic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/sample_chaotic.png -------------------------------------------------------------------------------- /docs/_static/sample_gate_by_gate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/sample_gate_by_gate.png -------------------------------------------------------------------------------- /docs/_static/to_dense.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jcmgray/quimb/41a91629750b9796a41d0bc5eae4c8cf0e958b2e/docs/_static/to_dense.png -------------------------------------------------------------------------------- /docs/_templates/layout.html: -------------------------------------------------------------------------------- 1 | {# Import the theme's layout. #} 2 | {% extends "!layout.html" %} 3 | 4 | {# Custom CSS overrides #} 5 | {% set bootswatch_css_custom = ['_static/my-styles.css'] %} 6 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # For the full list of built-in configuration values, see the documentation: 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 5 | 6 | import os 7 | import sys 8 | sys.path.append(os.path.abspath("./_pygments")) 9 | 10 | # -- Project information ----------------------------------------------------- 11 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information 12 | 13 | project = 'quimb' 14 | copyright = '2015-2024, Johnnie Gray' 15 | author = 'Johnnie Gray' 16 | 17 | # The full version, including alpha/beta/rc tags 18 | try: 19 | from quimb import __version__ 20 | release = __version__ 21 | except ImportError: 22 | try: 23 | from importlib.metadata import version as _version 24 | release = _version('quimb') 25 | except ImportError: 26 | release = '0.0.0+unknown' 27 | 28 | version = '.'.join(release.split('.')[:2]) 29 | 30 | # -- General configuration --------------------------------------------------- 31 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration 32 | 33 | extensions = [ 34 | 'sphinx.ext.intersphinx', 35 | 'sphinx.ext.extlinks', 36 | 'sphinx.ext.napoleon', 37 | 'sphinx.ext.linkcode', 38 | 'myst_nb', 39 | "sphinx_design", 40 | 'sphinx_copybutton', 41 | 'autoapi.extension', 42 | ] 43 | 44 | # msyt_nb configuration 45 | nb_execution_mode = "off" 46 | myst_heading_anchors = 4 47 | myst_enable_extensions = [ 48 | "amsmath", 49 | "colon_fence", 50 | "deflist", 51 | "dollarmath", 52 | "html_image", 53 | ] 54 | 55 | 56 | # sphinx-autoapi 57 | autoapi_dirs = ['../quimb'] 58 | 59 | extlinks = { 60 | 'issue': ('https://github.com/jcmgray/quimb/issues/%s', 'GH %s'), 61 | 'pull': ('https://github.com/jcmgray/quimb/pull/%s', 'PR %s'), 62 | } 63 | intersphinx_mapping = { 64 | 'python': ('https://docs.python.org/3/', None), 65 | 'numpy': ('https://numpy.org/doc/stable/', None), 66 | 'scipy': ('https://docs.scipy.org/doc/scipy/', None), 67 | 'cotengra': ('https://cotengra.readthedocs.io/en/latest/', None), 68 | 'autoray': ('https://autoray.readthedocs.io/en/latest/', None), 69 | } 70 | 71 | # Add any paths that contain templates here, relative to this directory. 72 | templates_path = ['_templates'] 73 | 74 | # List of patterns, relative to source directory, that match files and 75 | # directories to ignore when looking for source files. 76 | # This pattern also affects html_static_path and html_extra_path. 77 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints'] 78 | 79 | # -- Options for HTML output ------------------------------------------------- 80 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output 81 | 82 | html_theme = 'furo' 83 | html_theme_options = { 84 | "sidebar_hide_name": True, 85 | "light_css_variables": { 86 | # "color-brand-primary": "hsl(45, 80%, 45%)", 87 | "color-brand-primary": "hsl(210, 50%, 50%)", 88 | "color-brand-content": "hsl(210, 50%, 50%)", 89 | "font-stack": "Atkinson Hyperlegible, sans-serif", 90 | "font-stack--monospace": "Spline Sans Mono, monospace", 91 | "font-stack--headings": "Spline Sans Mono, monospace", 92 | }, 93 | "dark_css_variables": { 94 | "color-brand-primary": "hsl(210, 50%, 60%)", 95 | "color-brand-content": "hsl(210, 50%, 60%)", 96 | }, 97 | "light_logo": "quimb_logo_title.png", 98 | "dark_logo": "quimb_logo_title.png", 99 | } 100 | 101 | pygments_style = '_pygments_light.MarianaLight' 102 | pygments_dark_style = "_pygments_dark.MarianaDark" 103 | 104 | html_static_path = ['_static'] 105 | html_css_files = ["my-styles.css"] 106 | html_favicon = "_static/quimb.ico" 107 | 108 | 109 | def linkcode_resolve(domain, info): 110 | """ 111 | Determine the URL corresponding to Python object 112 | """ 113 | import quimb 114 | import quimb.tensor # needs to be imported 115 | import inspect 116 | 117 | if domain != "py": 118 | return None 119 | 120 | modname = info["module"] 121 | fullname = info["fullname"] 122 | 123 | submod = sys.modules.get(modname) 124 | if submod is None: 125 | return None 126 | 127 | obj = submod 128 | for part in fullname.split("."): 129 | try: 130 | obj = getattr(obj, part) 131 | except AttributeError: 132 | return None 133 | 134 | try: 135 | fn = inspect.getsourcefile(inspect.unwrap(obj)) 136 | except TypeError: 137 | fn = None 138 | if not fn: 139 | return None 140 | 141 | try: 142 | source, lineno = inspect.getsourcelines(obj) 143 | except OSError: 144 | lineno = None 145 | 146 | if lineno: 147 | linespec = f"#L{lineno}-L{lineno + len(source) - 1}" 148 | else: 149 | linespec = "" 150 | 151 | fn = os.path.relpath(fn, start=os.path.dirname(quimb.__file__)) 152 | 153 | if "+" in quimb.__version__: 154 | return ( 155 | f"https://github.com/jcmgray/quimb/blob/" 156 | f"main/quimb/{fn}{linespec}" 157 | ) 158 | else: 159 | return ( 160 | f"https://github.com/jcmgray/quimb/blob/" 161 | f"v{quimb.__version__}/quimb/{fn}{linespec}" 162 | ) 163 | -------------------------------------------------------------------------------- /docs/develop.md: -------------------------------------------------------------------------------- 1 | # Developer Notes 2 | 3 | ## Contributing 4 | 5 | Things to check if new functionality added: 6 | 7 | 1. Ensure functions are unit tested. 8 | 2. Ensure functions have [numpy style docstrings](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html). 9 | 3. Ensure code is PEP8 compliant. 10 | 4. Add to `quimb/__init__.py` and `"__all__"` if appropriate (or the 11 | tensor network equivalent `quimb.tensor.__init__.py`). 12 | 5. Add to changelog and elsewhere in docs. 13 | 14 | ## Running the Tests 15 | 16 | Testing `quimb` requires [pytest](https://docs.pytest.org/en/latest/index.html) (as well as `coverage` and `pytest-cov`) and simply involves running `pytest` in the root `quimb` directory. 17 | 18 | The tests can also be run with pre-spawned mpi workers using the command `quimb-mpi-python -m pytest` (but not in syncro mode -- see {ref}`mpistuff`). 19 | 20 | ## Building the docs locally 21 | 22 | Building the docs requires [sphinx](http://www.sphinx-doc.org), 23 | [myst_nb](https://myst-nb.readthedocs.io), 24 | [sphinx-autoapi](https://sphinx-autoapi.readthedocs.io), 25 | [sphinx_copybutton](https://sphinx-copybutton.readthedocs.io), 26 | and [furo](https://github.com/pradyunsg/furo). 27 | 28 | 1. `cd` into the `quimb/docs` folder. 29 | 2. To start from scratch, remove the `_build` folder. 30 | 3. Run `sphinx-build -b html . ./_build/html/`. 31 | 4. Launch the page: `open _build/html/index.html`. 32 | 33 | ### Building the DocSet 34 | 35 | Building the DocSet requires [doc2dash >= 2.4.1](https://github.com/hynek/doc2dash). 36 | 37 | 1. To start from scratch, remove `quimb/docs/_build`. 38 | 2. Run `make docset` in the `quimb/docs` folder. 39 | 3. Open the file `quimb/docs/_build/quimb.docset` to load it to Dash. 40 | 41 | Afterwards, in order to update the Dash repository with a the DocSet after a new release: 42 | 43 | 1. Clone the [Dash-User-Contributions](https://github.com/Kapeli/Dash-User-Contributions). 44 | 2. Go to `docsets/quimb`, create a new directory with the version name inside the `versions` dir and copy there the generated DocSet. 45 | 3. Edit the `docset.json`: update the `"version"` and add a new element below `"specific_versions"`. 46 | 4. Commit and create a new Pull Request. 47 | 48 | ## Minting a Release 49 | 50 | `quimb` uses [setuptools_scm](https://github.com/pypa/setuptools_scm) 51 | to manage version. The steps to release a new version 52 | on [pypi](https://pypi.org) are as follows: 53 | 54 | 1. Make sure all tests are passing, as well as the continuous integration 55 | and readthedocs build. 56 | 2. `git tag` the release with next `vX.Y.Z` 57 | 3. Push the tag to github: `git push --tags` and github actions will build and 58 | upload the release to pypi, which will then get picked up by conda-forge. 59 | 60 | Alternate manual release steps (after tagging): 61 | 62 | 3. Remove any old builds: `` rm dist/*` `` 63 | 4. Build the tar and wheel `python -m build` 64 | 5. Upload using twine: `twine upload dist/*` 65 | -------------------------------------------------------------------------------- /docs/distributed parallelism - mpi.md: -------------------------------------------------------------------------------- 1 | (mpistuff)= 2 | 3 | # MPI 4 | 5 | The `slepc` and `petsc` parts of `quimb` (`eigh(..., k=..., method='slepc')`, `svds(..., method='slepc')`, `expm(..., method='slepc')` etc.), as well as often being faster than `scipy`, perform the calculations using MPI and are thus suited to clusters with many nodes. 6 | 7 | These generally perform best when run on multiple, single-threaded MPI processes, whereas `numpy` and `scipy` need single-process multi-threaded exectution to parallize (via BLAS). 8 | By default, `quimb` thus switches between standard execution and a cached pool of MPI processes when required. It can also run more explicitly under MPI as descibed in {ref}`modes-of-execution`. 9 | 10 | If running in a distributed cluster it is also best not to pass full operators to these functions (which will be pickled then transferred), rather it is best to leave the operator unconstructed, whith each worker constructing only the rows it needs. 11 | 12 | 1. The first aspect is handled by the {class}`~quimb.Lazy` object, which is essentially 13 | `functools.partial` with a `.shape` attribute that must be supplied. 14 | 2. The second aspect (only constructing the right rows) is achieved whenever a function takes a 15 | `ownership` argument specifying the slice of rows to construct. Any operators based on 16 | {func}`~quimb.kron` and {func}`~quimb.ikron` such as the built-in Hamiltonians can do this. 17 | 18 | See the {ref}`examples` for a demonstration of this. 19 | 20 | (modes-of-execution)= 21 | 22 | ## Modes of execution 23 | 24 | - Normal, "dynamic MPI mode": main process is not MPI, can run many OMP threads, dynamically spawns a cached mpi pool of processes which are not multithreaded (for efficiency) to do MPI things. Works for interactive sessions and allows OMP parallelism followed by MPI parallelism. Might not work well in a multi-node setting. 25 | - `quimb-mpi-python`, "mpi4py.futures mode": all processes are MPI, are spawned at start and have single OMP thread. Workers are split off at startup and only master runs the script, passing args and results using pickle to workers. This is achieved using ` python -m mpi4py.futures