Enhance tests for the utility functions

Author: kaminotesf

tests/__init__.py

@@ -0,0 +1,115 @@
+"""
+Test Suite for Hadamard Random Forest (HRF) Quantum State Tomography Library
+
+This test module provides comprehensive testing for the HRF quantum state tomography library,
+which implements efficient reconstruction of real-valued quantum states using random forests
+over hypercube graphs. The library achieves exponential speedup (from O(4^n) to O(n) circuits)
+compared to traditional quantum state tomography methods.
+
+Test Module Structure
+====================
+
+The test suite is organized into three main modules, each testing different components
+of the HRF library:
+
+1. test_random_forest.py (20 tests)
+   - Tests core graph theory algorithms for hypercube spanning trees
+   - Validates uniform random tree generation using optimized algorithms
+   - Tests majority voting and sign reconstruction mechanisms
+   - Covers path finding and weight calculation functions
+   - Ensures reproducibility through random seed management
+
+2. test_sample.py (35 tests)
+   - Tests quantum circuit generation for Hadamard measurements
+   - Validates sampling from both simulators and real quantum hardware
+   - Tests M3 error mitigation integration with IBM Quantum backends
+   - Covers statevector reconstruction from measurement data
+   - Tests hardware-specific circuit transpilation and optimization
+
+3. test_utils.py (24 tests)
+   - Tests quantum entanglement measures (logarithmic negativity)
+   - Validates quantum magic quantification (stabilizer entropy)
+   - Tests quantum state overlap calculations (SWAP test)
+   - Covers mathematical utilities for partial transpose and trace norm
+   - Tests Pauli operator generation and conversion functions
+
+Testing Methodology
+===================
+
+Unit Testing Framework:
+- Built on Python's unittest framework with pytest integration
+- Total of 79 tests covering ~90% of the codebase functionality
+- Includes both unit tests and integration tests
+
+Mock Testing Strategy:
+- Extensive use of unittest.mock for quantum hardware operations
+- Mocked IBM Quantum backends to avoid actual hardware calls during CI
+- Simulated measurement results for deterministic testing
+
+Reproducibility:
+- Fixed random seeds (typically 42 or 999) for deterministic test results
+- Controlled random state generation for quantum states and parameters
+- Consistent test environments across different platforms
+
+Test Coverage Areas:
+- Algorithmic correctness of hypercube graph operations
+- Quantum circuit construction and transpilation
+- Hardware noise simulation and error mitigation
+- Mathematical accuracy of quantum information measures
+- Edge cases and error handling
+
+Quality Assurance Features:
+- Warning suppression for external library deprecations (mthree, Qiskit)
+- Numerical stability testing with small floating-point values
+- Input validation and error handling verification
+- Performance testing for large qubit counts (up to 10 qubits)
+
+Configuration and Execution
+===========================
+
+Test Configuration:
+- pytest.ini configures warning filters for clean test output
+- Suppresses DeprecationWarnings from mthree and Qiskit dependencies
+- Maintains UserWarning and RuntimeWarning visibility for debugging
+
+Running Tests:
+```bash
+# Run all tests
+pytest tests/
+
+# Run with verbose output
+pytest tests/ -v
+
+# Run specific test module
+pytest tests/test_utils.py
+
+# Run with coverage report
+coverage run -m pytest tests/
+coverage report
+
+# Run tests for specific functionality
+pytest tests/test_sample.py::TestQuantumSampling -v
+```
+
+Dependencies for Testing:
+- Core: numpy, scipy, networkx, qiskit
+- Testing: pytest, unittest.mock, coverage
+- Quantum: qiskit-aer, qiskit-ibm-runtime, mthree
+- Optional: pygraphviz (for tree visualization tests)
+
+Integration with CI/CD:
+- Automated testing on GitHub Actions
+- Coverage reporting via coveralls
+- Tests run on multiple Python versions and platforms
+- Graphviz-dependent tests are conditionally skipped in CI environments
+
+Test Data and Fixtures:
+- Uses tutorial notebooks as behavioral references
+- Includes known quantum states (Bell states, stabilizer states)
+- Validates against theoretical predictions from quantum information theory
+- Tests hardware noise models based on IBM Quantum device characteristics
+
+This test suite ensures the reliability, accuracy, and performance of the HRF
+quantum state tomography library across various quantum computing platforms
+and use cases.
+"""