Utilities API

I/O Helpers

Input/Output utilities for molecular data and results.

q2m3.utils.io.load_xyz(filepath)[source]

Load molecular structure from XYZ file.

Parameters:

filepath (str) – Path to XYZ file

Returns:

List of Atom objects

Raises:

  • FileNotFoundError – If file doesn’t exist

  • ValueError – If file format is invalid

Return type:

list[Atom]

q2m3.utils.io.save_json_results(results, filepath, indent=2)[source]

Save calculation results as strict JSON, including immutable dataclasses.

Parameters:

  • results (Any) – Results mapping or dataclass instance. Nested dataclasses, mappings, numpy values, and tuples are converted recursively. Complex numbers use dictionaries with real and imag fields.

  • filepath (str | Path) – Output file path

  • indent (int) – JSON indentation level

Raises:

  • ValueError – A numeric value is NaN or infinite.

  • TypeError – A value cannot be represented in JSON.

Return type:

None

q2m3.utils.io.load_config(filepath)[source]

Load configuration from YAML or JSON file.

Parameters:

filepath (str) – Path to config file

Returns:

Configuration dictionary

Raises:

  • FileNotFoundError – If file doesn’t exist

  • ValueError – If file format is not supported

Return type:

dict[str, Any]

Plotting Helpers

General plotting utilities for energy analysis.

Provides cross-module visualization tools such as HF vs quantum energy comparison.

q2m3.utils.plotting.plot_energy_comparison(hf_energies, quantum_energies, title='HF vs Quantum Energy Comparison', output_path=None, show=True)[source]

Plot correlation between HF and quantum energies.

Creates a two-panel figure: (1) scatter plot of HF vs quantum energies with y=x reference line, (2) histogram of energy differences.

Parameters:

  • hf_energies (Sequence[float]) – HF energies at quantum evaluation steps

  • quantum_energies (Sequence[float]) – Quantum algorithm energy estimates

  • title (str) – Plot title

  • output_path (str | Path | None) – Path to save figure

  • show (bool) – Whether to display

Returns:

Matplotlib Figure object

Return type:

Figure