Linear Solvers
Goal
Provide a universal workflow to select a solver, assess conditioning, and diagnose convergence for linear systems arising in numerical simulations.
Requirements
- Python 3.10+
- NumPy, SciPy (for matrix operations)
- See individual scripts for dependencies
Inputs to Gather
| Input |
Description |
Example |
| Matrix size |
Dimension of system |
n = 1000000 |
| Sparsity |
Fraction of nonzeros |
0.01% |
| Symmetry |
Is A = Aᵀ? |
yes |
| Definiteness |
Is A positive definite? |
yes (SPD) |
| Conditioning |
Estimated condition number |
10⁶ |
Decision Guidance
Solver Selection Flowchart
Is matrix small (n < 5000) and dense?
├── YES → Use direct solver (LU, Cholesky)
└── NO → Is matrix symmetric?
├── YES → Is it positive definite?
│ ├── YES → Use CG with AMG/IC preconditioner
│ └── NO → Use MINRES
└── NO → Is it nearly symmetric?
├── YES → Use BiCGSTAB
└── NO → Use GMRES with ILU/AMG
Quick Reference
| Matrix Type |
Solver |
Preconditioner |
| SPD, sparse |
CG |
AMG, IC |
| Symmetric indefinite |
MINRES |
ILU |
| Nonsymmetric |
GMRES, BiCGSTAB |
ILU, AMG |
| Dense |
LU, Cholesky |
None |
| Saddle point |
Schur complement, Uzawa |
Block preconditioner |
Script Outputs (JSON Fields)
| Script |
Key Outputs |
scripts/solver_selector.py |
recommended, alternatives, notes |
scripts/convergence_diagnostics.py |
rate, stagnation, recommended_action |
scripts/sparsity_stats.py |
nnz, density, bandwidth, symmetry |
scripts/preconditioner_advisor.py |
suggested, notes |
scripts/scaling_equilibration.py |
row_scale, col_scale, notes |
scripts/residual_norms.py |
residual_norms, relative_norms, converged |
Workflow
- Characterize matrix - symmetry, definiteness, sparsity
- Analyze sparsity - Run
scripts/sparsity_stats.py
- Select solver - Run
scripts/solver_selector.py
- Choose preconditioner - Run
scripts/preconditioner_advisor.py
- Apply scaling - If ill-conditioned, use
scripts/scaling_equilibration.py
- Monitor convergence - Use
scripts/convergence_diagnostics.py
- Diagnose issues - Check residual history with
scripts/residual_norms.py
Conversational Workflow Example
User: My GMRES solver is stagnating after 50 iterations. The residual drops to 1e-3 then stops improving.
Agent workflow:
- Diagnose convergence:
python3 scripts/convergence_diagnostics.py --residuals 1,0.1,0.01,0.005,0.003,0.002,0.002,0.002 --json
- Check for preconditioning advice:
python3 scripts/preconditioner_advisor.py --matrix-type nonsymmetric --sparse --stagnation --json
- Recommend: Increase restart parameter, try ILU(k) with higher k, or switch to AMG.
Pre-Solve Checklist
CLI Examples
# Analyze sparsity pattern
python3 scripts/sparsity_stats.py --matrix A.npy --json
# Select solver for SPD sparse system
python3 scripts/solver_selector.py --symmetric --positive-definite --sparse --size 1000000 --json
# Get preconditioner recommendation
python3 scripts/preconditioner_advisor.py --matrix-type spd --sparse --json
# Diagnose convergence from residual history
python3 scripts/convergence_diagnostics.py --residuals 1,0.2,0.05,0.01 --json
# Apply scaling
python3 scripts/scaling_equilibration.py --matrix A.npy --symmetric --json
# Compute residual norms
python3 scripts/residual_norms.py --residual 1,0.1,0.01 --rhs 1,0,0 --json
Error Handling
| Error |
Cause |
Resolution |
Matrix file not found |
Invalid path |
Check file exists |
Matrix must be square |
Non-square input |
Verify matrix dimensions |
Residuals must be positive |
Invalid residual data |
Check input format |
Interpretation Guidance
Convergence Rate
| Rate |
Meaning |
Action |
| < 0.1 |
Excellent |
Current setup optimal |
| 0.1 - 0.5 |
Good |
Acceptable for most problems |
| 0.5 - 0.9 |
Slow |
Consider better preconditioner |
| > 0.9 |
Stagnation |
Change solver or preconditioner |
Stagnation Diagnosis
| Pattern |
Likely Cause |
Fix |
| Flat residual |
Poor preconditioner |
Improve preconditioner |
| Oscillating |
Near-singular or indefinite |
Check matrix, try different solver |
| Very slow decay |
Ill-conditioned |
Apply scaling, use AMG |
Security
Input Validation
- All numeric inputs (residuals, tolerances, matrix entries) are validated as finite numbers
- Comma-separated residual/vector inputs are capped at 100,000 entries
- The
solver_selector.py --size parameter is bounded at 10 billion
--matrix-type is validated against a fixed allowlist (spd, symmetric, nonsymmetric)
- Boolean flags (
--symmetric, --positive-definite, --sparse, --stagnation) are type-safe argparse flags
File Access
sparsity_stats.py and scaling_equilibration.py read a single matrix file (.npy format) specified by --matrix
np.load() is called with allow_pickle=False to prevent arbitrary code execution via crafted .npy files
- Matrix files are rejected if they exceed 500 MB before any parsing occurs
- Matrix dimension limits (100,000 per dimension) prevent memory exhaustion
- All other scripts read no external files; inputs are provided via CLI arguments
Tool Restrictions
- Read: Used to inspect script source, references, and matrix files
- Write: Used to save analysis results or solver recommendations; writes are scoped to the user's working directory
- Grep/Glob: Used to locate relevant files and search references
- The skill's
allowed-tools excludes Bash to prevent the agent from executing arbitrary commands when processing untrusted matrix files or numeric inputs
Safety Measures
- No
eval(), exec(), or dynamic code generation
- All subprocess calls use explicit argument lists (no
shell=True)
- Reduced tool surface (no Bash) limits the agent to read/write operations only
- JSON output mode produces structured, parseable results without shell-interpretable content
Limitations
- Large dense matrices: Direct solvers may run out of memory
- Highly indefinite: Standard preconditioners may fail
- Saddle-point: Requires specialized block preconditioners
References
references/solver_decision_tree.md - Selection logic
references/preconditioner_catalog.md - Preconditioner options
references/convergence_patterns.md - Diagnosing failures
references/scaling_guidelines.md - Equilibration guidance
Version History
- v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
- v1.0.0: Initial release with 6 solver analysis scripts
1---2name: linear-solvers3description: >4 Select and configure linear solvers for Ax=b systems arising in numerical5 simulations — choose between direct (LU, Cholesky) and iterative (CG, GMRES,6 BiCGSTAB, MINRES) methods, analyze sparsity patterns and matrix conditioning,7 recommend preconditioners (AMG, ILU, IC), apply row/column scaling, and8 diagnose convergence stagnation from residual histories. Use when setting up9 a linear solve for FEM/FVM assembly, debugging slow or stalled Krylov10 iterations, choosing a preconditioner for SPD or nonsymmetric systems, or11 investigating ill-conditioning, even if the user only says "my solver is12 slow" or "GMRES won't converge."13allowed-tools: Read, Write, Grep, Glob14metadata:15 source: https://skillmd.com/skills/zuoguyoupan2023/linear-solvers16 author: HeshamFS17 version: "1.1.0"18 security_tier: medium19 security_reviewed: true20 tested_with:21 - claude-code22 - gemini-cli23 - vs-code-copilot24 eval_cases: 425 last_reviewed: "2026-03-26"26---2728# Linear Solvers2930## Goal3132Provide a universal workflow to select a solver, assess conditioning, and diagnose convergence for linear systems arising in numerical simulations.3334## Requirements3536- Python 3.10+37- NumPy, SciPy (for matrix operations)38- See individual scripts for dependencies3940## Inputs to Gather4142| Input | Description | Example |43|-------|-------------|---------|44| Matrix size | Dimension of system | `n = 1000000` |45| Sparsity | Fraction of nonzeros | `0.01%` |46| Symmetry | Is A = Aᵀ? | `yes` |47| Definiteness | Is A positive definite? | `yes (SPD)` |48| Conditioning | Estimated condition number | `10⁶` |4950## Decision Guidance5152### Solver Selection Flowchart5354```55Is matrix small (n < 5000) and dense?56├── YES → Use direct solver (LU, Cholesky)57└── NO → Is matrix symmetric?58 ├── YES → Is it positive definite?59 │ ├── YES → Use CG with AMG/IC preconditioner60 │ └── NO → Use MINRES61 └── NO → Is it nearly symmetric?62 ├── YES → Use BiCGSTAB63 └── NO → Use GMRES with ILU/AMG64```6566### Quick Reference6768| Matrix Type | Solver | Preconditioner |69|-------------|--------|----------------|70| SPD, sparse | CG | AMG, IC |71| Symmetric indefinite | MINRES | ILU |72| Nonsymmetric | GMRES, BiCGSTAB | ILU, AMG |73| Dense | LU, Cholesky | None |74| Saddle point | Schur complement, Uzawa | Block preconditioner |7576## Script Outputs (JSON Fields)7778| Script | Key Outputs |79|--------|-------------|80| `scripts/solver_selector.py` | `recommended`, `alternatives`, `notes` |81| `scripts/convergence_diagnostics.py` | `rate`, `stagnation`, `recommended_action` |82| `scripts/sparsity_stats.py` | `nnz`, `density`, `bandwidth`, `symmetry` |83| `scripts/preconditioner_advisor.py` | `suggested`, `notes` |84| `scripts/scaling_equilibration.py` | `row_scale`, `col_scale`, `notes` |85| `scripts/residual_norms.py` | `residual_norms`, `relative_norms`, `converged` |8687## Workflow88891. **Characterize matrix** - symmetry, definiteness, sparsity902. **Analyze sparsity** - Run `scripts/sparsity_stats.py`913. **Select solver** - Run `scripts/solver_selector.py`924. **Choose preconditioner** - Run `scripts/preconditioner_advisor.py`935. **Apply scaling** - If ill-conditioned, use `scripts/scaling_equilibration.py`946. **Monitor convergence** - Use `scripts/convergence_diagnostics.py`957. **Diagnose issues** - Check residual history with `scripts/residual_norms.py`9697## Conversational Workflow Example9899**User**: My GMRES solver is stagnating after 50 iterations. The residual drops to 1e-3 then stops improving.100101**Agent workflow**:1021. Diagnose convergence:103 ```bash104 python3 scripts/convergence_diagnostics.py --residuals 1,0.1,0.01,0.005,0.003,0.002,0.002,0.002 --json105 ```1062. Check for preconditioning advice:107 ```bash108 python3 scripts/preconditioner_advisor.py --matrix-type nonsymmetric --sparse --stagnation --json109 ```1103. Recommend: Increase restart parameter, try ILU(k) with higher k, or switch to AMG.111112## Pre-Solve Checklist113114- [ ] Confirm matrix symmetry/definiteness115- [ ] Decide direct vs iterative based on size and sparsity116- [ ] Set residual tolerance relative to physics scale117- [ ] Choose preconditioner appropriate to matrix structure118- [ ] Apply scaling/equilibration if needed119- [ ] Track convergence and adjust if stagnation occurs120121## CLI Examples122123```bash124# Analyze sparsity pattern125python3 scripts/sparsity_stats.py --matrix A.npy --json126127# Select solver for SPD sparse system128python3 scripts/solver_selector.py --symmetric --positive-definite --sparse --size 1000000 --json129130# Get preconditioner recommendation131python3 scripts/preconditioner_advisor.py --matrix-type spd --sparse --json132133# Diagnose convergence from residual history134python3 scripts/convergence_diagnostics.py --residuals 1,0.2,0.05,0.01 --json135136# Apply scaling137python3 scripts/scaling_equilibration.py --matrix A.npy --symmetric --json138139# Compute residual norms140python3 scripts/residual_norms.py --residual 1,0.1,0.01 --rhs 1,0,0 --json141```142143## Error Handling144145| Error | Cause | Resolution |146|-------|-------|------------|147| `Matrix file not found` | Invalid path | Check file exists |148| `Matrix must be square` | Non-square input | Verify matrix dimensions |149| `Residuals must be positive` | Invalid residual data | Check input format |150151## Interpretation Guidance152153### Convergence Rate154155| Rate | Meaning | Action |156|------|---------|--------|157| < 0.1 | Excellent | Current setup optimal |158| 0.1 - 0.5 | Good | Acceptable for most problems |159| 0.5 - 0.9 | Slow | Consider better preconditioner |160| > 0.9 | Stagnation | Change solver or preconditioner |161162### Stagnation Diagnosis163164| Pattern | Likely Cause | Fix |165|---------|--------------|-----|166| Flat residual | Poor preconditioner | Improve preconditioner |167| Oscillating | Near-singular or indefinite | Check matrix, try different solver |168| Very slow decay | Ill-conditioned | Apply scaling, use AMG |169170## Security171172### Input Validation173- All numeric inputs (residuals, tolerances, matrix entries) are validated as finite numbers174- Comma-separated residual/vector inputs are capped at 100,000 entries175- The `solver_selector.py` `--size` parameter is bounded at 10 billion176- `--matrix-type` is validated against a fixed allowlist (`spd`, `symmetric`, `nonsymmetric`)177- Boolean flags (`--symmetric`, `--positive-definite`, `--sparse`, `--stagnation`) are type-safe argparse flags178179### File Access180- `sparsity_stats.py` and `scaling_equilibration.py` read a single matrix file (`.npy` format) specified by `--matrix`181- `np.load()` is called with `allow_pickle=False` to prevent arbitrary code execution via crafted `.npy` files182- Matrix files are rejected if they exceed 500 MB before any parsing occurs183- Matrix dimension limits (100,000 per dimension) prevent memory exhaustion184- All other scripts read no external files; inputs are provided via CLI arguments185186### Tool Restrictions187- **Read**: Used to inspect script source, references, and matrix files188- **Write**: Used to save analysis results or solver recommendations; writes are scoped to the user's working directory189- **Grep/Glob**: Used to locate relevant files and search references190- The skill's `allowed-tools` excludes `Bash` to prevent the agent from executing arbitrary commands when processing untrusted matrix files or numeric inputs191192### Safety Measures193- No `eval()`, `exec()`, or dynamic code generation194- All subprocess calls use explicit argument lists (no `shell=True`)195- Reduced tool surface (no Bash) limits the agent to read/write operations only196- JSON output mode produces structured, parseable results without shell-interpretable content197198## Limitations199200- **Large dense matrices**: Direct solvers may run out of memory201- **Highly indefinite**: Standard preconditioners may fail202- **Saddle-point**: Requires specialized block preconditioners203204## References205206- `references/solver_decision_tree.md` - Selection logic207- `references/preconditioner_catalog.md` - Preconditioner options208- `references/convergence_patterns.md` - Diagnosing failures209- `references/scaling_guidelines.md` - Equilibration guidance210211## Version History212213- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples214- **v1.0.0**: Initial release with 6 solver analysis scripts