Use the C and C++ interfaces

include/rgsaddle.h declares the C application binary interface (ABI), version 1.15. It preserves the main band, minimum-mode and index-1 layouts and adds intrinsic reaction coordinate (IRC), Sella, constraint and geometry controls. Include this header rather than duplicating its structures. Check rgsaddle_abi_stamp before constructing a session.

A surface callback returns rgsaddle_status_t and receives one rgsaddle_surface_request_t. Positions and gradients are image-major Cartesian triples. The host supplies the energy and gradient arrays for every requested image; the library performs no Message Passing Interface (MPI) communication.

Create an opaque session, call its step entry, inspect rgsaddle_report_t, and free it. Check each function status before reading outputs. The host owns search limits and the surface lifetime. A reset marks a surface change. The report’s evaluations field counts the surface rows consumed by the step.

Band and minimum-mode force norms are selected by rgsaddle_band_set_force_gate and rgsaddle_minmode_set_force_gate. Their configuration layouts have no member for that norm. The optional feasible-step controls are rgsaddle_band_set_highs and rgsaddle_minmode_set_highs, with 0 or 1 as the flag.

rgsaddle_ocineb_create (ABI minor 20) builds the climbing-image band that hands the climbing image to a minimum-mode search. rgsaddle_ocineb_step is one band move, one alignment of the band tangent with the lowest mode, or one minimum-mode translation, and rgsaddle_ocineb_report_t names that phase. n_images is at least 3. The alignment tolerance must be at least 1/sqrt(2). A solid-state band is refused. rgsaddle_ocineb_positions copies the band, rgsaddle_ocineb_reset drops the hand-off state, and rgsaddle_ocineb_free releases the session. From minor 21 the hand-off is the band’s own refinement with these controls: the trigger is on the climbing image’s largest per-atom force, rgsaddle_minmode_config_t supplies only the mode estimate, and a RGSADDLE_OCINEB_MINMODE step is one P-RFO climb step. RGSADDLE_BAND_NO_MIN_MODE is not read here. The climbing image’s requests reach the point surface as one geometry with image = -1 and without RGSADDLE_REQ_CLIMBING_IMAGE.

rgsaddle_idpp_path (ABI minor 19) writes an initial path. n_images counts the endpoints and must be at least 3. reactant and product each hold 3 * n_atoms doubles. out holds n_images * 3 * n_atoms doubles, image-major. cell is a row-major 3x3 lattice, or NULL in free space. A singular cell returns RGSADDLE_INVALID_PARAMETER. Interior images are relaxed toward interpolated minimum-image pair distances. max_iterations, grad_tol, and max_move are the per-image L-BFGS stop. The call does not evaluate a surface.

rgsaddle_connect (ABI minor 18) is the run-to-completion double-ended search. Stamp rgsaddle_connect_config_t with the ABI version. max_calls is a positive iteration cap and force_tol is the Euclidean stop. A nonzero quench_nodes minimizes a node created by a split before the next segment. left and right each hold 3 * n_atoms positions, and position receives the returned geometry. The surface is called with one image and writes the energy and the Cartesian gradient. rgsaddle_connect_report_t carries the energy, the Euclidean gradient norm, the kind (s, u, or f), the Hessian index, and the evaluation count. The count includes finite differences that decide a step or an index. The Lanczos acceptance estimates the next curvature with two actions and does not build a dense Hessian. The COMPASS fallback does, and that Hessian is counted.

From ABI minor 21 a climbing band refines its climbing image by the lowest mode (see the band how-to). While that runs, each surface request carries the climbing image alone: a per-image host gets RGSADDLE_REQ_ONE_IMAGE with that image’s band index, and a batched host gets one geometry with n_images = 1 and image = -1. From a band config at minor 22 those requests also set RGSADDLE_REQ_CLIMBING_IMAGE (request flags bit 1), and a batched one then carries the climbing image’s band index in image, so a host that keeps per-image state, or that gives the one image every MPI rank, knows which image it is. A config below minor 22 gets the minor 21 request. The step report carries the curvature along the mode in curvature and 0 on a band step. Set RGSADDLE_BAND_NO_MIN_MODE (band config flag bit 3) for the plain CI-NEB of minor 20.

include/rgsaddle/session.hpp provides the C++ owning wrappers. Band, MinMode and Irc release their opaque handles automatically and translate failing statuses into exceptions. tests/c/main_abi_contract.h checks the retained main layouts and signatures; the C and C++ smoke executables exercise the official header and library together.