qdk_chemistry.migrate package

Migrate serialized data files across serialization-schema versions.

Each qdk-chemistry data class versions its serialization schema independently, and its deserializer accepts only the version the installed library was built against. Loading a file written against an older version of that class’s schema raises an error; use this module to upgrade such a file to the version the library accepts.

Command line:

python -m qdk_chemistry.migrate OLD_FILE NEW_FILE

Python:

from qdk_chemistry import migrate
migrate.convert_file("old.hamiltonian.json", "new.hamiltonian.h5")

The data type is taken from the name.type.ext filename convention (orbitals / hamiltonian / wavefunction / ansatz) and the serialization format from the file extension (.json or .h5 / .hdf5). Input and output formats may differ.

Migration is keyed point-by-point on each data class’s serialization version, not on a library release: every migratable type exposes a STEPS table mapping a source version to a (next_version, transform) pair, and the chain is followed until it reaches the version the installed library accepts. To support a future serialization-version bump for a data class, register the next step in that type’s STEPS table (_orbitals/_hamiltonian/_wavefunction); the migrated document is validated against the live deserializer, so a missing step fails loudly.

This module lives outside the data classes so that no legacy-schema knowledge leaks into the core serialization.

exception qdk_chemistry.migrate.MigrationError

Bases: RuntimeError

Raised when a file cannot be migrated to the current serialization version.

qdk_chemistry.migrate.convert_file(src, dst)

Migrate a single data file to the serialization version the library accepts.

Return type:

Path

Parameters:

• src (str | Path) – Path to the file to read (format inferred from its extension).

• dst (str | Path) – Path to write the migrated file (format inferred from its extension).

Returns:

The dst path as a pathlib.Path.

Raises:

MigrationError – If the data type/format cannot be determined, the source and destination are the same file, the file is already at the current serialization version, or the migration fails.

Submodules

• qdk_chemistry.migrate.__main__ module
  • MigrationError
  • convert_file()
  • main()
• qdk_chemistry.migrate._ansatz module
  • from_json_doc()
  • from_hdf5_file()
  • to_new_json()
• qdk_chemistry.migrate._hamiltonian module
  • from_json_doc()
  • from_hdf5_file()
  • from_hdf5_group()
  • to_new_json()
• qdk_chemistry.migrate._io module
  • migrate_doc()
  • detect_format()
  • detect_type()
  • read_matrix()
  • read_vector()
  • read_index_vector()
  • read_attr()
  • subgroup_to_json()
  • write_object()
• qdk_chemistry.migrate._orbitals module
  • BasisSet
    • BasisSet.__init__()
    • BasisSet.ao_extents()
    • BasisSet.ao_symmetries()
    • BasisSet.atomic_orbital_type_to_string()
    • BasisSet.basis_to_shell_index()
    • BasisSet.custom_ecp_name
    • BasisSet.custom_name
    • BasisSet.from_basis_name()
    • BasisSet.from_element_map()
    • BasisSet.from_file()
    • BasisSet.from_hdf5_file()
    • BasisSet.from_index_map()
    • BasisSet.from_json()
    • BasisSet.from_json_file()
    • BasisSet.get_angular_momentum()
    • BasisSet.get_atom_index_for_atomic_orbital()
    • BasisSet.get_atomic_orbital_indices_for_atom()
    • BasisSet.get_atomic_orbital_info()
    • BasisSet.get_atomic_orbital_type()
    • BasisSet.get_ecp_electrons()
    • BasisSet.get_ecp_name()
    • BasisSet.get_ecp_shell()
    • BasisSet.get_ecp_shell_indices_for_atom()
    • BasisSet.get_ecp_shell_indices_for_atom_and_orbital_type()
    • BasisSet.get_ecp_shell_indices_for_orbital_type()
    • BasisSet.get_ecp_shells()
    • BasisSet.get_ecp_shells_for_atom()
    • BasisSet.get_name()
    • BasisSet.get_num_atomic_orbitals()
    • BasisSet.get_num_atomic_orbitals_for_atom()
    • BasisSet.get_num_atomic_orbitals_for_orbital_type()
    • BasisSet.get_num_atoms()
    • BasisSet.get_num_ecp_shells()
    • BasisSet.get_num_orbitals_for_l()
    • BasisSet.get_num_shells()
    • BasisSet.get_shell()
    • BasisSet.get_shell_indices_for_atom()
    • BasisSet.get_shell_indices_for_atom_and_orbital_type()
    • BasisSet.get_shell_indices_for_orbital_type()
    • BasisSet.get_shells()
    • BasisSet.get_shells_for_atom()
    • BasisSet.get_structure()
    • BasisSet.get_summary()
    • BasisSet.get_supported_basis_set_names()
    • BasisSet.get_supported_elements_for_basis_set()
    • BasisSet.has_ecp_electrons()
    • BasisSet.has_ecp_shells()
    • BasisSet.has_structure()
    • BasisSet.l_to_orbital_type()
    • BasisSet.orbital_type_to_string()
    • BasisSet.string_to_atomic_orbital_type()
    • BasisSet.string_to_orbital_type()
    • BasisSet.to_file()
    • BasisSet.to_hdf5_file()
    • BasisSet.to_json()
    • BasisSet.to_json_file()
  • from_json_doc()
  • from_hdf5_group()
  • to_new_json()
• qdk_chemistry.migrate._sbt module
  • rank2_dict()
  • rank1_dict()
  • rank4_dict()
  • rank3_three_center_dict()
  • sparse_rank4_dict()
  • rank4_rdm_dict()
• qdk_chemistry.migrate._sparse module
  • from_json_doc()
  • from_hdf5_group()
  • to_new_json()
• qdk_chemistry.migrate._wavefunction module
  • from_json_doc()
  • from_hdf5_file()
  • from_hdf5_group()
  • to_new_json()