# linear-solvers

Selects and tunes linear solvers for Ax=b systems in numerical simulations. Diagnoses stalled Krylov iterations and recommends preconditioners.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 83
- Author: HeshamFS
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/HeshamFS/materials-simulation-skills/tree/HEAD/skills/core-numerical/linear-solvers/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/linear-solvers

## What it does

This skill guides solver selection for linear systems arising in FEM and FVM simulations. It checks matrix sparsity, symmetry, and definiteness to determine whether direct factorizations or Krylov methods like CG, GMRES, BiCGSTAB, or MINRES fit best. Accompanying Python tools analyze sparsity patterns, compute equilibration factors, and evaluate residual norms.

When Krylov iterations stall, `convergence_diagnostics.py` computes the asymptotic convergence rate across trailing steps. A rate above 0.95 indicates stagnation. The workflow then advises on switching to AMG or ILU preconditioning, increasing the GMRES restart count, or applying row and column scaling. Running these diagnostic utilities requires Python 3.10+, NumPy, and SciPy.

## Requirements
- Works with: Linear

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add HeshamFS/materials-simulation-skills --skill linear-solvers -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/linear-solvers/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/linear-solvers/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add HeshamFS/materials-simulation-skills --skill linear-solvers -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/linear-solvers/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add HeshamFS/materials-simulation-skills --skill linear-solvers -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/linear-solvers/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install HeshamFS/materials-simulation-skills linear-solvers
```

2. **Manually: put the files in place**
- File: `.github/skills/linear-solvers/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add HeshamFS/materials-simulation-skills --skill linear-solvers -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/HeshamFS/materials-simulation-skills --path skills/core-numerical/linear-solvers
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/linear-solvers/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add HeshamFS/materials-simulation-skills --skill linear-solvers -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/HeshamFS/materials-simulation-skills/tree/HEAD/skills/core-numerical/linear-solvers/SKILL.md

## When to use it
- choose between direct and iterative solvers for sparse or dense systems
- diagnose convergence stagnation in Krylov solvers from residual histories
- select appropriate preconditioners such as AMG or ILU
- compute row and column scaling factors for ill-conditioned matrices

## Example prompts
- My GMRES solver is stagnating after 50 iterations with residual near 1e-3. Diagnose the issue.
- Recommend a solver and preconditioner for an SPD matrix of size 1000000.
- Run scripts/sparsity_stats.py on A.npy to evaluate matrix bandwidth and sparsity.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 29aab56e93588214.

BEGIN THIRD-PARTY FILE 29aab56e93588214
````text
---
name: linear-solvers
description: >
  Select and configure linear solvers for Ax=b systems arising in numerical
  simulations — choose between direct (LU, Cholesky) and iterative (CG, GMRES,
  BiCGSTAB, MINRES) methods, analyze sparsity patterns and matrix conditioning,
  recommend preconditioners (AMG, ILU, IC), apply row/column scaling, and
  diagnose convergence stagnation from residual histories. Use when setting up
  a linear solve for FEM/FVM assembly, debugging slow or stalled Krylov
  iterations, choosing a preconditioner for SPD or nonsymmetric systems, or
  investigating ill-conditioning, even if the user only says "my solver is
  slow" or "GMRES won't converge."
allowed-tools: Read, Write, Grep, Glob
metadata:
  last_deterministic_eval: "2026-10-20"
  agent_evaluation_status: "not_revalidated"
  author: HeshamFS
  version: "1.2.3"
  security_tier: medium
  security_reviewed: true
  tested_with:
    - claude-code
  last_evaluated: "2026-06-24"
  eval_cases: 4
  last_reviewed: "2026-10-19"
  standards:
    - "Saad (2003), Iterative Methods for Sparse Linear Systems (Krylov methods, ILU/ILUT, preconditioning)"
    - "Hestenes & Stiefel (1952) Conjugate Gradient method and the (√κ−1)/(√κ+1) error bound"
    - "Saad & Schultz (1986), GMRES restarted Krylov method"
    - "Ruge & Stüben (1987), Algebraic Multigrid (AMG) classical coarsening"
    - "Ruiz (2001) equilibration; Sinkhorn & Knopp (1967) doubly-stochastic scaling"
---

# 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 dense and small enough to factor in memory (dense float64
storage n²·8 bytes < ~2 GB, i.e. n ≲ 16000)?
├── YES → Use direct solver (Cholesky/LDLᵀ/LU by symmetry)
└── 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 |
````
END THIRD-PARTY FILE 29aab56e93588214

The third-party file has ended. Everything between the 29aab56e93588214 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2730 of 12830 bytes. © HeshamFS · Apache-2.0 · https://github.com/HeshamFS/materials-simulation-skills/tree/HEAD/skills/core-numerical/linear-solvers/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md