Q-CTRL Dynamics Simulator API reference
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
タイプ: 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
タイプ: 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
タイプ: 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
タイプ: 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
タイプ: 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
タイプ: str
Simulation method. "trotter" is the supported method.
- Choices:
trotter
step_count
タイプ: int
Number of Trotter steps.
time_step
タイプ: float
Duration of each Trotter step.
observables
タイプ: 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
タイプ: 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
タイプ: list[float]
One coefficient per term in operators.
initial_state
タイプ: 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
タイプ: int
The number of shots to use for each circuit execution. Must be a positive integer.
- Required: Yes
- Example:
1000
backend_name
タイプ: str
デフォルト値: 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"
function_size
タイプ: str
デフォルト値: "M"
Size the job runs at: "S", "M", or "L". The required size depends on the number of qubits (two per lattice site), the number of Trotter steps, and the number of observables: up to 20 qubits, 10 steps, and 20 observables is "S", up to 50 qubits, 20 steps, and 50 observables is "M", and anything larger is "L". To calculate the size before you submit a job, see Function sizes. If the size is too small, the job fails with error 4600. If the size is larger than the job needs, the job runs normally and records a 4601 advisory event.
- Required: No
- Example:
"L"
Options
タイプ: dict
デフォルト値: {}
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
タイプ: str
デフォルト値: ""
An existing IBM Quantum Compute Service session ID.
- Example:
"cw4r3je6f0t010870y3g"
job_tags
タイプ: list[str]
デフォルト値: []
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.
タイプ: 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
タイプ: 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
タイプ: list[dict[str, Any]]
The observables that were measured, echoed back from the input.
warnings
タイプ: list[str]
Warnings produced while compiling or running the simulation.
metadata
resource_usage
タイプ: 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
タイプ: dict
Mapping the problem to the device.
RUNNING: OPTIMIZING_HARDWARE
タイプ: dict
Optimizing the circuits for the hardware.
RUNNING: WAITING_QPU
タイプ: dict
Time spent waiting on the QPU queue (CPU time).
RUNNING: EXECUTING_QPU
タイプ: dict
Time executing on the QPU (QPU time).
RUNNING: POST_PROCESSING
タイプ: dict
Post-processing of results.
Error handling
The function reports the following errors that relate to function_size. For all error codes, see the IBM Quantum error codes.
Code | Cause |
|---|---|
4600 | The function_size is too small for the workload. The job fails, and the message names the size to use. |
4601 | The function_size is larger than the workload needs. The job runs normally and records an advisory event that you can read with job.events(). |