Skip to content

pqblocks-population-anneal

Population Annealing Monte Carlo heuristic solver for Ising models and QUBO combinatorial optimization. Quantum-inspired classical optimization, not cryptography.

Install from GitHub Area Status Python Licence Source

At a glance
Area Quantum-inspired
Import import pqblocks_population_anneal
Command line library only
Version 0.1.0 (Alpha)
Python >=3.11
Native dependency none
Repository PQBlocks/population-annealing
Licence Apache-2.0

What is pqblocks-population-anneal?

Quantum-inspired Population Annealing Monte Carlo heuristic solver for Ising and QUBO combinatorial optimization.

Domain Classification: Quantum-inspired classical optimisation: not cryptography, no security claim.

Not cryptography

Quantum-inspired classical optimisation: not cryptography, no security claim.

Install

pip install git+https://github.com/PQBlocks/population-annealing

uv add git+https://github.com/PQBlocks/population-annealing

PyPI release staged

pqblocks-population-anneal installs from its GitHub repository while the PyPI release is staged. The import name and API are identical either way.

Quickstart

Executed, not just written

This is the quickstart from the package README. It was run against the package source when this page was generated.

quickstart.py
import numpy as np
from pqblocks_population_anneal import PopulationAnnealingSampler

# Define a 4-spin chain problem
h = np.array([0.5, -0.3, 0.2, -0.1])
J = np.array([
    [0.0, 1.0, -1.0, 0.0],
    [1.0, 0.0, 1.0, -1.0],
    [-1.0, 1.0, 0.0, 1.0],
    [0.0, -1.0, 1.0, 0.0]
])

# Initialize sampler with 100 replicas and 10 sweeps per temperature step
sampler = PopulationAnnealingSampler(num_replicas=100, num_sweeps=10)
best_state, best_energy, free_energy = sampler.sample(h, J, seed=42)

print(f"Best Spin State: {best_state}")
print(f"Best Energy: {best_energy:.6f}")
print(f"Estimated Free Energy: {free_energy:.6f}")

Examples

Runnable scripts in the repository:

Documentation and evidence

Every PQBlocks package ships the same evidence set, so each claim can be checked against tests, sources and measurements.

  • Overview

    What it does, install, usage and API.

  • For AI agents

    Correct imports, pitfalls and rules for coding assistants.

  • Security notes

    What it protects, hostile input, constant-time and audit status.

  • Testing

    Test suites, coverage, vectors and what is not covered.

  • Benchmarks

    Measured performance, including where it loses.

  • Evidence

    Primary sources and the method-to-code map.

  • Verification report

    Self-verification results, defects found and limits.

  • Use cases

    Worked scenarios and when to pick something else.

  • Changelog

    Every release and what changed.

  • pqblocks-anneal-sa: Simulated Annealing heuristic solver for Ising and QUBO optimization problems. Quantum-inspired classical…
  • pqblocks-anneal-schedule: Quantum-inspired instance-adaptive simulated annealing with statistics-driven schedule generation for Ising and QUBO…
  • pqblocks-anneal-sqa: Simulated Quantum Annealing (Path-Integral Monte Carlo via Suzuki-Trotter decomposition) heuristic solver for Ising…
  • pqblocks-bifurcation: Simulated Bifurcation (ballistic and discrete) heuristic solver for Ising and QUBO problems. Quantum-inspired…
  • pqblocks-digital-anneal: Digital Annealer-style parallel-trial heuristic solver for Ising and QUBO optimization problems. Quantum-inspired…
  • pqblocks-qiea: Quantum-Inspired Evolutionary Algorithm (QIEA) with Q-bit representations and quantum rotation gates for Ising and…
  • pqblocks-qubo: Unified mathematical representation and converter library for Quadratic Unconstrained Binary Optimization (QUBO) and…
  • pqblocks-qubo-bench: Benchmarking harness and standard instance loaders for quantum-inspired optimization algorithms against classical…