Re-enable BiCGSTAB and linSolve0 iterative solvers

.github/copilot-instructions.md

@@ -0,0 +1,33 @@
+## Engineering and workflow conventions
+
+## Workflow
+Use the Makefile : `make build`, `make test`, which internally use the `stack` CLI.
+
+### Clarity before code
+Do not jump into coding new features or fixing bugs without first fully understanding the requirements and implications.
+Always discuss with the user or team to clarify any ambiguities before starting implementation, and ask follow up questions if needed.
+
+### NO SHORTCUTS
+Never leave incomplete functions or stubs in the codebase. Every function must be fully implemented or explicitly marked as unimplemented with a clear error message. 
+Never delete or comment out tests to bypass failures; instead, investigate and resolve the underlying issues. 
+Never, ever, use "In a real implementation," or similar phrases to justify incomplete code or post-hoc defaults.
+Do /not/ mark functions as TODO or FIXME without prior approval from the user. Scope down a feature if needed, and tell the user what's missing.
+
+### Testing and validation
+A feature is not complete until it has comprehensive tests that validate its correctness and robustness.
+Meaningful tests rather than coverage: Aim for meaningful, high-quality tests that thoroughly validate core functionality and edge cases.
+Do not test trivial properties of data structures, but aim for domain-specific validation.
+
+
+### Debugging and troubleshooting
+When investigating or debugging, do not skip or modify tests, or mark them as pending, without receiving prior approval from the user.
+
+
+### Module Imports
+All imports must be explicit. If a module does not export an explicit list, import only the needed symbols. When importing an external library, import only the required functions/types.
+
+### Errors and exceptions
+* Never use `error` or `undefined`
+* functions with alternative return types should use sum types (e.g. Maybe, Either, or custom ones)
+* All error messages should be informative and include context about the failure that can be used to fix the issue.
+

BUILD_AND_TEST.md

@@ -0,0 +1,124 @@
+# Build and Test Instructions
+
+This document provides instructions for building and testing the BiCGSTAB and linSolve0 re-enablement.
+
+## Prerequisites
+
+- Stack build tool installed
+- Internet connection for downloading dependencies
+
+## Build
+
+```bash
+# Build the project
+stack build
+
+# Or using make
+make build
+```
+
+Expected output: Successful compilation with no errors.
+
+## Test
+
+### Run All Tests
+
+```bash
+# Run full test suite
+stack test
+
+# Or using make
+make test
+```
+
+### Run Specific Test Suites
+
+```bash
+# Test BiCGSTAB only
+stack test --test-arguments "-m BiCGSTAB"
+
+# Test CGS only
+stack test --test-arguments "-m CGS"
+
+# Test linSolve0 interface
+stack test --test-arguments "-m linSolve"
+```
+
+## Expected Test Results
+
+### BiCGSTAB Tests
+- ✅ bicgsInit creates initial BiCGSTAB state
+- ✅ bicgstabStep performs one iteration
+- ✅ BiCGSTAB converges on 2x2 system
+- ✅ BiCGSTAB converges on 3x3 SPD system
+- ✅ prop_bicgstab : BiCGSTAB converges for SPD systems (100 QuickCheck cases)
+
+### linSolve0 Tests
+- ✅ BiCGSTAB (2 x 2 dense)
+- ✅ BiCGSTAB (3 x 3 sparse, symmetric pos.def.)
+- ✅ CGS (2 x 2 dense)
+- ✅ CGS (3 x 3 sparse, SPD)
+- ✅ CGNE (2 x 2 dense)
+- ✅ CGNE (3 x 3 sparse, SPD)
+
+### CGS Tests (Existing, should still pass)
+- ✅ cgsInit creates initial CGS state
+- ✅ cgsStep performs one iteration
+- ✅ CGS converges on 2x2 system
+- ✅ CGS converges on 3x3 SPD system
+- ✅ prop_cgs : CGS converges for SPD systems (100 QuickCheck cases)
+
+## Troubleshooting
+
+### If Tests Fail
+
+1. **Check tolerance settings**: The tests use lenient tolerances (1e-4 relative, 1e-6 absolute)
+   - If tests fail due to convergence issues, consider increasing the number of iterations
+   - Location: `test/LibSpec.hs`, functions `checkBiCGSTAB`, `checkCGS`
+
+2. **Check system properties**: Property tests guard against degenerate cases:
+   - Systems smaller than 3x3
+   - Nearly zero RHS or solution vectors
+   - Very sparse matrices with few non-zeros
+   - Large sparse systems (n > 20 with density < 0.1)
+
+3. **Debug with trace output**: Use `checkCGSDebug` function for detailed iteration output
+
+4. **Verify preconditioning**: Consider adding preconditioning for ill-conditioned systems
+
+### Network Issues
+
+If `stack build` fails due to network timeouts:
+
+1. Try again - sometimes Stackage servers are temporarily unavailable
+2. Check your internet connection
+3. Try using a different resolver in `stack.yaml`
+4. Use cached dependencies if available: `stack build --no-install-ghc`
+
+## Verification Checklist
+
+Before considering the task complete:
+
+- [ ] `stack build` completes successfully with no warnings
+- [ ] All BiCGSTAB tests pass
+- [ ] All linSolve0 tests pass
+- [ ] All existing tests (CGS, etc.) still pass
+- [ ] No new compiler warnings introduced
+- [ ] Documentation is up to date
+
+## Performance Notes
+
+- BiCGSTAB typically converges faster than CGS on most systems
+- BiCGSTAB is more stable for ill-conditioned matrices
+- linSolve0 uses 200 fixed iterations - convergence usually happens much sooner
+- Property tests may take a few seconds due to QuickCheck generating 100 test cases
+
+## Next Steps
+
+After successful build and test:
+
+1. Review test output for any warnings
+2. Check if any tests are flaky or timeout
+3. Consider adding preconditioner support
+4. Benchmark performance against other solvers
+5. Add more comprehensive documentation/examples

COMMENTED_OUT_FUNCTIONS.md

@@ -4,6 +4,7 @@ This document lists all the functions that were commented out during the process
 
 **Status Updates:**
 - ✅ **CGS (Conjugate Gradient Squared)**: Re-enabled with comprehensive tests (see issue/PR for re-enabling CGS)
+- ✅ **BiCGSTAB (Biconjugate Gradient Stabilized)**: Re-enabled with comprehensive tests
 
 ## File: src/Numeric/LinearAlgebra/Sparse.hs
 
@@ -83,10 +84,12 @@ cgsStep aa rhat (CGS x r p u) = CGS xj1 rj1 pj1 uj1
 
 ---
 
-### 3. BiCGSTAB (Biconjugate Gradient Stabilized) Solver Functions
+### 3. ✅ BiCGSTAB (Biconjugate Gradient Stabilized) Solver Functions - **RE-ENABLED**
+
+**Status**: Functions have been uncommented, exported from the module, and comprehensive tests added.
 
 #### `bicgsInit`
-**Lines**: 950-954 (commented)
+**Status**: ✅ Active (lines 961-964)
 ```haskell
 bicgsInit :: LinearVectorSpace (SpVector a) =>
      MatrixType (SpVector a) -> SpVector a -> SpVector a -> BICGSTAB a
@@ -96,7 +99,7 @@ bicgsInit aa b x0 = BICGSTAB x0 r0 r0 where
 **Purpose**: Initializes the BiCGSTAB solver state
 
 #### `bicgstabStep`
-**Lines**: 956-971 (commented)
+**Status**: ✅ Active (lines 966-977)
 ```haskell
 bicgstabStep :: (V (SpVector a), Fractional (Scalar (SpVector a))) =>
      MatrixType (SpVector a) -> SpVector a -> BICGSTAB a -> BICGSTAB a
@@ -113,6 +116,12 @@ bicgstabStep aa r0hat (BICGSTAB x r p) = BICGSTAB xj1 rj1 pj1 where
 ```
 **Purpose**: Performs one iteration step of the BiCGSTAB algorithm
 
+**Tests Added**:
+- Unit tests for `bicgsInit` (verifies initial state)
+- Unit tests for `bicgstabStep` (verifies iteration works)
+- Integration tests on 2x2 and 3x3 systems
+- Property-based test for SPD (symmetric positive definite) systems
+
 ---
 
 ### 4. Moore-Penrose Pseudoinverse
@@ -145,13 +154,12 @@ class IterativeSolver s where
 ## Summary Statistics
 
 - **Total functions originally commented out**: 10
-- **Re-enabled**: 2 (CGS)
-- **Still commented out**: 8
+- **Re-enabled**: 4 (CGS + BiCGSTAB)
+- **Still commented out**: 6
   - BCG-related: 2 functions
-  - BiCGSTAB-related: 2 functions
   - Pseudoinverse: 1 function
   - Typeclass: 1 class definition
-  - Show instances: 3 instances (for BCG, CGS, BICGSTAB)
+  - Show instances: 1 instance (for BCG)
 
 ## Reason for Commenting Out