`mod ffi`¶

module ffi¶

Variables

const RKR_CON_SPEC_VERSION: u32¶

CON/convel format spec version. Use #if RKR_CON_SPEC_VERSION >= 2 in C/C++ to gate code that depends on atom_index semantics.

Tracks crate::CON_SPEC_VERSION (which the Rust API exposes as CON_SPEC_VERSION). Both macros are emitted into the C header for the convenience of either naming convention; they always carry the same value.

Functions

unsafe extern C fn con_frame_iterator_next(iterator: *mut CConFrameIterator) -> *mut RKRConFrame¶

Reads the next frame from the iterator, returning an opaque handle. The caller OWNS the returned handle and must free it with free_rkr_frame.

Safety iterator must be valid. The caller takes ownership of the returned frame.

unsafe extern C fn create_writer_from_path_c(filename_c: *const c_char) -> *mut RKRConFrameWriter¶

Creates a new frame writer for the specified file. The caller OWNS the returned pointer and MUST call free_rkr_writer.

Safety filename_c must be valid. The caller takes ownership of the returned writer.

unsafe extern C fn create_writer_from_path_with_precision_c(filename_c: *const c_char, precision: u8) -> *mut RKRConFrameWriter¶

Creates a new frame writer with custom floating-point precision. The caller OWNS the returned pointer and MUST call free_rkr_writer.

Safety filename_c must be valid. The caller takes ownership of the returned writer.

unsafe extern C fn create_writer_gzip_c(filename_c: *const c_char) -> *mut RKRConFrameWriter¶

Creates a new gzip-compressed frame writer for the specified file. The caller OWNS the returned pointer and MUST call free_rkr_writer.

Safety filename_c must be valid. The caller takes ownership of the returned writer.

unsafe extern C fn free_c_frame(frame: *mut CFrame)¶

Frees the memory of a CFrame struct, including its internal atoms array.

Safety frame must be valid or null.

unsafe extern C fn free_con_frame_iterator(iterator: *mut CConFrameIterator)¶

Frees the memory for a CConFrameIterator.

Safety iterator must be valid or null.

unsafe extern C fn free_rkr_frame(frame_handle: *mut RKRConFrame)¶

Frees the memory for an opaque RKRConFrame handle.

Safety frame_handle must be valid or null.

unsafe extern C fn free_rkr_frame_array(frames: *mut *mut RKRConFrame, num_frames: usize)¶

Frees an array of frame handles returned by rkr_read_all_frames. Each frame is freed individually, then the array itself.

Safety frames must be valid or null.

unsafe extern C fn free_rkr_frame_builder(builder_handle: *mut RKRConFrameBuilder)¶

Frees a frame builder without building.

Safety builder_handle must be valid or null.

unsafe extern C fn free_rkr_writer(writer_handle: *mut RKRConFrameWriter)¶

Frees the memory for an RKRConFrameWriter, closing the associated file.

Safety writer_handle must be valid or null.

unsafe extern C fn read_con_file_iterator(filename_c: *const c_char) -> *mut CConFrameIterator¶

Creates a new iterator for a .con or .convel file.

Returns NULL if the file cannot be read (missing, unreadable, or not valid UTF-8). A successfully-opened file with zero frames returns a non-NULL iterator that yields NULL on the first call to con_frame_iterator_next. The caller OWNS the returned pointer and MUST call free_con_frame_iterator.

Safety filename_c must be a valid null-terminated string. The caller takes ownership of the returned iterator.

extern C fn rkr_con_spec_version() -> u32¶: Returns the spec version at runtime (for dynamically linked consumers).

unsafe extern C fn rkr_frame_add_atom(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, is_fixed: bool, atom_id: u64, mass: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full with NULL velocity and force pointers. Adds an atom (no velocity, no forces) to the builder using a single uniform fixed flag. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_full(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, fixed_x: bool, fixed_y: bool, fixed_z: bool, atom_id: u64, mass: f64, velocity: *const f64, force: *const f64) -> RKRStatus¶

Adds an atom with optional per-axis fixed mask, velocity, and force vectors.

velocity and force are pointers to 3 contiguous f64 values, or NULL if absent. This is the unified entry point that replaces the eight rkr_frame_add_atom_* convenience functions; callers may continue using those for source compatibility.

Safety builder_handle and symbol must be valid. velocity (if non-null) must point to 3 contiguous f64 values, and force (if non-null) likewise.

unsafe extern C fn rkr_frame_add_atom_with_fixed_mask(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, fixed_x: bool, fixed_y: bool, fixed_z: bool, atom_id: u64, mass: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom (no velocity, no forces) using per-axis fixed flags. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_with_forces(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, is_fixed: bool, atom_id: u64, mass: f64, fx: f64, fy: f64, fz: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom with a force vector and a single uniform fixed flag. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_with_forces_fixed_mask(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, fixed_x: bool, fixed_y: bool, fixed_z: bool, atom_id: u64, mass: f64, fx: f64, fy: f64, fz: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom with a force vector and per-axis fixed flags. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_with_velocity(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, is_fixed: bool, atom_id: u64, mass: f64, vx: f64, vy: f64, vz: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom with a velocity vector and a single uniform fixed flag. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_with_velocity_and_forces(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, is_fixed: bool, atom_id: u64, mass: f64, vx: f64, vy: f64, vz: f64, fx: f64, fy: f64, fz: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom with both velocity and force vectors and a single uniform fixed flag. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_with_velocity_and_forces_fixed_mask(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, fixed_x: bool, fixed_y: bool, fixed_z: bool, atom_id: u64, mass: f64, vx: f64, vy: f64, vz: f64, fx: f64, fy: f64, fz: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom with both velocity and force vectors and per-axis fixed flags. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_add_atom_with_velocity_fixed_mask(builder_handle: *mut RKRConFrameBuilder, symbol: *const c_char, x: f64, y: f64, z: f64, fixed_x: bool, fixed_y: bool, fixed_z: bool, atom_id: u64, mass: f64, vx: f64, vy: f64, vz: f64) -> RKRStatus¶

Deprecated: prefer rkr_frame_add_atom_full. Adds an atom with a velocity vector and per-axis fixed flags. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and symbol must be valid.

unsafe extern C fn rkr_frame_atom_index_by_id(frame_handle: *const RKRConFrame, atom_id: u64) -> u64¶

Returns the position of an atom inside the frame’s atom_data array matching the given atom_id. Returns UINT64_MAX if no atom with that id exists or frame_handle is NULL.

O(N) per call. C/C++ consumers performing many lookups should cache a std::unordered_map<uint64_t, size_t> from a single sweep over the frame.

Safety

frame_handle must point to a valid RKRConFrame allocation.

unsafe extern C fn rkr_frame_builder_build(builder_handle: *mut RKRConFrameBuilder) -> *mut RKRConFrame¶

Consumes the builder and returns a finalized RKRConFrame handle. The builder handle is invalidated after this call. The caller OWNS the returned frame and MUST call free_rkr_frame. Returns NULL on error.

Safety builder_handle must be valid. The caller takes ownership of the returned frame.

unsafe extern C fn rkr_frame_builder_set_energy(builder_handle: *mut RKRConFrameBuilder, energy: f64) -> RKRStatus¶

Sets the per-frame total energy metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle must be valid.

unsafe extern C fn rkr_frame_builder_set_frame_index(builder_handle: *mut RKRConFrameBuilder, idx: u64) -> RKRStatus¶

Sets the zero-based frame index metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle must be valid.

unsafe extern C fn rkr_frame_builder_set_last_energy(builder_handle: *mut RKRConFrameBuilder, energy: f64) -> RKRStatus¶

Attaches a per-atom energy to the most recently added atom on a builder. No-op if no atom has been added yet.

Use this together with the per-frame energy metadata key when a caller wants to round-trip an “Energies of Component” decomposition alongside the total.

Safety builder_handle must be valid.

unsafe extern C fn rkr_frame_builder_set_last_force(builder_handle: *mut RKRConFrameBuilder, force: *const f64) -> RKRStatus¶

Attaches a force vector to the most recently added atom on a builder. No-op if no atom has been added yet.

Safety builder_handle must be valid. force must point to 3 contiguous f64 values.

unsafe extern C fn rkr_frame_builder_set_last_velocity(builder_handle: *mut RKRConFrameBuilder, velocity: *const f64) -> RKRStatus¶

Attaches a velocity vector to the most recently added atom on a builder. No-op if no atom has been added yet.

Safety builder_handle must be valid. velocity must point to 3 contiguous f64 values.

unsafe extern C fn rkr_frame_builder_set_metadata_json(builder_handle: *mut RKRConFrameBuilder, metadata_json: *const c_char) -> RKRStatus¶

Parses and sets JSON metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and metadata_json must be valid.

unsafe extern C fn rkr_frame_builder_set_neb_band(builder_handle: *mut RKRConFrameBuilder, band: u64) -> RKRStatus¶

Sets the NEB band index metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle must be valid.

unsafe extern C fn rkr_frame_builder_set_neb_bead(builder_handle: *mut RKRConFrameBuilder, bead: u64) -> RKRStatus¶

Sets the NEB bead index metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle must be valid.

unsafe extern C fn rkr_frame_builder_set_scalar_metadata(builder_handle: *mut RKRConFrameBuilder, key: *const c_char, value: f64) -> RKRStatus¶

Sets a numeric metadata key on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle and key must be valid.

unsafe extern C fn rkr_frame_builder_set_string_metadata(builder_handle: *mut RKRConFrameBuilder, key: *const c_char, value: *const c_char) -> RKRStatus¶

Sets a string metadata key on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle, key, and value must be valid.

unsafe extern C fn rkr_frame_builder_set_time(builder_handle: *mut RKRConFrameBuilder, time: f64) -> RKRStatus¶

Sets the simulation time metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle must be valid.

unsafe extern C fn rkr_frame_builder_set_timestep(builder_handle: *mut RKRConFrameBuilder, dt: f64) -> RKRStatus¶

Sets the timestep metadata on an existing frame builder. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety builder_handle must be valid.

extern C fn rkr_frame_energy(frame_handle: *const RKRConFrame) -> f64¶: Returns the per-frame energy from metadata, or NaN if absent.

extern C fn rkr_frame_frame_index(frame_handle: *const RKRConFrame) -> u64¶: Returns the zero-based frame index from metadata, or UINT64_MAX if absent.

unsafe extern C fn rkr_frame_get_header_line(frame_handle: *const RKRConFrame, is_prebox: bool, line_index: usize, buffer: *mut c_char, buffer_len: usize) -> RKRStatus¶

Copies a header string line into a caller-provided buffer.

is_prebox=true selects from the two prebox lines (line 0 = user text, line 1 = JSON metadata); false selects from the two postbox lines. Strings longer than buffer_len - 1 bytes are truncated; the final byte is always set to NUL.

Returns RKR_STATUS_SUCCESS on success, RKR_STATUS_INDEX_OUT_OF_BOUNDS if line_index >= 2, RKR_STATUS_NULL_POINTER if frame_handle or buffer is NULL, RKR_STATUS_BUFFER_TOO_SMALL if buffer_len == 0.

Pair with rkr_frame_get_header_line_cpp when the caller prefers an allocated string with no fixed length cap; that variant returns NULL for the same out-of-bounds condition.

Safety frame_handle must be valid. buffer must be at least buffer_len bytes.

unsafe extern C fn rkr_frame_get_header_line_cpp(frame_handle: *const RKRConFrame, is_prebox: bool, line_index: usize) -> *mut c_char¶

Gets a header string line as a newly allocated, null-terminated C string.

The caller OWNS the returned pointer and MUST call rkr_free_string on it to prevent a memory leak. Returns NULL on error or if the index is invalid (use rkr_frame_get_header_line when a status code is preferred to NULL-vs-success disambiguation).

The _cpp suffix is historical; the function is callable from both C and C++.

Safety frame_handle must be valid. The caller takes ownership of the returned string.

unsafe extern C fn rkr_frame_metadata_json(frame_handle: *const RKRConFrame) -> *mut c_char¶

Returns the JSON metadata line from a parsed frame as a heap-allocated null-terminated C string. The caller MUST free with rkr_free_string. Returns NULL on error.

Safety frame_handle must be valid. The caller takes ownership of the returned string.

extern C fn rkr_frame_neb_band(frame_handle: *const RKRConFrame) -> u64¶: Returns the NEB band index from metadata, or UINT64_MAX if absent.

extern C fn rkr_frame_neb_bead(frame_handle: *const RKRConFrame) -> u64¶: Returns the NEB bead index from metadata, or UINT64_MAX if absent.

unsafe extern C fn rkr_frame_new(cell: *const f64, angles: *const f64, prebox0: *const c_char, prebox1: *const c_char, postbox0: *const c_char, postbox1: *const c_char) -> *mut RKRConFrameBuilder¶

Creates a new frame builder with the given cell dimensions, angles, and header lines.

prebox1 is accepted for source compatibility but ignored: the JSON metadata line is regenerated by the writer from the builder’s spec_version, metadata, and sections. Pass NULL or any string. The caller OWNS the returned pointer and MUST call free_rkr_frame_builder or consume it via rkr_frame_builder_build. Returns NULL on error.

Safety cell and angles must point to 3 doubles. prebox0, postbox0, and postbox1 must be NULL or valid null-terminated strings; prebox1 is not dereferenced. The caller takes ownership of the returned builder.

unsafe extern C fn rkr_frame_potential_type(frame_handle: *const RKRConFrame) -> *mut c_char¶

Returns the potential type string from metadata as a heap-allocated null-terminated C string. The caller MUST free with rkr_free_string. Returns NULL if absent or on error.

Safety frame_handle must be valid. The caller takes ownership of the returned string.

extern C fn rkr_frame_spec_version(frame_handle: *const RKRConFrame) -> u32¶: Returns the spec version stored in a parsed frame’s header. Returns 0 on error (null handle).

extern C fn rkr_frame_time(frame_handle: *const RKRConFrame) -> f64¶: Returns the simulation time from metadata, or NaN if absent.

extern C fn rkr_frame_timestep(frame_handle: *const RKRConFrame) -> f64¶: Returns the integration timestep from metadata, or NaN if absent.

unsafe extern C fn rkr_frame_to_c_frame(frame_handle: *const RKRConFrame) -> *mut CFrame¶

Extracts the core atomic data into a transparent CFrame struct. The caller OWNS the returned pointer and MUST call free_c_frame on it.

Safety frame_handle must be valid. The caller takes ownership of the returned CFrame.

unsafe extern C fn rkr_free_string(s: *mut c_char)¶

Frees a C string that was allocated by Rust (e.g., from rkr_frame_metadata_json, rkr_frame_potential_type, or rkr_frame_get_header_line_cpp). Safe to call with NULL (no-op).

Safety s must be either NULL or a pointer previously returned by an allocating Rust FFI function in this crate.

extern C fn rkr_library_version() -> *const c_char¶: Returns a pointer to a static, null-terminated library version string. The returned pointer is valid for the lifetime of the process. Do NOT free it.

unsafe extern C fn rkr_read_all_frames(filename_c: *const c_char, num_frames: *mut usize) -> *mut *mut RKRConFrame¶

Reads all frames from a .con file using mmap. Returns an array of frame handles and sets num_frames to the count. The caller OWNS both the array and each frame handle. Free frames with free_rkr_frame and the array with free_rkr_frame_array. Returns NULL on error.

Safety filename_c and num_frames must be valid. The caller takes ownership of the returned handles and array.

unsafe extern C fn rkr_read_first_frame(filename_c: *const c_char) -> *mut RKRConFrame¶

Reads the first frame from a .con file. Uses read_to_string for small files (< 64 KiB) and mmap for larger ones. Stops after the first frame rather than parsing the entire file. The caller OWNS the returned handle and MUST call free_rkr_frame. Returns NULL on error.

Safety filename_c must be valid. The caller takes ownership of the returned frame.

extern C fn rkr_status_message(status: RKRStatus) -> *const c_char¶: Returns a stable, static message for a status code. The returned pointer is valid for the lifetime of the process. Do NOT free it.

unsafe extern C fn rkr_symbol_to_z(symbol: *const c_char) -> u64¶

Returns the atomic number for a chemical symbol, or 0 if the symbol is unknown or symbol is NULL. Lookup covers H..U (Z = 1..=92) and is case-sensitive: “Fe” works, “fe” does not.

Safety

symbol must be either NULL or a pointer to a NUL-terminated UTF-8 C string valid for reads up to the terminating NUL byte.

unsafe extern C fn rkr_writer_extend(writer_handle: *mut RKRConFrameWriter, frame_handles: *const *const RKRConFrame, num_frames: usize) -> RKRStatus¶

Writes multiple frames from an array of handles to the file managed by the writer. Returns RKR_STATUS_SUCCESS on success, or an error code.

Safety writer_handle and frame_handles must be valid.

extern C fn rkr_z_to_symbol(z: u64) -> *const c_char¶: Returns a pointer to a static, NUL-terminated chemical symbol for an atomic number, or “X” for unknown values. Coverage is H..U (Z = 1..=92). The returned pointer is valid for the lifetime of the process; do NOT free it.

Enums

enum RKRStatus¶

Error codes for RKR functions.

RKR_STATUS_SUCCESS¶: Function completed successfully.

RKR_STATUS_NULL_POINTER¶: A null pointer was passed for a required argument.

RKR_STATUS_INVALID_UTF8¶: An input string was not valid UTF-8.

RKR_STATUS_INVALID_JSON¶: JSON parsing or serialization failed.

RKR_STATUS_IO_ERROR¶: File I/O error.

RKR_STATUS_INDEX_OUT_OF_BOUNDS¶: Index out of bounds.

RKR_STATUS_BUFFER_TOO_SMALL¶: The destination buffer cannot hold a null-terminated string.

RKR_STATUS_INTERNAL_ERROR¶: An internal logic error or unhandled state.

Structs and Unions

struct CAtom¶

Transparent atom record extracted via rkr_frame_to_c_frame.

is_fixed is the OR of fixed_x, fixed_y, fixed_z; it is kept for source compatibility with pre-spec-v2 callers that did not have per-axis flags. New code should use the per-axis fields.

vx/vy/vz, fx/fy/fz, and energy carry meaningful values only when has_velocity, has_forces, or has_energy is true respectively; the values are zeroed otherwise.

atomic_number: u64¶

x: f64¶

y: f64¶

z: f64¶

atom_id: u64¶

mass: f64¶

is_fixed: bool¶: True when any of fixed_x, fixed_y, fixed_z is true. Kept for source compatibility; prefer the per-axis fields.

fixed_x: bool¶

fixed_y: bool¶

fixed_z: bool¶

vx: f64¶

vy: f64¶

vz: f64¶

has_velocity: bool¶

fx: f64¶

fy: f64¶

fz: f64¶

has_forces: bool¶

energy: f64¶: Per-atom energy contribution; meaningful only when has_energy is true. See crate::types::SECTION_ENERGIES.

has_energy: bool¶

struct CConFrameIterator¶

struct CFrame¶

A transparent, “lossy” C-struct containing only the core atomic data. This can be extracted from an RKRConFrame handle for direct data access. The caller is responsible for freeing the atoms array using free_c_frame.

atoms: *mut CAtom¶

num_atoms: usize¶

cell: [f64; 3]¶

angles: [f64; 3]¶

has_velocities: bool¶

has_forces: bool¶

has_energies: bool¶

struct RKRConFrame¶: An opaque handle to a full, lossless Rust ConFrame object. The C/C++ side needs to treat this as a void pointer

struct RKRConFrameBuilder¶: An opaque handle to a Rust ConFrameBuilder object.

struct RKRConFrameWriter¶: An opaque handle to a Rust ConFrameWriter object. The C/C++ side needs to treat this as a void pointer

mod ffi¶

`mod ffi`¶