Module ffi 

Structs

CAtom

Transparent atom record extracted via rkr_frame_to_c_frame.

CConFrameIterator

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.

RKRConFrame

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

RKRConFrameBuilder

An opaque handle to a Rust ConFrameBuilder object.

RKRConFrameWriter

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

Enums

RKRStatus

Error codes for RKR functions.

Constants

RKR_CON_SPEC_VERSION

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

Functions

con_frame_iterator_next^⚠

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.

create_writer_from_path_c^⚠

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

create_writer_from_path_with_precision_c^⚠

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

create_writer_gzip_c^⚠

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

free_c_frame^⚠

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

free_con_frame_iterator^⚠

Frees the memory for a CConFrameIterator.

free_rkr_frame^⚠

Frees the memory for an opaque RKRConFrame handle.

free_rkr_frame_array^⚠

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

free_rkr_frame_builder^⚠

Frees a frame builder without building.

free_rkr_writer^⚠

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

read_con_file_iterator^⚠

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

rkr_con_spec_version

Returns the spec version at runtime (for dynamically linked consumers).

rkr_frame_add_atom^⚠

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.

rkr_frame_add_atom_full^⚠

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

rkr_frame_add_atom_with_fixed_mask^⚠

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.

rkr_frame_add_atom_with_forces^⚠

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.

rkr_frame_add_atom_with_forces_fixed_mask^⚠

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.

rkr_frame_add_atom_with_velocity^⚠

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.

rkr_frame_add_atom_with_velocity_and_forces^⚠

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.

rkr_frame_add_atom_with_velocity_and_forces_fixed_mask^⚠

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.

rkr_frame_add_atom_with_velocity_fixed_mask^⚠

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.

rkr_frame_atom_index_by_id^⚠

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.

rkr_frame_builder_build^⚠

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.

rkr_frame_builder_set_energy^⚠

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

rkr_frame_builder_set_frame_index^⚠

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

rkr_frame_builder_set_last_energy^⚠

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

rkr_frame_builder_set_last_force^⚠

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

rkr_frame_builder_set_last_velocity^⚠

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

rkr_frame_builder_set_metadata_json^⚠

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

rkr_frame_builder_set_neb_band^⚠

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

rkr_frame_builder_set_neb_bead^⚠

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

rkr_frame_builder_set_scalar_metadata^⚠

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

rkr_frame_builder_set_string_metadata^⚠

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

rkr_frame_builder_set_time^⚠

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

rkr_frame_builder_set_timestep^⚠

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

rkr_frame_energy

Returns the per-frame energy from metadata, or NaN if absent.

rkr_frame_frame_index

Returns the zero-based frame index from metadata, or UINT64_MAX if absent.

rkr_frame_get_header_line^⚠

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

rkr_frame_get_header_line_cpp^⚠

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

rkr_frame_metadata_json^⚠

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.

rkr_frame_neb_band

Returns the NEB band index from metadata, or UINT64_MAX if absent.

rkr_frame_neb_bead

Returns the NEB bead index from metadata, or UINT64_MAX if absent.

rkr_frame_new^⚠

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

rkr_frame_potential_type^⚠

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.

rkr_frame_spec_version

Returns the spec version stored in a parsed frame’s header. Returns 0 on error (null handle).

rkr_frame_time

Returns the simulation time from metadata, or NaN if absent.

rkr_frame_timestep

Returns the integration timestep from metadata, or NaN if absent.

rkr_frame_to_c_frame^⚠

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

rkr_free_string^⚠

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).

rkr_library_version

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.

rkr_read_all_frames^⚠

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.

rkr_read_first_frame^⚠

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.

rkr_status_message

Returns a stable, static message for a status code. The returned pointer is valid for the lifetime of the process. Do NOT free it.

rkr_symbol_to_z^⚠

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.

rkr_writer_extend^⚠

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.

rkr_z_to_symbol

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.