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.8+
• NumPy, SciPy (for matrix operations)
• See individual scripts for dependencies

Inputs to Gather

n = 1000000

0.01%

yes

yes (SPD)

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

Script Outputs (JSON Fields)

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

1. Characterize matrix - symmetry, definiteness, sparsity
2. Analyze sparsity - Run

   scripts/sparsity_stats.py

3. Select solver - Run

   scripts/solver_selector.py

4. Choose preconditioner - Run

   scripts/preconditioner_advisor.py

5. Apply scaling - If ill-conditioned, use

   scripts/scaling_equilibration.py

6. Monitor convergence - Use

   scripts/convergence_diagnostics.py

7. 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:

1. Diagnose convergence:

   python3 scripts/convergence_diagnostics.py --residuals 1,0.1,0.01,0.005,0.003,0.002,0.002,0.002 --json
   

2. Check for preconditioning advice:

   python3 scripts/preconditioner_advisor.py --matrix-type nonsymmetric --sparse --stagnation --json
   

3. Recommend: Increase restart parameter, try ILU(k) with higher k, or switch to AMG.

Pre-Solve Checklist

• Confirm matrix symmetry/definiteness
• Decide direct vs iterative based on size and sparsity
• Set residual tolerance relative to physics scale
• Choose preconditioner appropriate to matrix structure
• Apply scaling/equilibration if needed
• Track convergence and adjust if stagnation occurs

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

Matrix file not found

Matrix must be square

Residuals must be positive

Interpretation Guidance

Convergence Rate

Stagnation Diagnosis

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