Options

The SDK lets you pass advanced options to the state preparation algorithm, so you can choose the method, the output format, and method-specific tuning parameters.

Arguments

• state, state_vector or params: the input state vector. It can be a list, a numpy ndarray, a scipy sparse sparray, or (for Qiskit) a Statevector.
• opt_params: every other setting, as an OptParams object or a plain dict with the same keys. q_alchemy_as_qasm also accepts them as keyword arguments.

Options

The OptParams object (from q_alchemy.initialize, also re-exported by the Qiskit and PennyLane integrations) supports these fields:

• max_fidelity_loss: how much fidelity you are willing to give up for a shallower circuit. Defaults to 0.0, an exact preparation. The SDK sends this to the service as min_fidelity = 1 - max_fidelity_loss.
• basis_gates: the gate set the returned circuit is transpiled to. Defaults to ["u", "cx"].
• api_key: your Q-Alchemy API key. Defaults to the Q_ALCHEMY_API_KEY environment variable. Keep it safe!
• initialization_method: the algorithm to use, from InitializationMethods. Defaults to InitializationMethods.AUTO. The available values are:
  • InitializationMethods.AUTO: runs several Tucker candidates (iterative and hierarchical, as resources allow) at your fidelity budget and keeps the cheapest realized circuit. Trivial inputs such as single-qubit and single-basis states take an exact fast path.
  • InitializationMethods.ITERATIVE_TUCKER: the iterative Tucker initializer.
  • InitializationMethods.HIERARCHICAL_TUCKER: the hierarchical Tucker initializer.
  • InitializationMethods.SWAP_PIVOT: the swap-pivot initializer, suited to very sparse states.
  • InitializationMethods.BAA_LOW_RANK: the BAA low-rank initializer. It is limited to 12 qubits.
• use_qasm3: experimental. If True, the circuit is returned as OpenQASM 3 instead of OpenQASM 2. Defaults to False.
• extra_kwargs: method-specific options, as a dict. Defaults to {}.
• remove_data: delete the job and its uploaded data once the result has been fetched. Defaults to True.
• job_completion_timeout_sec: how long to wait for the job before giving up. Defaults to 300.

Method-specific options

Method-specific options go in extra_kwargs as a plain dict. The SDK serializes it for you:

from q_alchemy.initialize import OptParams, InitializationMethods

opt_params = OptParams(
    max_fidelity_loss=0.05,
    initialization_method=InitializationMethods.ITERATIVE_TUCKER,
    extra_kwargs={"max_iterations": 10, "factors_size": 4},
)

Caution

Options are validated per method. A key the chosen method does not accept fails the job with Could not build the initialization circuit: ... instead of being silently ignored. In particular, the iterative Tucker keys are not valid under AUTO: pin the method to use them.

AUTO options

• cost_function: how the candidates are ranked. Defaults to "cx_then_depth". The other values are "depth_then_cx", "two_qubit_then_depth", "cx+depth", "cx" and "depth".
• basis_gates: the gate set used to compare candidates. Defaults to ["u", "cx"]. This is separate from the top-level basis_gates (see below).
• transpile_optimization_level: the Qiskit optimization level used when comparing candidates. Defaults to 1.
• seed_transpiler: the transpiler seed, for reproducible comparisons. Defaults to 0.
• dominant_basis_fast_path: a zero-CNOT shortcut for states dominated by a single basis state. Defaults to True.
• fidelity_tolerance: the numerical slack allowed on the fidelity budget.
• geometric_entanglement: an optional geometric-entanglement hint in [0, 1].
• check_normalization: whether to check that the input state is normalized. Defaults to True.

Iterative Tucker options

These apply only with initialization_method=InitializationMethods.ITERATIVE_TUCKER:

• max_iterations: the maximum number of iterations. If omitted or not positive, a value is chosen from the number of qubits.
• factors_size: the initial Tucker factor size. If omitted, 0, or outside the valid range, it is sized automatically.
• max_stepup: the maximum allowed increase in factor size when the search stalls. Defaults to 0.
• fallback: allow fallback behavior when the iterative search does not find an acceptable solution. Defaults to True.
• perturbation: what to do when the partition search stagnates. Defaults to None, meaning no perturbation.
• geometric_entanglement: an optional geometric-entanglement hint used by some fallback paths. If omitted or outside [0, 1], it defaults to 0.0.
• check_normalization: whether to check that the input state is normalized. Defaults to True.
• barriers: insert barriers between iterative layers, for debugging or benchmarking. They hurt transpilation, so leave this off in production. Defaults to False.

Other methods

• HIERARCHICAL_TUCKER: geometric_entanglement and check_normalization.
• SWAP_PIVOT: aux.
• BAA_LOW_RANK: strategy (defaults to "greedy"), use_low_rank (defaults to True), max_combination_size, iso_scheme and unitary_scheme.

Things to know

• Set the fidelity with max_fidelity_loss on OptParams, not in extra_kwargs. Every method also accepts max_fidelity_loss inside extra_kwargs, but if you put it there it silently overrides the top-level value.
• Under AUTO, the top-level basis_gates only affects the final transpilation. Candidates are compared on u/cx cost unless you also pass extra_kwargs={"basis_gates": [...]}.
• AUTO is a portfolio, not a fixed fallback chain. The candidates it tries depend on the qubit count and sparsity of your state, so the method reported in the result summary can differ between inputs.