Version 1.1 (#422)

Co-authored-by: Maximilian Morchen <v-mmorchen@microsoft.com>
Co-authored-by: Maximilian Mörchen <111281642+mmoerchen@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Rushi Gong <rushigong@microsoft.com>

Author: 5 people

INSTALL.md

@@ -8,10 +8,10 @@ Designed as both a **development platform** and a **composable framework**, QDK/
 
 QDK/Chemistry bridges classical computational chemistry with quantum computing by providing every stage of the quantum applications pipeline in a single, modular toolkit:
 
-- **Quantum algorithms** — a growing collection of chemistry-aware quantum algorithms, with composable building blocks for constructing higher-level quantum workflows
-- **Classical electronic structure** — production-quality classical methods that generate the high-quality inputs quantum algorithms require
-- **Composable architecture** — a plugin system that lets users assemble custom pipelines from interchangeable components, mixing native high-performance C++ backends with established community packages
-- **Multiple quantum backends** — execute circuits on a variety of simulators through a unified interface that decouples algorithm development from backend selection
+- **Quantum algorithms**: a growing collection of chemistry-aware quantum algorithms, with composable building blocks for constructing higher-level quantum workflows
+- **Classical electronic structure**: production-quality classical methods that generate the high-quality inputs quantum algorithms require
+- **Composable architecture**: a plugin system that lets users assemble custom pipelines from interchangeable components, mixing native high-performance C++ backends with established community packages
+- **Multiple quantum backends**: execute circuits on a variety of simulators through a unified interface that decouples algorithm development from backend selection
 
 ## Documentation
 
@@ -39,7 +39,12 @@ qdk-chemistry/
 
 ## Installing
 
-Detailed instructions for installing QDK/Chemistry can be found in [INSTALL.md](./INSTALL.md)
+```bash
+python3 -m venv venv && source venv/bin/activate
+python3 -m pip install 'qdk-chemistry[all]'
+```
+
+The `[all]` extra pulls in all optional dependencies so that examples and tests work without chasing missing packages. For other installation methods (Dev Container, building from source) and platform-specific notes, see [INSTALL.md](./INSTALL.md).
 
 ## Telemetry
 

README.md

@@ -1 +1 @@
-1.0.2
+1.1.0

VERSION

@@ -26,8 +26,8 @@
 
 ################################################################################
 # start-cell-run
-from pathlib import Path  # noqa: E402
-from qdk_chemistry.data import Structure  # noqa: E402
+from pathlib import Path
+from qdk_chemistry.data import Structure
 
 # Load a molecular structure (water molecule) from XYZ file
 structure = Structure.from_xyz_file(
@@ -52,7 +52,7 @@
 
 ################################################################################
 # start-cell-list-implementations
-from qdk_chemistry.algorithms import registry  # noqa: E402
+from qdk_chemistry.algorithms import registry
 
 print(registry.available("active_space_selector"))
 # ['pyscf_avas', 'qdk_occupation', 'qdk_autocas_eos', 'qdk_autocas', 'qdk_valence']
@@ -61,7 +61,7 @@
 
 ################################################################################
 # start-cell-autocas
-from qdk_chemistry.utils import compute_valence_space_parameters  # noqa: E402
+from qdk_chemistry.utils import compute_valence_space_parameters
 
 # Create a valence space active space selector
 valence_selector = create("active_space_selector", "qdk_valence")

docs/source/_static/examples/python/active_space_selector.py

@@ -0,0 +1,145 @@
+"""Circuit data class usage examples."""
+
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+################################################################################
+# start-cell-qsharp-workflow
+import json
+
+import qdk
+import qsharp
+from qdk_chemistry.data import Circuit
+from qdk_chemistry.data.circuit import QsharpFactoryData
+
+# 1. Define a Q# operation from string
+qsharp.eval(
+    """
+    operation GHZSample(n: Int) : Result[] {
+    use qs = Qubit[n];
+
+    H(qs[0]);
+    ApplyToEach(CNOT(qs[0], _), qs[1...]);
+
+    let results = MeasureEachZ(qs);
+    ResetAll(qs);
+    return results;
+    }
+    """
+)
+
+# 2. Get a Q# circuit object and wrap it
+qsharp_factory = QsharpFactoryData(
+    program=qdk.code.GHZSample,
+    parameter={"n": 3},
+)
+circuit = Circuit(qsharp_factory=qsharp_factory)
+
+# 3. Inspect the circuit
+qsharp_circuit = circuit.get_qsharp_circuit()
+print(qsharp_circuit)
+# Return an ASCII diagram of the circuit
+#    q_0    ── H ──── ● ──── ● ──── M ──── |0〉 ──
+#                     │      │      ╘════════════
+#    q_1    ───────── X ─────┼───── M ──── |0〉 ──
+#                            │      ╘════════════
+#    q_2    ──────────────── X ──── M ──── |0〉 ──
+#                                   ╘════════════
+
+# 4. Access the gate-level JSON structure
+circuit_json = json.loads(qsharp_circuit.json())
+print(f"Qubits: {len(circuit_json['qubits'])}")
+
+# 5. Resource estimation
+estimate_result = circuit.estimate()
+formatted = estimate_result["physicalCountsFormatted"]
+print(f"Physical qubits: {formatted['physicalQubits']}")
+print(f"Runtime: {formatted['runtime']}")
+# end-cell-qsharp-workflow
+################################################################################
+
+################################################################################
+# start-cell-qsharp-harness
+# Prepare single-reference state with Q# factory parameters
+from qdk_chemistry.data import Circuit
+from qdk_chemistry.utils.qsharp import QSHARP_UTILS
+
+# 1. Build a parameter object (a dictionary or a Q# structured parameter class)
+bitstring = [1, 1, 0, 0]
+params = QSHARP_UTILS.StatePreparation.SingleReferenceParams(
+    bitStrings=bitstring, numQubits=len(bitstring)
+)
+
+# 2. Create the factory — vars() converts the dataclass to a dict
+factory = QsharpFactoryData(
+    program=QSHARP_UTILS.StatePreparation.MakeSingleReferenceStateCircuit,
+    parameter=vars(params),
+)
+
+# 3. Wrap in a Circuit — nothing is compiled yet
+circuit = Circuit(qsharp_factory=factory, encoding="jordan-wigner")
+
+# 4. Compilation happens on demand:
+circuit.get_qsharp_circuit()  # → qsharp.circuit(program, **params)
+circuit.get_qir()  # → qsharp.compile(program, **params)
+# end-cell-qsharp-harness
+################################################################################
+
+################################################################################
+# start-cell-conversion
+import numpy as np
+from qdk_chemistry.algorithms import create
+from qdk_chemistry.data import Circuit, Structure
+
+# When algorithms produce circuits, they carry native Q# operations internally.
+# This enables end-to-end Q# composition without format conversions.
+coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.4]])
+structure = Structure(coords, symbols=["H", "H"])
+
+scf = create("scf_solver")
+_, wfn = scf.run(structure, charge=0, spin_multiplicity=1, basis_or_guess="sto-3g")
+ham = create("hamiltonian_constructor").run(wfn.get_orbitals())
+_, wfn_cas = create("multi_configuration_calculator").run(ham, 1, 1)
+
+# StatePreparation produces a Circuit with a native Q# factory
+state_prep = create("state_prep", "sparse_isometry_gf2x")
+circuit = state_prep.run(wfn_cas)
+
+# Inspect the Q# circuit (prune unused qubits for clarity)
+pruned_qsharp_circuit = circuit.get_qsharp_circuit(prune_classical_qubits=True)
+print(pruned_qsharp_circuit)
+
+# Get the QIR representation
+qir = circuit.get_qir()
+print(qir)
+
+# Export to OpenQASM or Qiskit when needed (if qiskit is installed)
+try:
+    qasm_str = circuit.get_qasm()
+    print(qasm_str)
+
+    qiskit_circuit = circuit.get_qiskit_circuit()
+    print(qiskit_circuit)
+except (ImportError, RuntimeError):
+    print("Qiskit not installed — skipping OpenQASM/Qiskit export")
+
+# end-cell-conversion
+################################################################################
+
+################################################################################
+# start-cell-serialization
+# Save to JSON
+circuit.to_json_file("example_circuit.circuit.json")
+
+# Load from JSON
+loaded = Circuit.from_json_file("example_circuit.circuit.json")
+
+# Save to HDF5
+circuit.to_hdf5_file("example_circuit.circuit.h5")
+
+# Load from HDF5
+loaded_h5 = Circuit.from_hdf5_file("example_circuit.circuit.h5")
+# end-cell-serialization
+################################################################################

docs/source/_static/examples/python/circuit.py

@@ -0,0 +1,111 @@
+"""Circuit executor usage examples."""
+
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+################################################################################
+# start-cell-create
+from qdk_chemistry.algorithms import create
+
+# Create the default executor (QDK sparse-state simulator)
+executor = create("circuit_executor")
+
+# Or select a specific implementation
+full_state = create("circuit_executor", "qdk_full_state_simulator")
+sparse_state = create("circuit_executor", "qdk_sparse_state_simulator")
+aer = create("circuit_executor", "qiskit_aer_simulator")
+# end-cell-create
+################################################################################
+
+################################################################################
+# start-cell-configure-qdk
+# Configure the QDK full-state simulator
+executor = create("circuit_executor", "qdk_full_state_simulator")
+executor.settings().set("type", "cpu")
+executor.settings().set("seed", 42)
+# end-cell-configure-qdk
+################################################################################
+
+################################################################################
+# start-cell-configure-qiskit
+# Configure the Qiskit Aer simulator
+executor = create("circuit_executor", "qiskit_aer_simulator")
+executor.settings().set("method", "statevector")
+executor.settings().set("seed", 42)
+executor.settings().set("transpile_optimization_level", 0)
+# end-cell-configure-qiskit
+################################################################################
+
+################################################################################
+# start-cell-run
+from qdk_chemistry.algorithms import create
+from qdk_chemistry.data import Circuit
+
+# Define a circuit in OpenQASM
+circuit = Circuit(
+    qasm="""
+    include "stdgates.inc";
+    qubit[2] q;
+    bit[2] c;
+    x q[0];
+    cx q[0], q[1];
+    c[0] = measure q[0];
+    c[1] = measure q[1];
+    """
+)
+
+# Execute with the QDK sparse-state simulator
+executor = create("circuit_executor", "qdk_sparse_state_simulator")
+result = executor.run(circuit, shots=1000)
+print(f"Bitstring counts: {result.bitstring_counts}")
+print(f"Total shots: {result.total_shots}")
+# end-cell-run
+################################################################################
+
+################################################################################
+# start-cell-noise
+from qdk_chemistry.algorithms import create
+from qdk_chemistry.data import Circuit, QuantumErrorProfile
+
+circuit = Circuit(
+    qasm="""
+    include "stdgates.inc";
+    qubit[2] q;
+    bit[2] c;
+    x q[0];
+    cx q[0], q[1];
+    c[0] = measure q[0];
+    c[1] = measure q[1];
+    """
+)
+
+# Define a noise model
+noise_model = QuantumErrorProfile(
+    name="depolarizing",
+    description="Simple depolarizing noise model",
+    errors={
+        "x": {"type": "depolarizing_error", "rate": 0.005, "num_qubits": 1},
+        "cx": {"type": "depolarizing_error", "rate": 0.007, "num_qubits": 2},
+    },
+)
+
+# Execute with noise
+executor = create("circuit_executor", "qdk_full_state_simulator", type="cpu")
+result = executor.run(circuit, shots=1000, noise=noise_model)
+print(f"Noisy bitstring counts: {result.bitstring_counts}")
+# end-cell-noise
+################################################################################
+
+################################################################################
+# start-cell-list-implementations
+from qdk_chemistry.algorithms import registry
+
+# List all registered circuit executor implementations
+implementations = registry.available("circuit_executor")
+print(
+    implementations
+)  # e.g. ['qdk_sparse_state_simulator', 'qdk_full_state_simulator', 'qiskit_aer_simulator']
+# end-cell-list-implementations
+################################################################################

docs/source/_static/examples/python/circuit_executor.py

@@ -0,0 +1,70 @@
+"""Controlled evolution circuit mapper usage examples."""
+
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+################################################################################
+# start-cell-create
+from qdk_chemistry.algorithms import create
+
+# Create the default mapper (pauli_sequence)
+mapper = create("controlled_evolution_circuit_mapper")
+# end-cell-create
+################################################################################
+
+################################################################################
+# start-cell-configure
+# Configure the power of the controlled unitary
+mapper = create("controlled_evolution_circuit_mapper", "pauli_sequence")
+mapper.settings().set("power", 4)
+# end-cell-configure
+################################################################################
+
+################################################################################
+# start-cell-run
+import numpy as np
+from qdk_chemistry.algorithms import create
+from qdk_chemistry.data import Structure
+
+# 1. Setup molecule
+coords = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.4]])
+symbols = ["H", "H"]
+structure = Structure(coords, symbols=symbols)
+
+# 2. SCF
+scf_solver = create("scf_solver")
+E_scf, wfn_scf = scf_solver.run(
+    structure, charge=0, spin_multiplicity=1, basis_or_guess="sto-3g"
+)
+
+# 3. Hamiltonian and qubit mapping
+hamiltonian_constructor = create("hamiltonian_constructor")
+hamiltonian = hamiltonian_constructor.run(wfn_scf.get_orbitals())
+qubit_mapper = create("qubit_mapper", encoding="jordan-wigner")
+qubit_ham = qubit_mapper.run(hamiltonian)
+
+# 4. Build time evolution unitary
+trotter = create("time_evolution_builder", "trotter", order=2)
+evolution = trotter.run(qubit_ham, time=0.1)
+
+# 5. Create a controlled version and map to a circuit
+from qdk_chemistry.data import ControlledTimeEvolutionUnitary
+
+controlled = ControlledTimeEvolutionUnitary(evolution, control_indices=[0])
+mapper = create("controlled_evolution_circuit_mapper", "pauli_sequence")
+circuit = mapper.run(controlled)
+print("Controlled evolution circuit generated")
+# end-cell-run
+################################################################################
+
+################################################################################
+# start-cell-list-implementations
+from qdk_chemistry.algorithms import registry
+
+# List all registered controlled evolution circuit mapper implementations
+implementations = registry.available("controlled_evolution_circuit_mapper")
+print(implementations)  # e.g. ['pauli_sequence']
+# end-cell-list-implementations
+################################################################################