Generalize TimeEvolutionUnitary and related builders to Unitary#448
Open
YingrongChen wants to merge 23 commits intomainfrom
Open
Generalize TimeEvolutionUnitary and related builders to Unitary#448YingrongChen wants to merge 23 commits intomainfrom
TimeEvolutionUnitary and related builders to Unitary#448YingrongChen wants to merge 23 commits intomainfrom
Conversation
📊 Coverage Summary
Detailed Coverage ReportsC++ Coverage DetailsPython Coverage DetailsPybind11 Coverage Details |
…n_unitary/builder/base.py
…e.py to hamiltonian_unitary/
…n.py to data/hamiltonian_unitary/
YingrongChen
requested review from
ConradJohnston,
nabbelbabbel and
wavefunction91
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR generalizes the codebase’s Hamiltonian-simulation/time-evolution abstractions into broader unitary abstractions (data model + algorithm interfaces), updating registries, docs, examples, and tests to use the new names and factory keys.
Changes:
- Renames time-evolution data classes/containers to
UnitaryRepresentation/UnitaryContainerand updates controlled-unitary handling toControlledUnitary. - Renames algorithm interfaces and factory keys to
HamiltonianUnitaryBuilderandControlledCircuitMapper, updating phase estimation to consume the generalized interfaces. - Updates Python tests, documentation, and example notebooks/scripts to the new import paths and registry keys.
Reviewed changes
Copilot reviewed 49 out of 50 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| python/tests/test_trotter_error.py | Updates imports to new hamiltonian_unitary path. |
| python/tests/test_time_evolution_trotter.py | Migrates tests to UnitaryRepresentation and new module paths. |
| python/tests/test_time_evolution_qdrift.py | Updates registry keys and expected types to new unitary abstractions. |
| python/tests/test_time_evolution_partially_randomized.py | Updates registry keys, imports, and expected unitary types. |
| python/tests/test_time_evolution_container.py | Updates container import path. |
| python/tests/test_time_evolution_circuit_mapper.py | Migrates controlled-unitary mapping tests to ControlledUnitary. |
| python/tests/test_phase_estimation_iterative.py | Updates QPE wiring to unitary_builder/controlled_circuit_mapper parameters and new registry keys. |
| python/tests/test_interop_qiskit_phase_estimation_standard.py | Updates Qiskit interop test wiring to the new keys/parameter names. |
| python/tests/test_controlled_time_evolution.py | Renames mock types/tests to ControlledUnitary / UnitaryContainer / UnitaryRepresentation. |
| python/tests/test_algorithms_registry.py | Updates expected default algorithm type names for the registry. |
| python/src/qdk_chemistry/plugins/qiskit/standard_phase_estimation.py | Migrates standard QPE plugin to new builder/mapper types and controlled-unitary data class. |
| python/src/qdk_chemistry/data/time_evolution/controlled_time_evolution.py | Removes old ControlledTimeEvolutionUnitary module (superseded by new unitary module). |
| python/src/qdk_chemistry/data/hamiltonian_unitary/controlled_time_evolution.py | Adds ControlledUnitary implementation and serialization under new unitary package. |
| python/src/qdk_chemistry/data/hamiltonian_unitary/containers/pauli_product_formula.py | Updates container base class to UnitaryContainer and refreshes docstrings. |
| python/src/qdk_chemistry/data/hamiltonian_unitary/containers/base.py | Renames/repurposes abstract container base to UnitaryContainer. |
| python/src/qdk_chemistry/data/hamiltonian_unitary/containers/init.py | Updates module docs for Hamiltonian unitary containers. |
| python/src/qdk_chemistry/data/hamiltonian_unitary/base.py | Introduces UnitaryRepresentation replacing TimeEvolutionUnitary. |
| python/src/qdk_chemistry/data/hamiltonian_unitary/init.py | Updates module docs for Hamiltonian unitary data package. |
| python/src/qdk_chemistry/data/init.py | Re-exports new unitary types and removes time-evolution exports. |
| python/src/qdk_chemistry/algorithms/time_evolution/controlled_circuit_mapper/base.py | Removes old controlled-evolution circuit mapper base (superseded by new mapper base). |
| python/src/qdk_chemistry/algorithms/registry.py | Registers new factories/algorithms for the renamed unitary builder and controlled circuit mapper. |
| python/src/qdk_chemistry/algorithms/phase_estimation/base.py | Updates phase estimation base to consume generalized unitary builder + controlled circuit mapper. |
| python/src/qdk_chemistry/algorithms/phase_estimation/iterative_phase_estimation.py | Updates IQPE implementation to use the generalized unitary builder/mapper interfaces. |
| python/src/qdk_chemistry/algorithms/phase_estimation/init.py | Updates module documentation wording from time-evolution to unitary. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/controlled_circuit_mapper/base.py | Adds generalized controlled circuit mapper base/factory with new registry key. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/controlled_circuit_mapper/pauli_sequence_mapper.py | Migrates Pauli-sequence mapper to ControlledUnitary and new mapper base/type name. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/controlled_circuit_mapper/init.py | Updates exports to new controlled circuit mapper factory name. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/builder/base.py | Introduces HamiltonianUnitaryBuilder + factory, keeps TimeEvolutionBuilder subclass for time-based builders. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/builder/trotter_error.py | Adds/relocates Trotter error-bound utilities under the new unitary builder package. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/builder/trotter.py | Migrates Trotter builder to return UnitaryRepresentation and new type name. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/builder/qdrift.py | Migrates qDRIFT builder to return UnitaryRepresentation and new type name. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/builder/partially_randomized.py | Migrates partially randomized builder to return UnitaryRepresentation and new type name. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/builder/init.py | Updates exports to new HamiltonianUnitaryBuilderFactory. |
| python/src/qdk_chemistry/algorithms/hamiltonian_unitary/init.py | Updates module documentation wording for the renamed package. |
| python/src/qdk_chemistry/algorithms/init.py | Exposes new builder/mapper base types and removes old time-evolution exports. |
| examples/qpe_stretched_n2.ipynb | Updates example wiring to new registry keys and parameter name unitary_builder. |
| examples/interoperability/qiskit/iqpe_trotter.py | Updates interop example to use new keys/parameter names. |
| examples/interoperability/qiskit/iqpe_model_hamiltonian.py | Updates interop example to use new keys/parameter names. |
| examples/factory_list.ipynb | Updates notebook but also changes stored outputs/metadata; includes new registry-related output content. |
| examples/extended_hubbard.ipynb | Updates example wiring to new registry keys and unitary_builder parameter. |
| docs/source/user/features.rst | Updates docs link to the renamed builder documentation. |
| docs/source/user/comprehensive/data/qpe_result.rst | Updates “Further reading” references to renamed builder doc. |
| docs/source/user/comprehensive/algorithms/phase_estimation.rst | Updates phase estimation documentation terminology and class references to new unitary abstractions. |
| docs/source/user/comprehensive/algorithms/index.rst | Updates algorithm index entries and type signatures to new names. |
| docs/source/user/comprehensive/algorithms/hamiltonian_unitary_builder.rst | Renames and rewrites builder docs for generalized Hamiltonian-unitary builder. |
| docs/source/user/comprehensive/algorithms/circuit_mapper.rst | Renames controlled evolution circuit mapper docs to controlled circuit mapper and updates references. |
| docs/source/_static/examples/python/release_notes_v1_1.py | Updates sample imports to new package paths. |
| docs/source/_static/examples/python/phase_estimation.py | Updates example wiring to new registry keys/parameter names. |
| docs/source/_static/examples/python/hamiltonian_unitary_builder.py | Updates example to new registry key and available() query key. |
| docs/source/_static/examples/python/circuit_mapper.py | Updates example to new mapper key and ControlledUnitary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Agent-Logs-Url: https://github.com/microsoft/qdk-chemistry/sessions/af236b7a-4f73-4db4-8b82-779d69d8618e Co-authored-by: YingrongChen <80119927+YingrongChen@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 49 out of 50 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (1)
python/src/qdk_chemistry/data/init.py:1
- These imports assume the new
qdk_chemistry.data.hamiltonian_unitary.{base,containers.*}modules exist. In this diff,UnitaryRepresentationandUnitaryContainerare implemented underqdk_chemistry.data.time_evolution.*(renamed in-place), but onlycontrolled_unitary.pyis added underdata/hamiltonian_unitary/. This will raiseModuleNotFoundErrorat import time. Fix by either (mandatory): (a) moving/addingbase.pyandcontainers/*intopython/src/qdk_chemistry/data/hamiltonian_unitary/to match these imports, or (b) reverting these imports toqdk_chemistry.data.time_evolution.*until the directory rename is complete.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR renames and generalizes the time-evolution-specific abstractions to broader "unitary" abstractions, preparing the codebase to support methods beyond Hamiltonian simulation. Scope of changes include documentation, example, python source and tests.
Rename Table
TimeEvolutionUnitaryUnitaryRepresentationTimeEvolutionUnitaryContainerUnitaryContainerControlledTimeEvolutionUnitaryControlledUnitaryTimeEvolutionBuilderHamiltonianUnitaryBuilderTimeEvolutionBuilderFactoryHamiltonianUnitaryBuilderFactoryControlledEvolutionCircuitMapperControlledCircuitMapperControlledEvolutionCircuitMapperFactoryControlledCircuitMapperFactorytime_evolution/hamiltonian_unitary/algorithms/anddata/)"time_evolution_builder""hamiltonian_unitary_builder""controlled_evolution_circuit_mapper""controlled_circuit_mapper"evolution_builderunitary_builderKey Design Changes
TimeEvolutionBuilderpreserved as subclass: The oldTimeEvolutionBuildernow extendsHamiltonianUnitaryBuilder, keeping thetimeparameter in its_run_implsignature. Existing Trotter/qDRIFT/PartiallyRandomized builders still inherit from it. Phase estimation dispatchesevolution_timefrom settings automatically when the builder is aTimeEvolutionBuilderinstance.Planned update: In the next PR, time will be added to the
TimeEvolutionBuildersettings. The_run_implmethod could also accept a power parameter from QPE to determine how to construct the powered Hamiltonian unitary.