1---2name: nonlinear-solvers3description: >4 Select and configure nonlinear solvers for root-finding f(x)=0, optimization5 min F(x), and least-squares problems — choose among Newton, Newton-Krylov,6 quasi-Newton (BFGS, L-BFGS), Broyden, Anderson acceleration, and7 Levenberg-Marquardt methods, configure line search or trust-region8 globalization, diagnose convergence rate (quadratic, linear, stagnated),9 and assess Jacobian quality and conditioning. Use when a Newton solver10 converges slowly or diverges, choosing between line search and trust region,11 debugging nonlinear iteration failures in FEM or phase-field codes, or12 selecting a solver for large-scale unconstrained optimization, even if13 the user only says "my Newton iterations aren't converging."14allowed-tools: Read, Bash, Write, Grep, Glob15metadata:16 source: https://skillmd.com/skills/zuoguyoupan2023/nonlinear-solvers17 author: HeshamFS18 version: "1.1.0"19 security_tier: high20 security_reviewed: true21 tested_with:22 - claude-code23 - gemini-cli24 - vs-code-copilot25 eval_cases: 526 last_reviewed: "2026-03-26"27---2829# Nonlinear Solvers3031## Goal3233Provide a universal workflow to select a nonlinear solver, configure globalization strategies, and diagnose convergence for root-finding, optimization, and least-squares problems.3435## Requirements3637- Python 3.10+38- NumPy (for Jacobian diagnostics)39- SciPy (optional, for advanced analysis)4041## Inputs to Gather4243| Input | Description | Example |44|-------|-------------|---------|45| Problem type | Root-finding, optimization, least-squares | `root-finding` |46| Problem size | Number of unknowns | `n = 10000` |47| Jacobian availability | Analytic, finite-diff, unavailable | `analytic` |48| Jacobian cost | Cheap or expensive to compute | `expensive` |49| Constraints | None, bounds, equality, inequality | `none` |50| Smoothness | Is objective/residual smooth? | `yes` |51| Residual history | Sequence of residual norms | `1,0.1,0.01,...` |5253## Decision Guidance5455### Solver Selection Flowchart5657```58Is Jacobian available and cheap?59├── YES → Problem size?60│ ├── Small (n < 1000) → Newton (full)61│ └── Large (n ≥ 1000) → Newton-Krylov62└── NO → Is objective smooth?63 ├── YES → Memory limited?64 │ ├── YES → L-BFGS or Broyden65 │ └── NO → BFGS66 └── NO → Anderson acceleration or Picard67```6869### Quick Reference7071| Problem Type | First Choice | Alternative | Globalization |72|--------------|--------------|-------------|---------------|73| Small root-finding | Newton | Broyden | Line search |74| Large root-finding | Newton-Krylov | Anderson | Trust region |75| Optimization | L-BFGS | BFGS | Wolfe line search |76| Least-squares | Levenberg-Marquardt | Gauss-Newton | Trust region |77| Bound constrained | L-BFGS-B | Trust-region reflective | Projected |7879## Script Outputs (JSON Fields)8081| Script | Key Outputs |82|--------|-------------|83| `scripts/solver_selector.py` | `recommended`, `alternatives`, `notes` |84| `scripts/convergence_analyzer.py` | `converged`, `convergence_type`, `estimated_rate`, `diagnosis` |85| `scripts/jacobian_diagnostics.py` | `condition_number`, `jacobian_quality`, `rank_deficient` |86| `scripts/globalization_advisor.py` | `strategy`, `line_search_type`, `trust_region_type`, `parameters` |87| `scripts/residual_monitor.py` | `patterns_detected`, `alerts`, `recommendations` |88| `scripts/step_quality.py` | `ratio`, `step_quality`, `accept_step`, `trust_radius_action` |8990## Workflow91921. **Characterize problem** - Identify type, size, Jacobian availability932. **Select solver** - Run `scripts/solver_selector.py`943. **Choose globalization** - Run `scripts/globalization_advisor.py`954. **Analyze Jacobian** - If available, run `scripts/jacobian_diagnostics.py`965. **Monitor residuals** - During solve, use `scripts/residual_monitor.py`976. **Analyze convergence** - Run `scripts/convergence_analyzer.py`987. **Evaluate steps** - For trust region, use `scripts/step_quality.py`99100## Conversational Workflow Example101102**User**: My Newton solver for a phase-field simulation is converging very slowly. After 50 iterations, the residual only dropped from 1 to 0.1.103104**Agent workflow**:1051. Analyze convergence:106 ```bash107 python3 scripts/convergence_analyzer.py --residuals 1,0.8,0.6,0.5,0.4,0.3,0.2,0.15,0.12,0.1 --json108 ```1092. Check globalization strategy:110 ```bash111 python3 scripts/globalization_advisor.py --problem-type root-finding --jacobian-quality ill-conditioned --previous-failures 0 --json112 ```1133. Recommend: Switch to trust region with Levenberg-Marquardt regularization, or use Newton-Krylov with better preconditioning.114115## Pre-Solve Checklist116117- [ ] Confirm problem type (root-finding, optimization, least-squares)118- [ ] Assess Jacobian availability and cost119- [ ] Check initial guess quality120- [ ] Set appropriate tolerances121- [ ] Choose globalization strategy122- [ ] Prepare to monitor convergence123124## CLI Examples125126```bash127# Select solver for large unconstrained optimization128python3 scripts/solver_selector.py --size 50000 --smooth --memory-limited --json129130# Analyze convergence from residual history131python3 scripts/convergence_analyzer.py --residuals 1,0.1,0.01,0.001,0.0001 --tolerance 1e-6 --json132133# Diagnose Jacobian quality134python3 scripts/jacobian_diagnostics.py --matrix jacobian.txt --json135136# Get globalization recommendation137python3 scripts/globalization_advisor.py --problem-type optimization --jacobian-quality good --json138139# Monitor residual patterns140python3 scripts/residual_monitor.py --residuals 1,0.8,0.9,0.7,0.75,0.6 --target-tolerance 1e-8 --json141142# Evaluate step quality for trust region143python3 scripts/step_quality.py --predicted-reduction 0.5 --actual-reduction 0.4 --step-norm 0.8 --gradient-norm 1.0 --trust-radius 1.0 --json144```145146## Error Handling147148| Error | Cause | Resolution |149|-------|-------|------------|150| `problem_size must be positive` | Invalid size | Check problem dimension |151| `constraint_type must be one of...` | Unknown constraint | Use: none, bound, equality, inequality |152| `residuals must be non-negative` | Invalid residual data | Check residual computation |153| `Matrix file not found` | Invalid path | Verify Jacobian file exists |154155## Interpretation Guidance156157### Convergence Type158159| Type | Meaning | Action |160|------|---------|--------|161| quadratic | Optimal Newton | Continue, near solution |162| superlinear | Quasi-Newton working | Monitor for stagnation |163| linear | Acceptable | May improve with preconditioner |164| sublinear | Too slow | Change method or formulation |165| stagnated | No progress | Check Jacobian, preconditioner |166| diverged | Increasing residual | Add globalization, check Jacobian |167168### Jacobian Quality169170| Quality | Condition Number | Action |171|---------|------------------|--------|172| good | < 10⁶ | Standard Newton works |173| moderately-conditioned | 10⁶ - 10¹⁰ | Consider scaling |174| ill-conditioned | > 10¹⁰ | Use regularization |175| near-singular | ∞ | Reformulate or use LM |176177### Step Quality (Trust Region)178179| Ratio ρ | Quality | Trust Radius |180|---------|---------|--------------|181| ρ < 0 | very_poor | Shrink aggressively |182| ρ < 0.25 | marginal | Shrink |183| 0.25 ≤ ρ < 0.75 | good | Maintain |184| ρ ≥ 0.75 | excellent | Expand if at boundary |185186## Security187188### Input Validation189- `--size` (problem size) is validated as a positive integer, bounded at 10 billion190- `--residuals` are validated as finite non-negative numbers, capped at 100,000 entries191- `--tolerance` and `--target-tolerance` are validated as finite positive numbers192- `--problem-type` and `--constraint-type` are validated against fixed allowlists193- `--jacobian-quality` is validated against a fixed allowlist (`good`, `ill-conditioned`, etc.)194- Step quality parameters (`predicted-reduction`, `actual-reduction`, `step-norm`, `gradient-norm`, `trust-radius`) are validated as finite numbers195196### File Access197- `jacobian_diagnostics.py` reads a single matrix file specified by `--matrix`; no directory traversal beyond the given path198- Matrix files are size-limited and loaded with `allow_pickle=False` to prevent code execution199- All other scripts read no external files; inputs are provided via CLI arguments200- Scripts write only to stdout (JSON output)201202### Tool Restrictions203- **Read**: Used to inspect script source, references, and user configuration files204- **Bash**: Used to execute the six Python analysis scripts (`solver_selector.py`, `convergence_analyzer.py`, `jacobian_diagnostics.py`, `globalization_advisor.py`, `residual_monitor.py`, `step_quality.py`) with explicit argument lists205- **Write**: Used to save analysis results or solver recommendations; writes are scoped to the user's working directory206- **Grep/Glob**: Used to locate relevant files and search references207208### Safety Measures209- No `eval()`, `exec()`, or dynamic code generation210- All subprocess calls use explicit argument lists (no `shell=True`)211- Matrix dimension limits prevent memory exhaustion when loading Jacobian files212- Residual history analysis operates on bounded-length numeric arrays only213214## Limitations215216- **No global convergence guarantee**: All methods may fail for pathological problems217- **Jacobian accuracy**: Finite-difference Jacobian may be inaccurate near discontinuities218- **Large dense problems**: May require specialized solvers not covered here219- **Constrained optimization**: Complex constraints need SQP or interior point methods220221## References222223- `references/solver_decision_tree.md` - Problem-based solver selection224- `references/method_catalog.md` - Method details and parameters225- `references/convergence_diagnostics.md` - Diagnosing convergence issues226- `references/globalization_strategies.md` - Line search and trust region227228## Version History229230- **v1.0.0** : Initial release with 6 analysis scripts