目录
Wei LIU

feat(fermion): measure native one-body density tensors (#1179)

Adds experimental native fermionic one-body density measurement and one-body energy reconstruction. Previously users could express density monomials individually but lacked a reusable ordered measurement and tensor assembly path. The new concrete Algorithms module returns Hermitian observables for gamma[p,q] = <a†p aq> and assembles ordinary complex PyTorch tensors from their real expectations.

Algorithms owns both operations; callers keep executing through fq.run. There is no new runtime, RDM class, dependency, root export or protected contract change. OpenFermion and Cirq are scientific references only and are not imported. The scope was committed before implementation in docs/development/FERMION_ONE_BODY_DENSITY.md.

User workflow

python -m examples.algorithms.fermion_one_body_density --encoding parity
python -m examples.algorithms.fermion_one_body_density --encoding bravyi_kitaev

Both use explicitly matched two-mode coherent one-particle preparations and the same native measurement/tensor consumer. Expected particle number: 1.0000000000; reconstructed energy: 0.4520082847; circuit-angle gradient: -0.5016897975; direct-energy residual: below 1e-12. Omitting --encoding selects JW. Normal execution uses X/RY/CX/S gates without dense reference state loading or diagonalization.

Verification

CI correction: the original head omitted the new density module from the existing executable-docstring entry list. Both failed Linux checks reported test_every_module_with_examples_is_covered. Commit 184a07264 adds the real one_body_density_observables entry to that list; no assertion or production behavior is changed. The full docstring gate and density unit/integration tests pass locally together (47 tests). Ruff, Black and Algorithms ownership pass. On corrected head 184a072641faffd10eeeca52a9e974492fed6906, both previously failed Linux jobs now pass: cpu-core-3-12-tests (8m25s) and coverage-shard (138, 2) (4m47s). Both native-fermion Python lanes also pass. Latest exact-head snapshot: 217 successful checks, 3 conditional skips, 19 still running, no failures. The full CI run is not yet complete.

  • 47 density unit/integration and selected example checks pass on macOS CPU: independent occupation-bit action, vacuum/determinant/complex/correlated states, JW/parity/BK replacement, particle number, spectral bounds, complex orbital rotations via independent two-particle minors, direct energy comparison, analytic/finite-difference gradients and optimizer update.
  • Another 71 existing encoding/algebra/dependency-isolation/public-API candidate regressions pass.
  • Fresh subprocesses run all three encodings while OpenFermion, Cirq, external science SDK imports and eigensolvers are blocked.
  • Strict module typing, Ruff, Black, architecture boundaries, Algorithms path ownership, protected API baseline, generated-document consistency, repository language, whitespace and local Markdown links pass.
  • The required full python tools/ci_tier.py pr-default run reached approximately 56% before its 600-second budget expired (exit 124). It is not a pass. Three QFT Hadamard/phase-fusion count assertions in tests/team/simulation/test_controlled_phase_graph.py fail with 44 applications versus expected 28. A focused run produces the identical three failures and eleven passes both on this head and in a separate clean detached checkout of baseline b58fc8a01d9395972042abd1aaa507c9769b73da; the baseline checkout was removed after comparison. No simulation source or assertion is changed by this PR. Linux coverage is left to CI.
  • Optional coverage instrumentation exited 245 before test output, also with plugin auto-loading disabled. No coverage percentage is claimed; ordinary focused pytest runs pass as recorded above.

Reproduce focused checks:

python -m pytest tests/unit/fermion/test_density.py tests/integration/test_fermion_one_body_density.py tests/test_algorithm_examples.py -k 'density or covered_and_indexed' -q
python -m pytest tests/unit/fermion/test_encoding.py tests/unit/test_observables_fermion.py tests/integration/test_native_fermion_isolation.py tests/unit/test_public_api_candidate.py -q

Limits and review boundary

single_device_fast_path, exact local CPU expectations; full-register matched encodings supplied by the caller. The assembler validates count, real singleton CPU tensors, dtype agreement and finiteness, and preserves autograd. Same-width state encoding/order cannot be inferred from unlabelled values. Hermiticity is imposed by the measurement design; no physical/noise projection occurs. Float32/complex64 assembly is accepted without a precision-equivalence claim.

Observable/output count is O(n²); encoded strings add width-dependent cost and statevector memory remains exponential. Dense occupation references and unitary completions exist only in tests up to four modes. No 2-RDM, molecular two-body energy reconstruction, sampling, hardware, accelerator or distributed support is claimed. Experimental capability registration remains a separate Integration follow-up after scientific acceptance.

Review subtraction: reuse existing FermionOperator, encoders, Observable, native expectations and PyTorch tensors; keep execution outside the science module and leave stable exports unchanged.

3天前4491次提交
FlagQuantum

Quantum computing, built for learning.

A PyTorch-first framework for differentiable quantum computing and quantum AI.

Qubit ordering · Quick start · Documentation · Wiki · Examples

Turn quantum circuits into trainable models. FlagQuantum brings PyTorch learning, multiple simulation representations, and hardware execution into one workflow. Its long-term goal is a continuous path from local scientific exploration to distributed training, device modeling, and fault-tolerant quantum computing research.

  • Train with PyTorch. Compose quantum and classical layers with autograd and familiar optimizers.
  • Choose the representation. Statevector, matrix product state (MPS), and tensor-network simulation for different circuit structures and resource budgets.
  • Connect simulation to hardware. Keep the circuit and requested observable explicit as you move between supported execution targets.

Support is specific to each backend and workload. Local training and selected distributed paths have correctness evidence. See the validation scope for what has been tested and what remains a research goal.

Qubit ordering: qubit 0 is the most-significant bit

[!IMPORTANT] FlagQuantum uses big-endian qubit order. For an n-qubit register, basis states are written as |q0 q1 ... q(n-1)>; qubit 0 is the most-significant bit (MSB), and qubit n-1 is the least-significant bit (LSB).

By default, a circuit starts in |00...0>, with amplitude 1 at statevector index 0 and 0 everywhere else. For example, applying X to qubit 0 of |000> produces |100> at index 4; applying it to qubit 2 produces |001> at index 1. This matches the tensor-product notation |q0> ⊗ |q1> ⊗ ... ⊗ |q(n-1)>, keeping equations, matrices, and qubit lists in the same left-to-right order.

Framework or service Exposed qubit/result order Compared with FlagQuantum
FlagQuantum Qubit 0 is the MSB Native convention
Cirq The first qubit in qubit_order is the MSB Same when ordered [q0, q1, ...]
PennyLane Basis-state digits follow the supplied qubit sequence Same when ordered [0, 1, ...]
Qiskit Qubit 0 is the LSB Opposite significance
NVIDIA cuStateVec Index bit 0 is the LSB Opposite significance
Jiuding QuantumAI Cloud Runs FlagQuantum remotely and returns FlagQuantum-ordered results Same
Quafu Provider count strings are converted to logical qubit order, with qubit 0 on the left Normalized to the same order
Amazon Braket Ascending qubit order, with qubit 0 as the MSB Same
Azure Quantum Depends on the selected Azure target and hardware provider No platform-wide convention

Endianness affects statevector, matrix, and bitstring indexing, not the (control, target) order of gate arguments. Convert representations at framework boundaries instead of reversing gate arguments. Cloud services commonly expose measurement results rather than raw statevectors, so the service rows describe the order visible at FlagQuantum’s result boundary.

Install and train your first quantum model

Requires Python 3.10–3.12. Choose the command for your computer.

macOS (Apple Silicon):

python -m pip install flagquantum

This release publishes macOS wheels for Apple Silicon only; Intel macOS is not a supported binary installation target.

Linux or Windows, CPU only:

python -m pip install "torch>=2.13,<2.15" --index-url https://download.pytorch.org/whl/cpu
python -m pip install flagquantum

FlagQuantum’s compiled extension uses PyTorch’s Stable ABI and is tested with PyTorch 2.10.x through 2.14.x in compatibility CI. New CPU/CUDA environments should use the recommended 2.13.x or 2.14.x runtime above. The first CPU install downloads about 200 MB of PyTorch. On a clean GitHub Ubuntu runner it took about 16 seconds; slower networks will take longer.

NVIDIA GPU: Select a PyTorch 2.13.x or 2.14.x CUDA command from the PyTorch installer, then run:

python -m pip install flagquantum

Installing from source? Follow the short setup in CONTRIBUTING.md.

Native accelerator support: FlagQuantum runs directly on the following vendor-provided PyTorch runtimes.

NVIDIA CUDA Upstream PyTorch
Hygon DCU Vendor PyTorch runtime
Moore Threads MUSA Vendor PyTorch runtime
MetaX Vendor PyTorch runtime
Biren Vendor PyTorch runtime
Huawei Ascend 910C Torch-FL with the pinned Ascend and FlagCX fixes

Keep the vendor runtime installed, then run python -m pip install flagquantum. The core requirement accepts torch>=2.10,<2.15, including local version labels such as 2.10.0+metax3.8.1.0; do not replace a managed runtime with an upstream CPU/CUDA wheel. Avoid --upgrade/--upgrade-strategy eager when retaining a managed runtime. The invertible extra still requires PyTorch 2.13.x and is not a vendor-runtime installation shortcut.

Huawei Ascend 910C support through Torch-FL: Native complex64/complex128 statevector, MPS, tensor-network and density-matrix execution, autograd and hybrid training, noise, TEBD, native dynamics and QEC predecoder training have hardware validation. Sharded statevector/MPS/TN training, two-host communication and checkpoint restart are also covered. Install the fixed source configuration in the 910C guide; previously published wheels alone do not contain the required fixes.

FLAGQUANTUM_TEST_ASCEND_910C=1 python -m pytest \
  tests/integration/test_ascend_circuit_workflows.py \
  tests/integration/test_ascend_native_dynamics.py -q

Quantum state, gradients and optimizer updates remain on flagos. The acceptance record states the measured functions and topology. This is hardware development support; production, performance and capacity certification remain outside the claim. Optional third-party runtimes retain their own hardware requirements.

To build a CPU or GPU environment with QSteed and optional JAX, follow the container guide.

Build a two-qubit circuit and learn its rotation angle by minimizing ⟨Z₀⟩. fq.Module exposes the quantum model to PyTorch; outputs selects what to measure after training.

import torch
import flagquantum as fq


def circuit(parameters):
    return fq.Circuit(2).ry(0, parameters[0]).cx(0, 1)


model = fq.Module(circuit, n_parameters=1, init=torch.tensor([0.25]))
training = fq.train(
    model,
    optimizer=torch.optim.Adam(model.parameters(), lr=0.05),
    objective=lambda z: z.mean(),
    steps=10,
)

trained_circuit = circuit(next(model.parameters()).detach())
measurement = fq.expectation(fq.Z(0))
result = fq.run(trained_circuit, outputs=measurement)
print(result.expectation())

For a complete classical–quantum model, follow the hybrid training example. The published wheel contains the flagquantum package only, so examples/ comes from a clone of this repository: git clone https://github.com/flagos-ai/FlagQuantum.git and run the examples from that working copy.

Same circuit. Different execution targets.

The experimental adapters can evaluate the same observable on a Jiuding QuantumAI Cloud GPU workspace or Quafu quantum hardware. Configure the Jiuding QuantumAI Cloud workspace and credentials or the Quafu token before running the corresponding call.

# Managed GPU simulation on Jiuding QuantumAI Cloud
jiuding_result = fq.run(
    trained_circuit, target="jiuding:gpu", outputs=measurement,
)

# Quantum hardware: service compilation and estimation from measured shots
quafu_result = fq.run(
    trained_circuit, target="quafu:Baihua",
    outputs=measurement, shots=1024,
)

The Jiuding QuantumAI Cloud call above needs JIUDING_WORKSPACE set to the running workspace name when it is invoked from outside that workspace; inside the workspace the name is discovered automatically. See repeated low-latency workspace execution.

Direct Quafu submission is available in the 0.3 release line. Install flagquantum==0.3.0 for this path. With the older 0.2.0 release, use the documented local QSteed compilation path instead: pass compiler="qsteed" after installing the separate FlagQuantum Compiler QSteed plugin, as described in optional local compiler plugin. The quafu extra does not install that plugin.

Jiuding QuantumAI Cloud computes a simulated expectation; Quafu estimates it from hardware measurements. The training example runs on your local machine; these calls evaluate the trained circuit remotely. Live provider access is required and is not certified by the local or A800 checks.

Go further

Connect simulation with device observations. Use QPU digital twins to compare calibration-based model predictions with measured counts. See the experiment guide for task binding and the scope of hardware validation.

Toward fault-tolerant quantum computing. Start with a local QEC memory experiment connecting syndrome extraction, decoding, and correction. Logical operations and hardware feedback are longer-term research goals.

Quantum AI tutorials · Distributed statevector · Distributed MPS · ARCHITECTURE.md

Documentation and Wiki

Start with the Wiki home or browse the Wiki Directory for the full learning path. Find a guide by topic:

Topic Wiki guides
Get started and understand the basics Installation and Compatibility · Quick Start · Core Concepts · Qubit Ordering and Result Conventions
Build circuits and train models Building and Simulating Circuits · Training Parameterized Circuits · Hybrid Classical-Quantum Models
Choose simulation and compute resources Choosing a Simulation Method · Accelerator Setup · Distributed Simulation and Training
Compile circuits and model noise Circuit Compilation and Interoperability · Noise and Open-System Simulation
Explore QEC, cloud execution, and device models Quantum Error Correction Experiments · Cloud and Quantum Hardware Execution · QPU Digital Twins
Reproduce results, troubleshoot, and contribute Reproducibility and Benchmarks · Troubleshooting and FAQ · Development and Contribution Guide · Documentation Guide

The Wiki guides currently target FlagQuantum 0.3.1 and state their verification scope. For versioned API contracts, executable examples, and support boundaries, use the repository documentation, examples, and capability catalog matching your installed release; main can describe newer development.

Citing FlagQuantum

If you use FlagQuantum in work you publish, cite the software through CITATION.cff. GitHub renders it under Cite this repository in APA and BibTeX, and cffconvert produces other formats from the same file, so a citation does not have to be assembled by hand.

Cite the version you ran rather than main: a result is reproducible against the release it was measured on. The file records 0.3.1; adjust the version and date if you ran an earlier release.

Support varies by execution path. See the capability catalog for maturity and limitations.

Benchmarks and validated results


Contributing · Apache License 2.0

    Gitlink(确实开源)
  • 加入我们
  • 官网邮箱:gitlink@ccf.org.cn
  • QQ群
  • QQ群
  • 公众号
  • 公众号

版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号