feat(nl): parse + evaluate AMPL external functions (#15)

[jkitchin]

Summary

• Phase 1: parse AMPL external-function segments (F, f<id>) and reject with a clear error naming the library and symbol.
• Phase 2: actually evaluate the external functions end-to-end via the funcadd_ASL ABI, so problems that call imported functions (IDAES Helmholtz property packages, etc.) solve instead of erroring.

Phase 2 design

• src/nl/external.rs — dlopens AMPLFUNC libraries via libloading, registers functions through funcadd_ASL / Addfunc, evaluates with value / gradient / packed-upper-triangular Hessian. A process-wide Mutex guards load+call because AMPL libs keep mutable global state. Arity and string-arg type bits are validated per call.
• src/nl/autodiff.rs — new TapeOp::Funcall variant holding Arc<ExternalLibrary>. Every tape pass handles it: forward, reverse (chain rule through derivs[k]), forward_tangent, hessian_accumulate (forward-over-reverse with the packed Hessian), hessian_sparsity (self-product over real-arg vars), remap_op.
• src/nl/problem_impl.rs — resolve_externals walks the NL AST for funcall ids, loads each path on AMPLFUNC (colon- or newline-separated) as Arc<ExternalLibrary>, and maps referenced names to a library. Clean error if AMPLFUNC is unset or a required symbol is missing.
• examples/probe_external.rs — diagnostic that lists functions registered by a library.

Result

AMPLFUNC=$HOME/.idaes/bin/general_helmholtz_external.dylib \
  cargo run --release --bin ripopt -- tests/fixtures/issue_15/idaes_helmholtz.nl
# → Optimal after 5 iterations. Objective: 0.000000000000000e0

Test coverage

Axis	Covered via
Parse funcall in objective / constraint	nl_parse_external_function_*
Load via funcadd_ASL	load_idaes_helmholtz_dylib_registers_known_functions
Clean error when AMPLFUNC unset	nl_parse_idaes_helmholtz_fixture
End-to-end IPM solve with externals	nl_build_idaes_helmholtz_with_amplfunc + CLI smoke
type=1 (string args) + variadic nargs<0	eval_vf_hp_* against IDAES Helmholtz vf_hp
type=0 (no strings) + exact nargs>0	eval_cbrt_matches_closed_form against IDAES functions.dylib
Closed-form value / deriv / Hessian check	eval_cbrt_matches_closed_form
Runtime arity mismatch rejection	eval_cbrt_arity_mismatch_errors
String arg to type=0 function rejected	eval_cbrt_rejects_string_arg

Known gaps — not exercised by any test

These paths are either not triggered by any AMPL library in our environment, or rely on optional AMPL ABI features we have not had a fixture for. The code may be wrong on these axes and we would not catch it:

• FUNCADD_OUTPUT_ARGS (type bit 2) — functions that return extra values through output slots instead of the return value. Our eval() accepts the type bit but does not wire the output path back to the caller. Likely broken if encountered.
• FUNCADD_RANDOM_VALUED (type bit 4) — RNG functions. Not handled at all; unusual in optimization NL files but possible.
• Multiple libraries colon- or newline-separated in AMPLFUNC — the splitter is implemented but no test exercises a model that needs symbols from two libraries at once.
• Same symbol registered by two libraries — our resolver is first-match-wins. Reasonable but untested.
• Library-reported errors via errmsg — we read the buffer and surface it as an Err, but no test triggers a library to write into it.
• Variadic calls with many reals (the IDAES fixture only hits nargs=-4, i.e. min 3). More extreme arities are not directly covered.

If you hit one of these in a real model, please open an issue with the library and .nl so we can add a fixture.

Test plan

• cargo test — 259/259 pass
• nl_parse_external_function_reports_clean_error — rejection path still works when AMPLFUNC is absent
• nl_parse_idaes_helmholtz_fixture — clean error when AMPLFUNC is unset (serialized via env_lock())
• nl_build_idaes_helmholtz_with_amplfunc — end-to-end build with AMPLFUNC set
• ripopt CLI solves tests/fixtures/issue_15/idaes_helmholtz.nl to Optimal
• Three new tests against functions.dylib cover type=0, exact arity, string-arg rejection

cc @CMarcher — phase 2 is ready. If you have a Helmholtz flowsheet .nl handy, you can solve it with:

AMPLFUNC=/path/to/library.dylib cargo run --release --bin ripopt -- yourmodel.nl

Multiple libraries work with colon- or newline-separated paths in AMPLFUNC.

Closes #15.

🤖 Generated with Claude Code