Optimization Skill

A modular numerical optimization library. Minimizes scalar functions of one or more variables using derivative-free (Nelder-Mead, Brent 1D, Simulated Annealing), first-order (gradient descent, BFGS, L-BFGS, conjugate gradient), second-order (Newton, Newton Trust Region, Krylov Trust Region), and constrained (Fminbox, IPNewton) methods.

When to use this skill

When you need to minimize a function without adding an optimization library dependency. Covers the core algorithms that scipy.optimize.minimize and Optim.jl provide, implemented from scratch with clear provenance.

Arguments

$ARGUMENTS has the format: <nodes> [--lang <language>]

• nodes: Space-separated list of node names to translate, or all for every node. Nodes must be provided in dependency order (see the node graph below).
• --lang: Target language (e.g. python, rust, go, typescript). Defaults to typescript if omitted.

Examples:

• nelder-mead --lang python — translate just the Nelder-Mead subset to Python
• all --lang rust — translate the full library to Rust
• bfgs l-bfgs minimize --lang go — translate selected nodes to Go

Node Graph

vec-ops ─────────────────────────┬──→ line-search ──────┬──→ hager-zhang ──────┐
                                 │                      │                      │
                                 ├──→ more-thuente      │                      │
                                 │                      │                      │
result-types ──────┬─────────────┤                      │                      │
                   │             │                      │                      │
test-functions     │   finite-diff ─────────────────────┤                      │
                   │             │                      │                      │
                   │     finite-hessian ←───────────────┤                      │
                   │             │                      │                      │
                   ├──→ nelder-mead                     │                      │
                   │                                    │                      │
                   ├──→ brent-1d (standalone)            │                      │
                   │                                    │                      │
                   ├──→ gradient-descent ←──────────────┤                      │
                   │                                    │                      │
                   ├──→ bfgs ←─────────────────────────┤                      │
                   │                                    │                      │
                   ├──→ l-bfgs ←───────────────────────┤                      │
                   │                                    │                      │
                   ├──→ conjugate-gradient ←────────────┴──────────────────────┘
                   │                                    │
                   ├──→ newton ←───────────────────────┤←── finite-hessian
                   │                                    │
                   ├──→ newton-trust-region ←───────────┤←── finite-hessian
                   │                                    │
                   ├──→ fminbox ←──────────────────────┤
                   │                                    │
                   ├──→ simulated-annealing               │
                   │                                    │
                   ├──→ krylov-trust-region ←──────────┤←── finite-hessian
                   │                                    │
                   ├──→ ip-newton ←───────────────────┤←── finite-hessian
                   │                                    │
                   └──→ minimize (root: public API) ←──┘

Nodes

Subset Extraction

• Just Nelder-Mead (derivative-free): vec-ops + result-types + nelder-mead
• Just BFGS: vec-ops + result-types + line-search + finite-diff + bfgs
• Just CG: vec-ops + result-types + line-search + hager-zhang + finite-diff + conjugate-gradient
• Just Newton: vec-ops + result-types + line-search + finite-diff + finite-hessian + newton
• Just Newton TR: vec-ops + result-types + finite-diff + finite-hessian + newton-trust-region
• Just Brent 1D: brent-1d (standalone, no dependencies)
• Just Fminbox (BFGS): vec-ops + result-types + line-search + finite-diff + bfgs + fminbox
• Just Simulated Annealing: result-types + simulated-annealing
• Just Krylov TR: vec-ops + result-types + finite-diff + finite-hessian + krylov-trust-region
• Just IPNewton: vec-ops + result-types + finite-diff + finite-hessian + ip-newton
• Full library: all 21 nodes
• Test functions are optional — only needed for validation

Handling help

When $ARGUMENTS is help, read HELP.md and use it to guide the user through node and language selection. The help guide contains a decision tree covering derivative availability, constraint types, problem scale, and language idioms. Walk through it interactively, asking the user about their requirements, then recommend specific nodes and a target language.

Translation Workflow

For each node in dependency order:

1. If $ARGUMENTS is help, read HELP.md and guide the user interactively
2. Read the node spec at nodes/<name>/spec.md for behavior, API, and test vectors
3. Read language-specific hints at nodes/<name>/to-<lang>.md if available
4. Generate the implementation and tests in the target language
5. If the spec is ambiguous, consult the TypeScript reference at reference/src/<name>.ts

Generated Code Documentation

Every public function, class, type, and interface in generated code must have idiomatic doc comments in the target language's standard format:

Doc comments should describe what the function does, its parameters, return value, and error conditions. Derive content from the node spec — do not invent behavior not in the spec.

Each generated file must include a provenance header as the first comment, in the file's idiomatic comment style:

Generated by {agent} using {model}
From special:optimization (https://github.com/caryden/special)
Node: {node-name}

Replace {agent}, {model}, and {node-name} with actual values. The provenance trace makes generated code traceable back to the skill and model that produced it.

The reference code is TypeScript with 100% line and function coverage. Every node has a corresponding test file at reference/src/<name>.test.ts that serves as the behavioral contract. Cross-validation against scipy v1.17.0 and Optim.jl v2.0.0 is documented in reference/CROSS-VALIDATION.md.

Key Design Decisions (Off-Policy)

These defaults differ across libraries. Our choices are documented with provenance:

Error Handling

• Line search failure: return result with converged=false and a descriptive message
• Max iterations exceeded: return result with converged=false
• Division by zero in finite differences: not guarded (caller's responsibility)
• No exceptions thrown by optimizers — all results are returned via OptimizeResult
• Invalid method name in minimize: throw an error before optimization begins
• Empty or zero-length input vectors: behavior is undefined (caller must validate)