Introduction

Start with the free service

Create an account in the Q-Alchemy Portal. The free service includes state preparation up to 12 qubits and simulator access with 4 MB RAM. Compare free, platform, and OEM access. For larger workloads, discuss business access with us.

This guide prepares a small, two-qubit Bell state. It needs no dataset download or quantum hardware: the service builds the preparation circuit, and you can check it locally.

Install the SDK

Use Python 3.11–3.14 in a virtual environment. These commands install the SDK with the Qiskit integration used for local verification below.

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "q-alchemy-sdk-py[qiskit]"

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install "q-alchemy-sdk-py[qiskit]"

For the PennyLane example, also install python -m pip install "q-alchemy-sdk-py[pennylane]".

Set your API key

In the Portal, choose Settings → API Keys and create a key. Set it in the terminal where you will run Python:

macOS / Linux

export Q_ALCHEMY_API_KEY="your-api-key"

Windows PowerShell

$env:Q_ALCHEMY_API_KEY = "your-api-key"

Replace your-api-key with your key. Keep it out of source control. The examples below read it from the environment.

Prepare and verify your first state

Save this as first_state.py, then run python first_state.py in the same terminal. It submits a state-preparation job to Q-Alchemy and simulates the returned two-qubit circuit locally with Qiskit.

import os
import numpy as np
from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector, state_fidelity
from q_alchemy.initialize import q_alchemy_as_qasm

state = np.array([1, 0, 0, 1], dtype=complex) / np.sqrt(2)
qasm = q_alchemy_as_qasm(
    state,
    max_fidelity_loss=0.0,
    api_key=os.environ["Q_ALCHEMY_API_KEY"],
)
prep = QuantumCircuit.from_qasm_str(qasm)
fidelity = state_fidelity(Statevector.from_instruction(prep), Statevector(state))
print(f"Qubits: {prep.num_qubits}")
print(f"Local simulation fidelity: {fidelity:.6f}")
assert prep.num_qubits == 2
assert fidelity > 0.99, "Check the returned preparation before continuing."

The input has equal amplitudes for 00 and 11. You should see Qubits: 2 and a local simulation fidelity close to 1.000000; the assertions check that the example produced a suitable result. Equivalent preparation circuits can have different gate sequences.

If Python reports KeyError: 'Q_ALCHEMY_API_KEY', set the key in the same terminal. For authentication errors, check your Portal key. For missing modules, activate the virtual environment and install the integration above.

Choose your integration

Each example below is complete after installation and API-key setup. All use the same normalized input.

OpenQASM

import os
import numpy as np
from q_alchemy.initialize import q_alchemy_as_qasm

state = np.array([1, 0, 0, 1], dtype=complex) / np.sqrt(2)
qasm, summary = q_alchemy_as_qasm(
    state,
    max_fidelity_loss=0.0,
    api_key=os.environ["Q_ALCHEMY_API_KEY"],
    return_summary=True,
)
print(qasm)
print(summary)

Qiskit

import os
import numpy as np
from qiskit.quantum_info import Statevector, state_fidelity
from q_alchemy.qiskit_integration import QAlchemyInitialize, OptParams

state = np.array([1, 0, 0, 1], dtype=complex) / np.sqrt(2)
prep = QAlchemyInitialize(
    params=state.tolist(),
    opt_params=OptParams(
        max_fidelity_loss=0.0,
        api_key=os.environ["Q_ALCHEMY_API_KEY"],
    ),
).definition
print(prep.draw(output="text"))
fidelity = state_fidelity(Statevector.from_instruction(prep), Statevector(state))
print(f"Local simulation fidelity: {fidelity:.6f}")

PennyLane

import os
import numpy as np
import pennylane as qml
from q_alchemy.pennylane_integration import QAlchemyStatePreparation, OptParams

state = np.array([1, 0, 0, 1], dtype=complex) / np.sqrt(2)
dev = qml.device("default.qubit", wires=2)

@qml.qnode(dev)
def circuit():
    QAlchemyStatePreparation(
        state,
        wires=[0, 1],
        opt_params=OptParams(
            max_fidelity_loss=0.0,
            api_key=os.environ["Q_ALCHEMY_API_KEY"],
        ),
    )
    return qml.probs(wires=[0, 1])

print(circuit())  # Expected approximately [0.5, 0.0, 0.0, 0.5]

The PennyLane example asks Q-Alchemy to synthesize the preparation and executes that circuit on a local default.qubit simulator. It does not submit a hardware job.

Next steps

• Python SDK: integrations, batching, and the hosted sparse simulator.
• Options: preparation methods, output formats, and method-specific controls.
• Algorithm: how state preparation works and how to interpret its results.
• Feasibility Suite: assess a wider workload with your resource and quality targets.

For a guided introduction, request a demo. Advanced integrations can use the REST API reference, built on PineXQ.