new example, demonstration, tutorial files

[BrendanKKrueger]

Details proposed by Claude

Add Tutorial and Example Configuration Files for Common Use Cases

Summary

The QHAT analysis tool currently has two configuration files:

• all_analyses.config - comprehensive reference showing all options
• error_analysis_tutorial.config - pedagogical tutorial for error analysis

We need additional tutorial and example configurations to cover common use cases and help users learn the tool effectively. This issue proposes six new configuration files that fill important pedagogical and practical gaps.

Motivation

Current gaps:

1. No QPE tutorial: Quantum Phase Estimation is a major algorithm type but has no dedicated tutorial. Users learning QPE must figure it out from all_analyses.config comments.

2. No production templates: Researchers wanting to "just run a ground state energy calculation" have no clean, minimal template to copy-paste and modify.

3. No encoding comparison guide: Users must choose between Trotter, LCU, and Double Factorization without guidance on trade-offs or when to use each.

4. No parameter study examples: Researchers generating paper figures (error vs. cost plots) have no guidance on systematic parameter variation.

5. No large-system guidance: Systems >12 qubits hit memory limits, but there's no documentation on memory management strategies.

6. Numerical simulation not featured: State evolution is buried in comprehensive examples rather than highlighted as a standalone capability.

Impact: Users spend time rediscovering best practices, may choose inappropriate methods, or give up on using advanced features.

Proposed Solution

Add six new .config files to analysis/examples/:

High Priority (Implement First)

1. qpe_tutorial.config - Quantum Phase Estimation Tutorial

Purpose: Teach QPE algorithm usage with pedagogical progression.

Content:

• Introduction: QPE vs. time evolution, when to use each
• Phase qubit selection: Precision vs. cost trade-off
• Probability of failure parameter and its meaning
• Energy shift handling for QPE (why it's required)
• Resource scaling analysis
• Interpreting phase estimation results
• Comparison to time evolution tutorial

Learning objectives:

• Understand QPE-specific parameters (num_phase_qubits, probability_of_failure)
• Choose appropriate phase precision for desired energy resolution
• Interpret QPE output (phases → energies)

Estimated size: 250-300 lines

---

2. ground_state_energy.config - Minimal Production Template

Purpose: Copy-paste template for the most common research task.

Content:

• Minimal configuration for ground state energy calculation
• Only essential analyses: resource estimation + eigenvalue errors
• Chemical accuracy context (kcal/mol, mH conversions)
• Clear comments on parameters to modify for your system
• Best practices for choosing error budgets in chemistry
• Production-ready file naming conventions

Target audience: Computational chemists, pragmatic users

Design principle: If it's not essential for ground state energy, it's not in this file.

Estimated size: 100-150 lines (deliberately minimal)

---

3. encoding_methods_comparison.config - When to Use Which Encoding

Purpose: Help users choose between Trotter, LCU, and Double Factorization.

Content:

• Template with all three encodings (two commented out)
• Clear instructions: "Uncomment the encoding you want to use"
• Comparison table in comments:
  • Trotter: Pros (simple, widely used), Cons (many gates), Best for (all systems)
  • LCU: Pros (good scaling), Cons (block encoding complexity), Best for (large systems)
  • DF: Pros (optimal for molecules), Cons (requires structure), Best for (electronic structure)
• Resource estimation for comparison
• References to literature for each method

Format: Users uncomment one encoding block and run.

Estimated size: 200-250 lines

---

Medium Priority (Implement Second)

4. scaling_study.config - Systematic Parameter Studies

Purpose: Template for generating research data (plots for papers).

Content:

• How to systematically vary parameters (energy_error, Trotter order, system size)
• Recommended output file naming for parameter sweeps
• Comments showing Python wrapper pattern for automation
• What to measure: T-count, error metrics, memory usage
• Example data collection workflow
• Guidance on parallel execution

Target audience: Users writing papers with computational results

Estimated size: 200-250 lines

---

5. numerical_simulation_tutorial.config - State Evolution Focus

Purpose: Showcase state evolution as standalone capability.

Content:

• Creating and formatting input states
• Single vs. multiple state evolution
• Exact vs. approximate comparison
• Time series evolution (multiple timesteps)
• Analyzing evolved states (populations, overlaps)
• When to use this vs. error analysis

Use case: Users who want to evolve states, not analyze algorithms.

Estimated size: 200-250 lines

---

6. large_system_workflow.config - Memory Management for >12 Qubits

Purpose: Guidance on working with systems that exceed dense matrix limits.

Content:

• Memory threshold configuration
• Matrix-free operator strategies
• Which analyses work at large scale (eigenvalue errors: yes, matrix norms: no)
• Computational time expectations
• What to avoid (operations requiring full dense matrices)
• Alternative workflows when matrices are too large

Warning level: Mark as "advanced" - requires understanding trade-offs.

Estimated size: 200-250 lines

---

Detailed Scope

What Each File Must Include

All configuration files must have:

1. Comprehensive header docstring following the template from error_analysis_tutorial.config:

   • PURPOSE section
   • LEARNING OBJECTIVES or TARGET AUDIENCE
   • USAGE command
   • WHAT THIS FILE DEMONSTRATES
   • NEXT STEPS or RELATED EXAMPLES

2. Step-by-step structure with numbered sections or clear progression

3. Inline pedagogical comments explaining:

   • What each parameter does
   • Why we chose particular values
   • What happens if you change them
   • Common pitfalls to avoid

4. "TRY THIS" experimentation prompts where appropriate

5. Expected output section explaining:

   • What files are produced
   • How to interpret results
   • Sanity checks for validation

6. Valid Python syntax (runnable with python3.11 -m qhat.analysis.driver)

Directory Structure

analysis/examples/
├── all_analyses.config              (existing - complete reference)
├── error_analysis_tutorial.config   (existing - error analysis tutorial)
├── qpe_tutorial.config              (new - QPE tutorial)
├── ground_state_energy.config       (new - production template)
├── encoding_methods_comparison.config (new - encoding choice guide)
├── scaling_study.config             (new - parameter studies)
├── numerical_simulation_tutorial.config (new - state evolution focus)
├── large_system_workflow.config     (new - memory management)
└── config.py                        (existing - basic example)

Documentation Updates Required

Update analysis/README.md with new section:

## Tutorial and Example Configurations

The `examples/` directory contains configurations for learning and production use:

### Tutorials (Learning)
- **error_analysis_tutorial.config** - Error analysis from first principles
- **qpe_tutorial.config** - Quantum Phase Estimation algorithm
- **numerical_simulation_tutorial.config** - Evolving quantum states

### Production Templates
- **ground_state_energy.config** - Minimal template for chemistry calculations
- **encoding_methods_comparison.config** - Choose encoding method (Trotter/LCU/DF)

### Advanced Topics
- **scaling_study.config** - Parameter sweeps for research papers
- **large_system_workflow.config** - Memory management for >12 qubits

### Complete Reference
- **all_analyses.config** - Every available option (demonstration only)
- **config.py** - Basic minimal example

Success Criteria

Acceptance Criteria

For each configuration file:

• Valid Python syntax (passes python3.11 -m py_compile)
• Comprehensive header docstring with all required sections
• Successfully runs with python3.11 -m qhat.analysis.driver
• Produces expected output files
• All inline comments are pedagogical (explain "why", not just "what")
• File size appropriate to scope (not bloated with unnecessary features)

For documentation:

• README.md updated with new section describing all tutorials
• Each file listed with one-sentence description
• Clear guidance on which file to use for which purpose

Testing

Each configuration should be tested by:

1. Running successfully on the example Be-H system
2. Verifying all output files are created
3. Checking that results make sense (sanity checks pass)
4. Having someone unfamiliar with the code try to follow the tutorial

Implementation Plan

Phase 1: High Priority (Target: 1 week)

1. Create qpe_tutorial.config
2. Create ground_state_energy.config
3. Create encoding_methods_comparison.config
4. Update README.md for Phase 1 files
5. Test all three files

Phase 2: Medium Priority (Target: 1 week)

1. Create scaling_study.config
2. Create numerical_simulation_tutorial.config
3. Create large_system_workflow.config
4. Update README.md for Phase 2 files
5. Test all three files

Suggested Workflow

• Create new branch: tutorial-configs or similar
• One commit per config file (easier to review)
• Final commit: README.md updates
• Merge request after Phase 1 complete (don't wait for Phase 2)

Out of Scope

The following are not included in this issue:

• Creating actual test systems for tutorials (use existing Be-H examples)
• Automated testing of configuration files (manual testing is sufficient)
• Python scripting examples for parameter sweeps (just comments/templates in configs)
• Web-based documentation (just README.md updates)
• Integration with CI/CD (configs are examples, not tests)

Alternatives Considered

Alternative 1: Jupyter Notebooks

Rejected because:

• Adds dependency on Jupyter
• Harder to version control
• Config files are already Python, just with domain-specific semantics

Alternative 2: Comprehensive Documentation in README Only

Rejected because:

• Users learn better from runnable examples
• README is reference material, not tutorial material
• Examples make it easier to get started quickly

Alternative 3: Single "tutorial.config" with Everything

Rejected because:

• Would be overwhelming (500+ lines)
• Different use cases need different focus
• Modular tutorials allow targeted learning

References

• Current tutorial structure: analysis/examples/error_analysis_tutorial.config
• Current comprehensive reference: analysis/examples/all_analyses.config
• Best practices source: This conversation and established patterns

Notes for Implementer

• Follow the header format from error_analysis_tutorial.config - it's been well-received
• Keep production templates (ground_state_energy.config) deliberately minimal
• Keep tutorials (*_tutorial.config) comprehensive with lots of explanation
• Use consistent naming: *_tutorial.config for pedagogical, *.config for production/reference
• All tutorials should reference each other ("see also X for...")
• Consider adding a "recommended learning path" comment in each tutorial

Estimated Effort

• Phase 1 (high priority): 8-12 hours total

  • qpe_tutorial.config: 3-4 hours
  • ground_state_energy.config: 2-3 hours (minimal by design)
  • encoding_methods_comparison.config: 3-4 hours
  • Testing and README: 1-2 hours

• Phase 2 (medium priority): 8-12 hours total

  • Each config: 2-3 hours
  • Testing and README: 2-3 hours

Total: 16-24 hours for all six files