update llm files

Author: refraction-ray

examples/hamiltonian_building.py

@@ -47,6 +47,11 @@
 h12 = tc.quantum.heisenberg_hamiltonian(
     g, hzz=1, hxx=0, hyy=0, hz=0, hx=-1, hy=0, sparse=True
 )
+# JAX is asynchronous; block to measure execution time
+if hasattr(h12, "data") and hasattr(h12.data, "block_until_ready"):
+    h12.data.block_until_ready()
+elif hasattr(h12, "block_until_ready"):
+    h12.block_until_ready()
 time1 = time.perf_counter()
 
 print("tc (jax) time: ", time1 - time0)
@@ -55,6 +60,10 @@
 h12 = tc.quantum.heisenberg_hamiltonian(
     g, hzz=1, hxx=0, hyy=0, hz=0, hx=-1, hy=0, sparse=True
 )
+if hasattr(h12, "data") and hasattr(h12.data, "block_until_ready"):
+    h12.data.block_until_ready()
+elif hasattr(h12, "block_until_ready"):
+    h12.block_until_ready()
 time1 = time.perf_counter()
 
 print("tc (jax) time (after jit): ", time1 - time0)

llm.md

@@ -1,26 +1,33 @@
 # TensorCircuit-NG Repository Guide for AI Agents
 
-## Repository Overview
+## Core Philosophy
 
-TensorCircuit is a high-performance unified quantum computing framework designed for the NISQ (Noisy Intermediate-Scale Quantum) era. It provides a comprehensive set of tools for quantum circuit simulation with support for multiple backends including Numpy, TensorFlow, JAX, and PyTorch.
+TensorCircuit is a **Tensor Network-first**, **Multi-Backend** quantum computing framework. When contributing to this codebase, you must adhere to the following architectural principles:
 
-## Documentation and AI Native Services
+### Unified Backend Interface
+- **Rule**: Never use backend-specific libraries (numpy, tensorflow, jax) directly in core logic.
+- **Pattern**: Use the `tc.backend` abstraction for all tensor operations.
+- **Example**: Use `tc.backend.sin(x)` instead of `np.sin(x)` or `tf.math.sin(x)`. This ensures code runs seamlessly on TensorFlow, JAX, PyTorch, and NumPy.
 
-### Official Documentation
+### Differentiable Programming (AD)
+- **Rule**: All core components must be differentiable.
+- **Pattern**: Avoid operations that break the computation graph (e.g., converting to numpy inside a differentiable function, using in-place assignments on tensors).
+- **Goal**: End-to-end differentiability allows variational algorithms and gradient-based optimization to work out of the box.
 
-- Main Documentation: https://tensorcircuit-ng.readthedocs.io/
-- Quick Start Guide: https://tensorcircuit-ng.readthedocs.io/en/latest/quickstart.html
-- Tutorials: https://tensorcircuit-ng.readthedocs.io/en/latest/tutorial.html
-- API Reference: Available in docstrings throughout the codebase
+### JIT-First Optimization
+- **Rule**: Write code that is JIT-compilable (Just-In-Time).
+- **Pattern**: Avoid Python control flow (if/else) that depends on tensor values. Use `tc.backend.cond` or `tc.backend.switch` if necessary, or structure code to be statically analyzable.
+- **Benefit**: This enables massive speedups on JAX and TensorFlow backends.
 
-### AI-Native Documentation Services
-
-- Devin Deepwiki: https://deepwiki.com/tensorcircuit/tensorcircuit-ng
-- Context7 MCP: https://context7.com/tensorcircuit/tensorcircuit-ng
 
-### Educational Resources
+## Repository Structure
 
-- Quantum Computing Lectures with TC-NG: https://github.com/sxzgroup/qc_lecture
+- `tensorcircuit/`: Core package source code.
+  - `backends/`: Backend implementations (avoid modifying unless necessary).
+  - `templates/`: High-level modules (ansatzes, Hamiltonians, graphs).
+- `examples/`: Usage demos and benchmarks. Use these as reference implementations.
+- `tests/`: Comprehensive test suite. Check these for expected behavior.
+- `docs/`: Sphinx documentation source.
 
 ## Configuration and Dependencies
 
@@ -63,42 +70,39 @@ TensorCircuit is a high-performance unified quantum computing framework designed
 
 3. `.pylintrc` - Code style enforcement with specific rules enabled
 
-## Common Bash Commands
 
-### Development Checks
+## AI Agent Best Practices
+
+### Code Navigation
+- **Search First**: The codebase is extensive. Search for class definitions (e.g., `class Hamiltonian`) rather than guessing file paths.
+- **Check Tests**: `tests/test_*.py` files are the ultimate source of truth for how APIs are intended to be used.
+
+### Coding Standards
+- **Linting**: We enforce strict **Pylint** and **Black** formatting.
+  - Run `bash check_all.sh` before submitting changes.
+  - Target Pylint score: 10.0/10.
+- **Type Hinting**: Use type hints liberally to aid static analysis.
+- **Documentation**: Write clear docstrings (reStructuredText format) for all public APIs.
 
+### Common Workflows
+
+#### 1. Running Tests
 ```bash
-# Run all checks (black, mypy, pylint, pytest, sphinx)
-bash check_all.sh
-
-# Equivalent to the following individual checks:
-black . --check                    # Code formatting check
-mypy tensorcircuit                 # Type checking
-pylint tensorcircuit tests examples/*.py  # Code linting
-pytest -n auto --cov=tensorcircuit -vv -W ignore::DeprecationWarning  # Run tests
-
-# Run all tests with coverage report
-pytest --cov=tensorcircuit --cov-report=xml -svv --benchmark-skip
-
-# Run specific test file
-pytest tests/test_circuit.py
-
-# Install dependencies
-pip install --upgrade pip
-pip install -r requirements/requirements.txt
-pip install -r requirements/requirements-dev.txt
-pip install -r requirements/requirements-extra.txt
-pip install -r requirements/requirements-types.txt
-```
+# Run all tests (auto-parallelized)
+pytest -n auto
 
-## AI Agent Best Practices
+# Run specific test file (useful during debugging)
+pytest tests/test_hamiltonians.py
+```
 
-### Efficient Code Navigation
+#### 2. Checking Code Quality
+```bash
+# Check formatting
+black . --check
 
-- Use the search function to find specific classes and functions rather than browsing files
-- Look for example usage in the /examples/ directory when learning new features
-- Check tests in /tests/ directory for detailed usage examples
-- Refer to docstrings for API documentation
+# Run linter on specific file
+pylint tensorcircuit/quantum.py
+```
 
 ### Common Patterns in the Codebase
 
@@ -108,13 +112,11 @@ pip install -r requirements/requirements-types.txt
 - Vectorized operations using tc.backend.vmap patterns
 - Context managers for temporary configuration changes
 
-### Working with Quantum Concepts
-
-- Familiarity with quantum computing basics (qubits, gates, measurements)
-- Understanding of tensor network concepts for advanced features
-- Knowledge of different quantum computing paradigms (digital, analog, noisy, etc.)
+### Branch Strategy
 
-## Additional Information
+- master branch for stable releases
+- beta branch for nightly builds (as seen in nightly_release.yml)
+- pull requests for feature development
 
 ### Test Structure
 
@@ -130,18 +132,18 @@ pip install -r requirements/requirements-types.txt
 
 ### Package Distribution
 
-- Distributed as tensorcircuit-ng package
+- Distributed as tensorcircuit-ng package in PyPI
 - Supports extra dependencies for specific backends (tensorflow, jax, torch, qiskit, cloud)
 
-### Core Design Principles
+## Further Reading
 
-- Unified interface across multiple backends
-- High performance through tensor network optimizations
-- Extensible architecture for quantum computing research
-- Compatibility with major quantum computing frameworks
+- **Specific Protocols**: See `experience.md` for detailed protocols on development, profiling, and performance tuning.
+
+- **Official Docs**: https://tensorcircuit-ng.readthedocs.io/
+
+### AI-Native Documentation Services
+
+- Devin Deepwiki: https://deepwiki.com/tensorcircuit/tensorcircuit-ng
+- Context7 MCP: https://context7.com/tensorcircuit/tensorcircuit-ng
 
-### Branch Strategy
 
-- master branch for stable releases
-- beta branch for nightly builds (as seen in nightly_release.yml)
-- pull requests for feature development

llm_experience.md

@@ -0,0 +1,36 @@
+# TensorCircuit Development Experience & Protocols
+
+This document records specific technical protocols, lessons learned, and advanced practices for developing TensorCircuit. Refer to this when implementing complex features or debugging performance issues.
+
+## JAX, Compilation, and Performance
+
+1.  **Benchmarking JAX Code**:
+    *   JAX execution is asynchronous. To measure execution time accurately, always call `.block_until_ready()` on the result's data buffer (e.g., `result.data.block_until_ready()`).
+    *   Failing to block will only measure the dispatch time, leading to confusing results (e.g., "first run faster than second run").
+
+2.  **Memory Management (OOM Prevention)**:
+    *   For operations over large batches (e.g., summing $2^{22}$ Pauli strings), `vmap` materializes all intermediate results in memory.
+    *   **Protocol**: Use `jax.lax.scan` or sequential loops for reductions over large inputs to keep peak memory usage constant ($O(1)$) rather than linear ($O(N)$).
+
+## Testing and Robustness
+
+1.  **Sparse Matrix Compatibility**:
+    *   TensorCircuit supports multiple sparse formats (Scipy CSR/COO, JAX BCOO, TensorFlow SparseTensor).
+    *   **Protocol**: When handling sparse outputs, do NOT assume specific attributes like `.row` or `.col` exist (missing in JAX BCOO or Scipy CSR).
+    *   **Check**: Use `hasattr(obj, "tocoo")` to detect Scipy sparse matrices and convert them if a standard COO interface is needed.
+    *   **Comparison**: Compare sparse matrices by subtraction (`abs(A - B).max() ≈ 0`) rather than element-wise attribute checks, to be robust against format differences.
+
+## Visualization
+
+1.  **Non-Blocking Plots**:
+    *   Library plotting functions (e.g., `Lattice.show`) must accept an optional `ax` (Matplotlib Axis) argument.
+    *   **Protocol**: Draw on the provided `ax` and avoid calling `plt.show()` inside library functions. This allows users to embed plots in subplots and manage the figure lifecycle (saving/closing) themselves.
+
+## Benchmarking External Libraries
+
+1.  **Environment Isolation**:
+    *   When benchmarking against external libraries (e.g., QuSpin, Quimb, Qiskit) that may have conflicting dependencies, create a dedicated Conda environment (e.g., `bench_quspin`).
+    *   Install the external library there using pip from the specific conda environment and run the benchmark script using that specific interpreter.
+
+2.  **Fair Comparison**:
+    *   Ensure "apples-to-apples" settings (e.g., same precision `complex128`) to support valid performance claims.