Skip to content
Q-Alchemy Docs

Options

The SDK supports passing advanced options to the core initialization algorithm so you can control method selection, output format, and method-specific optimization parameters.

Arguments

Section titled “Arguments”
  • state or state_vector or params: the input state vector. Can be provided as a list, a numpy ndarray, a sparse sparray, or (for Qiskit) a Statevector object.
  • opt_params: all other arguments are passed as keyword arguments, either as a dict or as an OptParams object.

Options

Section titled “Options”

The OptParams object currently supports the following fields:

  • min_fidelity: the minimum fidelity desired. Internally, Q-Alchemy uses the corresponding maximum fidelity loss (1 - min_fidelity) when selecting or configuring approximation methods. Looser fidelity targets can produce shallower circuits.
  • basis_gates: the basis gates used for transpilation/output of the resulting circuit.
  • api_key: your Q-Alchemy API key. Can also be provided via the Q_ALCHEMY_API_KEY environment variable. Keep it safe!
  • options: an InitializeOptions object containing method selection and output settings.
  • initialization_method: the initialization method to use. Defaults to InitializeMethods.AUTO. Available values are:
  • InitializeMethods.AUTO: uses Q-Alchemy’s heuristic strategy to choose an initialization approach based on the input state and fidelity target. Depending on the case, it may use a product-state style solution, Iterative Tucker, Hierarchical Tucker, or fallback alternatives.
  • InitializeMethods.ITERATIVE_TUCKER: explicitly uses the iterative Tucker-based initializer.
  • InitializeMethods.HIERARCHICAL_TUCKER: explicitly uses the hierarchical Tucker-based initializer.
  • InitializeMethods.SWAP_PIVOT: explicitly uses the swap-pivot initializer.
  • InitializeMethods.BAA_LOW_RANK: explicitly uses the BAA low-rank initializer.
  • use_qasm3: experimental: if True, QASM output is generated in QASM 3 format. Defaults to False. This option is ignored by QPY output methods.
  • extra_kwargs: a JSON string containing method-specific options. Defaults to "{}".

Method-specific options

Section titled “Method-specific options”

Method-specific options are passed inside extra_kwargs as a keyword dictionary. For example: extra_kwargs='{"max_iterations": 10, "factors_size": 4}';

If you are constructing the options programmatically, make sure extra_kwargs is serialized as valid JSON before passing it to the SDK, e.g. extra_kwargs=json.dumps(dict(max_iterations=10, factors_size=4))

Iterative Tucker options

Section titled “Iterative Tucker options”

The following keys are supported by the Iterative Tucker initializer through extra_kwargs:

  • max_fidelity_loss: maximum allowed fidelity loss for approximation. If omitted or invalid, defaults to 0.0.
  • max_iterations: maximum number of iterations. If not provided or set to a non-positive value, a value is chosen automatically based on the number of qubits.
  • factors_size: initial Tucker factor size. If omitted or outside the valid range, automatic sizing is used.
  • max_stepup: maximum allowed increase in factor size if a stall is detected. Defaults to 0.
  • logical_swaps: if True, the algorithm first tries a logical qubit reordering to improve grouping. Defaults to False.
  • fallback: if True, allows fallback behavior when the iterative search does not find an acceptable solution. Defaults to True.
  • perturbation: controls what happens when the partition search stagnates. Supported values include:
  • "shift": cyclically shifts qubits in the partition.
  • "random": selects a random partition.
  • "bump": tries a larger factor size.

The current default is null / omitted, which means no perturbation is applied.

  • geometric_entanglement: optional geometric-entanglement hint used by some fallback paths. If omitted or outside [0, 1], defaults to 0.0.
  • check_normalization: if True, checks whether the input state is normalized before proceeding. Defaults to True.
  • barriers: if True, inserts barriers between iterative layers for debugging or benchmarking. For best transpilation results, disable or remove these barriers in production. Defaults to False.

Notes on AUTO

Section titled “Notes on AUTO”

InitializeMethods.AUTO is a heuristic dispatcher, not a fixed linear fallback chain. In the current implementation, it analyzes the state and may choose among different strategies depending on quantities such as geometric entanglement, sparsity, qubit count, and fidelity target. It may try Iterative Tucker, Hierarchical Tucker, or specialized fallback behavior, and then keep the better circuit according to an internal cost comparison.