From 51c50cf73289cad9c9eee80c9863e8de51833ee5 Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Tue, 23 Jun 2026 16:16:13 +0200 Subject: [PATCH 1/7] Docs: replace xyz files with xyz strings --- .../examples/cpp/active_space_selector.cpp | 9 ++++++-- docs/source/_static/examples/cpp/ansatz.cpp | 8 +++++-- .../examples/cpp/dynamical_correlation.cpp | 8 +++++-- .../_static/examples/cpp/hamiltonian.cpp | 9 ++++++-- .../examples/cpp/hamiltonian_constructor.cpp | 9 +++++--- .../source/_static/examples/cpp/localizer.cpp | 9 ++++++-- docs/source/_static/examples/cpp/orbitals.cpp | 8 +++++-- .../_static/examples/cpp/quickstart.cpp | 17 ++++++++++++--- .../_static/examples/cpp/scf_solver.cpp | 8 +++++-- .../examples/data/n2_stretched.structure.xyz | 4 ---- .../examples/data/para_benzyne.structure.xyz | 12 ----------- .../examples/python/active_space_selector.py | 13 +++++++----- docs/source/_static/examples/python/ansatz.py | 10 ++++++--- .../examples/python/design_principles.py | 11 ++++++---- .../examples/python/dynamical_correlation.py | 11 ++++++---- .../examples/python/factory_pattern.py | 10 ++++++--- .../_static/examples/python/hamiltonian.py | 13 +++++++----- .../python/hamiltonian_constructor.py | 11 ++++++---- .../_static/examples/python/interfaces.py | 10 ++++++--- .../_static/examples/python/localizer.py | 13 +++++++----- .../_static/examples/python/mc_calculator.py | 10 ++++++--- docs/source/_static/examples/python/mcscf.py | 12 ++++++----- .../_static/examples/python/orbitals.py | 10 ++++++--- .../_static/examples/python/qubit_mapper.py | 12 +++++++---- .../_static/examples/python/quickstart.py | 21 +++++++++++++------ .../examples/python/release_notes_v1_1.py | 10 +++++---- .../_static/examples/python/scf_solver.py | 10 ++++++--- 27 files changed, 188 insertions(+), 100 deletions(-) delete mode 100644 docs/source/_static/examples/data/n2_stretched.structure.xyz delete mode 100644 docs/source/_static/examples/data/para_benzyne.structure.xyz diff --git a/docs/source/_static/examples/cpp/active_space_selector.cpp b/docs/source/_static/examples/cpp/active_space_selector.cpp index 45150fc1f..b43948b19 100644 --- a/docs/source/_static/examples/cpp/active_space_selector.cpp +++ b/docs/source/_static/examples/cpp/active_space_selector.cpp @@ -28,8 +28,13 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-run - // Load a molecular structure (water molecule) from XYZ file - auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); + // Load a molecular structure (water molecule) from an XYZ string + auto structure = Structure::from_xyz(R"(3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +)"); int charge = 0; // First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/cpp/ansatz.cpp b/docs/source/_static/examples/cpp/ansatz.cpp index c6bd2b1f1..033336e54 100644 --- a/docs/source/_static/examples/cpp/ansatz.cpp +++ b/docs/source/_static/examples/cpp/ansatz.cpp @@ -12,8 +12,12 @@ using namespace qdk::chemistry::data; using namespace qdk::chemistry::algorithms; int main() { - // Load H2 structure from XYZ file - auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); + // Load H2 structure from an XYZ string + auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // SCF auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/dynamical_correlation.cpp b/docs/source/_static/examples/cpp/dynamical_correlation.cpp index 771a8c14c..43f567d0e 100644 --- a/docs/source/_static/examples/cpp/dynamical_correlation.cpp +++ b/docs/source/_static/examples/cpp/dynamical_correlation.cpp @@ -25,8 +25,12 @@ auto mp2_calculator = // ----------------------------------------------------------------------------- // start-cell-run -// Load H2 structure from XYZ file -auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); +// Load H2 structure from an XYZ string +auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Run initial SCF to get reference wavefunction auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian.cpp b/docs/source/_static/examples/cpp/hamiltonian.cpp index 4416ead90..856f9fee9 100644 --- a/docs/source/_static/examples/cpp/hamiltonian.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian.cpp @@ -5,8 +5,13 @@ // Hamiltonian usage examples. // -------------------------------------------------------------------------------------------- // start-cell-hamiltonian-creation -// Load structure from XYZ file -auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); +// Load structure from an XYZ string +auto structure = Structure::from_xyz(R"(3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +)"); // Run initial SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp index fb76ff1eb..3078741b3 100644 --- a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp @@ -26,9 +26,12 @@ hamiltonian_constructor->settings().set("eri_method", "direct"); // -------------------------------------------------------------------------------------------- // start-cell-construct -// Load structure from XYZ file -auto structure = std::make_shared( - Structure::from_xyz_file("../data/h2.structure.xyz")); +// Load structure from an XYZ string +auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Run a SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/localizer.cpp b/docs/source/_static/examples/cpp/localizer.cpp index 32699f52f..d9b269aef 100644 --- a/docs/source/_static/examples/cpp/localizer.cpp +++ b/docs/source/_static/examples/cpp/localizer.cpp @@ -29,8 +29,13 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-localize - // Load H2O molecule from XYZ file - auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); + // Load H2O molecule from an XYZ string + auto structure = Structure::from_xyz(R"(3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +)"); // Obtain orbitals from SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/orbitals.cpp b/docs/source/_static/examples/cpp/orbitals.cpp index c3f767e98..5553afa1e 100644 --- a/docs/source/_static/examples/cpp/orbitals.cpp +++ b/docs/source/_static/examples/cpp/orbitals.cpp @@ -13,8 +13,12 @@ using namespace qdk::chemistry::algorithms; int main() { // Obtain orbitals from a SCF calculation - // Load H2 molecule from XYZ file - auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); + // Load H2 molecule from an XYZ string + auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Obtain orbitals from a SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/quickstart.cpp b/docs/source/_static/examples/cpp/quickstart.cpp index 639cf5aa0..5f57feb32 100644 --- a/docs/source/_static/examples/cpp/quickstart.cpp +++ b/docs/source/_static/examples/cpp/quickstart.cpp @@ -25,9 +25,20 @@ using namespace qdk::chemistry; int main() { // --------------------------------------------------------------------------- // start-cell-structure - // Load para-benzyne structure from XYZ file - auto structure = std::make_shared( - data::Structure::from_xyz_file("../data/para_benzyne.structure.xyz")); + // Load para-benzyne structure from an XYZ string + auto structure = data::Structure::from_xyz(R"(10 +para-Benzyne +C 0.000000 1.396000 0.000000 +C 1.209077 0.698000 0.000000 +C 1.209077 -0.698000 0.000000 +C 0.000000 -1.396000 0.000000 +C -1.209077 -0.698000 0.000000 +C -1.209077 0.698000 0.000000 +H 2.151000 1.242000 0.000000 +H 2.151000 -1.242000 0.000000 +H -2.151000 -1.242000 0.000000 +H -2.151000 1.242000 0.000000 +)"); std::cout << "Created structure with " << structure->get_num_atoms() << " atoms" << std::endl; diff --git a/docs/source/_static/examples/cpp/scf_solver.cpp b/docs/source/_static/examples/cpp/scf_solver.cpp index ffd794636..2e8964b78 100644 --- a/docs/source/_static/examples/cpp/scf_solver.cpp +++ b/docs/source/_static/examples/cpp/scf_solver.cpp @@ -28,8 +28,12 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-run - // Load structure from XYZ file - auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); + // Load structure from an XYZ string + auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Run the SCF calculation auto [E_scf, wfn] = scf_solver->run(structure, 0, 1, "def2-tzvpp"); diff --git a/docs/source/_static/examples/data/n2_stretched.structure.xyz b/docs/source/_static/examples/data/n2_stretched.structure.xyz deleted file mode 100644 index cebe9864f..000000000 --- a/docs/source/_static/examples/data/n2_stretched.structure.xyz +++ /dev/null @@ -1,4 +0,0 @@ -2 - -N 0 0 0 -N 0 0 2 \ No newline at end of file diff --git a/docs/source/_static/examples/data/para_benzyne.structure.xyz b/docs/source/_static/examples/data/para_benzyne.structure.xyz deleted file mode 100644 index 726c2d4b0..000000000 --- a/docs/source/_static/examples/data/para_benzyne.structure.xyz +++ /dev/null @@ -1,12 +0,0 @@ -10 -para-Benzyne -C 0.000000 1.396000 0.000000 -C 1.209077 0.698000 0.000000 -C 1.209077 -0.698000 0.000000 -C 0.000000 -1.396000 0.000000 -C -1.209077 -0.698000 0.000000 -C -1.209077 0.698000 0.000000 -H 2.151000 1.242000 0.000000 -H 2.151000 -1.242000 0.000000 -H -2.151000 -1.242000 0.000000 -H -2.151000 1.242000 0.000000 diff --git a/docs/source/_static/examples/python/active_space_selector.py b/docs/source/_static/examples/python/active_space_selector.py index ac780784e..eafc09cbf 100644 --- a/docs/source/_static/examples/python/active_space_selector.py +++ b/docs/source/_static/examples/python/active_space_selector.py @@ -26,13 +26,16 @@ ################################################################################ # start-cell-run -from pathlib import Path from qdk_chemistry.data import Structure -# Load a molecular structure (water molecule) from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) +# Define a molecular structure (water molecule) in XYZ format +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/ansatz.py b/docs/source/_static/examples/python/ansatz.py index 378ac76fe..3a3ec2ec6 100644 --- a/docs/source/_static/examples/python/ansatz.py +++ b/docs/source/_static/examples/python/ansatz.py @@ -7,12 +7,16 @@ ################################################################################ # start-cell-create -from pathlib import Path from qdk_chemistry.data import Ansatz, Structure from qdk_chemistry.algorithms import create -# Load H2 molecule structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/design_principles.py b/docs/source/_static/examples/python/design_principles.py index f67159b48..a67f3c4d7 100644 --- a/docs/source/_static/examples/python/design_principles.py +++ b/docs/source/_static/examples/python/design_principles.py @@ -7,8 +7,6 @@ ################################################################################ # start-cell-scf-create -from pathlib import Path - from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure @@ -25,8 +23,13 @@ ################################################################################ # start-cell-data-flow -# Load a Structure from file (data classes in QDK/Chemistry are immutable by design) -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define a Structure (data classes in QDK/Chemistry are immutable by design) +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Configure and run SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/dynamical_correlation.py b/docs/source/_static/examples/python/dynamical_correlation.py index de737becf..507e49504 100644 --- a/docs/source/_static/examples/python/dynamical_correlation.py +++ b/docs/source/_static/examples/python/dynamical_correlation.py @@ -23,12 +23,15 @@ ################################################################################ # start-cell-run -from pathlib import Path - from qdk_chemistry.data import Ansatz, Structure -# Load H2 structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run initial SCF to get reference wavefunction scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/factory_pattern.py b/docs/source/_static/examples/python/factory_pattern.py index 0dfb487c5..4b43cb246 100644 --- a/docs/source/_static/examples/python/factory_pattern.py +++ b/docs/source/_static/examples/python/factory_pattern.py @@ -7,12 +7,16 @@ ################################################################################ # start-cell-scf-localizer -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure -# Load H2 molecule from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Create a SCF solver using the default implementation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian.py b/docs/source/_static/examples/python/hamiltonian.py index 14b1c3cd8..36f4aa257 100644 --- a/docs/source/_static/examples/python/hamiltonian.py +++ b/docs/source/_static/examples/python/hamiltonian.py @@ -7,14 +7,17 @@ ################################################################################ # start-cell-hamiltonian-creation -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, SpinChannel -# Load a structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) +# Define the water molecule in XYZ format +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Run initial SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian_constructor.py b/docs/source/_static/examples/python/hamiltonian_constructor.py index 8206db0dd..c9a34dfbc 100644 --- a/docs/source/_static/examples/python/hamiltonian_constructor.py +++ b/docs/source/_static/examples/python/hamiltonian_constructor.py @@ -4,8 +4,6 @@ # Copyright (c) Microsoft Corporation. All rights reserved. # Licensed under the MIT License. See LICENSE.txt in the project root for license information. # -------------------------------------------------------------------------------------------- -from pathlib import Path - from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure @@ -32,8 +30,13 @@ ################################################################################ # start-cell-construct -# Load a structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run a SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/interfaces.py b/docs/source/_static/examples/python/interfaces.py index 442abc048..6a938b054 100644 --- a/docs/source/_static/examples/python/interfaces.py +++ b/docs/source/_static/examples/python/interfaces.py @@ -7,12 +7,16 @@ ################################################################################ # start-cell-scf -from pathlib import Path from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure -# Load H2 molecule from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Create a SCF solver using the factory scf_solver = create("scf_solver", "pyscf") diff --git a/docs/source/_static/examples/python/localizer.py b/docs/source/_static/examples/python/localizer.py index 564e33edc..9aafb48f5 100644 --- a/docs/source/_static/examples/python/localizer.py +++ b/docs/source/_static/examples/python/localizer.py @@ -7,7 +7,6 @@ ################################################################################ # start-cell-create -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure @@ -29,10 +28,14 @@ ################################################################################ # start-cell-localize -# Load H2O molecule from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) +# Define the water molecule in XYZ format +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Obtain orbitals from SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mc_calculator.py b/docs/source/_static/examples/python/mc_calculator.py index cbf578d56..e376cb2c9 100644 --- a/docs/source/_static/examples/python/mc_calculator.py +++ b/docs/source/_static/examples/python/mc_calculator.py @@ -23,12 +23,16 @@ ################################################################################ # start-cell-run -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure -# Load H2 structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mcscf.py b/docs/source/_static/examples/python/mcscf.py index c86d1737e..ccfcf5888 100644 --- a/docs/source/_static/examples/python/mcscf.py +++ b/docs/source/_static/examples/python/mcscf.py @@ -53,14 +53,16 @@ ################################################################################ # start-cell-run -from pathlib import Path from qdk_chemistry.data import Structure from qdk_chemistry.utils import compute_valence_space_parameters -# Load nitrogen molecule structure -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/n2_stretched.structure.xyz" -) +# Define the stretched nitrogen molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +N2 (stretched) +N 0 0 0 +N 0 0 2 +""") charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/orbitals.py b/docs/source/_static/examples/python/orbitals.py index 5454942cb..dc86d6623 100644 --- a/docs/source/_static/examples/python/orbitals.py +++ b/docs/source/_static/examples/python/orbitals.py @@ -5,15 +5,19 @@ # Licensed under the MIT License. See LICENSE.txt in the project root for license information. # -------------------------------------------------------------------------------------------- -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, ModelOrbitals from qdk_chemistry.data.symmetry import spin_index_set ################################################################################ # start-cell-create -# Load H2 molecule from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Obtain orbitals from a SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/qubit_mapper.py b/docs/source/_static/examples/python/qubit_mapper.py index f2ace3146..da9cbe5f8 100644 --- a/docs/source/_static/examples/python/qubit_mapper.py +++ b/docs/source/_static/examples/python/qubit_mapper.py @@ -25,12 +25,16 @@ ################################################################################ # start-cell-run -from pathlib import Path - from qdk_chemistry.data import Structure -# Read a molecular structure from XYZ file -structure = Structure.from_xyz_file(Path(".") / "../data/water.structure.xyz") +# Define a molecular structure (water) in XYZ format +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Perform an SCF calculation to generate initial orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/quickstart.py b/docs/source/_static/examples/python/quickstart.py index fec133c0f..97df3ce82 100644 --- a/docs/source/_static/examples/python/quickstart.py +++ b/docs/source/_static/examples/python/quickstart.py @@ -7,16 +7,25 @@ ################################################################################ # start-cell-structure -from pathlib import Path - import numpy as np from qdk_chemistry.algorithms import create from qdk_chemistry.data import AlgorithmRef, Structure -# Load para-benzyne structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/para_benzyne.structure.xyz" -) +# Define the para-benzyne molecule in XYZ format +structure = Structure.from_xyz("""\ +10 +para-Benzyne +C 0.000000 1.396000 0.000000 +C 1.209077 0.698000 0.000000 +C 1.209077 -0.698000 0.000000 +C 0.000000 -1.396000 0.000000 +C -1.209077 -0.698000 0.000000 +C -1.209077 0.698000 0.000000 +H 2.151000 1.242000 0.000000 +H 2.151000 -1.242000 0.000000 +H -2.151000 -1.242000 0.000000 +H -2.151000 1.242000 0.000000 +""") print(f"Created structure with {structure.get_num_atoms()} atoms") print(f"Elements: {structure.get_elements()}") diff --git a/docs/source/_static/examples/python/release_notes_v1_1.py b/docs/source/_static/examples/python/release_notes_v1_1.py index db68ce4ed..daf5066fb 100644 --- a/docs/source/_static/examples/python/release_notes_v1_1.py +++ b/docs/source/_static/examples/python/release_notes_v1_1.py @@ -11,7 +11,6 @@ # -------------------------------------------------------------------------------------------- import importlib.util -from pathlib import Path import numpy as np from qdk_chemistry.algorithms import create @@ -21,9 +20,12 @@ # Shared pipeline: H2 molecule → SCF → active-space → Hamiltonian → QubitHam # (used by cells below that need a fermionic or qubit Hamiltonian) # --------------------------------------------------------------------------- -_h2_structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) +_h2_structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") _scf = create("scf_solver") _E_scf, _wfn_scf = _scf.run( _h2_structure, charge=0, spin_multiplicity=1, basis_or_guess="sto-3g" diff --git a/docs/source/_static/examples/python/scf_solver.py b/docs/source/_static/examples/python/scf_solver.py index d1bc1ca37..c2d17c2cd 100644 --- a/docs/source/_static/examples/python/scf_solver.py +++ b/docs/source/_static/examples/python/scf_solver.py @@ -8,7 +8,6 @@ ################################################################################ # start-cell-create import numpy as np -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, BasisSet @@ -28,8 +27,13 @@ ################################################################################ # start-cell-run -# Load structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +# Define the H2 molecule in XYZ format +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run scf E_scf, wfn = scf_solver.run( From 9aa340b0818188eb44aca76b595ab95aab043ba8 Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Wed, 24 Jun 2026 07:49:44 +0000 Subject: [PATCH 2/7] Revert "Docs: replace xyz files with xyz strings" This reverts commit cea9d5c181c7d6a51e27f25a445306dc41872c95. --- .../examples/cpp/active_space_selector.cpp | 9 ++------ docs/source/_static/examples/cpp/ansatz.cpp | 8 ++----- .../examples/cpp/dynamical_correlation.cpp | 8 ++----- .../_static/examples/cpp/hamiltonian.cpp | 9 ++------ .../examples/cpp/hamiltonian_constructor.cpp | 9 +++----- .../source/_static/examples/cpp/localizer.cpp | 9 ++------ docs/source/_static/examples/cpp/orbitals.cpp | 8 ++----- .../_static/examples/cpp/quickstart.cpp | 17 +++------------ .../_static/examples/cpp/scf_solver.cpp | 8 ++----- .../examples/data/n2_stretched.structure.xyz | 4 ++++ .../examples/data/para_benzyne.structure.xyz | 12 +++++++++++ .../examples/python/active_space_selector.py | 13 +++++------- docs/source/_static/examples/python/ansatz.py | 10 +++------ .../examples/python/design_principles.py | 11 ++++------ .../examples/python/dynamical_correlation.py | 11 ++++------ .../examples/python/factory_pattern.py | 10 +++------ .../_static/examples/python/hamiltonian.py | 13 +++++------- .../python/hamiltonian_constructor.py | 11 ++++------ .../_static/examples/python/interfaces.py | 10 +++------ .../_static/examples/python/localizer.py | 13 +++++------- .../_static/examples/python/mc_calculator.py | 10 +++------ docs/source/_static/examples/python/mcscf.py | 12 +++++------ .../_static/examples/python/orbitals.py | 10 +++------ .../_static/examples/python/qubit_mapper.py | 12 ++++------- .../_static/examples/python/quickstart.py | 21 ++++++------------- .../examples/python/release_notes_v1_1.py | 10 ++++----- .../_static/examples/python/scf_solver.py | 10 +++------ 27 files changed, 100 insertions(+), 188 deletions(-) create mode 100644 docs/source/_static/examples/data/n2_stretched.structure.xyz create mode 100644 docs/source/_static/examples/data/para_benzyne.structure.xyz diff --git a/docs/source/_static/examples/cpp/active_space_selector.cpp b/docs/source/_static/examples/cpp/active_space_selector.cpp index b43948b19..45150fc1f 100644 --- a/docs/source/_static/examples/cpp/active_space_selector.cpp +++ b/docs/source/_static/examples/cpp/active_space_selector.cpp @@ -28,13 +28,8 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-run - // Load a molecular structure (water molecule) from an XYZ string - auto structure = Structure::from_xyz(R"(3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -)"); + // Load a molecular structure (water molecule) from XYZ file + auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); int charge = 0; // First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/cpp/ansatz.cpp b/docs/source/_static/examples/cpp/ansatz.cpp index 033336e54..c6bd2b1f1 100644 --- a/docs/source/_static/examples/cpp/ansatz.cpp +++ b/docs/source/_static/examples/cpp/ansatz.cpp @@ -12,12 +12,8 @@ using namespace qdk::chemistry::data; using namespace qdk::chemistry::algorithms; int main() { - // Load H2 structure from an XYZ string - auto structure = Structure::from_xyz(R"(2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -)"); + // Load H2 structure from XYZ file + auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); // SCF auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/dynamical_correlation.cpp b/docs/source/_static/examples/cpp/dynamical_correlation.cpp index 43f567d0e..771a8c14c 100644 --- a/docs/source/_static/examples/cpp/dynamical_correlation.cpp +++ b/docs/source/_static/examples/cpp/dynamical_correlation.cpp @@ -25,12 +25,8 @@ auto mp2_calculator = // ----------------------------------------------------------------------------- // start-cell-run -// Load H2 structure from an XYZ string -auto structure = Structure::from_xyz(R"(2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -)"); +// Load H2 structure from XYZ file +auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); // Run initial SCF to get reference wavefunction auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian.cpp b/docs/source/_static/examples/cpp/hamiltonian.cpp index 856f9fee9..4416ead90 100644 --- a/docs/source/_static/examples/cpp/hamiltonian.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian.cpp @@ -5,13 +5,8 @@ // Hamiltonian usage examples. // -------------------------------------------------------------------------------------------- // start-cell-hamiltonian-creation -// Load structure from an XYZ string -auto structure = Structure::from_xyz(R"(3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -)"); +// Load structure from XYZ file +auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); // Run initial SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp index 3078741b3..fb76ff1eb 100644 --- a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp @@ -26,12 +26,9 @@ hamiltonian_constructor->settings().set("eri_method", "direct"); // -------------------------------------------------------------------------------------------- // start-cell-construct -// Load structure from an XYZ string -auto structure = Structure::from_xyz(R"(2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -)"); +// Load structure from XYZ file +auto structure = std::make_shared( + Structure::from_xyz_file("../data/h2.structure.xyz")); // Run a SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/localizer.cpp b/docs/source/_static/examples/cpp/localizer.cpp index d9b269aef..32699f52f 100644 --- a/docs/source/_static/examples/cpp/localizer.cpp +++ b/docs/source/_static/examples/cpp/localizer.cpp @@ -29,13 +29,8 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-localize - // Load H2O molecule from an XYZ string - auto structure = Structure::from_xyz(R"(3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -)"); + // Load H2O molecule from XYZ file + auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); // Obtain orbitals from SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/orbitals.cpp b/docs/source/_static/examples/cpp/orbitals.cpp index 5553afa1e..c3f767e98 100644 --- a/docs/source/_static/examples/cpp/orbitals.cpp +++ b/docs/source/_static/examples/cpp/orbitals.cpp @@ -13,12 +13,8 @@ using namespace qdk::chemistry::algorithms; int main() { // Obtain orbitals from a SCF calculation - // Load H2 molecule from an XYZ string - auto structure = Structure::from_xyz(R"(2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -)"); + // Load H2 molecule from XYZ file + auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); // Obtain orbitals from a SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/quickstart.cpp b/docs/source/_static/examples/cpp/quickstart.cpp index 5f57feb32..639cf5aa0 100644 --- a/docs/source/_static/examples/cpp/quickstart.cpp +++ b/docs/source/_static/examples/cpp/quickstart.cpp @@ -25,20 +25,9 @@ using namespace qdk::chemistry; int main() { // --------------------------------------------------------------------------- // start-cell-structure - // Load para-benzyne structure from an XYZ string - auto structure = data::Structure::from_xyz(R"(10 -para-Benzyne -C 0.000000 1.396000 0.000000 -C 1.209077 0.698000 0.000000 -C 1.209077 -0.698000 0.000000 -C 0.000000 -1.396000 0.000000 -C -1.209077 -0.698000 0.000000 -C -1.209077 0.698000 0.000000 -H 2.151000 1.242000 0.000000 -H 2.151000 -1.242000 0.000000 -H -2.151000 -1.242000 0.000000 -H -2.151000 1.242000 0.000000 -)"); + // Load para-benzyne structure from XYZ file + auto structure = std::make_shared( + data::Structure::from_xyz_file("../data/para_benzyne.structure.xyz")); std::cout << "Created structure with " << structure->get_num_atoms() << " atoms" << std::endl; diff --git a/docs/source/_static/examples/cpp/scf_solver.cpp b/docs/source/_static/examples/cpp/scf_solver.cpp index 2e8964b78..ffd794636 100644 --- a/docs/source/_static/examples/cpp/scf_solver.cpp +++ b/docs/source/_static/examples/cpp/scf_solver.cpp @@ -28,12 +28,8 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-run - // Load structure from an XYZ string - auto structure = Structure::from_xyz(R"(2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -)"); + // Load structure from XYZ file + auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); // Run the SCF calculation auto [E_scf, wfn] = scf_solver->run(structure, 0, 1, "def2-tzvpp"); diff --git a/docs/source/_static/examples/data/n2_stretched.structure.xyz b/docs/source/_static/examples/data/n2_stretched.structure.xyz new file mode 100644 index 000000000..cebe9864f --- /dev/null +++ b/docs/source/_static/examples/data/n2_stretched.structure.xyz @@ -0,0 +1,4 @@ +2 + +N 0 0 0 +N 0 0 2 \ No newline at end of file diff --git a/docs/source/_static/examples/data/para_benzyne.structure.xyz b/docs/source/_static/examples/data/para_benzyne.structure.xyz new file mode 100644 index 000000000..726c2d4b0 --- /dev/null +++ b/docs/source/_static/examples/data/para_benzyne.structure.xyz @@ -0,0 +1,12 @@ +10 +para-Benzyne +C 0.000000 1.396000 0.000000 +C 1.209077 0.698000 0.000000 +C 1.209077 -0.698000 0.000000 +C 0.000000 -1.396000 0.000000 +C -1.209077 -0.698000 0.000000 +C -1.209077 0.698000 0.000000 +H 2.151000 1.242000 0.000000 +H 2.151000 -1.242000 0.000000 +H -2.151000 -1.242000 0.000000 +H -2.151000 1.242000 0.000000 diff --git a/docs/source/_static/examples/python/active_space_selector.py b/docs/source/_static/examples/python/active_space_selector.py index eafc09cbf..ac780784e 100644 --- a/docs/source/_static/examples/python/active_space_selector.py +++ b/docs/source/_static/examples/python/active_space_selector.py @@ -26,16 +26,13 @@ ################################################################################ # start-cell-run +from pathlib import Path from qdk_chemistry.data import Structure -# Define a molecular structure (water molecule) in XYZ format -structure = Structure.from_xyz("""\ -3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -""") +# Load a molecular structure (water molecule) from XYZ file +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/water.structure.xyz" +) charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/ansatz.py b/docs/source/_static/examples/python/ansatz.py index 3a3ec2ec6..378ac76fe 100644 --- a/docs/source/_static/examples/python/ansatz.py +++ b/docs/source/_static/examples/python/ansatz.py @@ -7,16 +7,12 @@ ################################################################################ # start-cell-create +from pathlib import Path from qdk_chemistry.data import Ansatz, Structure from qdk_chemistry.algorithms import create -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load H2 molecule structure from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/design_principles.py b/docs/source/_static/examples/python/design_principles.py index a67f3c4d7..f67159b48 100644 --- a/docs/source/_static/examples/python/design_principles.py +++ b/docs/source/_static/examples/python/design_principles.py @@ -7,6 +7,8 @@ ################################################################################ # start-cell-scf-create +from pathlib import Path + from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure @@ -23,13 +25,8 @@ ################################################################################ # start-cell-data-flow -# Define a Structure (data classes in QDK/Chemistry are immutable by design) -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load a Structure from file (data classes in QDK/Chemistry are immutable by design) +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Configure and run SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/dynamical_correlation.py b/docs/source/_static/examples/python/dynamical_correlation.py index 507e49504..de737becf 100644 --- a/docs/source/_static/examples/python/dynamical_correlation.py +++ b/docs/source/_static/examples/python/dynamical_correlation.py @@ -23,15 +23,12 @@ ################################################################################ # start-cell-run +from pathlib import Path + from qdk_chemistry.data import Ansatz, Structure -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load H2 structure from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Run initial SCF to get reference wavefunction scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/factory_pattern.py b/docs/source/_static/examples/python/factory_pattern.py index 4b43cb246..0dfb487c5 100644 --- a/docs/source/_static/examples/python/factory_pattern.py +++ b/docs/source/_static/examples/python/factory_pattern.py @@ -7,16 +7,12 @@ ################################################################################ # start-cell-scf-localizer +from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load H2 molecule from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Create a SCF solver using the default implementation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian.py b/docs/source/_static/examples/python/hamiltonian.py index 36f4aa257..14b1c3cd8 100644 --- a/docs/source/_static/examples/python/hamiltonian.py +++ b/docs/source/_static/examples/python/hamiltonian.py @@ -7,17 +7,14 @@ ################################################################################ # start-cell-hamiltonian-creation +from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, SpinChannel -# Define the water molecule in XYZ format -structure = Structure.from_xyz("""\ -3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -""") +# Load a structure from XYZ file +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/water.structure.xyz" +) # Run initial SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian_constructor.py b/docs/source/_static/examples/python/hamiltonian_constructor.py index c9a34dfbc..8206db0dd 100644 --- a/docs/source/_static/examples/python/hamiltonian_constructor.py +++ b/docs/source/_static/examples/python/hamiltonian_constructor.py @@ -4,6 +4,8 @@ # Copyright (c) Microsoft Corporation. All rights reserved. # Licensed under the MIT License. See LICENSE.txt in the project root for license information. # -------------------------------------------------------------------------------------------- +from pathlib import Path + from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure @@ -30,13 +32,8 @@ ################################################################################ # start-cell-construct -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load a structure from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Run a SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/interfaces.py b/docs/source/_static/examples/python/interfaces.py index 6a938b054..442abc048 100644 --- a/docs/source/_static/examples/python/interfaces.py +++ b/docs/source/_static/examples/python/interfaces.py @@ -7,16 +7,12 @@ ################################################################################ # start-cell-scf +from pathlib import Path from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load H2 molecule from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Create a SCF solver using the factory scf_solver = create("scf_solver", "pyscf") diff --git a/docs/source/_static/examples/python/localizer.py b/docs/source/_static/examples/python/localizer.py index 9aafb48f5..564e33edc 100644 --- a/docs/source/_static/examples/python/localizer.py +++ b/docs/source/_static/examples/python/localizer.py @@ -7,6 +7,7 @@ ################################################################################ # start-cell-create +from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure @@ -28,14 +29,10 @@ ################################################################################ # start-cell-localize -# Define the water molecule in XYZ format -structure = Structure.from_xyz("""\ -3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -""") +# Load H2O molecule from XYZ file +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/water.structure.xyz" +) # Obtain orbitals from SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mc_calculator.py b/docs/source/_static/examples/python/mc_calculator.py index e376cb2c9..cbf578d56 100644 --- a/docs/source/_static/examples/python/mc_calculator.py +++ b/docs/source/_static/examples/python/mc_calculator.py @@ -23,16 +23,12 @@ ################################################################################ # start-cell-run +from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load H2 structure from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Run SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mcscf.py b/docs/source/_static/examples/python/mcscf.py index ccfcf5888..c86d1737e 100644 --- a/docs/source/_static/examples/python/mcscf.py +++ b/docs/source/_static/examples/python/mcscf.py @@ -53,16 +53,14 @@ ################################################################################ # start-cell-run +from pathlib import Path from qdk_chemistry.data import Structure from qdk_chemistry.utils import compute_valence_space_parameters -# Define the stretched nitrogen molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -N2 (stretched) -N 0 0 0 -N 0 0 2 -""") +# Load nitrogen molecule structure +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/n2_stretched.structure.xyz" +) charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/orbitals.py b/docs/source/_static/examples/python/orbitals.py index dc86d6623..5454942cb 100644 --- a/docs/source/_static/examples/python/orbitals.py +++ b/docs/source/_static/examples/python/orbitals.py @@ -5,19 +5,15 @@ # Licensed under the MIT License. See LICENSE.txt in the project root for license information. # -------------------------------------------------------------------------------------------- +from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, ModelOrbitals from qdk_chemistry.data.symmetry import spin_index_set ################################################################################ # start-cell-create -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load H2 molecule from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Obtain orbitals from a SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/qubit_mapper.py b/docs/source/_static/examples/python/qubit_mapper.py index da9cbe5f8..f2ace3146 100644 --- a/docs/source/_static/examples/python/qubit_mapper.py +++ b/docs/source/_static/examples/python/qubit_mapper.py @@ -25,16 +25,12 @@ ################################################################################ # start-cell-run +from pathlib import Path + from qdk_chemistry.data import Structure -# Define a molecular structure (water) in XYZ format -structure = Structure.from_xyz("""\ -3 -Water molecule -O 0.000000 0.000000 0.000000 -H 0.758602 0.000000 0.504284 -H -0.758602 0.000000 0.504284 -""") +# Read a molecular structure from XYZ file +structure = Structure.from_xyz_file(Path(".") / "../data/water.structure.xyz") # Perform an SCF calculation to generate initial orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/quickstart.py b/docs/source/_static/examples/python/quickstart.py index 97df3ce82..fec133c0f 100644 --- a/docs/source/_static/examples/python/quickstart.py +++ b/docs/source/_static/examples/python/quickstart.py @@ -7,25 +7,16 @@ ################################################################################ # start-cell-structure +from pathlib import Path + import numpy as np from qdk_chemistry.algorithms import create from qdk_chemistry.data import AlgorithmRef, Structure -# Define the para-benzyne molecule in XYZ format -structure = Structure.from_xyz("""\ -10 -para-Benzyne -C 0.000000 1.396000 0.000000 -C 1.209077 0.698000 0.000000 -C 1.209077 -0.698000 0.000000 -C 0.000000 -1.396000 0.000000 -C -1.209077 -0.698000 0.000000 -C -1.209077 0.698000 0.000000 -H 2.151000 1.242000 0.000000 -H 2.151000 -1.242000 0.000000 -H -2.151000 -1.242000 0.000000 -H -2.151000 1.242000 0.000000 -""") +# Load para-benzyne structure from XYZ file +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/para_benzyne.structure.xyz" +) print(f"Created structure with {structure.get_num_atoms()} atoms") print(f"Elements: {structure.get_elements()}") diff --git a/docs/source/_static/examples/python/release_notes_v1_1.py b/docs/source/_static/examples/python/release_notes_v1_1.py index daf5066fb..db68ce4ed 100644 --- a/docs/source/_static/examples/python/release_notes_v1_1.py +++ b/docs/source/_static/examples/python/release_notes_v1_1.py @@ -11,6 +11,7 @@ # -------------------------------------------------------------------------------------------- import importlib.util +from pathlib import Path import numpy as np from qdk_chemistry.algorithms import create @@ -20,12 +21,9 @@ # Shared pipeline: H2 molecule → SCF → active-space → Hamiltonian → QubitHam # (used by cells below that need a fermionic or qubit Hamiltonian) # --------------------------------------------------------------------------- -_h2_structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +_h2_structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) _scf = create("scf_solver") _E_scf, _wfn_scf = _scf.run( _h2_structure, charge=0, spin_multiplicity=1, basis_or_guess="sto-3g" diff --git a/docs/source/_static/examples/python/scf_solver.py b/docs/source/_static/examples/python/scf_solver.py index c2d17c2cd..d1bc1ca37 100644 --- a/docs/source/_static/examples/python/scf_solver.py +++ b/docs/source/_static/examples/python/scf_solver.py @@ -8,6 +8,7 @@ ################################################################################ # start-cell-create import numpy as np +from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, BasisSet @@ -27,13 +28,8 @@ ################################################################################ # start-cell-run -# Define the H2 molecule in XYZ format -structure = Structure.from_xyz("""\ -2 -H2 molecule -H 0.000000 0.000000 0.000000 -H 0.000000 0.000000 0.740848 -""") +# Load structure from XYZ file +structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") # Run scf E_scf, wfn = scf_solver.run( From 73818eded1e0b568e1929d060294302ecdc0b207 Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Wed, 24 Jun 2026 11:46:03 +0200 Subject: [PATCH 3/7] docs: inline xyz files at build time (opt-in) --- docs/source/_ext/inline_xyz.py | 209 ++++++++++++++++++ .../examples/cpp/active_space_selector.cpp | 3 +- docs/source/_static/examples/cpp/ansatz.cpp | 3 +- .../examples/cpp/dynamical_correlation.cpp | 3 +- .../_static/examples/cpp/hamiltonian.cpp | 3 +- .../examples/cpp/hamiltonian_constructor.cpp | 2 +- .../source/_static/examples/cpp/localizer.cpp | 3 +- docs/source/_static/examples/cpp/orbitals.cpp | 3 +- .../_static/examples/cpp/quickstart.cpp | 5 +- .../_static/examples/cpp/scf_solver.cpp | 3 +- .../_static/examples/cpp/serialization.cpp | 2 +- .../examples/python/active_space_selector.py | 2 +- docs/source/_static/examples/python/ansatz.py | 4 +- .../_static/examples/python/basis_set.py | 2 +- .../examples/python/design_principles.py | 4 +- .../examples/python/dynamical_correlation.py | 4 +- .../examples/python/factory_pattern.py | 4 +- .../_static/examples/python/hamiltonian.py | 2 +- .../python/hamiltonian_constructor.py | 4 +- .../_static/examples/python/interfaces.py | 4 +- .../_static/examples/python/localizer.py | 2 +- .../_static/examples/python/mc_calculator.py | 4 +- docs/source/_static/examples/python/mcscf.py | 2 +- .../_static/examples/python/orbitals.py | 4 +- .../_static/examples/python/qubit_mapper.py | 4 +- .../_static/examples/python/quickstart.py | 2 +- .../_static/examples/python/scf_solver.py | 4 +- .../_static/examples/python/serialization.py | 4 +- docs/source/conf.py | 5 + 29 files changed, 272 insertions(+), 28 deletions(-) create mode 100644 docs/source/_ext/inline_xyz.py diff --git a/docs/source/_ext/inline_xyz.py b/docs/source/_ext/inline_xyz.py new file mode 100644 index 000000000..f7028bf43 --- /dev/null +++ b/docs/source/_ext/inline_xyz.py @@ -0,0 +1,209 @@ +# -------------------------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See LICENSE.txt in the project root for license information. +# -------------------------------------------------------------------------------------------- +"""Sphinx extension: inline ``.xyz`` files into example snippets at build time. + +The example scripts under ``docs/source/_static/examples`` load molecular +geometries from ``.xyz`` files, e.g.:: + + structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") + +Keeping the geometry in standalone ``.xyz`` files gives us a single source of +truth (the files are also used when the examples are executed as part of the +test suite). However, when these snippets are rendered into the documentation +via ``literalinclude``, a reader cannot access ``../data/h2.structure.xyz``. + +This extension rewrites ``from_xyz_file()`` calls into an +equivalent ``from_xyz()`` call *only in the rendered +documentation*, and only for calls that explicitly opt in (see below). The +files on disk are left untouched, so the examples remain runnable and the +``.xyz`` files remain the single source of truth. + +Python snippets become:: + + structure = Structure.from_xyz(\"\"\"\\ + 2 + H2 molecule + H 0.000000 0.000000 0.000000 + H 0.000000 0.000000 0.740848 + \"\"\") + +C++ snippets become:: + + auto structure = Structure::from_xyz(R"(2 + H2 molecule + H 0.000000 0.000000 0.000000 + H 0.000000 0.000000 0.740848 + )"); + +The rewrite hooks into ``LiteralIncludeReader.read_file`` because the +``literalinclude`` directive (unlike ``include``) does not emit the +``include-read`` event. + +Opt-in +------ +Inlining is opt-in: by default the rendered docs show exactly what is in the +file. A call is inlined only when it carries the marker comment +``docs:inline-xyz`` anywhere within the call (so it also works when a formatter +wraps the call across multiple lines):: + + structure = Structure.from_xyz_file(path) # docs:inline-xyz + +The marker itself is stripped from the rendered output so readers never see it. +Calls without the marker (e.g. the ``Structure`` file-loading tutorial) are left +verbatim as ``from_xyz_file`` calls. +""" + +from __future__ import annotations + +import re +from pathlib import Path +from typing import Any + +from sphinx.application import Sphinx +from sphinx.directives import code as _code +from sphinx.util import logging + +logger = logging.getLogger(__name__) + +# Directory containing the example snippets that may reference ``.xyz`` files. +_EXAMPLES_DIR = ( + Path(__file__).resolve().parent.parent / "_static" / "examples" +).resolve() + +# Source file types whose ``from_xyz_file`` calls should be inlined. +_PYTHON_SUFFIXES = {".py"} +_CPP_SUFFIXES = {".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".h"} + +# Matches the start of a ``from_xyz_file(`` call (Python or C++). +_CALL_RE = re.compile(r"from_xyz_file\s*\(") + +# Matches a quoted string literal that ends in ``.xyz``. +_XYZ_PATH_RE = re.compile(r"""['"]([^'"]*\.xyz)['"]""") + +# Marker comment that opts a call *into* inlining (rewritten to ``from_xyz``). +# The marker is stripped from the rendered output. +_INLINE_MARKER = "docs:inline-xyz" +_INLINE_MARKER_STRIP_RE = re.compile( + r"[ \t]*(?:#|//)[ \t]*" + re.escape(_INLINE_MARKER) + r"[ \t]*$" +) + + +def _find_matching_paren(text: str, open_idx: int) -> int: + """Return the index of the ``)`` matching the ``(`` at ``open_idx``. + + String literals are skipped so that parentheses inside quotes are ignored. + Returns ``-1`` if no matching parenthesis is found. + """ + depth = 0 + i = open_idx + in_str: str | None = None + while i < len(text): + ch = text[i] + if in_str is not None: + if ch == "\\": + i += 2 + continue + if ch == in_str: + in_str = None + elif ch in "\"'": + in_str = ch + elif ch == "(": + depth += 1 + elif ch == ")": + depth -= 1 + if depth == 0: + return i + i += 1 + return -1 + + +def _embed(contents: str, suffix: str) -> str: + """Build the inline ``from_xyz(...)`` replacement for the given contents.""" + if not contents.endswith("\n"): + contents += "\n" + if suffix in _PYTHON_SUFFIXES: + return 'from_xyz("""\\\n' + contents + '""")' + # C/C++ raw string literal keeps the contents verbatim. + return 'from_xyz(R"(' + contents + ')")' + + +def _strip_inline_markers(text: str) -> str: + """Remove trailing ``docs:inline-xyz`` marker comments from each line.""" + return "\n".join(_INLINE_MARKER_STRIP_RE.sub("", line) for line in text.split("\n")) + + +def _inline_xyz_in_text(text: str, example_dir: Path, suffix: str) -> str: + """Replace ``from_xyz_file(...)`` calls referencing ``.xyz`` files inline.""" + pieces: list[str] = [] + pos = 0 + for match in _CALL_RE.finditer(text): + open_paren = match.end() - 1 + close_paren = _find_matching_paren(text, open_paren) + if close_paren == -1: + continue + # Only inline calls that opt in via the marker anywhere within the + # (possibly multi-line) call, including trailing comments. + call_span_start = text.rfind("\n", 0, match.start()) + 1 + call_span_end = text.find("\n", close_paren) + if call_span_end == -1: + call_span_end = len(text) + if _INLINE_MARKER not in text[call_span_start:call_span_end]: + continue + inner = text[open_paren + 1 : close_paren] + path_match = _XYZ_PATH_RE.search(inner) + if path_match is None: + continue + xyz_path = (example_dir / path_match.group(1)).resolve() + if not xyz_path.is_file(): + continue + contents = xyz_path.read_text(encoding="utf-8") + pieces.append(text[pos : match.start()]) + pieces.append(_embed(contents, suffix)) + pos = close_paren + 1 + if not pieces: + return text + pieces.append(text[pos:]) + return "".join(pieces) + + +def _maybe_inline_xyz(filename: Path, lines: list[str]) -> list[str]: + """Inline ``.xyz`` contents for example snippets; otherwise return as-is.""" + resolved = filename.resolve() + if _EXAMPLES_DIR not in resolved.parents: + return lines + suffix = resolved.suffix.lower() + if suffix not in _PYTHON_SUFFIXES and suffix not in _CPP_SUFFIXES: + return lines + + text = "".join(lines) + if _INLINE_MARKER not in text: + return lines + + new_text = _inline_xyz_in_text(text, resolved.parent, suffix) + new_text = _strip_inline_markers(new_text) + if new_text == text: + return lines + return new_text.splitlines(keepends=True) + + +_orig_read_file = _code.LiteralIncludeReader.read_file + + +def _patched_read_file(self, filename, location=None): # type: ignore[no-untyped-def] + lines = _orig_read_file(self, filename, location=location) + try: + return _maybe_inline_xyz(Path(filename), lines) + except Exception as exc: # pragma: no cover - never break the build + logger.warning("inline_xyz: failed to inline %s: %s", filename, exc) + return lines + + +def setup(app: Sphinx) -> dict[str, Any]: + _code.LiteralIncludeReader.read_file = _patched_read_file + return { + "version": "1.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/source/_static/examples/cpp/active_space_selector.cpp b/docs/source/_static/examples/cpp/active_space_selector.cpp index 45150fc1f..8d3dc78b1 100644 --- a/docs/source/_static/examples/cpp/active_space_selector.cpp +++ b/docs/source/_static/examples/cpp/active_space_selector.cpp @@ -29,7 +29,8 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-run // Load a molecular structure (water molecule) from XYZ file - auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); + auto structure = Structure::from_xyz_file( + "../data/water.structure.xyz"); // docs:inline-xyz int charge = 0; // First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/cpp/ansatz.cpp b/docs/source/_static/examples/cpp/ansatz.cpp index c6bd2b1f1..375697e10 100644 --- a/docs/source/_static/examples/cpp/ansatz.cpp +++ b/docs/source/_static/examples/cpp/ansatz.cpp @@ -13,7 +13,8 @@ using namespace qdk::chemistry::algorithms; int main() { // Load H2 structure from XYZ file - auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); + auto structure = + Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz // SCF auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/dynamical_correlation.cpp b/docs/source/_static/examples/cpp/dynamical_correlation.cpp index 771a8c14c..8a81037ff 100644 --- a/docs/source/_static/examples/cpp/dynamical_correlation.cpp +++ b/docs/source/_static/examples/cpp/dynamical_correlation.cpp @@ -26,7 +26,8 @@ auto mp2_calculator = // ----------------------------------------------------------------------------- // start-cell-run // Load H2 structure from XYZ file -auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); +auto structure = + Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz // Run initial SCF to get reference wavefunction auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian.cpp b/docs/source/_static/examples/cpp/hamiltonian.cpp index 4416ead90..a85a5af3b 100644 --- a/docs/source/_static/examples/cpp/hamiltonian.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian.cpp @@ -6,7 +6,8 @@ // -------------------------------------------------------------------------------------------- // start-cell-hamiltonian-creation // Load structure from XYZ file -auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); +auto structure = + Structure::from_xyz_file("../data/water.structure.xyz"); // docs:inline-xyz // Run initial SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp index fb76ff1eb..b5ca3500e 100644 --- a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp @@ -28,7 +28,7 @@ hamiltonian_constructor->settings().set("eri_method", "direct"); // start-cell-construct // Load structure from XYZ file auto structure = std::make_shared( - Structure::from_xyz_file("../data/h2.structure.xyz")); + Structure::from_xyz_file("../data/h2.structure.xyz")); // docs:inline-xyz // Run a SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/localizer.cpp b/docs/source/_static/examples/cpp/localizer.cpp index 32699f52f..1b016a1c0 100644 --- a/docs/source/_static/examples/cpp/localizer.cpp +++ b/docs/source/_static/examples/cpp/localizer.cpp @@ -30,7 +30,8 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-localize // Load H2O molecule from XYZ file - auto structure = Structure::from_xyz_file("../data/water.structure.xyz"); + auto structure = Structure::from_xyz_file( + "../data/water.structure.xyz"); // docs:inline-xyz // Obtain orbitals from SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/orbitals.cpp b/docs/source/_static/examples/cpp/orbitals.cpp index c3f767e98..c9b9a50e8 100644 --- a/docs/source/_static/examples/cpp/orbitals.cpp +++ b/docs/source/_static/examples/cpp/orbitals.cpp @@ -14,7 +14,8 @@ using namespace qdk::chemistry::algorithms; int main() { // Obtain orbitals from a SCF calculation // Load H2 molecule from XYZ file - auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); + auto structure = + Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz // Obtain orbitals from a SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/quickstart.cpp b/docs/source/_static/examples/cpp/quickstart.cpp index 639cf5aa0..4b1ad377a 100644 --- a/docs/source/_static/examples/cpp/quickstart.cpp +++ b/docs/source/_static/examples/cpp/quickstart.cpp @@ -26,8 +26,9 @@ int main() { // --------------------------------------------------------------------------- // start-cell-structure // Load para-benzyne structure from XYZ file - auto structure = std::make_shared( - data::Structure::from_xyz_file("../data/para_benzyne.structure.xyz")); + auto structure = + std::make_shared(data::Structure::from_xyz_file( + "../data/para_benzyne.structure.xyz")); // docs:inline-xyz std::cout << "Created structure with " << structure->get_num_atoms() << " atoms" << std::endl; diff --git a/docs/source/_static/examples/cpp/scf_solver.cpp b/docs/source/_static/examples/cpp/scf_solver.cpp index ffd794636..2fd3cf4f4 100644 --- a/docs/source/_static/examples/cpp/scf_solver.cpp +++ b/docs/source/_static/examples/cpp/scf_solver.cpp @@ -29,7 +29,8 @@ int main() { // -------------------------------------------------------------------------------------------- // start-cell-run // Load structure from XYZ file - auto structure = Structure::from_xyz_file("../data/h2.structure.xyz"); + auto structure = + Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz // Run the SCF calculation auto [E_scf, wfn] = scf_solver->run(structure, 0, 1, "def2-tzvpp"); diff --git a/docs/source/_static/examples/cpp/serialization.cpp b/docs/source/_static/examples/cpp/serialization.cpp index 82de01932..150fac0c5 100644 --- a/docs/source/_static/examples/cpp/serialization.cpp +++ b/docs/source/_static/examples/cpp/serialization.cpp @@ -13,7 +13,7 @@ int main() { // Load structure from XYZ file (the file uses Angstrom, converted to Bohr // internally) Structure structure_from_file = - Structure::from_xyz_file("../data/h2.structure.xyz"); + Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz // For demonstration: create a structure with custom masses and charges // (requires explicit coordinates, here in Bohr) diff --git a/docs/source/_static/examples/python/active_space_selector.py b/docs/source/_static/examples/python/active_space_selector.py index ac780784e..f7f2727db 100644 --- a/docs/source/_static/examples/python/active_space_selector.py +++ b/docs/source/_static/examples/python/active_space_selector.py @@ -32,7 +32,7 @@ # Load a molecular structure (water molecule) from XYZ file structure = Structure.from_xyz_file( Path(__file__).parent / "../data/water.structure.xyz" -) +) # docs:inline-xyz charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/ansatz.py b/docs/source/_static/examples/python/ansatz.py index 378ac76fe..14b1856f0 100644 --- a/docs/source/_static/examples/python/ansatz.py +++ b/docs/source/_static/examples/python/ansatz.py @@ -12,7 +12,9 @@ from qdk_chemistry.algorithms import create # Load H2 molecule structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/basis_set.py b/docs/source/_static/examples/python/basis_set.py index 1669c39cf..173d82ed4 100644 --- a/docs/source/_static/examples/python/basis_set.py +++ b/docs/source/_static/examples/python/basis_set.py @@ -14,7 +14,7 @@ # Load a water molecule structure from XYZ file structure = Structure.from_xyz_file( Path(__file__).parent / "../data/water.structure.xyz" -) +) # docs:inline-xyz # Create basis sets from the library using basis set name basis_from_name = BasisSet.from_basis_name("sto-3g", structure) diff --git a/docs/source/_static/examples/python/design_principles.py b/docs/source/_static/examples/python/design_principles.py index f67159b48..2f3812ee1 100644 --- a/docs/source/_static/examples/python/design_principles.py +++ b/docs/source/_static/examples/python/design_principles.py @@ -26,7 +26,9 @@ ################################################################################ # start-cell-data-flow # Load a Structure from file (data classes in QDK/Chemistry are immutable by design) -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Configure and run SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/dynamical_correlation.py b/docs/source/_static/examples/python/dynamical_correlation.py index de737becf..03680f7ba 100644 --- a/docs/source/_static/examples/python/dynamical_correlation.py +++ b/docs/source/_static/examples/python/dynamical_correlation.py @@ -28,7 +28,9 @@ from qdk_chemistry.data import Ansatz, Structure # Load H2 structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Run initial SCF to get reference wavefunction scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/factory_pattern.py b/docs/source/_static/examples/python/factory_pattern.py index 0dfb487c5..88bd1f06d 100644 --- a/docs/source/_static/examples/python/factory_pattern.py +++ b/docs/source/_static/examples/python/factory_pattern.py @@ -12,7 +12,9 @@ from qdk_chemistry.data import Structure # Load H2 molecule from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Create a SCF solver using the default implementation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian.py b/docs/source/_static/examples/python/hamiltonian.py index 14b1c3cd8..ba5d5171a 100644 --- a/docs/source/_static/examples/python/hamiltonian.py +++ b/docs/source/_static/examples/python/hamiltonian.py @@ -14,7 +14,7 @@ # Load a structure from XYZ file structure = Structure.from_xyz_file( Path(__file__).parent / "../data/water.structure.xyz" -) +) # docs:inline-xyz # Run initial SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian_constructor.py b/docs/source/_static/examples/python/hamiltonian_constructor.py index 8206db0dd..04c381218 100644 --- a/docs/source/_static/examples/python/hamiltonian_constructor.py +++ b/docs/source/_static/examples/python/hamiltonian_constructor.py @@ -33,7 +33,9 @@ ################################################################################ # start-cell-construct # Load a structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Run a SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/interfaces.py b/docs/source/_static/examples/python/interfaces.py index 442abc048..e2f473a47 100644 --- a/docs/source/_static/examples/python/interfaces.py +++ b/docs/source/_static/examples/python/interfaces.py @@ -12,7 +12,9 @@ from qdk_chemistry.data import Structure # Load H2 molecule from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Create a SCF solver using the factory scf_solver = create("scf_solver", "pyscf") diff --git a/docs/source/_static/examples/python/localizer.py b/docs/source/_static/examples/python/localizer.py index 564e33edc..0c1f3b75f 100644 --- a/docs/source/_static/examples/python/localizer.py +++ b/docs/source/_static/examples/python/localizer.py @@ -32,7 +32,7 @@ # Load H2O molecule from XYZ file structure = Structure.from_xyz_file( Path(__file__).parent / "../data/water.structure.xyz" -) +) # docs:inline-xyz # Obtain orbitals from SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mc_calculator.py b/docs/source/_static/examples/python/mc_calculator.py index cbf578d56..9ac4eb97a 100644 --- a/docs/source/_static/examples/python/mc_calculator.py +++ b/docs/source/_static/examples/python/mc_calculator.py @@ -28,7 +28,9 @@ from qdk_chemistry.data import Structure # Load H2 structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Run SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mcscf.py b/docs/source/_static/examples/python/mcscf.py index c86d1737e..cfe9146d8 100644 --- a/docs/source/_static/examples/python/mcscf.py +++ b/docs/source/_static/examples/python/mcscf.py @@ -60,7 +60,7 @@ # Load nitrogen molecule structure structure = Structure.from_xyz_file( Path(__file__).parent / "../data/n2_stretched.structure.xyz" -) +) # docs:inline-xyz charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/orbitals.py b/docs/source/_static/examples/python/orbitals.py index 5454942cb..fde25d925 100644 --- a/docs/source/_static/examples/python/orbitals.py +++ b/docs/source/_static/examples/python/orbitals.py @@ -13,7 +13,9 @@ ################################################################################ # start-cell-create # Load H2 molecule from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Obtain orbitals from a SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/qubit_mapper.py b/docs/source/_static/examples/python/qubit_mapper.py index f2ace3146..5781d8636 100644 --- a/docs/source/_static/examples/python/qubit_mapper.py +++ b/docs/source/_static/examples/python/qubit_mapper.py @@ -30,7 +30,9 @@ from qdk_chemistry.data import Structure # Read a molecular structure from XYZ file -structure = Structure.from_xyz_file(Path(".") / "../data/water.structure.xyz") +structure = Structure.from_xyz_file( + Path(".") / "../data/water.structure.xyz" +) # docs:inline-xyz # Perform an SCF calculation to generate initial orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/quickstart.py b/docs/source/_static/examples/python/quickstart.py index fec133c0f..a280f453e 100644 --- a/docs/source/_static/examples/python/quickstart.py +++ b/docs/source/_static/examples/python/quickstart.py @@ -16,7 +16,7 @@ # Load para-benzyne structure from XYZ file structure = Structure.from_xyz_file( Path(__file__).parent / "../data/para_benzyne.structure.xyz" -) +) # docs:inline-xyz print(f"Created structure with {structure.get_num_atoms()} atoms") print(f"Elements: {structure.get_elements()}") diff --git a/docs/source/_static/examples/python/scf_solver.py b/docs/source/_static/examples/python/scf_solver.py index d1bc1ca37..b6248903a 100644 --- a/docs/source/_static/examples/python/scf_solver.py +++ b/docs/source/_static/examples/python/scf_solver.py @@ -29,7 +29,9 @@ ################################################################################ # start-cell-run # Load structure from XYZ file -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # Run scf E_scf, wfn = scf_solver.run( diff --git a/docs/source/_static/examples/python/serialization.py b/docs/source/_static/examples/python/serialization.py index 256a11608..0f8f3614a 100644 --- a/docs/source/_static/examples/python/serialization.py +++ b/docs/source/_static/examples/python/serialization.py @@ -19,7 +19,9 @@ ) # Load structure from XYZ file (the file uses Angstrom, which is converted to Bohr internally) -structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") +structure = Structure.from_xyz_file( + Path(__file__).parent / "../data/h2.structure.xyz" +) # docs:inline-xyz # For demonstration: create a structure with custom masses and charges # (requires explicit coordinates, here in Bohr) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9a0178fe9..ad8c09345 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -43,6 +43,9 @@ # compiled C++ extension (_core) from the installed package is preferred. sys.path.append(str(_repo_root / "python" / "src")) +# Add the local Sphinx extension directory (docs/source/_ext). +sys.path.insert(0, str(Path(__file__).resolve().parent / "_ext")) + # Check if Graphviz 'dot' executable is available if shutil.which("dot") is None: sys.stderr.write("ERROR: Graphviz 'dot' executable not found.\n") @@ -70,6 +73,8 @@ "sphinx.ext.graphviz", # Support for Graphviz diagrams "sphinxcontrib.bibtex", # Support for bibliographic references "sphinx_copybutton", # Add "copy" buttons to code blocks + # Local extensions (docs/source/_ext) + "inline_xyz", # Inline .xyz files into example snippets at build time ] # Configure viewcode to only show source for project modules, not dependencies From 3577cab3fde7972877606d0e6c2864621ff17c67 Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Wed, 24 Jun 2026 13:09:53 +0200 Subject: [PATCH 4/7] add warning if .xyz file not accessible --- docs/source/_ext/inline_xyz.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/source/_ext/inline_xyz.py b/docs/source/_ext/inline_xyz.py index f7028bf43..55127ae03 100644 --- a/docs/source/_ext/inline_xyz.py +++ b/docs/source/_ext/inline_xyz.py @@ -153,10 +153,15 @@ def _inline_xyz_in_text(text: str, example_dir: Path, suffix: str) -> str: continue inner = text[open_paren + 1 : close_paren] path_match = _XYZ_PATH_RE.search(inner) - if path_match is None: - continue - xyz_path = (example_dir / path_match.group(1)).resolve() - if not xyz_path.is_file(): + xyz_path = (example_dir / path_match.group(1)).resolve() if path_match else None + if xyz_path is None or not xyz_path.is_file(): + # The call opted in but we cannot inline it; warn rather than + # silently leaving ``from_xyz_file`` in the rendered output. + logger.warning( + "inline_xyz: %s marker present but no readable .xyz file found: %s", + _INLINE_MARKER, + text[call_span_start:call_span_end].strip(), + ) continue contents = xyz_path.read_text(encoding="utf-8") pieces.append(text[pos : match.start()]) From 115f09a35767ea67fc638c0615dccce8e16f7eeb Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Thu, 25 Jun 2026 15:28:07 +0200 Subject: [PATCH 5/7] examples: duplicate xyz strings to fscripts; test for consistency --- docs/source/_ext/inline_xyz.py | 214 ------------------ .../examples/cpp/active_space_selector.cpp | 9 +- docs/source/_static/examples/cpp/ansatz.cpp | 8 +- .../examples/cpp/dynamical_correlation.cpp | 8 +- .../_static/examples/cpp/hamiltonian.cpp | 9 +- .../examples/cpp/hamiltonian_constructor.cpp | 8 +- .../source/_static/examples/cpp/localizer.cpp | 9 +- docs/source/_static/examples/cpp/orbitals.cpp | 8 +- .../_static/examples/cpp/quickstart.cpp | 16 +- .../_static/examples/cpp/scf_solver.cpp | 8 +- .../_static/examples/cpp/serialization.cpp | 8 +- .../examples/python/active_space_selector.py | 12 +- docs/source/_static/examples/python/ansatz.py | 11 +- .../_static/examples/python/basis_set.py | 11 +- .../examples/python/design_principles.py | 11 +- .../examples/python/dynamical_correlation.py | 11 +- .../examples/python/factory_pattern.py | 11 +- .../_static/examples/python/hamiltonian.py | 12 +- .../python/hamiltonian_constructor.py | 11 +- .../_static/examples/python/interfaces.py | 11 +- .../_static/examples/python/localizer.py | 12 +- .../_static/examples/python/mc_calculator.py | 11 +- docs/source/_static/examples/python/mcscf.py | 11 +- .../_static/examples/python/orbitals.py | 11 +- .../_static/examples/python/qubit_mapper.py | 12 +- .../_static/examples/python/quickstart.py | 19 +- .../_static/examples/python/scf_solver.py | 11 +- .../_static/examples/python/serialization.py | 11 +- docs/source/conf.py | 5 - python/tests/test_docs_xyz_consistency.py | 61 +++++ 30 files changed, 264 insertions(+), 306 deletions(-) delete mode 100644 docs/source/_ext/inline_xyz.py create mode 100644 python/tests/test_docs_xyz_consistency.py diff --git a/docs/source/_ext/inline_xyz.py b/docs/source/_ext/inline_xyz.py deleted file mode 100644 index 55127ae03..000000000 --- a/docs/source/_ext/inline_xyz.py +++ /dev/null @@ -1,214 +0,0 @@ -# -------------------------------------------------------------------------------------------- -# Copyright (c) Microsoft Corporation. All rights reserved. -# Licensed under the MIT License. See LICENSE.txt in the project root for license information. -# -------------------------------------------------------------------------------------------- -"""Sphinx extension: inline ``.xyz`` files into example snippets at build time. - -The example scripts under ``docs/source/_static/examples`` load molecular -geometries from ``.xyz`` files, e.g.:: - - structure = Structure.from_xyz_file(Path(__file__).parent / "../data/h2.structure.xyz") - -Keeping the geometry in standalone ``.xyz`` files gives us a single source of -truth (the files are also used when the examples are executed as part of the -test suite). However, when these snippets are rendered into the documentation -via ``literalinclude``, a reader cannot access ``../data/h2.structure.xyz``. - -This extension rewrites ``from_xyz_file()`` calls into an -equivalent ``from_xyz()`` call *only in the rendered -documentation*, and only for calls that explicitly opt in (see below). The -files on disk are left untouched, so the examples remain runnable and the -``.xyz`` files remain the single source of truth. - -Python snippets become:: - - structure = Structure.from_xyz(\"\"\"\\ - 2 - H2 molecule - H 0.000000 0.000000 0.000000 - H 0.000000 0.000000 0.740848 - \"\"\") - -C++ snippets become:: - - auto structure = Structure::from_xyz(R"(2 - H2 molecule - H 0.000000 0.000000 0.000000 - H 0.000000 0.000000 0.740848 - )"); - -The rewrite hooks into ``LiteralIncludeReader.read_file`` because the -``literalinclude`` directive (unlike ``include``) does not emit the -``include-read`` event. - -Opt-in ------- -Inlining is opt-in: by default the rendered docs show exactly what is in the -file. A call is inlined only when it carries the marker comment -``docs:inline-xyz`` anywhere within the call (so it also works when a formatter -wraps the call across multiple lines):: - - structure = Structure.from_xyz_file(path) # docs:inline-xyz - -The marker itself is stripped from the rendered output so readers never see it. -Calls without the marker (e.g. the ``Structure`` file-loading tutorial) are left -verbatim as ``from_xyz_file`` calls. -""" - -from __future__ import annotations - -import re -from pathlib import Path -from typing import Any - -from sphinx.application import Sphinx -from sphinx.directives import code as _code -from sphinx.util import logging - -logger = logging.getLogger(__name__) - -# Directory containing the example snippets that may reference ``.xyz`` files. -_EXAMPLES_DIR = ( - Path(__file__).resolve().parent.parent / "_static" / "examples" -).resolve() - -# Source file types whose ``from_xyz_file`` calls should be inlined. -_PYTHON_SUFFIXES = {".py"} -_CPP_SUFFIXES = {".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".h"} - -# Matches the start of a ``from_xyz_file(`` call (Python or C++). -_CALL_RE = re.compile(r"from_xyz_file\s*\(") - -# Matches a quoted string literal that ends in ``.xyz``. -_XYZ_PATH_RE = re.compile(r"""['"]([^'"]*\.xyz)['"]""") - -# Marker comment that opts a call *into* inlining (rewritten to ``from_xyz``). -# The marker is stripped from the rendered output. -_INLINE_MARKER = "docs:inline-xyz" -_INLINE_MARKER_STRIP_RE = re.compile( - r"[ \t]*(?:#|//)[ \t]*" + re.escape(_INLINE_MARKER) + r"[ \t]*$" -) - - -def _find_matching_paren(text: str, open_idx: int) -> int: - """Return the index of the ``)`` matching the ``(`` at ``open_idx``. - - String literals are skipped so that parentheses inside quotes are ignored. - Returns ``-1`` if no matching parenthesis is found. - """ - depth = 0 - i = open_idx - in_str: str | None = None - while i < len(text): - ch = text[i] - if in_str is not None: - if ch == "\\": - i += 2 - continue - if ch == in_str: - in_str = None - elif ch in "\"'": - in_str = ch - elif ch == "(": - depth += 1 - elif ch == ")": - depth -= 1 - if depth == 0: - return i - i += 1 - return -1 - - -def _embed(contents: str, suffix: str) -> str: - """Build the inline ``from_xyz(...)`` replacement for the given contents.""" - if not contents.endswith("\n"): - contents += "\n" - if suffix in _PYTHON_SUFFIXES: - return 'from_xyz("""\\\n' + contents + '""")' - # C/C++ raw string literal keeps the contents verbatim. - return 'from_xyz(R"(' + contents + ')")' - - -def _strip_inline_markers(text: str) -> str: - """Remove trailing ``docs:inline-xyz`` marker comments from each line.""" - return "\n".join(_INLINE_MARKER_STRIP_RE.sub("", line) for line in text.split("\n")) - - -def _inline_xyz_in_text(text: str, example_dir: Path, suffix: str) -> str: - """Replace ``from_xyz_file(...)`` calls referencing ``.xyz`` files inline.""" - pieces: list[str] = [] - pos = 0 - for match in _CALL_RE.finditer(text): - open_paren = match.end() - 1 - close_paren = _find_matching_paren(text, open_paren) - if close_paren == -1: - continue - # Only inline calls that opt in via the marker anywhere within the - # (possibly multi-line) call, including trailing comments. - call_span_start = text.rfind("\n", 0, match.start()) + 1 - call_span_end = text.find("\n", close_paren) - if call_span_end == -1: - call_span_end = len(text) - if _INLINE_MARKER not in text[call_span_start:call_span_end]: - continue - inner = text[open_paren + 1 : close_paren] - path_match = _XYZ_PATH_RE.search(inner) - xyz_path = (example_dir / path_match.group(1)).resolve() if path_match else None - if xyz_path is None or not xyz_path.is_file(): - # The call opted in but we cannot inline it; warn rather than - # silently leaving ``from_xyz_file`` in the rendered output. - logger.warning( - "inline_xyz: %s marker present but no readable .xyz file found: %s", - _INLINE_MARKER, - text[call_span_start:call_span_end].strip(), - ) - continue - contents = xyz_path.read_text(encoding="utf-8") - pieces.append(text[pos : match.start()]) - pieces.append(_embed(contents, suffix)) - pos = close_paren + 1 - if not pieces: - return text - pieces.append(text[pos:]) - return "".join(pieces) - - -def _maybe_inline_xyz(filename: Path, lines: list[str]) -> list[str]: - """Inline ``.xyz`` contents for example snippets; otherwise return as-is.""" - resolved = filename.resolve() - if _EXAMPLES_DIR not in resolved.parents: - return lines - suffix = resolved.suffix.lower() - if suffix not in _PYTHON_SUFFIXES and suffix not in _CPP_SUFFIXES: - return lines - - text = "".join(lines) - if _INLINE_MARKER not in text: - return lines - - new_text = _inline_xyz_in_text(text, resolved.parent, suffix) - new_text = _strip_inline_markers(new_text) - if new_text == text: - return lines - return new_text.splitlines(keepends=True) - - -_orig_read_file = _code.LiteralIncludeReader.read_file - - -def _patched_read_file(self, filename, location=None): # type: ignore[no-untyped-def] - lines = _orig_read_file(self, filename, location=location) - try: - return _maybe_inline_xyz(Path(filename), lines) - except Exception as exc: # pragma: no cover - never break the build - logger.warning("inline_xyz: failed to inline %s: %s", filename, exc) - return lines - - -def setup(app: Sphinx) -> dict[str, Any]: - _code.LiteralIncludeReader.read_file = _patched_read_file - return { - "version": "1.0", - "parallel_read_safe": True, - "parallel_write_safe": True, - } diff --git a/docs/source/_static/examples/cpp/active_space_selector.cpp b/docs/source/_static/examples/cpp/active_space_selector.cpp index 8d3dc78b1..e49d4a8c9 100644 --- a/docs/source/_static/examples/cpp/active_space_selector.cpp +++ b/docs/source/_static/examples/cpp/active_space_selector.cpp @@ -27,10 +27,15 @@ int main() { // -------------------------------------------------------------------------------------------- // -------------------------------------------------------------------------------------------- + // docs:xyz ../data/water.structure.xyz // start-cell-run // Load a molecular structure (water molecule) from XYZ file - auto structure = Structure::from_xyz_file( - "../data/water.structure.xyz"); // docs:inline-xyz + auto structure = Structure::from_xyz(R"(3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +)"); int charge = 0; // First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/cpp/ansatz.cpp b/docs/source/_static/examples/cpp/ansatz.cpp index 375697e10..9395f676c 100644 --- a/docs/source/_static/examples/cpp/ansatz.cpp +++ b/docs/source/_static/examples/cpp/ansatz.cpp @@ -4,6 +4,7 @@ // Ansatz usage examples. // -------------------------------------------------------------------------------------------- +// docs:xyz ../data/h2.structure.xyz // start-cell-create #include #include @@ -13,8 +14,11 @@ using namespace qdk::chemistry::algorithms; int main() { // Load H2 structure from XYZ file - auto structure = - Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz + auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // SCF auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/dynamical_correlation.cpp b/docs/source/_static/examples/cpp/dynamical_correlation.cpp index 8a81037ff..8a0342624 100644 --- a/docs/source/_static/examples/cpp/dynamical_correlation.cpp +++ b/docs/source/_static/examples/cpp/dynamical_correlation.cpp @@ -24,10 +24,14 @@ auto mp2_calculator = // ----------------------------------------------------------------------------- // ----------------------------------------------------------------------------- +// docs:xyz ../data/h2.structure.xyz // start-cell-run // Load H2 structure from XYZ file -auto structure = - Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz +auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Run initial SCF to get reference wavefunction auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian.cpp b/docs/source/_static/examples/cpp/hamiltonian.cpp index a85a5af3b..f09dbfd8d 100644 --- a/docs/source/_static/examples/cpp/hamiltonian.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian.cpp @@ -4,10 +4,15 @@ // Hamiltonian usage examples. // -------------------------------------------------------------------------------------------- +// docs:xyz ../data/water.structure.xyz // start-cell-hamiltonian-creation // Load structure from XYZ file -auto structure = - Structure::from_xyz_file("../data/water.structure.xyz"); // docs:inline-xyz +auto structure = Structure::from_xyz(R"(3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +)"); // Run initial SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp index b5ca3500e..78a11dad3 100644 --- a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp @@ -25,10 +25,14 @@ hamiltonian_constructor->settings().set("eri_method", "direct"); // -------------------------------------------------------------------------------------------- // -------------------------------------------------------------------------------------------- +// docs:xyz ../data/h2.structure.xyz // start-cell-construct // Load structure from XYZ file -auto structure = std::make_shared( - Structure::from_xyz_file("../data/h2.structure.xyz")); // docs:inline-xyz +auto structure = std::make_shared(Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)")); // Run a SCF to get orbitals auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/localizer.cpp b/docs/source/_static/examples/cpp/localizer.cpp index 1b016a1c0..d2b16c656 100644 --- a/docs/source/_static/examples/cpp/localizer.cpp +++ b/docs/source/_static/examples/cpp/localizer.cpp @@ -28,10 +28,15 @@ int main() { // -------------------------------------------------------------------------------------------- // -------------------------------------------------------------------------------------------- + // docs:xyz ../data/water.structure.xyz // start-cell-localize // Load H2O molecule from XYZ file - auto structure = Structure::from_xyz_file( - "../data/water.structure.xyz"); // docs:inline-xyz + auto structure = Structure::from_xyz(R"(3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +)"); // Obtain orbitals from SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/orbitals.cpp b/docs/source/_static/examples/cpp/orbitals.cpp index c9b9a50e8..e7fe6ef42 100644 --- a/docs/source/_static/examples/cpp/orbitals.cpp +++ b/docs/source/_static/examples/cpp/orbitals.cpp @@ -4,6 +4,7 @@ // Orbitals usage examples. // -------------------------------------------------------------------------------------------- +// docs:xyz ../data/h2.structure.xyz // start-cell-create #include #include @@ -14,8 +15,11 @@ using namespace qdk::chemistry::algorithms; int main() { // Obtain orbitals from a SCF calculation // Load H2 molecule from XYZ file - auto structure = - Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz + auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Obtain orbitals from a SCF calculation auto scf_solver = ScfSolverFactory::create(); diff --git a/docs/source/_static/examples/cpp/quickstart.cpp b/docs/source/_static/examples/cpp/quickstart.cpp index 4b1ad377a..6d66e1d6d 100644 --- a/docs/source/_static/examples/cpp/quickstart.cpp +++ b/docs/source/_static/examples/cpp/quickstart.cpp @@ -24,11 +24,23 @@ using namespace qdk::chemistry; int main() { // --------------------------------------------------------------------------- + // docs:xyz ../data/para_benzyne.structure.xyz // start-cell-structure // Load para-benzyne structure from XYZ file auto structure = - std::make_shared(data::Structure::from_xyz_file( - "../data/para_benzyne.structure.xyz")); // docs:inline-xyz + std::make_shared(data::Structure::from_xyz(R"(10 +para-Benzyne +C 0.000000 1.396000 0.000000 +C 1.209077 0.698000 0.000000 +C 1.209077 -0.698000 0.000000 +C 0.000000 -1.396000 0.000000 +C -1.209077 -0.698000 0.000000 +C -1.209077 0.698000 0.000000 +H 2.151000 1.242000 0.000000 +H 2.151000 -1.242000 0.000000 +H -2.151000 -1.242000 0.000000 +H -2.151000 1.242000 0.000000 +)")); std::cout << "Created structure with " << structure->get_num_atoms() << " atoms" << std::endl; diff --git a/docs/source/_static/examples/cpp/scf_solver.cpp b/docs/source/_static/examples/cpp/scf_solver.cpp index 2fd3cf4f4..640c68387 100644 --- a/docs/source/_static/examples/cpp/scf_solver.cpp +++ b/docs/source/_static/examples/cpp/scf_solver.cpp @@ -27,10 +27,14 @@ int main() { // -------------------------------------------------------------------------------------------- // -------------------------------------------------------------------------------------------- + // docs:xyz ../data/h2.structure.xyz // start-cell-run // Load structure from XYZ file - auto structure = - Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz + auto structure = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // Run the SCF calculation auto [E_scf, wfn] = scf_solver->run(structure, 0, 1, "def2-tzvpp"); diff --git a/docs/source/_static/examples/cpp/serialization.cpp b/docs/source/_static/examples/cpp/serialization.cpp index 150fac0c5..ebfdbe4a1 100644 --- a/docs/source/_static/examples/cpp/serialization.cpp +++ b/docs/source/_static/examples/cpp/serialization.cpp @@ -4,6 +4,7 @@ // Serialization usage examples. // -------------------------------------------------------------------------------------------- +// docs:xyz ../data/h2.structure.xyz // start-cell-json #include #include @@ -12,8 +13,11 @@ using namespace qdk::chemistry::data; int main() { // Load structure from XYZ file (the file uses Angstrom, converted to Bohr // internally) - Structure structure_from_file = - Structure::from_xyz_file("../data/h2.structure.xyz"); // docs:inline-xyz + Structure structure_from_file = Structure::from_xyz(R"(2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +)"); // For demonstration: create a structure with custom masses and charges // (requires explicit coordinates, here in Bohr) diff --git a/docs/source/_static/examples/python/active_space_selector.py b/docs/source/_static/examples/python/active_space_selector.py index f7f2727db..738ac5bc7 100644 --- a/docs/source/_static/examples/python/active_space_selector.py +++ b/docs/source/_static/examples/python/active_space_selector.py @@ -25,14 +25,18 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/water.structure.xyz # start-cell-run -from pathlib import Path from qdk_chemistry.data import Structure # Load a molecular structure (water molecule) from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/ansatz.py b/docs/source/_static/examples/python/ansatz.py index 14b1856f0..6c98961f8 100644 --- a/docs/source/_static/examples/python/ansatz.py +++ b/docs/source/_static/examples/python/ansatz.py @@ -6,15 +6,18 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-create -from pathlib import Path from qdk_chemistry.data import Ansatz, Structure from qdk_chemistry.algorithms import create # Load H2 molecule structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/basis_set.py b/docs/source/_static/examples/python/basis_set.py index 173d82ed4..6255a011f 100644 --- a/docs/source/_static/examples/python/basis_set.py +++ b/docs/source/_static/examples/python/basis_set.py @@ -6,15 +6,20 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/water.structure.xyz # start-cell-loading import numpy as np from pathlib import Path from qdk_chemistry.data import AOType, BasisSet, OrbitalType, Shell, Structure # Load a water molecule structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Create basis sets from the library using basis set name basis_from_name = BasisSet.from_basis_name("sto-3g", structure) diff --git a/docs/source/_static/examples/python/design_principles.py b/docs/source/_static/examples/python/design_principles.py index 2f3812ee1..c4ea741dc 100644 --- a/docs/source/_static/examples/python/design_principles.py +++ b/docs/source/_static/examples/python/design_principles.py @@ -7,7 +7,6 @@ ################################################################################ # start-cell-scf-create -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure @@ -24,11 +23,15 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-data-flow # Load a Structure from file (data classes in QDK/Chemistry are immutable by design) -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Configure and run SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/dynamical_correlation.py b/docs/source/_static/examples/python/dynamical_correlation.py index 03680f7ba..b25e195f2 100644 --- a/docs/source/_static/examples/python/dynamical_correlation.py +++ b/docs/source/_static/examples/python/dynamical_correlation.py @@ -22,15 +22,18 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-run -from pathlib import Path from qdk_chemistry.data import Ansatz, Structure # Load H2 structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run initial SCF to get reference wavefunction scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/factory_pattern.py b/docs/source/_static/examples/python/factory_pattern.py index 88bd1f06d..65f60f5cb 100644 --- a/docs/source/_static/examples/python/factory_pattern.py +++ b/docs/source/_static/examples/python/factory_pattern.py @@ -6,15 +6,18 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-scf-localizer -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure # Load H2 molecule from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Create a SCF solver using the default implementation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian.py b/docs/source/_static/examples/python/hamiltonian.py index ba5d5171a..1b7796b53 100644 --- a/docs/source/_static/examples/python/hamiltonian.py +++ b/docs/source/_static/examples/python/hamiltonian.py @@ -6,15 +6,19 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/water.structure.xyz # start-cell-hamiltonian-creation -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, SpinChannel # Load a structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Run initial SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/hamiltonian_constructor.py b/docs/source/_static/examples/python/hamiltonian_constructor.py index 04c381218..d8a2f8050 100644 --- a/docs/source/_static/examples/python/hamiltonian_constructor.py +++ b/docs/source/_static/examples/python/hamiltonian_constructor.py @@ -4,7 +4,6 @@ # Copyright (c) Microsoft Corporation. All rights reserved. # Licensed under the MIT License. See LICENSE.txt in the project root for license information. # -------------------------------------------------------------------------------------------- -from pathlib import Path from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure @@ -31,11 +30,15 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-construct # Load a structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run a SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/interfaces.py b/docs/source/_static/examples/python/interfaces.py index e2f473a47..f335fe38d 100644 --- a/docs/source/_static/examples/python/interfaces.py +++ b/docs/source/_static/examples/python/interfaces.py @@ -6,15 +6,18 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-scf -from pathlib import Path from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure # Load H2 molecule from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Create a SCF solver using the factory scf_solver = create("scf_solver", "pyscf") diff --git a/docs/source/_static/examples/python/localizer.py b/docs/source/_static/examples/python/localizer.py index 0c1f3b75f..2cb644d6d 100644 --- a/docs/source/_static/examples/python/localizer.py +++ b/docs/source/_static/examples/python/localizer.py @@ -7,7 +7,6 @@ ################################################################################ # start-cell-create -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure @@ -28,11 +27,16 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/water.structure.xyz # start-cell-localize # Load H2O molecule from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/water.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Obtain orbitals from SCF scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mc_calculator.py b/docs/source/_static/examples/python/mc_calculator.py index 9ac4eb97a..25ca32e10 100644 --- a/docs/source/_static/examples/python/mc_calculator.py +++ b/docs/source/_static/examples/python/mc_calculator.py @@ -22,15 +22,18 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-run -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure # Load H2 structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run SCF to get orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/mcscf.py b/docs/source/_static/examples/python/mcscf.py index cfe9146d8..83fb91950 100644 --- a/docs/source/_static/examples/python/mcscf.py +++ b/docs/source/_static/examples/python/mcscf.py @@ -52,15 +52,18 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/n2_stretched.structure.xyz # start-cell-run -from pathlib import Path from qdk_chemistry.data import Structure from qdk_chemistry.utils import compute_valence_space_parameters # Load nitrogen molecule structure -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/n2_stretched.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 + +N 0 0 0 +N 0 0 2 +""") charge = 0 # First, run SCF to get molecular orbitals diff --git a/docs/source/_static/examples/python/orbitals.py b/docs/source/_static/examples/python/orbitals.py index fde25d925..58e674291 100644 --- a/docs/source/_static/examples/python/orbitals.py +++ b/docs/source/_static/examples/python/orbitals.py @@ -5,17 +5,20 @@ # Licensed under the MIT License. See LICENSE.txt in the project root for license information. # -------------------------------------------------------------------------------------------- -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, ModelOrbitals from qdk_chemistry.data.symmetry import spin_index_set ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-create # Load H2 molecule from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Obtain orbitals from a SCF calculation scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/qubit_mapper.py b/docs/source/_static/examples/python/qubit_mapper.py index 5781d8636..e604812cc 100644 --- a/docs/source/_static/examples/python/qubit_mapper.py +++ b/docs/source/_static/examples/python/qubit_mapper.py @@ -24,15 +24,19 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/water.structure.xyz # start-cell-run -from pathlib import Path from qdk_chemistry.data import Structure # Read a molecular structure from XYZ file -structure = Structure.from_xyz_file( - Path(".") / "../data/water.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +3 +Water molecule +O 0.000000 0.000000 0.000000 +H 0.758602 0.000000 0.504284 +H -0.758602 0.000000 0.504284 +""") # Perform an SCF calculation to generate initial orbitals scf_solver = create("scf_solver") diff --git a/docs/source/_static/examples/python/quickstart.py b/docs/source/_static/examples/python/quickstart.py index a280f453e..6c6ccd9a0 100644 --- a/docs/source/_static/examples/python/quickstart.py +++ b/docs/source/_static/examples/python/quickstart.py @@ -6,17 +6,28 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/para_benzyne.structure.xyz # start-cell-structure -from pathlib import Path import numpy as np from qdk_chemistry.algorithms import create from qdk_chemistry.data import AlgorithmRef, Structure # Load para-benzyne structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/para_benzyne.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +10 +para-Benzyne +C 0.000000 1.396000 0.000000 +C 1.209077 0.698000 0.000000 +C 1.209077 -0.698000 0.000000 +C 0.000000 -1.396000 0.000000 +C -1.209077 -0.698000 0.000000 +C -1.209077 0.698000 0.000000 +H 2.151000 1.242000 0.000000 +H 2.151000 -1.242000 0.000000 +H -2.151000 -1.242000 0.000000 +H -2.151000 1.242000 0.000000 +""") print(f"Created structure with {structure.get_num_atoms()} atoms") print(f"Elements: {structure.get_elements()}") diff --git a/docs/source/_static/examples/python/scf_solver.py b/docs/source/_static/examples/python/scf_solver.py index b6248903a..d06878d2b 100644 --- a/docs/source/_static/examples/python/scf_solver.py +++ b/docs/source/_static/examples/python/scf_solver.py @@ -8,7 +8,6 @@ ################################################################################ # start-cell-create import numpy as np -from pathlib import Path from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, BasisSet @@ -27,11 +26,15 @@ ################################################################################ ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-run # Load structure from XYZ file -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # Run scf E_scf, wfn = scf_solver.run( diff --git a/docs/source/_static/examples/python/serialization.py b/docs/source/_static/examples/python/serialization.py index 0f8f3614a..2be4d6413 100644 --- a/docs/source/_static/examples/python/serialization.py +++ b/docs/source/_static/examples/python/serialization.py @@ -6,9 +6,9 @@ # -------------------------------------------------------------------------------------------- ################################################################################ +# docs:xyz ../data/h2.structure.xyz # start-cell-json import os -from pathlib import Path import numpy as np from qdk_chemistry.data import ( @@ -19,9 +19,12 @@ ) # Load structure from XYZ file (the file uses Angstrom, which is converted to Bohr internally) -structure = Structure.from_xyz_file( - Path(__file__).parent / "../data/h2.structure.xyz" -) # docs:inline-xyz +structure = Structure.from_xyz("""\ +2 +H2 molecule +H 0.000000 0.000000 0.000000 +H 0.000000 0.000000 0.740848 +""") # For demonstration: create a structure with custom masses and charges # (requires explicit coordinates, here in Bohr) diff --git a/docs/source/conf.py b/docs/source/conf.py index ad8c09345..9a0178fe9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -43,9 +43,6 @@ # compiled C++ extension (_core) from the installed package is preferred. sys.path.append(str(_repo_root / "python" / "src")) -# Add the local Sphinx extension directory (docs/source/_ext). -sys.path.insert(0, str(Path(__file__).resolve().parent / "_ext")) - # Check if Graphviz 'dot' executable is available if shutil.which("dot") is None: sys.stderr.write("ERROR: Graphviz 'dot' executable not found.\n") @@ -73,8 +70,6 @@ "sphinx.ext.graphviz", # Support for Graphviz diagrams "sphinxcontrib.bibtex", # Support for bibliographic references "sphinx_copybutton", # Add "copy" buttons to code blocks - # Local extensions (docs/source/_ext) - "inline_xyz", # Inline .xyz files into example snippets at build time ] # Configure viewcode to only show source for project modules, not dependencies diff --git a/python/tests/test_docs_xyz_consistency.py b/python/tests/test_docs_xyz_consistency.py new file mode 100644 index 000000000..b8f0d8fe1 --- /dev/null +++ b/python/tests/test_docs_xyz_consistency.py @@ -0,0 +1,61 @@ +"""Verify inlined ``from_xyz(...)`` blobs in docs examples match their .xyz files. + +The documentation examples hard-code molecular geometries inline so that the +rendered snippet, the executed code, and the tested code are identical. Each +inlined blob is tagged with a hidden ``docs:xyz `` comment (placed outside +the rendered cell window) pointing at the canonical ``.xyz`` file. This test +keeps the two in sync: if a ``.xyz`` file changes, the inline blob must be +updated to match (and vice versa). +""" + +# -------------------------------------------------------------------------------------------- +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. See LICENSE.txt in the project root for license information. +# -------------------------------------------------------------------------------------------- + +import re +from pathlib import Path + +import pytest + +EXAMPLES_DIR = Path(__file__).parent.parent.parent / "docs" / "source" / "_static" / "examples" + +_TAG_RE = re.compile(r"(?:#|//)\s*docs:xyz\s+(\S+)") +_PY_BLOB_RE = re.compile(r'from_xyz\("""\\?\n(.*?)"""', re.DOTALL) +_CPP_BLOB_RE = re.compile(r'from_xyz\(R"\((.*?)\)"\)', re.DOTALL) + + +def _example_files() -> list[Path]: + """Return all Python and C++ example source files.""" + return [p for p in sorted(EXAMPLES_DIR.rglob("*")) if p.suffix.lower() in {".py", ".cpp"}] + + +def _inlined_examples() -> list[Path]: + """Example files that contain at least one ``docs:xyz`` tag.""" + return [p for p in _example_files() if _TAG_RE.search(p.read_text(encoding="utf-8"))] + + +def test_some_examples_are_inlined(): + """Guard against the regexes silently matching nothing.""" + assert _inlined_examples(), "no docs examples with inlined from_xyz blobs were found" + + +@pytest.mark.parametrize("path", _inlined_examples(), ids=lambda p: str(p.relative_to(EXAMPLES_DIR))) +def test_inline_blobs_match_xyz_files(path: Path): + """Each inlined from_xyz blob must match its tagged .xyz file byte-for-byte.""" + text = path.read_text(encoding="utf-8") + tags = _TAG_RE.findall(text) + blob_re = _PY_BLOB_RE if path.suffix.lower() == ".py" else _CPP_BLOB_RE + blobs = blob_re.findall(text) + + assert len(tags) == len(blobs), f"{path}: {len(tags)} docs:xyz tag(s) but {len(blobs)} from_xyz blob(s)" + + for rel, blob in zip(tags, blobs, strict=True): + xyz_file = (path.parent / rel).resolve() + assert xyz_file.is_file(), f"{path}: docs:xyz target not found: {rel}" + expected = xyz_file.read_text(encoding="utf-8").rstrip("\n") + assert blob.rstrip("\n") == expected, f"{path}: inline blob does not match {rel}" + + +if __name__ == "__main__": + raise SystemExit(pytest.main([__file__, "-v"])) From 890d561f562da778c267c231ad055104d426cf6a Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Thu, 25 Jun 2026 17:46:04 +0300 Subject: [PATCH 6/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- python/tests/test_docs_xyz_consistency.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/python/tests/test_docs_xyz_consistency.py b/python/tests/test_docs_xyz_consistency.py index b8f0d8fe1..e42955517 100644 --- a/python/tests/test_docs_xyz_consistency.py +++ b/python/tests/test_docs_xyz_consistency.py @@ -50,8 +50,10 @@ def test_inline_blobs_match_xyz_files(path: Path): assert len(tags) == len(blobs), f"{path}: {len(tags)} docs:xyz tag(s) but {len(blobs)} from_xyz blob(s)" + data_root = (EXAMPLES_DIR / "data").resolve() for rel, blob in zip(tags, blobs, strict=True): xyz_file = (path.parent / rel).resolve() + assert xyz_file.is_relative_to(data_root), f"{path}: docs:xyz target must be under {data_root}: {rel}" assert xyz_file.is_file(), f"{path}: docs:xyz target not found: {rel}" expected = xyz_file.read_text(encoding="utf-8").rstrip("\n") assert blob.rstrip("\n") == expected, f"{path}: inline blob does not match {rel}" From 6b5563a2e84bd3d23d9c991b36a25b9903da53ea Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Thu, 25 Jun 2026 17:17:15 +0200 Subject: [PATCH 7/7] update comments --- docs/source/_static/examples/cpp/active_space_selector.cpp | 2 +- docs/source/_static/examples/cpp/ansatz.cpp | 2 +- docs/source/_static/examples/cpp/dynamical_correlation.cpp | 2 +- docs/source/_static/examples/cpp/hamiltonian.cpp | 2 +- docs/source/_static/examples/cpp/hamiltonian_constructor.cpp | 2 +- docs/source/_static/examples/cpp/localizer.cpp | 2 +- docs/source/_static/examples/cpp/orbitals.cpp | 2 +- docs/source/_static/examples/cpp/quickstart.cpp | 2 +- docs/source/_static/examples/cpp/scf_solver.cpp | 2 +- docs/source/_static/examples/cpp/serialization.cpp | 4 ++-- docs/source/_static/examples/python/active_space_selector.py | 2 +- docs/source/_static/examples/python/ansatz.py | 2 +- docs/source/_static/examples/python/basis_set.py | 2 +- docs/source/_static/examples/python/design_principles.py | 2 +- docs/source/_static/examples/python/dynamical_correlation.py | 2 +- docs/source/_static/examples/python/factory_pattern.py | 2 +- docs/source/_static/examples/python/hamiltonian.py | 2 +- .../source/_static/examples/python/hamiltonian_constructor.py | 2 +- docs/source/_static/examples/python/interfaces.py | 2 +- docs/source/_static/examples/python/localizer.py | 2 +- docs/source/_static/examples/python/mc_calculator.py | 2 +- docs/source/_static/examples/python/mcscf.py | 2 +- docs/source/_static/examples/python/orbitals.py | 2 +- docs/source/_static/examples/python/qubit_mapper.py | 2 +- docs/source/_static/examples/python/quickstart.py | 2 +- docs/source/_static/examples/python/scf_solver.py | 2 +- docs/source/_static/examples/python/serialization.py | 2 +- 27 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/source/_static/examples/cpp/active_space_selector.cpp b/docs/source/_static/examples/cpp/active_space_selector.cpp index e49d4a8c9..a5675256f 100644 --- a/docs/source/_static/examples/cpp/active_space_selector.cpp +++ b/docs/source/_static/examples/cpp/active_space_selector.cpp @@ -29,7 +29,7 @@ int main() { // -------------------------------------------------------------------------------------------- // docs:xyz ../data/water.structure.xyz // start-cell-run - // Load a molecular structure (water molecule) from XYZ file + // Load a molecular structure (water molecule) from inline XYZ file auto structure = Structure::from_xyz(R"(3 Water molecule O 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/ansatz.cpp b/docs/source/_static/examples/cpp/ansatz.cpp index 9395f676c..d56fd508a 100644 --- a/docs/source/_static/examples/cpp/ansatz.cpp +++ b/docs/source/_static/examples/cpp/ansatz.cpp @@ -13,7 +13,7 @@ using namespace qdk::chemistry::data; using namespace qdk::chemistry::algorithms; int main() { - // Load H2 structure from XYZ file + // Load H2 structure from inline XYZ file auto structure = Structure::from_xyz(R"(2 H2 molecule H 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/dynamical_correlation.cpp b/docs/source/_static/examples/cpp/dynamical_correlation.cpp index 8a0342624..b125efa30 100644 --- a/docs/source/_static/examples/cpp/dynamical_correlation.cpp +++ b/docs/source/_static/examples/cpp/dynamical_correlation.cpp @@ -26,7 +26,7 @@ auto mp2_calculator = // ----------------------------------------------------------------------------- // docs:xyz ../data/h2.structure.xyz // start-cell-run -// Load H2 structure from XYZ file +// Load H2 structure from inline XYZ file auto structure = Structure::from_xyz(R"(2 H2 molecule H 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/hamiltonian.cpp b/docs/source/_static/examples/cpp/hamiltonian.cpp index f09dbfd8d..865111748 100644 --- a/docs/source/_static/examples/cpp/hamiltonian.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian.cpp @@ -6,7 +6,7 @@ // -------------------------------------------------------------------------------------------- // docs:xyz ../data/water.structure.xyz // start-cell-hamiltonian-creation -// Load structure from XYZ file +// Load structure from inline XYZ file auto structure = Structure::from_xyz(R"(3 Water molecule O 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp index 78a11dad3..be1dd44c8 100644 --- a/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp +++ b/docs/source/_static/examples/cpp/hamiltonian_constructor.cpp @@ -27,7 +27,7 @@ hamiltonian_constructor->settings().set("eri_method", "direct"); // -------------------------------------------------------------------------------------------- // docs:xyz ../data/h2.structure.xyz // start-cell-construct -// Load structure from XYZ file +// Load structure from inline XYZ file auto structure = std::make_shared(Structure::from_xyz(R"(2 H2 molecule H 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/localizer.cpp b/docs/source/_static/examples/cpp/localizer.cpp index d2b16c656..4643ea4ee 100644 --- a/docs/source/_static/examples/cpp/localizer.cpp +++ b/docs/source/_static/examples/cpp/localizer.cpp @@ -30,7 +30,7 @@ int main() { // -------------------------------------------------------------------------------------------- // docs:xyz ../data/water.structure.xyz // start-cell-localize - // Load H2O molecule from XYZ file + // Load H2O molecule from inline XYZ file auto structure = Structure::from_xyz(R"(3 Water molecule O 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/orbitals.cpp b/docs/source/_static/examples/cpp/orbitals.cpp index e7fe6ef42..f560ff6b1 100644 --- a/docs/source/_static/examples/cpp/orbitals.cpp +++ b/docs/source/_static/examples/cpp/orbitals.cpp @@ -14,7 +14,7 @@ using namespace qdk::chemistry::algorithms; int main() { // Obtain orbitals from a SCF calculation - // Load H2 molecule from XYZ file + // Load H2 molecule from inline XYZ file auto structure = Structure::from_xyz(R"(2 H2 molecule H 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/quickstart.cpp b/docs/source/_static/examples/cpp/quickstart.cpp index 6d66e1d6d..faae3333b 100644 --- a/docs/source/_static/examples/cpp/quickstart.cpp +++ b/docs/source/_static/examples/cpp/quickstart.cpp @@ -26,7 +26,7 @@ int main() { // --------------------------------------------------------------------------- // docs:xyz ../data/para_benzyne.structure.xyz // start-cell-structure - // Load para-benzyne structure from XYZ file + // Load para-benzyne structure from inline XYZ file auto structure = std::make_shared(data::Structure::from_xyz(R"(10 para-Benzyne diff --git a/docs/source/_static/examples/cpp/scf_solver.cpp b/docs/source/_static/examples/cpp/scf_solver.cpp index 640c68387..44a0a2dc2 100644 --- a/docs/source/_static/examples/cpp/scf_solver.cpp +++ b/docs/source/_static/examples/cpp/scf_solver.cpp @@ -29,7 +29,7 @@ int main() { // -------------------------------------------------------------------------------------------- // docs:xyz ../data/h2.structure.xyz // start-cell-run - // Load structure from XYZ file + // Load structure from inline XYZ file auto structure = Structure::from_xyz(R"(2 H2 molecule H 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/cpp/serialization.cpp b/docs/source/_static/examples/cpp/serialization.cpp index ebfdbe4a1..fbe56717b 100644 --- a/docs/source/_static/examples/cpp/serialization.cpp +++ b/docs/source/_static/examples/cpp/serialization.cpp @@ -11,8 +11,8 @@ using namespace qdk::chemistry::data; int main() { - // Load structure from XYZ file (the file uses Angstrom, converted to Bohr - // internally) + // Load structure from inline XYZ file (the data uses Angstrom, converted to + // Bohr internally) Structure structure_from_file = Structure::from_xyz(R"(2 H2 molecule H 0.000000 0.000000 0.000000 diff --git a/docs/source/_static/examples/python/active_space_selector.py b/docs/source/_static/examples/python/active_space_selector.py index 738ac5bc7..4d3375011 100644 --- a/docs/source/_static/examples/python/active_space_selector.py +++ b/docs/source/_static/examples/python/active_space_selector.py @@ -29,7 +29,7 @@ # start-cell-run from qdk_chemistry.data import Structure -# Load a molecular structure (water molecule) from XYZ file +# Load a molecular structure (water molecule) from inline XYZ file structure = Structure.from_xyz("""\ 3 Water molecule diff --git a/docs/source/_static/examples/python/ansatz.py b/docs/source/_static/examples/python/ansatz.py index 6c98961f8..2a10d918b 100644 --- a/docs/source/_static/examples/python/ansatz.py +++ b/docs/source/_static/examples/python/ansatz.py @@ -11,7 +11,7 @@ from qdk_chemistry.data import Ansatz, Structure from qdk_chemistry.algorithms import create -# Load H2 molecule structure from XYZ file +# Load H2 molecule structure from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/basis_set.py b/docs/source/_static/examples/python/basis_set.py index 6255a011f..d5a3ce7e5 100644 --- a/docs/source/_static/examples/python/basis_set.py +++ b/docs/source/_static/examples/python/basis_set.py @@ -12,7 +12,7 @@ from pathlib import Path from qdk_chemistry.data import AOType, BasisSet, OrbitalType, Shell, Structure -# Load a water molecule structure from XYZ file +# Load a water molecule structure from inline XYZ file structure = Structure.from_xyz("""\ 3 Water molecule diff --git a/docs/source/_static/examples/python/design_principles.py b/docs/source/_static/examples/python/design_principles.py index c4ea741dc..fb6638b4b 100644 --- a/docs/source/_static/examples/python/design_principles.py +++ b/docs/source/_static/examples/python/design_principles.py @@ -25,7 +25,7 @@ ################################################################################ # docs:xyz ../data/h2.structure.xyz # start-cell-data-flow -# Load a Structure from file (data classes in QDK/Chemistry are immutable by design) +# Load a Structure from inline XYZ file (data classes in QDK/Chemistry are immutable by design) structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/dynamical_correlation.py b/docs/source/_static/examples/python/dynamical_correlation.py index b25e195f2..0f52197db 100644 --- a/docs/source/_static/examples/python/dynamical_correlation.py +++ b/docs/source/_static/examples/python/dynamical_correlation.py @@ -27,7 +27,7 @@ from qdk_chemistry.data import Ansatz, Structure -# Load H2 structure from XYZ file +# Load H2 structure from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/factory_pattern.py b/docs/source/_static/examples/python/factory_pattern.py index 65f60f5cb..df0ac8f23 100644 --- a/docs/source/_static/examples/python/factory_pattern.py +++ b/docs/source/_static/examples/python/factory_pattern.py @@ -11,7 +11,7 @@ from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure -# Load H2 molecule from XYZ file +# Load H2 molecule from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/hamiltonian.py b/docs/source/_static/examples/python/hamiltonian.py index 1b7796b53..1d97800f5 100644 --- a/docs/source/_static/examples/python/hamiltonian.py +++ b/docs/source/_static/examples/python/hamiltonian.py @@ -11,7 +11,7 @@ from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure, SpinChannel -# Load a structure from XYZ file +# Load a structure from inline XYZ file structure = Structure.from_xyz("""\ 3 Water molecule diff --git a/docs/source/_static/examples/python/hamiltonian_constructor.py b/docs/source/_static/examples/python/hamiltonian_constructor.py index d8a2f8050..862e9a48a 100644 --- a/docs/source/_static/examples/python/hamiltonian_constructor.py +++ b/docs/source/_static/examples/python/hamiltonian_constructor.py @@ -32,7 +32,7 @@ ################################################################################ # docs:xyz ../data/h2.structure.xyz # start-cell-construct -# Load a structure from XYZ file +# Load a structure from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/interfaces.py b/docs/source/_static/examples/python/interfaces.py index f335fe38d..ebdc5fc1b 100644 --- a/docs/source/_static/examples/python/interfaces.py +++ b/docs/source/_static/examples/python/interfaces.py @@ -11,7 +11,7 @@ from qdk_chemistry.algorithms import available, create from qdk_chemistry.data import Structure -# Load H2 molecule from XYZ file +# Load H2 molecule from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/localizer.py b/docs/source/_static/examples/python/localizer.py index 2cb644d6d..20bc39c49 100644 --- a/docs/source/_static/examples/python/localizer.py +++ b/docs/source/_static/examples/python/localizer.py @@ -29,7 +29,7 @@ ################################################################################ # docs:xyz ../data/water.structure.xyz # start-cell-localize -# Load H2O molecule from XYZ file +# Load H2O molecule from inline XYZ file structure = Structure.from_xyz("""\ 3 Water molecule diff --git a/docs/source/_static/examples/python/mc_calculator.py b/docs/source/_static/examples/python/mc_calculator.py index 25ca32e10..896ecafa6 100644 --- a/docs/source/_static/examples/python/mc_calculator.py +++ b/docs/source/_static/examples/python/mc_calculator.py @@ -27,7 +27,7 @@ from qdk_chemistry.algorithms import create from qdk_chemistry.data import Structure -# Load H2 structure from XYZ file +# Load H2 structure from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/mcscf.py b/docs/source/_static/examples/python/mcscf.py index 83fb91950..2660633c6 100644 --- a/docs/source/_static/examples/python/mcscf.py +++ b/docs/source/_static/examples/python/mcscf.py @@ -57,7 +57,7 @@ from qdk_chemistry.data import Structure from qdk_chemistry.utils import compute_valence_space_parameters -# Load nitrogen molecule structure +# Load nitrogen molecule structure from inline XYZ file structure = Structure.from_xyz("""\ 2 diff --git a/docs/source/_static/examples/python/orbitals.py b/docs/source/_static/examples/python/orbitals.py index 58e674291..483901158 100644 --- a/docs/source/_static/examples/python/orbitals.py +++ b/docs/source/_static/examples/python/orbitals.py @@ -12,7 +12,7 @@ ################################################################################ # docs:xyz ../data/h2.structure.xyz # start-cell-create -# Load H2 molecule from XYZ file +# Load H2 molecule from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/qubit_mapper.py b/docs/source/_static/examples/python/qubit_mapper.py index e604812cc..f07b954b9 100644 --- a/docs/source/_static/examples/python/qubit_mapper.py +++ b/docs/source/_static/examples/python/qubit_mapper.py @@ -29,7 +29,7 @@ from qdk_chemistry.data import Structure -# Read a molecular structure from XYZ file +# Read a molecular structure from inline XYZ file structure = Structure.from_xyz("""\ 3 Water molecule diff --git a/docs/source/_static/examples/python/quickstart.py b/docs/source/_static/examples/python/quickstart.py index 6c6ccd9a0..dfb0309f4 100644 --- a/docs/source/_static/examples/python/quickstart.py +++ b/docs/source/_static/examples/python/quickstart.py @@ -13,7 +13,7 @@ from qdk_chemistry.algorithms import create from qdk_chemistry.data import AlgorithmRef, Structure -# Load para-benzyne structure from XYZ file +# Load para-benzyne structure from inline XYZ file structure = Structure.from_xyz("""\ 10 para-Benzyne diff --git a/docs/source/_static/examples/python/scf_solver.py b/docs/source/_static/examples/python/scf_solver.py index d06878d2b..fb38ec28d 100644 --- a/docs/source/_static/examples/python/scf_solver.py +++ b/docs/source/_static/examples/python/scf_solver.py @@ -28,7 +28,7 @@ ################################################################################ # docs:xyz ../data/h2.structure.xyz # start-cell-run -# Load structure from XYZ file +# Load structure from inline XYZ file structure = Structure.from_xyz("""\ 2 H2 molecule diff --git a/docs/source/_static/examples/python/serialization.py b/docs/source/_static/examples/python/serialization.py index 2be4d6413..32a31a24f 100644 --- a/docs/source/_static/examples/python/serialization.py +++ b/docs/source/_static/examples/python/serialization.py @@ -18,7 +18,7 @@ ModelOrbitals, ) -# Load structure from XYZ file (the file uses Angstrom, which is converted to Bohr internally) +# Load structure from inline XYZ file (the data uses Angstrom, which is converted to Bohr internally) structure = Structure.from_xyz("""\ 2 H2 molecule