Metadata-Version: 2.2
Name: qanneal
Version: 0.4.0
Summary: Research-grade simulated quantum annealing toolkit
Author: qanneal contributors
License: 1, Sqaod
         
         				Apache License
                                    Version 2.0, January 2004
                                 http://www.apache.org/licenses/
         
            TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
         
            1. Definitions.
         
               "License" shall mean the terms and conditions for use, reproduction,
               and distribution as defined by Sections 1 through 9 of this document.
         
               "Licensor" shall mean the copyright owner or entity authorized by
               the copyright owner that is granting the License.
         
               "Legal Entity" shall mean the union of the acting entity and all
               other entities that control, are controlled by, or are under common
               control with that entity. For the purposes of this definition,
               "control" means (i) the power, direct or indirect, to cause the
               direction or management of such entity, whether by contract or
               otherwise, or (ii) ownership of fifty percent (50%) or more of the
               outstanding shares, or (iii) beneficial ownership of such entity.
         
               "You" (or "Your") shall mean an individual or Legal Entity
               exercising permissions granted by this License.
         
               "Source" form shall mean the preferred form for making modifications,
               including but not limited to software source code, documentation
               source, and configuration files.
         
               "Object" form shall mean any form resulting from mechanical
               transformation or translation of a Source form, including but
               not limited to compiled object code, generated documentation,
               and conversions to other media types.
         
               "Work" shall mean the work of authorship, whether in Source or
               Object form, made available under the License, as indicated by a
               copyright notice that is included in or attached to the work
               (an example is provided in the Appendix below).
         
               "Derivative Works" shall mean any work, whether in Source or Object
               form, that is based on (or derived from) the Work and for which the
               editorial revisions, annotations, elaborations, or other modifications
               represent, as a whole, an original work of authorship. For the purposes
               of this License, Derivative Works shall not include works that remain
               separable from, or merely link (or bind by name) to the interfaces of,
               the Work and Derivative Works thereof.
         
               "Contribution" shall mean any work of authorship, including
               the original version of the Work and any modifications or additions
               to that Work or Derivative Works thereof, that is intentionally
               submitted to Licensor for inclusion in the Work by the copyright owner
               or by an individual or Legal Entity authorized to submit on behalf of
               the copyright owner. For the purposes of this definition, "submitted"
               means any form of electronic, verbal, or written communication sent
               to the Licensor or its representatives, including but not limited to
               communication on electronic mailing lists, source code control systems,
               and issue tracking systems that are managed by, or on behalf of, the
               Licensor for the purpose of discussing and improving the Work, but
               excluding communication that is conspicuously marked or otherwise
               designated in writing by the copyright owner as "Not a Contribution."
         
               "Contributor" shall mean Licensor and any individual or Legal Entity
               on behalf of whom a Contribution has been received by Licensor and
               subsequently incorporated within the Work.
         
            2. Grant of Copyright License. Subject to the terms and conditions of
               this License, each Contributor hereby grants to You a perpetual,
               worldwide, non-exclusive, no-charge, royalty-free, irrevocable
               copyright license to reproduce, prepare Derivative Works of,
               publicly display, publicly perform, sublicense, and distribute the
               Work and such Derivative Works in Source or Object form.
         
            3. Grant of Patent License. Subject to the terms and conditions of
               this License, each Contributor hereby grants to You a perpetual,
               worldwide, non-exclusive, no-charge, royalty-free, irrevocable
               (except as stated in this section) patent license to make, have made,
               use, offer to sell, sell, import, and otherwise transfer the Work,
               where such license applies only to those patent claims licensable
               by such Contributor that are necessarily infringed by their
               Contribution(s) alone or by combination of their Contribution(s)
               with the Work to which such Contribution(s) was submitted. If You
               institute patent litigation against any entity (including a
               cross-claim or counterclaim in a lawsuit) alleging that the Work
               or a Contribution incorporated within the Work constitutes direct
               or contributory patent infringement, then any patent licenses
               granted to You under this License for that Work shall terminate
               as of the date such litigation is filed.
         
            4. Redistribution. You may reproduce and distribute copies of the
               Work or Derivative Works thereof in any medium, with or without
               modifications, and in Source or Object form, provided that You
               meet the following conditions:
         
               (a) You must give any other recipients of the Work or
                   Derivative Works a copy of this License; and
         
               (b) You must cause any modified files to carry prominent notices
                   stating that You changed the files; and
         
               (c) You must retain, in the Source form of any Derivative Works
                   that You distribute, all copyright, patent, trademark, and
                   attribution notices from the Source form of the Work,
                   excluding those notices that do not pertain to any part of
                   the Derivative Works; and
         
               (d) If the Work includes a "NOTICE" text file as part of its
                   distribution, then any Derivative Works that You distribute must
                   include a readable copy of the attribution notices contained
                   within such NOTICE file, excluding those notices that do not
                   pertain to any part of the Derivative Works, in at least one
                   of the following places: within a NOTICE text file distributed
                   as part of the Derivative Works; within the Source form or
                   documentation, if provided along with the Derivative Works; or,
                   within a display generated by the Derivative Works, if and
                   wherever such third-party notices normally appear. The contents
                   of the NOTICE file are for informational purposes only and
                   do not modify the License. You may add Your own attribution
                   notices within Derivative Works that You distribute, alongside
                   or as an addendum to the NOTICE text from the Work, provided
                   that such additional attribution notices cannot be construed
                   as modifying the License.
         
               You may add Your own copyright statement to Your modifications and
               may provide additional or different license terms and conditions
               for use, reproduction, or distribution of Your modifications, or
               for any such Derivative Works as a whole, provided Your use,
               reproduction, and distribution of the Work otherwise complies with
               the conditions stated in this License.
         
            5. Submission of Contributions. Unless You explicitly state otherwise,
               any Contribution intentionally submitted for inclusion in the Work
               by You to the Licensor shall be under the terms and conditions of
               this License, without any additional terms or conditions.
               Notwithstanding the above, nothing herein shall supersede or modify
               the terms of any separate license agreement you may have executed
               with Licensor regarding such Contributions.
         
            6. Trademarks. This License does not grant permission to use the trade
               names, trademarks, service marks, or product names of the Licensor,
               except as required for reasonable and customary use in describing the
               origin of the Work and reproducing the content of the NOTICE file.
         
            7. Disclaimer of Warranty. Unless required by applicable law or
               agreed to in writing, Licensor provides the Work (and each
               Contributor provides its Contributions) on an "AS IS" BASIS,
               WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
               implied, including, without limitation, any warranties or conditions
               of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
               PARTICULAR PURPOSE. You are solely responsible for determining the
               appropriateness of using or redistributing the Work and assume any
               risks associated with Your exercise of permissions under this License.
         
            8. Limitation of Liability. In no event and under no legal theory,
               whether in tort (including negligence), contract, or otherwise,
               unless required by applicable law (such as deliberate and grossly
               negligent acts) or agreed to in writing, shall any Contributor be
               liable to You for damages, including any direct, indirect, special,
               incidental, or consequential damages of any character arising as a
               result of this License or out of the use or inability to use the
               Work (including but not limited to damages for loss of goodwill,
               work stoppage, computer failure or malfunction, or any and all
               other commercial damages or losses), even if such Contributor
               has been advised of the possibility of such damages.
         
            9. Accepting Warranty or Additional Liability. While redistributing
               the Work or Derivative Works thereof, You may choose to offer,
               and charge a fee for, acceptance of support, warranty, indemnity,
               or other liability obligations and/or rights consistent with this
               License. However, in accepting such obligations, You may act only
               on Your own behalf and on Your sole responsibility, not on behalf
               of any other Contributor, and only if You agree to indemnify,
               defend, and hold each Contributor harmless for any liability
               incurred by, or claims asserted against, such Contributor by reason
               of your accepting any such warranty or additional liability.
         
            END OF TERMS AND CONDITIONS
         
            APPENDIX: How to apply the Apache License to your work.
         
               To apply the Apache License to your work, attach the following
               boilerplate notice, with the fields enclosed by brackets "[]"
               replaced with your own identifying information. (Don't include
               the brackets!)  The text should be enclosed in the appropriate
               comment syntax for the file format. We also recommend that a
               file or class name and description of purpose be included on the
               same "printed page" as the copyright notice for easier
               identification within third-party archives.
         
            Copyright 2018 Shinya Morino
         
            Licensed under the Apache License, Version 2.0 (the "License");
            you may not use this file except in compliance with the License.
            You may obtain a copy of the License at
         
                http://www.apache.org/licenses/LICENSE-2.0
         
            Unless required by applicable law or agreed to in writing, software
            distributed under the License is distributed on an "AS IS" BASIS,
            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
            See the License for the specific language governing permissions and
            limitations under the License.
         
         
         2. Eigen (https://http://eigen.tuxfamily.org)
         
         Mozilla Public License
         Version 2.0
         1. Definitions
         
         1.1. “Contributor”
         
             means each individual or legal entity that creates, contributes to the creation of, or owns Covered Software.
         1.2. “Contributor Version”
         
             means the combination of the Contributions of others (if any) used by a Contributor and that particular Contributor’s Contribution.
         1.3. “Contribution”
         
             means Covered Software of a particular Contributor.
         1.4. “Covered Software”
         
             means Source Code Form to which the initial Contributor has attached the notice in Exhibit A, the Executable Form of such Source Code Form, and Modifications of such Source Code Form, in each case including portions thereof.
         1.5. “Incompatible With Secondary Licenses”
         
             means
         
                 that the initial Contributor has attached the notice described in Exhibit B to the Covered Software; or
         
                 that the Covered Software was made available under the terms of version 1.1 or earlier of the License, but not also under the terms of a Secondary License.
         
         1.6. “Executable Form”
         
             means any form of the work other than Source Code Form.
         1.7. “Larger Work”
         
             means a work that combines Covered Software with other material, in a separate file or files, that is not Covered Software.
         1.8. “License”
         
             means this document.
         1.9. “Licensable”
         
             means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently, any and all of the rights conveyed by this License.
         1.10. “Modifications”
         
             means any of the following:
         
                 any file in Source Code Form that results from an addition to, deletion from, or modification of the contents of Covered Software; or
         
                 any new file in Source Code Form that contains any Covered Software.
         
         1.11. “Patent Claims” of a Contributor
         
             means any patent claim(s), including without limitation, method, process, and apparatus claims, in any patent Licensable by such Contributor that would be infringed, but for the grant of the License, by the making, using, selling, offering for sale, having made, import, or transfer of either its Contributions or its Contributor Version.
         1.12. “Secondary License”
         
             means either the GNU General Public License, Version 2.0, the GNU Lesser General Public License, Version 2.1, the GNU Affero General Public License, Version 3.0, or any later versions of those licenses.
         1.13. “Source Code Form”
         
             means the form of the work preferred for making modifications.
         1.14. “You” (or “Your”)
         
             means an individual or a legal entity exercising rights under this License. For legal entities, “You” includes any entity that controls, is controlled by, or is under common control with You. For purposes of this definition, “control” means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity.
         
         2. License Grants and Conditions
         2.1. Grants
         
         Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license:
         
             under intellectual property rights (other than patent or trademark) Licensable by such Contributor to use, reproduce, make available, modify, display, perform, distribute, and otherwise exploit its Contributions, either on an unmodified basis, with Modifications, or as part of a Larger Work; and
         
             under Patent Claims of such Contributor to make, use, sell, offer for sale, have made, import, and otherwise transfer either its Contributions or its Contributor Version.
         
         2.2. Effective Date
         
         The licenses granted in Section 2.1 with respect to any Contribution become effective for each Contribution on the date the Contributor first distributes such Contribution.
         2.3. Limitations on Grant Scope
         
         The licenses granted in this Section 2 are the only rights granted under this License. No additional rights or licenses will be implied from the distribution or licensing of Covered Software under this License. Notwithstanding Section 2.1(b) above, no patent license is granted by a Contributor:
         
             for any code that a Contributor has removed from Covered Software; or
         
             for infringements caused by: (i) Your and any other third party’s modifications of Covered Software, or (ii) the combination of its Contributions with other software (except as part of its Contributor Version); or
         
             under Patent Claims infringed by Covered Software in the absence of its Contributions.
         
         This License does not grant any rights in the trademarks, service marks, or logos of any Contributor (except as may be necessary to comply with the notice requirements in Section 3.4).
         2.4. Subsequent Licenses
         
         No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this License (see Section 10.2) or under the terms of a Secondary License (if permitted under the terms of Section 3.3).
         2.5. Representation
         
         Each Contributor represents that the Contributor believes its Contributions are its original creation(s) or it has sufficient rights to grant the rights to its Contributions conveyed by this License.
         2.6. Fair Use
         
         This License is not intended to limit any rights You have under applicable copyright doctrines of fair use, fair dealing, or other equivalents.
         2.7. Conditions
         
         Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in Section 2.1.
         3. Responsibilities
         3.1. Distribution of Source Form
         
         All distribution of Covered Software in Source Code Form, including any Modifications that You create or to which You contribute, must be under the terms of this License. You must inform recipients that the Source Code Form of the Covered Software is governed by the terms of this License, and how they can obtain a copy of this License. You may not attempt to alter or restrict the recipients’ rights in the Source Code Form.
         3.2. Distribution of Executable Form
         
         If You distribute Covered Software in Executable Form then:
         
             such Covered Software must also be made available in Source Code Form, as described in Section 3.1, and You must inform recipients of the Executable Form how they can obtain a copy of such Source Code Form by reasonable means in a timely manner, at a charge no more than the cost of distribution to the recipient; and
         
             You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the license for the Executable Form does not attempt to limit or alter the recipients’ rights in the Source Code Form under this License.
         
         3.3. Distribution of a Larger Work
         
         You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered Software with a work governed by one or more Secondary Licenses, and the Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered Software under the terms of either this License or such Secondary License(s).
         3.4. Notices
         
         You may not remove or alter the substance of any license notices (including copyright notices, patent notices, disclaimers of warranty, or limitations of liability) contained within the Source Code Form of the Covered Software, except that You may alter any license notices to the extent required to remedy known factual inaccuracies.
         3.5. Application of Additional Terms
         
         You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Software. However, You may do so only on Your own behalf, and not on behalf of any Contributor. You must make it absolutely clear that any such warranty, support, indemnity, or liability obligation is offered by You alone, and You hereby agree to indemnify every Contributor for any liability incurred by such Contributor as a result of warranty, support, indemnity or liability terms You offer. You may include additional disclaimers of warranty and limitations of liability specific to any jurisdiction.
         4. Inability to Comply Due to Statute or Regulation
         
         If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be placed in a text file included with all distributions of the Covered Software under this License. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it.
         5. Termination
         
         5.1. The rights granted under this License will terminate automatically if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such Contributor explicitly and finally terminates Your grants, and (b) on an ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor notifies You of the non-compliance by some reasonable means, this is the first time You have received notice of non-compliance with this License from such Contributor, and You become compliant prior to 30 days after Your receipt of the notice.
         
         5.2. If You initiate litigation against any entity by asserting a patent infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate.
         
         5.3. In the event of termination under Sections 5.1 or 5.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or Your distributors under this License prior to termination shall survive termination.
         6. Disclaimer of Warranty
         
         Covered Software is provided under this License on an “as is” basis, without warranty of any kind, either expressed, implied, or statutory, including, without limitation, warranties that the Covered Software is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality and performance of the Covered Software is with You. Should any Covered Software prove defective in any respect, You (not any Contributor) assume the cost of any necessary servicing, repair, or correction. This disclaimer of warranty constitutes an essential part of this License. No use of any Covered Software is authorized under this License except under this disclaimer.
         7. Limitation of Liability
         
         Under no circumstances and under no legal theory, whether tort (including negligence), contract, or otherwise, shall any Contributor, or anyone who distributes Covered Software as permitted above, be liable to You for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for lost profits, loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses, even if such party shall have been informed of the possibility of such damages. This limitation of liability shall not apply to liability for death or personal injury resulting from such party’s negligence to the extent applicable law prohibits such limitation. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so this exclusion and limitation may not apply to You.
         8. Litigation
         
         Any litigation relating to this License may be brought only in the courts of a jurisdiction where the defendant maintains its principal place of business and such litigation shall be governed by laws of that jurisdiction, without reference to its conflict-of-law provisions. Nothing in this Section shall prevent a party’s ability to bring cross-claims or counter-claims.
         9. Miscellaneous
         
         This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor.
         10. Versions of the License
         10.1. New Versions
         
         Mozilla Foundation is the license steward. Except as provided in Section 10.3, no one other than the license steward has the right to modify or publish new versions of this License. Each version will be given a distinguishing version number.
         10.2. Effect of New Versions
         
         You may distribute the Covered Software under the terms of the version of the License under which You originally received the Covered Software, or under the terms of any subsequent version published by the license steward.
         10.3. Modified Versions
         
         If you create software not governed by this License, and you want to create a new license for such software, you may create and use a modified version of this License if you rename the license and remove any references to the name of the license steward (except to note that such modified license differs from this License).
         10.4. Distributing Source Code Form that is Incompatible With Secondary Licenses
         
         If You choose to distribute Source Code Form that is Incompatible With Secondary Licenses under the terms of this version of the License, the notice described in Exhibit B of this License must be attached.
         Exhibit A - Source Code Form License Notice
         
             This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
         
         If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice.
         
         You may add additional accurate notices of copyright ownership.
         Exhibit B - “Incompatible With Secondary Licenses” Notice
         
             This Source Code Form is “Incompatible With Secondary Licenses”, as defined by the Mozilla Public License, v. 2.0.
         
         
         3. CUB (https://github.com/NVlabs/cub)
         
         Copyright (c) 2010-2011, Duane Merrill.  All rights reserved.
         Copyright (c) 2011-2018, NVIDIA CORPORATION.  All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
            *  Redistributions of source code must retain the above copyright
               notice, this list of conditions and the following disclaimer.
            *  Redistributions in binary form must reproduce the above copyright
               notice, this list of conditions and the following disclaimer in the
               documentation and/or other materials provided with the distribution.
            *  Neither the name of the NVIDIA CORPORATION nor the
               names of its contributors may be used to endorse or promote products
               derived from this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
         ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL NVIDIA CORPORATION BE LIABLE FOR ANY
         DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
         (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
         LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
         ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
         SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
         
         EOD
         
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Description-Content-Type: text/markdown

# qanneal

**Research-grade Ising/QUBO optimizer** with eight annealing engines — from classical SA to the closest available CPU simulation of quantum annealing, including optimal-control diagonal-catalyst variants.

| Method | Short name | What it simulates |
|--------|-----------|-------------------|
| Simulated Annealing | `sa` | Classical thermal fluctuations |
| Simulated Quantum Annealing | `sqa` | Discrete-time path-integral (Trotterized QA) |
| SQA + Parallel Tempering | `sqapt` | QA with replica exchange on a (β, Γ) ladder |
| Continuous-Time PIMC | `ctpimc` | Continuous-time path-integral (worldline sampling) |
| SQA + Diagonal Catalyst | `sqa-c` | SQA with learned optimal-control catalyst C(t) |
| SQA + Catalyst + Cluster | `sqa-csw` | `sqa-c` plus Swendsen–Wang cluster updates |
| SQAPT + Diagonal Catalyst | `sqapt-c` | SQAPT with per-rung catalyst |
| SQAPT + Catalyst + Cluster | `sqapt-csw` | `sqapt-c` plus Swendsen–Wang cluster updates |

All engines share a unified `solve()` Python API and a C++17 core with pybind11 bindings.

---

## Install

### From PyPI (recommended)

```bash
pip install qanneal
```

### From source

```bash
# From repo root
python -m pip install . --no-build-isolation

# Editable/development
python -m pip install -e . --no-build-isolation

# Convenience scripts
./setup.sh        # macOS / Linux
setup.bat         # Windows cmd
./setup.ps1       # Windows PowerShell
```

**Requirements**: Python ≥ 3.11, numpy, C++17 compiler (for source builds).

### Optional dependencies

| Package | Enables |
|---------|---------|
| `tqdm` | Progress bar during multi-read runs |
| `matplotlib` | Plots in examples and animation lab |
| `dimod` | `dimod.BinaryQuadraticModel` as input to `solve()` |
| `networkx` | `networkx.Graph` as input to `solve()` |
| `mpi4py` | Multi-node HPC launcher |

```bash
pip install tqdm matplotlib dimod networkx
```

---

## Quickstart

### Solve a QUBO in one call

```python
import numpy as np
from qanneal import solve

# Minimise x₀ + x₂ − 2x₀x₁ − 2x₁x₂
Q = np.array([
    [ 1.0, -2.0,  0.0],
    [-2.0,  0.0, -2.0],
    [ 0.0, -2.0,  1.0],
], dtype=float)

result = solve(Q, method="sqapt", reads=16, seed=0, return_bits=True)
print(result.best_sample)   # array of bits {0, 1}
print(result.best_energy)   # minimum QUBO energy found
```

### Number partition (classic NP-hard)

```python
import numpy as np
from qanneal import DenseIsing, solve

# Partition [3, 5, 7, 11, 13] into two equal-sum groups
nums = np.array([3, 5, 7, 11, 13], dtype=float)
n = len(nums)

h = np.zeros(n)
J = np.zeros((n, n))
for i in range(n):
    for j in range(i + 1, n):
        J[i, j] = J[j, i] = 2.0 * nums[i] * nums[j]

ising = DenseIsing(h, J, c=float(np.dot(nums, nums)))
result = solve(ising, method="sqa", reads=20, seed=42)
diff = abs(float(np.dot(nums, result.best_sample)))
print(f"Partition diff: {diff}")  # 0.0 = perfect split
```

### dimod BQM input

```python
import dimod
from qanneal import solve

bqm = dimod.BinaryQuadraticModel({"a": 1.0, "b": -1.0}, {("a", "b"): -2.0}, "BINARY")
result = solve(bqm, method="sqapt", reads=8, return_bits=True)
print(dict(zip(result.var_order, result.best_sample)))
```

### NetworkX graph input

```python
import networkx as nx
from qanneal import solve

G = nx.Graph()
G.add_node(0, bias=0.5)
G.add_node(1, bias=-0.3)
G.add_edge(0, 1, weight=1.2)
G.add_edge(1, 2, weight=-0.8)
G.add_node(2, bias=0.0)

result = solve(G, method="sqa", reads=10, return_bits=True)
print(result.best_sample, result.best_energy)
```

---

## The Eight Methods

### `sa` — Simulated Annealing

Classical Metropolis single-chain optimizer. At each temperature step, proposes random
single-spin flips and accepts with probability `min(1, exp(−β ΔE))`.

- **Use when**: fast results, simple landscapes, baseline comparisons.
- **Key control**: `sweeps_per_beta` (thermal equilibration per temperature step).

### `sqa` — Simulated Quantum Annealing

Quantum Monte Carlo in the Suzuki–Trotter formulation. The spin system is replicated
across `trotter_slices` imaginary-time slices; flips along the time dimension mimic
quantum tunneling through energy barriers.

Trotter coupling: `J_⊥ = ½ ln(1 / tanh(βΓ/M))` where M = trotter_slices.

- **Use when**: landscapes have tall narrow barriers that classical SA misses.
- **Key extra controls**: `trotter_slices`, `worldline_sweeps`, `cluster_sweeps`.

### `sqapt` — SQA + Parallel Tempering *(recommended default)*

Multiple SQA replicas run simultaneously at different `(β, Γ)` points on a ladder.
Adjacent replicas periodically swap configurations, letting solutions discovered at
high fluctuations (large Γ, low β) flow toward low-energy states at strong freezing.

- **Use when**: rugged/multi-modal landscapes, moderate to hard combinatorial problems.
- **Key extra controls**: `replicas`, `pt_steps`, `swap_interval`.

### `ctpimc` — Continuous-Time PIMC

Samples worldlines in continuous imaginary time using Swendsen–Wang cluster updates.
No Trotter discretisation error; better mixing in the high-Γ regime.

- **Use when**: you want a closer analog to D-Wave sampling; density-matrix–level statistics.
- **Key extra controls**: `ctpimc_qubits_per_update`, `ctpimc_qubits_per_chain`.

### `sqa-c` — SQA + Diagonal Catalyst

Extends SQA with a learned diagonal catalyst H_cat = C(t) × K(σ). The catalyst schedule
C(t) is optimized by gradient descent on the expected problem energy, following optimal-
control derivation. Catalyst type `K` is configurable (see `catalyst_type` below).

- **Use when**: you want automatic schedule improvement beyond hand-tuned (β, Γ) ramps.
- **Key extra controls**: `catalyst_opt_iterations`, `catalyst_samples_per_step`, `catalyst_learning_rate`, `catalyst_type`.

### `sqa-csw` — SQA + Catalyst + Swendsen–Wang

Same as `sqa-c` but additionally applies Swendsen–Wang cluster updates along the
imaginary-time direction. Cluster moves accelerate mixing in strongly frustrated instances.

- `cluster_sweeps` defaults to 2 when using `sqa-csw`.

### `sqapt-c` — SQAPT + Diagonal Catalyst

SQAPT with an independent per-rung catalyst on each ladder replica.

### `sqapt-csw` — SQAPT + Catalyst + Swendsen–Wang

`sqapt-c` plus cluster updates. Highest-quality method; most expensive.

### Catalyst types (`catalyst_type`)

| Type | Operator K | Notes |
|------|-----------|-------|
| `"linear"` | `Σᵢ sᵢ` | Uniform transverse field — the paper's default |
| `"staggered"` | `Σᵢ εᵢ sᵢ` | Signed/parity field |
| `"product"` | `Σᵢ<ⱼ Jᵢⱼ sᵢ sⱼ` | Coupling rescale; needs non-zero Ising h |
| `"mean_field"` | `(Σᵢ sᵢ)² / N` | Collective magnetization |
| `"none"` | `0` | Reduces to SQA / SQAPT |

```python
result = solve(Q, method="sqa-c", catalyst_type="linear",
               catalyst_opt_iterations=12, reads=8)
```

---

## Problem Input Formats

`solve()` auto-detects the problem type — no manual conversion needed:

| Python type | Interpretation |
|-------------|---------------|
| `DenseIsing(h, J, c)` | Dense Ising model, passed directly |
| `SparseIsing(h, edges, n, c)` | Sparse Ising, passed directly |
| `QUBO(Q)` | Converted via `to_ising()` |
| `np.ndarray` shape `(n, n)` | Treated as QUBO matrix |
| `dict{(i,j): float}` | Sparse QUBO dictionary |
| `list[(i,j,float)]` | Sparse QUBO entry list |
| `dimod.BinaryQuadraticModel` | Auto-converted (requires `dimod`) |
| `networkx.Graph` | Node `bias` + edge `weight` attrs (requires `networkx`) |

---

## Core Concepts

### Energy Conventions

**QUBO** (binary variables x ∈ {0, 1}):
```
E(x) = Σᵢ Σⱼ Qᵢⱼ xᵢ xⱼ
```
- `Q[i,i]`: linear (bias) term for variable i.
- `Q[i,j]` (i ≠ j): quadratic coupling. Include both Q[i,j] and Q[j,i] for symmetric problems.

**Ising** (spins s ∈ {−1, +1}):
```
E(s) = Σᵢ hᵢ sᵢ  +  Σᵢ<ⱼ Jᵢⱼ sᵢ sⱼ  +  c
```
- `h`: local magnetic fields.
- `J`: pairwise coupling matrix.
- `c`: constant energy offset.

**Conversion**: `x = (s + 1) / 2`. Pass `return_bits=True` to `solve()` for automatic conversion.

### Hamiltonian Models

| Class | Memory | Best for |
|-------|--------|---------|
| `DenseIsing(h, J, c)` | O(n²) | n ≤ ~3 000, fully connected |
| `SparseIsing(h, edges, n, c)` | O(n + \|E\|) | sparse graphs, n up to 100 000+ |
| `QUBO(Q)` | O(n²) | binary variables; call `.to_ising()` internally |

---

## Schedule Design

Every annealer needs a **schedule** — a sequence of `(β, Γ)` or just `β` values.

### Problem-adaptive schedules *(recommended)*

```python
from qanneal import auto_schedule_sa_tuned, auto_schedule_sqa_tuned, auto_ladder_sqa_tuned

# For SA
schedule = auto_schedule_sa_tuned(ising, mode="balanced")

# For SQA / CT-PIMC
schedule = auto_schedule_sqa_tuned(ising, mode="balanced")

# For SQAPT — returns a (β, Γ) ladder with `replicas` points
ladder = auto_ladder_sqa_tuned(ising, replicas=8, mode="balanced")
```

**How tuning works**: The helper probes ~256 random single-spin flips, computes the
75th-percentile |ΔE|, and derives `β_start`/`β_end` from physical acceptance-target
heuristics. This avoids manual tuning across problem sizes and coupling scales.

| `mode` | Steps | Exploration | Use when |
|--------|-------|------------|---------|
| `"fast"` | 30–40 | High | Prototyping, large sweeps |
| `"balanced"` | 60–80 | Medium | Default production |
| `"accurate"` | 110–130 | Low | Best solution quality |

### Fixed schedules *(manual)*

```python
from qanneal import AnnealSchedule, SQASchedule
import numpy as np

# SA: linear β ramp
schedule = AnnealSchedule.linear(beta_start=0.1, beta_end=5.0, steps=60)

# SQA: paired (β, Γ) — geometric Γ decay is strongly recommended over linear
schedule = SQASchedule.from_vectors(
    betas=np.linspace(0.1, 5.0, 60).tolist(),
    gammas=np.geomspace(5.0, 0.01, 60).tolist(),
)
```

---

## Full Parameter Reference for `solve()`

### Common parameters (all methods)

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `"sqa"` | Algorithm: `"sa"`, `"sqa"`, `"sqapt"`, `"ctpimc"`, `"sqa-c"`, `"sqa-csw"`, `"sqapt-c"`, `"sqapt-csw"` |
| `reads` | 1 | Independent runs; the best across all reads is returned |
| `sweeps_per_beta` | 20 | Metropolis sweeps per temperature step |
| `schedule` | None | Schedule object; auto-selected per method if None |
| `seed` | None | RNG seed (int); None = random |
| `backend` | `"cpu"` | Compute backend |
| `progress` | True | Show tqdm progress bar (requires `tqdm`) |
| `n` | None | Hint for problem size (dict/list inputs) |
| `return_bits` | False | Return {0,1} bits instead of {−1,+1} spins |

### SQA and SQAPT (`method="sqa"` or `"sqapt"`)

| Parameter | Default | Description |
|-----------|---------|-------------|
| `trotter_slices` | 32 | Number of imaginary-time slices. More → less Trotter error, more cost |
| `replicas` | 1 | Parallel SQA chains (SQA) or PT ladder size (SQAPT) |
| `worldline_sweeps` | 5 | Flip one spin through all time-slices at once (improves mixing) |
| `cluster_sweeps` | 0 | Swendsen–Wang cluster updates along imaginary time |
| `continuous_time_slices` | 0 | If > 0, approximates continuous-time limit within SQA |

### SQAPT only (`method="sqapt"`)

| Parameter | Default | Description |
|-----------|---------|-------------|
| `pt_steps` | 50 | Number of local-update + swap epochs |
| `swap_interval` | 1 | Attempt replica swap every N steps |
| `pt_betas` | None | Explicit β ladder (overrides schedule) |
| `pt_gammas` | None | Explicit Γ ladder (must pair with pt_betas) |

### CT-PIMC only (`method="ctpimc"`)

| Parameter | Default | Description |
|-----------|---------|-------------|
| `ctpimc_qubits_per_update` | 1 | Spins updated per cluster proposal |
| `ctpimc_qubits_per_chain` | 1 | Chain length for multi-qubit proposals |

### Catalyst variants (`method="sqa-c"`, `"sqa-csw"`, `"sqapt-c"`, `"sqapt-csw"`)

| Parameter | Default | Description |
|-----------|---------|-------------|
| `catalyst_type` | `"linear"` | Catalyst operator K: `"linear"`, `"staggered"`, `"product"`, `"mean_field"`, `"none"` |
| `catalyst_opt_iterations` | 8 | Gradient-descent steps per read to optimise C(t) |
| `catalyst_samples_per_step` | 16 | Monte Carlo samples per gradient step |
| `catalyst_learning_rate` | 0.1 | Step size for the catalyst schedule update |
| `catalyst_opt_interval` | 4 | Steps between catalyst optimisation calls (SQAPT-c only) |

---

## Accessing Results

```python
result = solve(problem, method="sqapt", reads=32)

result.best_sample    # np.ndarray shape (n,), dtype int — best spin/bit configuration
result.best_energy    # float — lowest energy found across all reads
result.samples        # list of n arrays — one per read
result.energies       # list of floats — one per read
result.trace          # list of floats — energy trace from the first read
result.var_order      # variable ordering (relevant for BQM/graph inputs)
result.return_bits    # bool — whether samples are bits or spins

# Convert spins to bits manually (if return_bits=False)
bits = ((result.best_sample + 1) // 2).astype(int)
```

### Observers (low-level diagnostics)

```python
from qanneal import Annealer, MetricsObserver, AnnealSchedule

ising = ...
schedule = AnnealSchedule.linear(0.1, 5.0, 60)
obs = MetricsObserver()
ann = Annealer(ising, schedule)
res = ann.run(sweeps_per_beta=40, observer=obs)

import matplotlib.pyplot as plt
plt.plot(obs.energy_trace)
plt.xlabel("Temperature step"); plt.ylabel("Energy"); plt.show()
```

SQA observers (`SQAMetricsObserver`, `SQAStateTraceObserver`) capture per-sweep replica/slice
state snapshots — see `docs/sqa_trace_parameters.md` for the full field list.

---

## Interactive GUI

qanneal ships a three-tab interactive learning lab built with Tkinter + Matplotlib.

```python
from qanneal import launch_graph_editor
launch_graph_editor()

# or from the command line:
# python examples/python/graph_editor_gui.py
```

**Tab 1 — Graph Editor**: Draw graphs, set node biases and edge weights, choose problem
type (MaxCut, QUBO, number partition) and method, then run `solve()` and inspect results.

**Tab 2 — Animation Lab**: Replay the energy trace and schedule from the last solve run.
Shows per-method physics subplots (Γ decay, worldline snapshots, swap acceptance).

**Tab 3 — Tutorial**: Seven interactive concept cards covering: SA, inverse temperature β,
transverse field Γ, Trotter slices, parallel tempering, energy landscapes, and problem encodings.

*Requires*: `matplotlib` with the `TkAgg` backend.

---

## Parallelism

### OpenMP (automatic, within a run)

Enabled by default (`QANNEAL_ENABLE_OPENMP=ON`). Parallelizes:
- `ReplicaAnnealer` — across replicas
- `SQAAnnealer` — across replicas × slices (disabled when an observer is attached)
- `SQAParallelTemperingAnnealer` — across ladder replicas

Control at runtime:
```bash
export OMP_NUM_THREADS=8
```

### Multi-process / multi-node

For large problems or many reads, use the HPC launcher:

```bash
# Single node, multiprocessing (no extra deps)
python examples/python/hpc_sqa_launcher.py \
  --n 5000 --method sqapt --reads 64 --workers 8

# Multi-node MPI (requires mpi4py)
mpirun -n 32 python examples/python/hpc_sqa_launcher.py \
  --n 50000 --method sqa --reads 8 --mpi

# SLURM job array (most portable, no mpi4py needed)
sbatch scripts/slurm/run_sqa_array.sh
python examples/python/merge_array_results.py results/run_*.json
```

### C++ MPI (build-time)

```bash
cmake -S . -B build -DQANNEAL_ENABLE_MPI=ON
cmake --build build
mpirun -n 8 build/qanneal_mpi_example
```

---

## Notebooks

Interactive Jupyter notebooks in `notebooks/`:

| Notebook | What you'll learn |
|----------|------------------|
| `01_quickstart.ipynb` | First problem, SA vs SQA comparison |
| `02_sqa_physics.ipynb` | Trotter slices, Γ schedules, worldline sweeps |
| `03_sqapt_and_ctpimc.ipynb` | Replica exchange, (β,Γ) ladders, CT-PIMC |
| `04_large_problems.ipynb` | SparseIsing, Chimera/MaxCut, HPC scaling |

---

## Examples

```bash
# Tuned SQAPT demo
python examples/python/tuned_sqapt_demo.py --mode balanced

# Diagonal catalyst advantage benchmark
python examples/python/catalyst_advantage.py

# Number partition benchmark (SA / SQA / SQAPT / CT-PIMC vs D-Wave SDK)
python examples/python/number_partition_benchmark.py \
  --with-sqapt --with-ctpimc --schedule-mode balanced --jobs 8

# Full comparative benchmark vs D-Wave
python examples/python/dwave_comparative_benchmark.py --n 40 --reads 16

# HPC scaling benchmark
python examples/python/hpc_sqa_launcher.py --scaling --method sqapt --mode fast

# Interactive graph problem editor
python examples/python/graph_editor_gui.py
```

---

## Low-Level C++ API

For use without Python, include the umbrella header:

```cpp
#include "qanneal/core.hpp"
```

### Key classes

| Class | Header |
|-------|--------|
| `DenseIsing` | `dense_ising.hpp` |
| `SparseIsing`, `SparseEdge` | `sparse_ising.hpp` |
| `QUBO` | `qubo.hpp` |
| `AnnealSchedule` | `schedule.hpp` |
| `SQASchedule` | `sqa_schedule.hpp` |
| `Annealer` | `annealer.hpp` |
| `ReplicaAnnealer` | `replica_annealer.hpp` |
| `ParallelTemperingAnnealer` | `parallel_tempering.hpp` |
| `SQAAnnealer` | `sqa_annealer.hpp` |
| `SQAParallelTemperingAnnealer` | `sqa_parallel_tempering.hpp` |
| `CTPIMCAnnealer` | `ctpimc_annealer.hpp` |
| `State` | `state.hpp` |
| `MetricsObserver`, `StateTraceObserver` | `metrics_observer.hpp` |
| `SQAMetricsObserver`, `SQAStateTraceObserver` | `metrics_observer.hpp` |
| `MPIContext` | `mpi/mpi_context.hpp` |

### CMake build options

```bash
cmake -S . -B build \
  -DQANNEAL_ENABLE_OPENMP=ON   \
  -DQANNEAL_ENABLE_MPI=OFF     \
  -DQANNEAL_BUILD_TESTS=ON     \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build
```

| CMake Flag | Default | Effect |
|-----------|---------|--------|
| `QANNEAL_ENABLE_OPENMP` | ON | Parallel loops in Replica/SQA/SQAPT annealers |
| `QANNEAL_ENABLE_MPI` | OFF | Distributed `run_replica_anneal()` |
| `QANNEAL_BUILD_TESTS` | ON | Build C++ unit tests |
| `QANNEAL_BUILD_PYTHON` | OFF* | Build pybind11 Python extension (*forced ON by scikit-build) |
| `QANNEAL_ENABLE_CUDA` | OFF | CUDA backend (stub; not yet wired) |

---

## Documentation

| File | Content |
|------|---------|
| `docs/api.md` | Complete API reference (all classes, parameters, return types) |
| `docs/overview.md` | Architecture, data flow, component map |
| `docs/user_guide.md` | Step-by-step usage guide with physical intuition |
| `docs/ctpimc.md` | CT-PIMC algorithm details |
| `docs/sqa_trace_parameters.md` | SQA observer field guide |

---

## License

Apache-2.0. See `LICENSE` and `NOTICE`.
The CT-PIMC engine uses D-Wave's localPIMC (Apache-2.0), credited in `NOTICE`.
