Hamiltonian simulation ====================== The :class:`~qdk_chemistry.algorithms.time_evolution.hamiltonian_simulation.base.HamiltonianSimulation` algorithm in QDK/Chemistry simulates the time evolution of a quantum system under a time-dependent Hamiltonian and measures observable expectation values. Following QDK/Chemistry's :doc:`algorithm design principles <../design/index>`, it takes a :class:`~qdk_chemistry.data.TimeDependentQubitHamiltonian`, a list of observable :class:`~qdk_chemistry.data.QubitOperator` operators, and a state-preparation :class:`~qdk_chemistry.data.Circuit` as input and returns a list of :class:`~qdk_chemistry.data.EnergyExpectationResult` and :class:`~qdk_chemistry.data.MeasurementData` pairs. Overview -------- Hamiltonian simulation solves the time-dependent Schrödinger equation :math:`i\,\partial_t U = H(t)\,U` on a quantum computer. For a Hamiltonian that changes with time — for example, a molecule driven by a laser pulse — the algorithm constructs a quantum circuit for the full evolution and then executes it to measure observable expectation values. Circuit construction is delegated to an :doc:`EvolutionCircuitBuilder `, which handles time-stepping, propagation, and circuit-to-gates mapping. The simulation algorithm adds circuit execution and observable measurement on top. For resource estimation (without circuit execution), use the :doc:`EvolutionCircuitBuilder ` directly. Using the HamiltonianSimulation ------------------------------- .. note:: This algorithm is currently available only in the Python API. This section demonstrates how to create, configure, and run a Hamiltonian simulation. The ``run`` method returns a list of tuples containing :class:`~qdk_chemistry.data.EnergyExpectationResult` and :class:`~qdk_chemistry.data.MeasurementData` objects — one per observable. Input requirements ~~~~~~~~~~~~~~~~~~ The :class:`~qdk_chemistry.algorithms.time_evolution.hamiltonian_simulation.base.HamiltonianSimulation` requires the following inputs: TimeDependentQubitHamiltonian A :class:`~qdk_chemistry.data.TimeDependentQubitHamiltonian` describing how the Hamiltonian varies with time. Observables A list of :class:`~qdk_chemistry.data.QubitOperator` operators to measure after evolution. Each observable must have the same number of qubits as the Hamiltonian. State preparation circuit A :class:`~qdk_chemistry.data.Circuit` that prepares the initial state before time evolution. This is typically generated by the :doc:`StatePreparation ` algorithm from a :class:`~qdk_chemistry.data.Wavefunction`. .. rubric:: Creating a simulation algorithm .. tab:: Python API .. literalinclude:: ../../../_static/examples/python/hamiltonian_simulation.py :language: python :start-after: # start-cell-create :end-before: # end-cell-create .. rubric:: Configuring settings Settings vary by implementation. See `Available implementations`_ below for implementation-specific options. .. tab:: Python API .. literalinclude:: ../../../_static/examples/python/hamiltonian_simulation.py :language: python :start-after: # start-cell-configure :end-before: # end-cell-configure .. rubric:: Running the simulation .. tab:: Python API .. literalinclude:: ../../../_static/examples/python/hamiltonian_simulation.py :language: python :start-after: # start-cell-run :end-before: # end-cell-run Available implementations ------------------------- QDK/Chemistry's :class:`~qdk_chemistry.algorithms.time_evolution.hamiltonian_simulation.base.HamiltonianSimulation` provides a unified interface for time-dependent simulation methods. You can discover available implementations programmatically: .. tab:: Python API .. literalinclude:: ../../../_static/examples/python/hamiltonian_simulation.py :language: python :start-after: # start-cell-list-implementations :end-before: # end-cell-list-implementations Euler integrator ~~~~~~~~~~~~~~~~ .. rubric:: Factory name: ``"euler_integrator"`` The Euler integrator delegates circuit construction to an :doc:`EulerEvolutionCircuitBuilder `, then executes the resulting circuit and measures each observable independently using the configured expectation estimator. The circuit builder handles all time-stepping, propagation, and circuit mapping. See :doc:`EvolutionCircuitBuilder ` for details on how the evolution circuit is constructed. .. rubric:: Settings Direct settings on :class:`~qdk_chemistry.algorithms.time_evolution.hamiltonian_simulation.base.HamiltonianSimulationSettings`: .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Setting - Type - Description * - ``evolution_circuit_builder`` - :class:`~qdk_chemistry.data.AlgorithmRef` - Evolution circuit builder used to construct the state-prep + evolution circuit. Default: :class:`~qdk_chemistry.data.AlgorithmRef` to ``"evolution_circuit_builder"`` with method ``"euler"``. * - ``circuit_executor`` - :class:`~qdk_chemistry.data.AlgorithmRef` - Circuit executor used to run quantum circuits. Default: :class:`~qdk_chemistry.data.AlgorithmRef` to ``"circuit_executor"`` with method ``"qdk_sparse_state_simulator"``. * - ``observable_estimator`` - :class:`~qdk_chemistry.data.AlgorithmRef` - Estimator used to compute observable expectation values. Default: :class:`~qdk_chemistry.data.AlgorithmRef` to ``"expectation_estimator"`` with method ``"qdk"``. Nested algorithm configuration (via ``evolution_circuit_builder``): See :doc:`EvolutionCircuitBuilder ` for configuring: - ``total_time`` — Total evolution time - ``dt`` — Time step size - ``propagator`` — Propagator for computing effective Hamiltonians - ``evolution_builder`` — Unitary builder (e.g., Trotter) - ``circuit_mapper`` — Circuit compilation strategy Related classes --------------- - :class:`~qdk_chemistry.data.TimeDependentQubitHamiltonian`: Input time-dependent Hamiltonian - :class:`~qdk_chemistry.data.QubitOperator`: Observable operators - :class:`~qdk_chemistry.data.Circuit`: State-preparation circuit and output evolution circuit - :class:`~qdk_chemistry.data.EnergyExpectationResult`: Output energy expectation values - :class:`~qdk_chemistry.data.MeasurementData`: Output measurement data - :class:`~qdk_chemistry.algorithms.time_evolution.evolution_circuit_builder.base.EvolutionCircuitBuilder`: Constructs the evolution circuit Further reading --------------- - The above examples can be downloaded as a complete `Python <../../../_static/examples/python/hamiltonian_simulation.py>`_ script. - :doc:`EvolutionCircuitBuilder `: Time-evolution circuit composition - :doc:`Propagator `: Effective Hamiltonians for time-dependent evolution - :doc:`HamiltonianUnitaryBuilder `: Constructs the time-evolution unitary from the effective Hamiltonian - :doc:`ExpectationEstimator `: Observable expectation value estimation - :doc:`CircuitExecutor `: Quantum circuit execution backends - :doc:`Settings `: Configuration settings for algorithms - :doc:`Factory Pattern `: Understanding algorithm creation