Q-CTRL Dynamics Simulator API reference
Qiskit Functions — pre-built tools created by partner organizations — abstract away parts of the software development workflow to simplify and accelerate utility-scale algorithm discovery and application development. Click to view the guide for this Qiskit Function.
Q-CTRL Dynamics Simulator guide
Dynamics Simulator accepts a physical model description rather than circuits. Fire Opal builds and optimizes the circuits for the target backend, so do not transpile or pre-compile anything.
Inputs
See the following list for all input parameters that this API accepts. All inputs are passed as keyword arguments. model, simulation, and observables can each be given either as a Python dictionary (list of dictionaries for observables) or as a JSON string. The function rejects unknown top-level arguments.
model
Type: dict[str, Any] or str
The Fermi-Hubbard model, given as a dictionary or a JSON string. See Model fields for the fields it contains.
- Required: Yes
- Example:
{"hopping_amplitude": 1.0, "on_site_interaction": [2.0, 2.5, 2.0], "chemical_potential": 0.5}
Model fields
hopping_amplitude
Type: float or list[float]
Tunneling amplitude. A scalar is broadcast across all bonds. A list must have len(initial_state) - 1 entries (one per bond).
on_site_interaction
Type: float or list[float]
On-site interaction strength. A scalar is broadcast across all sites. A list must have len(initial_state) entries (one per site).
chemical_potential
Type: float or list[float]
Chemical potential. A scalar is broadcast across all sites. A list must have len(initial_state) entries (one per site).
simulation
Type: dict[str, Any] or str
The Trotter simulation scheme, given as a dictionary or a JSON string. See Simulation fields for the fields it contains.
- Required: Yes
- Example:
{"method": "trotter", "step_count": 5, "time_step": 0.1}
Simulation fields
method
Type: str
Simulation method. "trotter" is the supported method.
- Choices:
trotter
step_count
Type: int
Number of Trotter steps.
time_step
Type: float
Duration of each Trotter step.
observables
Type: list[dict[str, Any]] or str
The sparse occupation operators to measure, one dictionary per observable, given as a list of dictionaries or a JSON string. Must contain at least one observable. See Observable fields for the fields each dictionary contains.
- Required: Yes
- Example:
[{"operators": [[["Nup", 0]]], "coefficients": [1.0]}]
Observable fields
operators
Type: list[list[list[str, int]]]
The terms of the observable. Each term is a product of [operator_name, site_index] pairs, where operator_name is "Nup" or "Ndn".
coefficients
Type: list[float]
One coefficient per term in operators.
initial_state
Type: str
The initial Fock state, with one character per lattice site. Must be non-empty. The number of lattice sites is len(initial_state), and the simulation uses 2 * len(initial_state) qubits. The backend must have at least that many qubits.
- Required: Yes
- Allowed characters:
"e": (empty) unoccupied site"u": (up) singly occupied, spin up"d": (down) singly occupied, spin down"b": (both) doubly occupied
- Example:
"udb"
shots
Type: int
The number of shots to use for each circuit execution. Must be a positive integer.
- Required: Yes
- Example:
1000
backend_name
Type: str
Default value: Automatic selection
Name of the backend to use. If you don't provide a name, the function automatically selects a backend with enough qubits.
- Required: No
- Example:
"ibm_phoenix"
Options
Type: dict
Default value: {}
Additional run options, passed as options. Options are specified as a nested dictionary. See the options list for details and default values.
- Required: No
- Example:
{"job_tags": ["my_tag"]}
Options list
session_id
Type: str
Default value: ""
An existing IBM Quantum Compute Service session ID.
- Example:
"cw4r3je6f0t010870y3g"
job_tags
Type: list[str]
Default value: []
A list of job tags.
- Example:
["job_tag1", "job_tag2"]
Outputs
The output of this API is a dict that contains the simulation results and metadata. The results include the expectation values of the requested observables at every time step of the Trotterized time evolution.
Type: dict[str, Any]
The simulation results and metadata listed under Output structure.
- Example:
{"observable_expectation_values": [ [1.0, 0.96, 0.91],[0.0, 0.04, 0.08]], "observables": [{"operators": [[["Nup", 0]]],"coefficients": [1.0]}], "warnings": [], "metadata": {}}
Output structure
observable_expectation_values
Type: list[list[float]]
Expectation values, one list per input observable, in the same order as observables. Each list contains step_count + 1 values, including the initial state.
observables
Type: list[dict[str, Any]]
The observables that were measured, echoed back from the input.
warnings
Type: list[str]
Warnings produced while compiling or running the simulation.
metadata
resource_usage
Type: dict
A breakdown of CPU and QPU time (in seconds) for each stage of the run. Each stage has a CPU_TIME and a QPU_TIME.
RUNNING: MAPPING
Type: dict
Mapping the problem to the device.
RUNNING: OPTIMIZING_HARDWARE
Type: dict
Optimizing the circuits for the hardware.
RUNNING: WAITING_QPU
Type: dict
Time spent waiting on the QPU queue (CPU time).
RUNNING: EXECUTING_QPU
Type: dict
Time executing on the QPU (QPU time).
RUNNING: POST_PROCESSING
Type: dict
Post-processing of results.