Agent skill

nonlinear-solvers

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

View SKILL.md on GitHub Repository
Stars 29
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/HeshamFS/materials-simulation-skills/tree/main/skills/core-numerical/nonlinear-solvers

Metadata

Additional technical details for this skill

author
HeshamFS
version
1.1.0
eval cases
2
tested with 
[
    "claude-code",
    "gemini-cli",
    "vs-code-copilot"
]
last reviewed
2026-03-26
security tier
high
security reviewed
YES

SKILL.md

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.8+
  • 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

Solver Selection Flowchart

Is Jacobian available and cheap?
├── YES → Problem size?
│   ├── Small (n < 1000) → Newton (full)
│   └── Large (n ≥ 1000) → Newton-Krylov
└── NO → Is objective smooth?
    ├── YES → Memory limited?
    │   ├── YES → L-BFGS or Broyden
    │   └── NO → BFGS
    └── NO → Anderson acceleration or Picard

Quick Reference

Problem Type First Choice Alternative Globalization
Small root-finding Newton Broyden Line search
Large root-finding Newton-Krylov Anderson Trust region
Optimization L-BFGS BFGS Wolfe line search
Least-squares Levenberg-Marquardt Gauss-Newton Trust region
Bound constrained L-BFGS-B Trust-region reflective Projected

Script Outputs (JSON Fields)

Script Key Outputs
scripts/solver_selector.py recommended, alternatives, notes
scripts/convergence_analyzer.py converged, convergence_type, estimated_rate, diagnosis
scripts/jacobian_diagnostics.py condition_number, jacobian_quality, rank_deficient
scripts/globalization_advisor.py strategy, line_search_type, trust_region_type, parameters
scripts/residual_monitor.py patterns_detected, alerts, recommendations
scripts/step_quality.py ratio, step_quality, accept_step, trust_radius_action

Workflow

  1. Characterize problem - Identify type, size, Jacobian availability
  2. Select solver - Run scripts/solver_selector.py
  3. Choose globalization - Run scripts/globalization_advisor.py
  4. Analyze Jacobian - If available, run scripts/jacobian_diagnostics.py
  5. Monitor residuals - During solve, use scripts/residual_monitor.py
  6. Analyze convergence - Run scripts/convergence_analyzer.py
  7. Evaluate steps - For trust region, use scripts/step_quality.py

Conversational Workflow Example

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.

Agent workflow:

  1. Analyze convergence:
    bash
    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 --json
  2. Check globalization strategy:
    bash
    python3 scripts/globalization_advisor.py --problem-type root-finding --jacobian-quality ill-conditioned --previous-failures 0 --json
  3. Recommend: Switch to trust region with Levenberg-Marquardt regularization, or use Newton-Krylov with better preconditioning.

Pre-Solve Checklist

  • Confirm problem type (root-finding, optimization, least-squares)
  • Assess Jacobian availability and cost
  • Check initial guess quality
  • Set appropriate tolerances
  • Choose globalization strategy
  • Prepare to monitor convergence

CLI Examples

bash
# Select solver for large unconstrained optimization
python3 scripts/solver_selector.py --size 50000 --smooth --memory-limited --json

# Analyze convergence from residual history
python3 scripts/convergence_analyzer.py --residuals 1,0.1,0.01,0.001,0.0001 --tolerance 1e-6 --json

# Diagnose Jacobian quality
python3 scripts/jacobian_diagnostics.py --matrix jacobian.txt --json

# Get globalization recommendation
python3 scripts/globalization_advisor.py --problem-type optimization --jacobian-quality good --json

# Monitor residual patterns
python3 scripts/residual_monitor.py --residuals 1,0.8,0.9,0.7,0.75,0.6 --target-tolerance 1e-8 --json

# Evaluate step quality for trust region
python3 scripts/step_quality.py --predicted-reduction 0.5 --actual-reduction 0.4 --step-norm 0.8 --gradient-norm 1.0 --trust-radius 1.0 --json

Error Handling

Error Cause Resolution
problem_size must be positive Invalid size Check problem dimension
constraint_type must be one of... Unknown constraint Use: none, bound, equality, inequality
residuals must be non-negative Invalid residual data Check residual computation
Matrix file not found Invalid path Verify Jacobian file exists

Interpretation Guidance

Convergence Type

Type Meaning Action
quadratic Optimal Newton Continue, near solution
superlinear Quasi-Newton working Monitor for stagnation
linear Acceptable May improve with preconditioner
sublinear Too slow Change method or formulation
stagnated No progress Check Jacobian, preconditioner
diverged Increasing residual Add globalization, check Jacobian

Jacobian Quality

Quality Condition Number Action
good < 10⁶ Standard Newton works
moderately-conditioned 10⁶ - 10¹⁰ Consider scaling
ill-conditioned > 10¹⁰ Use regularization
near-singular ∞ Reformulate or use LM

Step Quality (Trust Region)

Ratio ρ Quality Trust Radius
ρ < 0 very_poor Shrink aggressively
ρ < 0.25 marginal Shrink
0.25 ≤ ρ < 0.75 good Maintain
ρ ≥ 0.75 excellent Expand if at boundary

Security

Input Validation

  • --size (problem size) is validated as a positive integer, bounded at 10 billion
  • --residuals are validated as finite non-negative numbers, capped at 100,000 entries
  • --tolerance and --target-tolerance are validated as finite positive numbers
  • --problem-type and --constraint-type are validated against fixed allowlists
  • --jacobian-quality is validated against a fixed allowlist (good, ill-conditioned, etc.)
  • Step quality parameters (predicted-reduction, actual-reduction, step-norm, gradient-norm, trust-radius) are validated as finite numbers

File Access

  • jacobian_diagnostics.py reads a single matrix file specified by --matrix; no directory traversal beyond the given path
  • Matrix files are size-limited and loaded with allow_pickle=False to prevent code execution
  • All other scripts read no external files; inputs are provided via CLI arguments
  • Scripts write only to stdout (JSON output)

Tool Restrictions

  • Read: Used to inspect script source, references, and user configuration files
  • 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 lists
  • 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

Safety Measures

  • No eval(), exec(), or dynamic code generation
  • All subprocess calls use explicit argument lists (no shell=True)
  • Matrix dimension limits prevent memory exhaustion when loading Jacobian files
  • Residual history analysis operates on bounded-length numeric arrays only

Limitations

  • No global convergence guarantee: All methods may fail for pathological problems
  • Jacobian accuracy: Finite-difference Jacobian may be inaccurate near discontinuities
  • Large dense problems: May require specialized solvers not covered here
  • Constrained optimization: Complex constraints need SQP or interior point methods

References

  • references/solver_decision_tree.md - Problem-based solver selection
  • references/method_catalog.md - Method details and parameters
  • references/convergence_diagnostics.md - Diagnosing convergence issues
  • references/globalization_strategies.md - Line search and trust region

Version History

  • v1.0.0 : Initial release with 6 analysis scripts

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

HeshamFS/materials-simulation-skills

post-processing

Extract, analyze, and summarize simulation output data — pull spatial fields at specific timesteps, compute time-series trends and detect steady state, extract line profiles through the domain, generate statistical summaries and distributions, calculate derived quantities (gradients, fluxes, volume fractions, interface area), compare results against analytical solutions or experimental data, and produce automated analysis reports. Use when interpreting finished simulation results, checking mass or energy conservation, comparing two runs or meshes, extracting interface profiles from phase-field output, or preparing publication-quality analysis, even if the user only says "what do my results look like" or "did my simulation reach steady state."

29 2
Explore
HeshamFS/materials-simulation-skills

performance-profiling

Identify computational bottlenecks, analyze parallel scaling, estimate memory requirements, and generate optimization recommendations for materials simulations — parse timing logs to find dominant phases (solver, assembly, I/O), evaluate strong and weak scaling efficiency, profile memory from mesh and field parameters, and detect bottlenecks with actionable fix suggestions. Use when a simulation is running slower than expected, investigating MPI scaling efficiency, planning HPC resource allocation, deciding whether to tune the preconditioner or reduce I/O frequency, or estimating if a problem fits in available RAM, even if the user only says "my simulation is too slow" or "how many nodes do I need."

29 2
Explore
HeshamFS/materials-simulation-skills

parameter-optimization

Explore and optimize simulation parameters via design of experiments (DOE), sensitivity analysis, and optimizer selection — generate Latin Hypercube, quasi-random, or factorial sample plans, rank parameter influence with sensitivity scores, recommend Bayesian optimization, CMA-ES, or gradient- based methods based on dimension and budget, and fit surrogate models for expensive evaluations. Use when calibrating material properties against experimental data, planning a parameter sweep, performing uncertainty quantification, or choosing an optimization strategy for a simulation with a limited evaluation budget, even if the user only says "which parameters matter most" or "how do I calibrate my model."

29 2
Explore
HeshamFS/materials-simulation-skills

simulation-validator

Validate simulations across three stages — run pre-flight checks on configuration files (parameter ranges, required fields, disk space), monitor runtime logs for residual growth, NaN/Inf, and adaptive dt collapse, and perform post-flight validation of results (physical bounds, mass/energy conservation, convergence). Diagnose failed simulations with probable-cause analysis and recommended fixes. Use when preparing to launch a simulation, checking whether a running job is healthy, verifying that finished results are trustworthy, or debugging a crash or blow-up, even if the user only says "my simulation crashed" or "can I trust these results."

29 2
Explore
HeshamFS/materials-simulation-skills

simulation-orchestrator

Orchestrate multi-simulation campaigns — generate parameter sweep configurations (grid, linspace, or Latin Hypercube sampling), initialize and track batch job campaigns, monitor job completion status, and aggregate results with summary statistics across all runs. Use when running a parameter study across dt, kappa, or other simulation inputs, managing dozens or hundreds of simulation configurations, combining outputs from completed batch runs to find the best result, or automating the generate-run-collect workflow for systematic studies, even if the user only says "I need to try many parameter combinations" or "how do I organize a sweep."

29 2
Explore
HeshamFS/materials-simulation-skills

ontology-explorer

Parse, navigate, and query materials science ontology structures — browse class hierarchies, inspect individual classes and their properties, look up object and data property definitions with domain/range, search for ontology terms by keyword, and parse or summarize raw OWL/XML files. Supports the OCDO ecosystem (CMSO, ASMO, CDCO, PODO, PLDO, LDO). Use when exploring what classes or properties an ontology provides, finding the right CMSO term for a crystal structure or simulation concept, understanding parent-child class relationships, or onboarding to an unfamiliar materials ontology, even if the user only says "what ontology terms describe my FCC copper simulation" or "show me the CMSO class hierarchy."

29 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results