# nonlinear-solvers

Choose a nonlinear solver, set its globalization strategy, and inspect convergence and Jacobian quality. Useful when Newton iterations stall or diverge.

- 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/nonlinear-solvers/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/nonlinear-solvers

## What it does

The skill covers root-finding, optimization, and least-squares problems. It uses problem size and Jacobian availability to guide choices among Newton, Newton-Krylov, BFGS, L-BFGS, Broyden, Anderson acceleration, and Levenberg-Marquardt. It also advises on line search versus trust-region methods.

Its scripts select solvers, analyze convergence and Jacobians, recommend globalization settings, track residual patterns, and assess steps. Results are available in JSON. Jacobian diagnostics require Python 3.10+ and NumPy; SciPy is optional for advanced analysis. Projects without a Python environment cannot run these scripts as provided.

Start by describing the problem type, size, and Jacobian. Then inspect residual history and solver settings. The recommendations differ for small and large problems, so problem size can change the suggested method.

## Requirements
- Works with: Linear

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

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

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add HeshamFS/materials-simulation-skills --skill nonlinear-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/nonlinear-solvers/SKILL.md

## When to use it
- choose a method for root-finding or optimization
- diagnose slow or divergent Newton iterations
- estimate convergence from residual history
- check Jacobian conditioning and quality
- select line search or a trust region

## Example prompts
- Choose a solver for a large root-finding problem with an expensive analytic Jacobian.
- Analyze this residual history and explain why Newton is converging slowly.
- Check the Jacobian in `jacobian.txt` and recommend a globalization strategy.

## 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: 3aa5786210dd9d22.

BEGIN THIRD-PARTY FILE 3aa5786210dd9d22
```text
---
name: nonlinear-solvers
description: >
  Select and configure nonlinear solvers for root-finding f(x)=0, optimization
  min F(x), and least-squares problems — choose among Newton, Newton-Krylov,
  quasi-Newton (BFGS, L-BFGS), Broyden, Anderson acceleration, and
  Levenberg-Marquardt methods, configure line search or trust-region
  globalization, diagnose convergence rate (quadratic, linear, stagnated),
  and assess Jacobian quality and conditioning. Use when a Newton solver
  converges slowly or diverges, choosing between line search and trust region,
  debugging nonlinear iteration failures in FEM or phase-field codes, or
  selecting a solver for large-scale unconstrained optimization, even if
  the user only says "my Newton iterations aren't converging."
allowed-tools: Read, Bash, Write, Grep, Glob
metadata:
  last_deterministic_eval: "2026-10-20"
  agent_evaluation_status: "not_revalidated"
  author: HeshamFS
  version: "1.2.3"
  security_tier: high
  security_reviewed: true
  tested_with:
    - claude-code
  last_evaluated: "2026-06-24"
  eval_cases: 5
  last_reviewed: "2026-10-19"
  standards:
    - "Nocedal & Wright (2006), Numerical Optimization (BFGS/L-BFGS, trust region, dogleg, Steihaug-CG, Wolfe conditions)"
    - "Dennis & Schnabel (1996), Numerical Methods for Unconstrained Optimization and Nonlinear Equations (Newton, Broyden good/bad, line-search globalization)"
    - "Kelley (1995), Iterative Methods for Linear and Nonlinear Equations (inexact Newton, Newton-Krylov); Eisenstat & Walker (1996) forcing sequence"
    - "Walker & Ni (2011), Anderson acceleration for fixed-point iterations (Anderson 1965)"
    - "Levenberg (1944) / Marquardt (1963), Levenberg-Marquardt method for nonlinear least-squares"
---

# Nonlinear Solvers

## Goal

Provide a universal workflow to select a nonlinear solver, configure globalization strategies, and diagnose convergence for root-finding, optimization, and least-squares problems.

## Requirements

- Python 3.10+
- NumPy (for Jacobian diagnostics)
- SciPy (optional, for advanced analysis)

## Inputs to Gather

| Input | Description | Example |
|-------|-------------|---------|
| Problem type | Root-finding, optimization, least-squares | `root-finding` |
| Problem size | Number of unknowns | `n = 10000` |
| Jacobian availability | Analytic, finite-diff, unavailable | `analytic` |
| Jacobian cost | Cheap or expensive to compute | `expensive` |
| Constraints | None, bounds, equality, inequality | `none` |
| Smoothness | Is objective/residual smooth? | `yes` |
| Residual history | Sequence of residual norms | `1,0.1,0.01,...` |

## Decision Guidance
```
END THIRD-PARTY FILE 3aa5786210dd9d22

The third-party file has ended. Everything between the 3aa5786210dd9d22 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 2644 of 17139 bytes. © HeshamFS · Apache-2.0 · https://github.com/HeshamFS/materials-simulation-skills/tree/HEAD/skills/core-numerical/nonlinear-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