# Lesson 34 — A complete scientific and engineering review

## The final deliverable is an argument supported by artifacts

Imagine presenting our work to a joint review with chemists, numerical-method developers, quantum-algorithm researchers, compiler engineers, resource-estimation specialists, and hardware/error-correction model owners.

The opening claim is not simply that we generated a circuit. It is that a specified computational workflow can answer a specified question, to a stated standard, with understood limitations and conditional costs. Every part of that claim needs evidence from a different stage.

This final lesson conducts that review. We will use the small stretched-nitrogen teaching problem to make the handoffs concrete, then explain how the conclusions change for a scientifically ambitious problem. The [repository overview](https://github.com/microsoft/qdk-chemistry/blob/97a3ff4f/README.md) describes an end-to-end toolkit; our job is to understand what the ends and the connections actually mean.

No new chemistry calculation, simulation, or physical resource estimate is performed in this capstone. Recorded examples remain evidence about their stated model and revision, while the decision exercises below are illustrative.

## 1. State the scientific question before choosing the algorithm

For the teaching case, we ask for a fixed-geometry ground-state energy of neutral singlet nitrogen at 1.85 Å. We use the finite orbital representation and selected active-space model described by the [ground-state tutorial](https://github.com/microsoft/qdk-chemistry/blob/97a3ff4f/docs/source/tutorials/ground_state_molecular_energies_with_qpe/index.rst).

This is not a complete simulation of industrial ammonia production. It is not a free energy at a specified temperature, a chemical reaction rate, or an assertion that nitrogen needs a quantum computer. A deliberately tractable problem lets us compare transformations and algorithms against a classical reference.

A scientifically ambitious application would need a different first page: the real decision to be informed, the chemical species and environment, required comparisons, necessary accuracy, and a competitive classical baseline. Quantum computing is a candidate method, not the definition of the problem.

The first review gate is therefore a problem statement that distinguishes the physical system, the chosen mathematical model, and the quantity being calculated. An energy target without a reference and scope is incomplete.

## 2. Build an input record another team can interpret

The initial artifact is the molecular structure, with explicit elements, coordinates, and units. Charge and spin multiplicity are supplied separately. The basis defines the available one-electron functions; any effective core potential defines which electrons are explicitly represented and changes the Hamiltonian accordingly.

For our running N2 geometry, the physical all-electron count is fourteen. The named cc-pVDZ resource supplies 28 spherical atomic basis functions for the two atoms before any numerical rank reduction. A restricted reference has seven doubly occupied spatial orbitals, but that description does not assert that a correlated ground state remains a single determinant.

The separate [nitrogen notebook](https://github.com/microsoft/qdk-chemistry/blob/97a3ff4f/examples/qpe_stretched_n2.ipynb) uses 1.270025 Å. It is a useful example of additional techniques, including resource estimation, but its numerical results cannot be silently appended to the 1.85 Å tutorial record.

The input review checks more than whether a file loads. Did the XYZ ångström values become bohr correctly? Are electron count and multiplicity consistent? Are basis functions spherical or Cartesian along a supported conversion path? Are ECP effective charges separate from physical nuclear charges? Does an orbital guess still refer to the geometry and basis it claims to use?

These checks are inexpensive relative to a large calculation and prevent entire workflows from answering the wrong question.

## 3. Generate a classical starting point—and record what converged

The native `scf_solver` implementation can produce a Hartree–Fock or supported Kohn–Sham starting solution. A PySCF plugin can provide another implementation with its own capabilities and numerical semantics.

The selected approximation, basis, orbital restrictions, initial guess, and numerical convergence strategy must be recorded separately. Increasing the iteration limit does not turn Hartree–Fock into a correlated method. Choosing a larger basis does not remove the single-determinant restriction. Switching numerical backends does not guarantee identical integration grids or stopping criteria.

The output is an energy and a wavefunction carrying orbitals, not merely a number. The next teams need coefficients, orbital identities, occupations, and the associated basis.

The second review gate asks whether the calculation actually converged and whether the resulting stationary solution is appropriate. Convergence can lead to an unstable or undesired solution. Stability analysis and reoptimization can change the outcome; a transition from restricted to unrestricted orbitals must be visible in the record. Equal alpha and beta counts do not alone certify total-spin purity.

If we optimize geometry rather than hold it fixed, that is a distinct scientific task requiring derivatives and an optimizer. A small gradient does not establish whether the stationary point is a minimum or a transition-state saddle. Nor does an optimizer automatically retain the desired electronic state along a path.

## 4. Reduce the problem without hiding what was excluded

The full orbital basis can be too expensive for a complete many-electron treatment. We therefore choose a correlated representation and, often, an active space.

An active space specifies which orbitals can change occupation and how many electrons participate explicitly in that many-electron calculation. Inactive electrons are not simply erased: their influence enters effective one-electron terms and an energy constant. Empty orbitals outside the selected space cannot contribute excitations in the same way as retained orbitals.

Methods offered by the repository include valence-based and occupation-based selection, entropy-based autoCAS variants, and optional AVAS through PySCF. Each uses a different kind of evidence. Entropy selection requires suitable correlated-state information; the selector does not magically compute an otherwise intractable exact full wavefunction first.

Orbital localization and natural-orbital methods change the representation in which selection and correlation are expressed. This can improve interpretability or make an approximation more compact, but a transformation of an orbital container is not automatically a transformation of every correlated coefficient. The actual localizer output contract must be respected.

A six-electron, six-spatial-orbital space with three alpha and three beta electrons has 400 determinants in that fixed-spin-projection basis before further reductions. This makes a useful small reference problem. Choosing it is still a model decision, not proof that every chemically important effect lies inside those six orbitals.

The model-reduction review therefore needs both cost and error evidence. Which physics motivated the selected space? What happens when it is enlarged? Are we following orbital character consistently along changed geometries? Does the comparison use the same physical conditions and energy reference?

A smaller qubit count is not sufficient justification if the reduced model no longer answers the scientific question.

## 5. Solve a tractable reference and choose an affordable trial state

For a small selected space, `macis_cas` supplies a complete-active-space CI reference up to its numerical tolerances. `macis_asci` selects important determinants and can produce a useful approximation for larger spaces. Projected multi-configuration calculation optimizes coefficients in a supplied determinant set.

These are distinct tasks. Selecting the two largest coefficients and renormalizing them is not generally the same as solving again in that two-determinant subspace. The latter can improve the coefficients within the chosen support without restoring omitted configurations.

The reference wavefunction is useful for scientific interpretation and, in a small demonstration, for checking the quantum algorithm. The trial wavefunction is the state we choose to load into the quantum circuit. A compact trial can save preparation cost while reducing overlap with the target state.

For an ideal coherent energy-phase measurement, the target eigenstate weight helps determine the chance of observing its phase. That familiar statement does not automatically apply to this repository fresh-state-per-bit iterative implementation as a complete-run success law. Actual scheduling and aggregation matter.

The trial-state review asks for the preparation method, occupied-mode order, normalization, signs/phases, any truncation, and evidence for target-state overlap or success. A cheap preparation circuit with essentially no useful target overlap may make the total calculation more expensive than a larger preparation.

State-preparation methods also have different purposes. A clean molecular trial-state loader and a coefficient/index loader with entangled helper registers for block encoding are not interchangeable just because both are called state preparation.

## 6. Construct and compress the Hamiltonian carefully

The molecular Hamiltonian must agree with the chosen orbital space and electron model. Its integral convention, spin blocks, storage form, and constant-energy contribution travel with it.

Canonical four-center storage, Cholesky factors, double-factorized representations, and sparse model containers have different access and reconstruction costs. Thresholded factorization changes the represented numerical operator; it is not merely a different file format. A threshold on an integral residual does not automatically certify an energy error of the same magnitude.

The third review gate checks numerical equivalence where equivalence is intended, and quantified approximation where terms or factors have been discarded. A consumer that reconstructs a full tensor can remove the memory advantage of compact storage. A specialized algorithm may need exactly the factorization or positivity assumptions that its interface expects.

Do not fill an absent implementation with a conceptual promise. At this source revision, effective-Hamiltonian downfolding has interface infrastructure but no concrete registered implementation in the inspected factory. Its theory can explain an important research direction, but the course should not present that direction as a shipped end-to-end routine.

Likewise, MCSCF is accessed through the supported PySCF integration rather than a universally available native orbital optimizer. Native MP2 amplitudes and optional CCSD results have container and downstream-access limitations. Choosing a method includes choosing a compatible consumer of its output.

## 7. Translate the model into a compatible quantum workload

Fermion-to-qubit mapping translates creation/annihilation algebra into qubit operators. Jordan–Wigner, Bravyi–Kitaev, parity-related representations, and custom mappings differ in what the qubits and operator strings mean.

The initial state, Hamiltonian, observables, register ordering, and any symmetry reduction must use compatible conventions. Equal width does not prove compatibility. Renaming the encoding field does not perform the required state transformation. Permuting wires does not generally implement every fermionic remapping.

Symmetry can reduce storage or the quantum register, but those are different operations. The specialized tapering path in this revision should not be advertised as a general automatic point-group or Clifford-symmetry compiler. Fixing electron parities also does not uniquely fix exact electron number.

The quantum-model review checks the sector, transformation, phase conventions, and any auxiliary codespace. A lowest eigenvalue in the wrong sector is still the wrong scientific answer.

The [quickstart](https://github.com/microsoft/qdk-chemistry/blob/97a3ff4f/docs/source/_static/examples/python/quickstart.py) illustrates a concrete handoff from selected orbitals and a sparse trial state to qubit mapping and sampled expectation. It is one branch through the library, not a substitute for inspecting compatibility in every alternative route.

## 8. Choose the algorithm according to the quantity and precision required

The major quantum routes answer related but different questions:

| Route | What it aims to obtain | Main cost and interpretation concerns |
|---|---|---|
| Pauli expectation sampling | Mean value of an observable in the prepared state | Group compatibility, shot allocation, covariance, state-preparation repetitions, and sampling uncertainty. |
| Standard phase estimation | Eigenphase information from a coherent phase-register circuit | Controlled evolution, phase-register size, state overlap, finite resolution, aliases and decoding. |
| Iterative phase estimation | Phase bits through repeated controlled-operation circuits and feedback | Longest powers, per-bit state preparation, majority aggregation, and implementation-specific success semantics. |
| Unary/SOSSA route | Phase information through its specialized block/walk construction | Correct normalization/shift, required operation capabilities, simulator restrictions and specialized decoding. |
| Hadamard tests | Real or imaginary parts of a controlled-unitary overlap | Controlled phase conventions, repeated measurements, available adjoints and register layout. |
| Time-dependent simulation | Observable responses under a specified driven Hamiltonian | Time discretization, supported drive model, accumulated circuit prefixes and fresh measurements. |

Hamiltonian time evolution can be constructed with product formulas, randomized approaches, or block-encoding/walk techniques. Trotter error, randomized-channel guarantees, coherent fixed-circuit error, and finite factorization error are not the same kind of statement. Comparing algorithms requires matching the scientific model, target accuracy, success criterion, and full workload scope.

A qubitized walk avoids a particular Trotter approximation for its ideal represented operator, but it does not eliminate imperfect input models, state preparation, factorization thresholds, rotation synthesis, or measurement limitations.

Amplitude amplification can improve an ideal good-subspace probability using repeated reflections. It does not supply a free exact ground-state oracle. The actual marking circuit, phase resolution, uncomputation, and repeated preparation costs must be included. Off-grid cleanup limitations matter to whether the ideal two-dimensional amplification picture applies at all.

## 9. Keep an energy and error ledger

A final energy should be accompanied by a ledger explaining how it was reconstructed:

| Artifact or stage | Quantity to track |
|---|---|
| Fixed nuclei | Nuclear or effective core–core repulsion under the selected model. |
| Active-space construction | Constant core/inactive contribution and active electronic terms. |
| Ordinary molecular Pauli mapping | Mapped operator energy, with the molecular core contribution generally retained separately on this route. |
| SOS representation | Its own normalization and energy-shift convention, which can already include the molecular core contribution. |
| Trial-state expectation | Energy of the prepared state, not automatically an exact ground-state eigenvalue. |
| Phase decoding | Phase sign, time/scale, periodic branch, and shift used to turn phase information into energy. |
| Reported total | The intended model quantity with every required constant included exactly once. |

The table is a review aid, not an instruction to add the core energy indiscriminately. The ordinary Pauli and SOS paths have different conventions. A total-energy decoder followed by a second core-energy addition gives a wrong but potentially plausible answer.

We also distinguish four words that are often used too loosely. **Accuracy** is closeness to a specified reference. **Precision** concerns the spread of repeated results. **Resolution** describes distinguishable numerical intervals. **Uncertainty** expresses what values remain plausible under the available evidence and assumptions.

A result printed to twelve decimal places need not be accurate to twelve decimals. A stable but incomplete active-space model can be highly repeatable and scientifically biased. A fine phase grid does not remove finite sampling or a wrong phase branch.

The error ledger should include physical-model choices, basis/ECP approximation, active-space and correlation omissions, numerical convergence and factorization, state-preparation effects, Hamiltonian simulation/synthesis, phase resolution, statistical sampling, and hardware failure assumptions. Deterministic error bounds, variances, and probabilities cannot be added indiscriminately because their units and meanings differ.

The current expectation-estimator variance field omits within-group covariance. It is not automatically a certified uncertainty interval. The iterative QPE output does not preserve every histogram and decoder choice. These limits motivate preserving additional records where an application needs defensible statistical conclusions.

## 10. Count the complete calculation before estimating a machine

A resource estimate is conditional on the workload supplied. Estimating one largest QPE iteration can be useful for comparing components, but it is not the total cost of every bit, shot, repetition, and geometry in a campaign.

The nitrogen resource notebook explicitly selects a largest iteration circuit. The review must identify what is excluded before anyone interprets its table as the price of answering the chemistry question.

Logical accounting tracks problem qubits, helper registers, peak live allocation, gate types, dependencies/depth, measurements, classical feedback, and repeated state preparation. Sequential peak widths should not simply be added together, while operation counts and repetitions often must be accumulated. A reused phase-gradient register is not free unless its preparation and ownership are accounted for in the chosen boundary.

The broader QDK estimation tools combine that application with physical-operation and error-correction assumptions. The [Circuit adapter](https://github.com/microsoft/qdk-chemistry/blob/97a3ff4f/python/src/qdk_chemistry/data/circuit.py) exposes two alternative routes: `estimate()` delegates to QDK counting/estimation facilities, while `get_qre_application()` supplies an application for direct `qdk.qre` studies.

Neither method manufactures a trustworthy overlap estimate, determines the scientific validity of the active space, or infers all omitted workflow repetitions. Those are application inputs.

## 11. Make the partner-team contracts explicit

Functional responsibilities help prevent a problem from disappearing between teams. They are not a claim about any particular corporate organizational chart.

| Functional workstream | Supplies | Needs from the rest of the workflow |
|---|---|---|
| Application and chemistry | Scientific objective, model, tolerances, meaningful comparisons and interpretation | A real customer/scientific decision and suitable reference evidence. |
| Classical numerical methods | Orbitals, integrals, correlated approximations, derivatives and reduced models | Accurate structures, conventions, compute/memory budgets and required outputs. |
| Quantum algorithms | Compatible state loading, operator constructions, measurement/phase procedures and success assumptions | A precise model, usable trial state and error budget. |
| Compiler and execution | Supported quantum-program representations, gate transformations, simulation/execution semantics | Valid circuits, correct control/phase behavior and declared target capability. |
| Error-correction specialists | Code and logical-operation models, distance/error assumptions, factory constructions | Logical workload and required reliability. |
| Hardware-model specialists | Physical operation times, errors, connectivity and supported instruction assumptions | A stated architecture and evidence for parameter values. |
| Resource estimation | Consistent enumeration and comparison of physical space/time alternatives | Compatible application, hardware, QEC, synthesis and failure-budget inputs. |
| Platform and reliability | Packaging, jobs, storage, provenance, interfaces and diagnostics | Supported dependencies, typed contracts and deployment/permission requirements. |

The resource-estimation and error-correction teams are not merely the last box after chemistry. Their results can send us back to improve state preparation, active-space choices, factorization, or precision allocation. Conversely, making a circuit cheaper is not useful if it violates the chemistry accuracy requirement.

A Pareto frontier describes tradeoffs among feasible candidates under the modeled assumptions. It is not a list of devices known to exist, a delivery date, a bill, or evidence of scientific advantage.

## 12. Operational delivery is another evidence layer

The workflow must retain artifacts and versions, handle optional dependencies, and distinguish newly computed results from cached ones. Remote submission must yield a durable identifier, meaningful status, and retrievable output. A finished process with missing output is not a complete handoff.

The user interfaces from Lesson 32 can lower the effort needed to operate this process, but they must not hide units, settings, existing-output decisions, or submitted-job status. Visualizing orbitals and entanglement can improve understanding; a visualization cannot validate information absent from the underlying wavefunction.

Build and release checks from Lesson 33 ensure that another environment can install and use the package. Published wheels, supported plugins, source-main behavior, and documentation versions are different compatibility boundaries. A source capability unavailable in a particular wheel/platform should be reported as unavailable, not worked around by inventing output.

The final operational record should make it possible to rerun or diagnose the study without relying on a scientist memory of a notebook session. That includes scientific configuration, code and dependency versions, hashes and saved payloads, random seeds where relevant, convergence/status information, and the parameters used to produce visual or resource reports.

## 13. The alternative examples are part of the system, not distractions

A complete understanding of the repository also includes paths that do not begin with our nitrogen geometry:

- The para-benzyne quickstart illustrates sparse-state preparation and sampled energy comparison.
- Lattice models such as Hubbard, PPP, Ising, and Heisenberg can enter at a model-Hamiltonian stage, bypassing molecular basis/integral preprocessing under different physical assumptions.
- The extended-Hubbard notebook connects a molecularly motivated problem to a reduced model; it does not establish that every reduced model is quantitatively ab initio.
- Driven-evolution examples study time-dependent observable behavior rather than a single static ground-state energy.
- Qiskit, OpenFermion, PennyLane, and RDKit interoperability examples illustrate representation or workflow boundaries, not interchangeable capabilities without conversion checks.
- C++ and Python language examples show different user-facing routes through the native library and bindings.
- Remote/backend and assistant examples explain operation and artifact management, rather than a new electronic-structure approximation.

The [examples overview](https://github.com/microsoft/qdk-chemistry/blob/97a3ff4f/examples/README.md) identifies their dependencies and companion files. Their results belong to their own models, geometries, versions, and execution conditions.

## 14. A coverage map for the entire course

The course has connected the major repository areas to the work they support:

| Lessons | Repository responsibilities covered |
|---|---|
| 1–4 | Scientific question, fundamental electronic description, public data/algorithm interfaces, structures, units, bases, ECP resources and provenance. |
| 5–8 | Native/PySCF SCF, convergence and stability, population/derivative/geometry methods, orbital transformations and visualization inputs. |
| 9–12 | MACIS and correlated methods, configurations/RDMs, selectors, MCSCF/MP2/CC adapters, effective-interface boundary, Hamiltonian containers and factorization. |
| 13–17 | Qubits/gates, Pauli and Majorana representations, mappings and symmetry/tapering, state-preparation families, circuit containers/mappers and compiler interoperation. |
| 18–23 | Product-formula/randomized/splitting methods, block encodings/SOSSA walks, grouping/sampling, QPE variants, overlaps/amplification, and driven dynamics. |
| 24–29 | Lattice models, simulators/noise/interoperability, scientific output/error interpretation, logical workload, QEC/hardware concepts and both resource-estimation routes. |
| 30–33 | Persistence/migration/hashes, remote/cache/Discovery, CLI/MCP/plugins/widgets, native/binding/dependency/build/test/docs/release/telemetry/support infrastructure. |
| 34 | Integrated decisions, evidence, scope boundaries and cross-team handoffs. |

This is capability and workstream coverage, not a claim that every line or every numerical parameter in the original repository has been formally audited. Reference datasets, basis archives, images, generated metadata and build scripts serve the responsibilities identified above. A new implementation or a changed revision can require a new review; the course is anchored to source revision `97a3ff4f`.

## 15. Conduct the final go/no-go review

A useful review separates different kinds of readiness instead of giving the entire project one undifferentiated green light.

**Scientific readiness:** the question matters, the model and comparison are appropriate, and remaining approximation errors are acceptable for the intended decision.

**Algorithmic readiness:** the encodings, state preparation, operator constructions, measurements and decoding are consistent, and success/accuracy assumptions are justified for the actual implementation.

**Engineering readiness:** artifacts can be reconstructed, errors are surfaced, supported environments are known, and the workflow can be repeated and maintained.

**Resource readiness:** the complete workload is counted and compatible physical/QEC models yield a credible feasibility range with sensitivity analysis.

**Practical advantage:** a fair comparison shows a benefit over the relevant classical alternatives at the required quality and full cost. None of the preceding readiness checks alone establishes this strongest claim.

For a teaching benchmark, successfully reproducing the matching classical selected-space result is already valuable. It exercises the entire translation and makes errors visible. For a proposed useful quantum application, that is a beginning rather than the final argument.

If resources are too large, we can investigate better representations or algorithms, but must preserve scientific validity. If model error dominates, a smaller quantum-circuit approximation error may be irrelevant. If trial-state success is poorly understood, a precise per-circuit resource count may still leave the full workload unknown. If an interface exists without an implementation, the honest outcome is a development need, not a fabricated calculation.

The team work is therefore a feedback loop: choose a meaningful question, build and validate a model, prepare and execute a compatible computation, interpret the evidence, estimate its complete cost, and revise the limiting stage. The repository gives us interoperable tools for that loop. Engineering judgment consists of knowing what each tool actually contributes—and what responsibility remains outside it.