crs_nomad_api: Native NOMAD C API for package authors

In crs: Categorical Regression Splines

Native NOMAD C API for package authors

Description

crs exposes a native C interface to the embedded NOMAD solver for package authors who need to call NOMAD from compiled code without routing each black-box evaluation through the snomadr() R interface.

Details

The installed header ‘crs_nomad_native.h’ defines the final API surface: crs_nomad_problem, crs_nomad_result, crs_nomad_option, crs_nomad_eval_fn, and crs_nomad_solve. The callable is registered with R_RegisterCCallable() under the package name "crs" and symbol name "crs_nomad_solve".

The final API supports two callback modes. CRS_NOMAD_CALLBACK_C calls a package-supplied C callback and is the preferred mode when the objective is available in compiled code. CRS_NOMAD_CALLBACK_R is an explicit bridge for routes whose objective still lives in R; callers pass a protected R function and environment through crs_nomad_r_callback.

This is the only native NOMAD C callable exported by crs; legacy v1/v2 development callables are intentionally not registered.

The callable itself must be invoked from the main R interpreter thread of the current process. It uses R's protection stack, unwind protection, and user interrupt machinery, and must not be called from native worker threads, signal handlers, or contexts that are not executing through R or a registered native call on that thread.

Callback Contract

C callbacks return 0 on successful evaluation, fill exactly problem->m black-box outputs, and return nonzero on evaluation failure. They must not retain pointers supplied by crs.

R callback bridge users must ensure the R function and environment stored in crs_nomad_r_callback remain protected for the duration of crs_nomad_solve. R errors are trapped and reported as callback failures. R callbacks are main-thread callbacks; explicit NB_THREADS_PARALLEL_EVAL > 1 is rejected for R callbacks, including when supplied through ‘nomad.opt’. Use the default or set it explicitly to 1.

Numeric And Option Semantics

random_seed > 0 sets NOMAD's SEED. When crs generates multi-start points, the same seed also controls that start generation; random_seed = 0 uses time-varying generated starts, matching the historical snomadr() posture.

Bounds may use -Inf and Inf for unbounded coordinates. NaN is invalid in starting points and bounds. The embedded NOMAD4 C interface represents categorical inputs through its integer input type, so callers remain responsible for category encoding and decoding.

NaN black-box outputs are callback failures for all output types. Infinite objective outputs are coerced to +/-DBL_MAX, matching snomadr() compatibility. Infinite PB or EB constraint outputs are passed through to NOMAD as infeasibility signals.

The native API currently requires NOMAD's evaluation cache (EVAL_USE_CACHE = TRUE, the NOMAD default), because result recovery is based on NOMAD's cache-backed incumbent state. Supplying EVAL_USE_CACHE = FALSE to crs_nomad_solve is rejected early with a clear error. The public R-level snomadr() interface retains its separate cache option behavior.

Ownership

The problem structure and all pointer fields are borrowed and read-only. The caller owns result->solution and result->outputs; crs does not return memory that callers must free.

See Also

snomadr

crs documentation built on June 2, 2026, 1:07 a.m.