Exact numerical simulation

[BrendanKKrueger]

Depends on #29

Step 4 of #25

Summary from Claude below

Branch 4: Exact Numerical Simulation

Title

Branch 4: Add exact numerical simulation (completes exact matrix analysis implementation)

Description

Overview

This PR implements exact numerical simulation using the exact Hamiltonian matrix (without Trotter or other approximations). This is Branch 4, the final branch in a 5-branch implementation plan to add comprehensive exact matrix analysis and error quantification capabilities to QHAT.

Purpose

• Apply exact Hamiltonian matrix to quantum states
• Enable direct comparison: exact evolution vs approximate algorithm evolution
• Validate algorithm correctness on specific input states
• Scale to 25-30 qubits using matrix-free operators
• Complete the exact matrix analysis pipeline

Changes Made

Modified Files:

1. analysis/config_types.py

   • Added exact_simulation_inputs field (default: None, disabled)
     • Accepts single filename (string)
     • Accepts list of filenames
   • Updated TOML serialization

2. analysis/analysis.py

   • Added exact_numerical_simulation() function (~90 lines)
     • Similar structure to existing numerical_simulation()
     • Uses exact Hamiltonian matrix instead of approximate unitary
     • Output filename: input_exact_final.npy (vs input_final.npy for approximate)
     • Works with both dense matrices and matrix-free operators
     • Uses matvec() method for matrix-free operators
     • Validates dimensions, reports norms
   • Updated analyze_algorithm() to:
     • Include exact_simulation_inputs in validation
     • Mark exact matrix as needed when exact simulation requested
     • Dispatch to exact_numerical_simulation() when requested

3. analysis/README.md

   • Added "Exact Numerical Simulation" section
   • Documented input/output format
   • Explained scaling characteristics
   • Provided usage examples
   • Showed how to compare exact vs approximate results
   • Updated "Generated Files" section to include exact simulation outputs
   • Changed "Numerical Simulation" header to "Numerical Simulation (Approximate)"

4. analysis/examples/config_full_analysis.py

   • Updated to show exact simulation (replacing final "Future Analyses" placeholder)
   • Demonstrated single and multiple state simulations
   • Showed how to run both approximate and exact simulations together
   • Included full validation workflow example using all analyses
   • Added comprehensive comments explaining usage

New Files:

1. analysis/tests/test_exact_simulation.py (477 lines)
   • 13 comprehensive tests covering:
     • Basic exact simulation (3 tests): identity, Pauli Z, Pauli X
     • Multiple input states (1 test)
     • Output file naming (2 tests): suffix and path preservation
     • Norm preservation (1 test)
     • Matrix-free operators (2 tests): identity and Pauli X
     • Error handling (3 tests): missing file, dimension mismatch, invalid input type
     • Known analytical result (1 test): Hadamard gate
   • All tests passing ✓

Technical Details

Exact Simulation Function:

def exact_numerical_simulation(config_analysis, hamiltonian, exact_matrix) -> dict:
    """
    Apply exact Hamiltonian matrix to input state(s).
    
    - Uses exact_matrix (can be dense or matrix-free PauliStringOperator)
    - Output files: input_exact_final.npy
    - Works independently or alongside approximate simulation
    """

Key features:

• Dual-mode operation: Dense matrices for small systems, matrix-free for large
• Automatic method selection: Uses matvec() if available, otherwise @ operator
• Distinctive output naming: _exact_final suffix distinguishes from _final (approximate)
• Independent of approximate: Can run exact simulation without approximate simulation
• Compatible with Branch 1: Uses exact matrices from _compute_exact_matrix()

Comparison workflow:

Users can run both simulations on the same input:

# Configuration
analysis.numerical_simulation_inputs = "initial_state.npy"
analysis.exact_simulation_inputs = "initial_state.npy"

# Produces two output files:
# - initial_state_final.npy        (approximate evolution)
# - initial_state_exact_final.npy  (exact evolution)

# Then manually compare:
import numpy as np
approx = np.load("initial_state_final.npy")
exact = np.load("initial_state_exact_final.npy")
error = np.linalg.norm(exact - approx)

Scaling:

• ≤15 qubits: Uses dense exact matrix (fast)
• 16-30 qubits: Uses matrix-free PauliStringOperator
  • Memory: O(2^N) for state vectors
  • Computation time depends on number of Pauli terms
  • Can reach 30 qubits (16 GB for 30-qubit state)
• Limited by: State vector size, not matrix size

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix
• Documentation update
• Breaking change

Testing

Test Coverage:

• 13 unit/integration tests for exact simulation (all passing)
• 218 existing tests from Branches 0-3 continue to pass
• Total: 231 tests, 100% passing

Test Highlights:

• Exact simulation with known operators verified (identity, Pauli matrices)
• Multiple input states verified
• Output filename suffix verified (_exact_final)
• Path preservation verified
• Norm preservation verified
• Matrix-free operators verified
• Known analytical results verified (Hadamard gate)
• Error handling verified (missing files, dimension mismatches)

Running Tests:

# All tests
python3.11 -m pytest analysis/tests/ -v

# Just exact simulation
python3.11 -m pytest analysis/tests/test_exact_simulation.py -v

# Quick run
python3.11 -m pytest analysis/tests/ -q

Usage Example

# In configuration file (e.g., config_full_analysis.py)

# Example 1: Single state exact simulation
analysis.exact_simulation_inputs = "initial_state.npy"

# Example 2: Multiple states
analysis.exact_simulation_inputs = [
    "ground_state.npy",
    "excited_state.npy",
    "superposition.npy"
]

# Example 3: Compare exact vs approximate
analysis.numerical_simulation_inputs = "initial_state.npy"  # Approximate
analysis.exact_simulation_inputs = "initial_state.npy"      # Exact
# Produces:
#   initial_state_final.npy        (approximate result)
#   initial_state_exact_final.npy  (exact result)

# Example 4: Full validation workflow (all analyses)
analysis.resource_estimator = "pyLIQTR"
analysis.matrix_output_file = "unitary.npz"
analysis.exact_matrix_output_file = "exact.npz"
analysis.num_eigenvalues = 5
analysis.eigendecomposition_matrices = "both"
analysis.error_num_eigenvalues = 1
analysis.error_state_inputs = "ground.npy"
analysis.numerical_simulation_inputs = "initial_state.npy"
analysis.exact_simulation_inputs = "initial_state.npy"

Output:

• Files: input_exact_final.npy for each input
• Can be compared directly with approximate simulation outputs

Context: Implementation Plan

This is Branch 4, the final branch in a 5-branch sequence:

• Branch 0: Comprehensive configuration baseline ✓ (complete)
• Branch 1: Exact matrix computation ✓ (complete)
• Branch 2: Eigendecomposition analysis ✓ (complete)
• Branch 3: Error metrics ✓ (complete)
• Branch 4: Exact numerical simulation ← YOU ARE HERE (completes implementation)

All branches deliver independent, testable functionality. The full pipeline is now complete.

Benefits

For Users:

• Direct comparison of exact vs approximate evolution
• Validate algorithm correctness on specific states
• Understand exact quantum dynamics
• Complete analysis pipeline: from Hamiltonian to exact/approximate comparison

For Developers:

• Reuses existing infrastructure (Branch 1 exact matrices, file I/O)
• Mirrors numerical_simulation() structure (easy to understand)
• Clean integration with existing analysis framework
• Comprehensive test coverage

For the Project:

• Completes the 5-branch implementation plan
• All exact matrix analysis capabilities now available
• Users can perform comprehensive algorithm validation
• Foundation for future analysis extensions

Performance

Scaling:

• 2-10 qubits: Instant (dense matrices)
• 15 qubits: Seconds (dense matrix, dimension 32768)
• 20 qubits: Fast with matrix-free operator (state vector size 1 MB)
• 25 qubits: Still feasible (state vector size 256 MB)
• 30 qubits: Limit (state vector size 16 GB)

Memory:

• Limited by state vector size: 2^N complex numbers
• 30 qubits = 2^30 × 16 bytes = 16 GB

Comparison with approximate simulation:

• Same scaling characteristics
• Both limited by state vector size
• Matrix-free operators enable large-scale simulations

Checklist

• Code follows project style guidelines
• All tests pass (231/231)
• Documentation updated (README, config examples)
• No breaking changes to existing API
• Backward compatible (exact simulation disabled by default)
• Branch pushed to remote
• Code review completed
• Ready to merge

Merge Dependencies

• Base branch: bkk_error_metrics (Branch 3)
• Target branch: main
• Depends on: Branches 1, 2, and 3 should be merged first

Commits

1. 4871b3a: Branch 4: Add exact numerical simulation

Related Issues

Completes the effort to add exact matrix analysis and error quantification capabilities to QHAT for validating algorithm accuracy.

This is the final branch in the 5-branch implementation plan.

Reviewers

@lanl/qhat-team

Notes for Reviewers

Key files to review:

• analysis/analysis.py: New exact_numerical_simulation() function (~90 lines)
  • Similar to numerical_simulation() but uses exact matrix
  • Output naming: _exact_final suffix
• analysis/config_types.py: New exact_simulation_inputs field
• Test file: Comprehensive coverage (13 tests)

Design decisions to consider:

• Output naming (_exact_final vs _final) distinguishes exact from approximate
• Function mirrors numerical_simulation() structure for consistency
• Works with both dense and matrix-free operators (automatic)
• Independent: can run exact simulation without approximate simulation

Integration with previous branches:

• Branch 1: Uses exact matrices from _compute_exact_matrix()
• Branch 2: Independent of eigendecomposition
• Branch 3: Can be used alongside error analysis
• All branches: Form complete validation pipeline

Testing:

• 231 tests (128 original + 53 Branch 1 + 19 Branch 2 + 18 Branch 3 + 13 Branch 4), all passing
• Tests run in ~45 seconds on standard hardware
• No integration issues with existing functionality

Implementation completeness:

• ✅ Branch 0: Configuration baseline
• ✅ Branch 1: Exact matrix computation
• ✅ Branch 2: Eigendecomposition
• ✅ Branch 3: Error analysis
• ✅ Branch 4: Exact simulation
• All planned features implemented

Future possibilities (not in scope):

• Automatic comparison (exact vs approximate) with built-in error reporting
• Time-dependent simulations (multiple time steps)
• Additional error metrics
• Visualization tools

Summary

This PR completes the 5-branch implementation plan by adding exact numerical simulation. Users can now:

1. Compute exact matrices (Branch 1)
2. Analyze eigenspectra (Branch 2)
3. Quantify errors (Branch 3)
4. Simulate exact evolution (Branch 4)
5. Compare with approximate algorithms (all branches together)

The complete pipeline enables comprehensive validation of quantum algorithms in QHAT.