--- title: Q-CTRL Dynamics Simulator API reference description: API reference for Q-CTRL Dynamics Simulator, including inputs, outputs, and configuration options source: https://quantum.cloud.ibm.com/docs/en/api/functions/q-ctrl-dynamics-simulator --- # Q-CTRL Dynamics Simulator API reference - [**Qiskit Functions**](/docs/guides/q-ctrl-dynamics-simulator) — 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. > **Caution** > > 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](#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](#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](#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](#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](#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.