============== ``mod eindir`` ============== .. rust:module:: rgpot_core::eindir :index: 0 :vis: pub rgpot as a strict superset of eindir: first-member struct embedding. ``rgpot_potential_t`` embeds ``eindir_objective_t`` as its FIRST member, so a ``rgpot_potential_t*`` IS-A ``eindir_objective_t*`` at the C ABI with zero cost: .. code-block:: c rgpot_potential_t *pot = rgpot_potential_new_eindir(...); eindir_objective_t *obj = (eindir_objective_t*)pot; // zero-cost cast double val; eindir_objective_eval(obj, x, &val); // works The eval_fn / grad_fn stored in the embedded base call through to the rgpot callback, so evaluation logic lives once -- there is no duplicate eval path and no conversion method. .. rust:use:: rgpot_core::eindir :used_name: self .. rust:use:: rgpot_core :used_name: crate .. rust:use:: std::os::raw::c_void :used_name: c_void .. rust:use:: dlpk::sys::DLManagedTensorVersioned :used_name: DLManagedTensorVersioned .. rust:use:: rgpot_core::potential::PotentialCallback :used_name: PotentialCallback .. rust:use:: rgpot_core::status::rgpot_status_t :used_name: rgpot_status_t .. rust:use:: rgpot_core::tensor::rgpot_tensor_cpu_f64_2d :used_name: rgpot_tensor_cpu_f64_2d .. rust:use:: rgpot_core::tensor::rgpot_tensor_cpu_f64_matrix3 :used_name: rgpot_tensor_cpu_f64_matrix3 .. rust:use:: rgpot_core::tensor::rgpot_tensor_cpu_i32_1d :used_name: rgpot_tensor_cpu_i32_1d .. rust:use:: rgpot_core::tensor::rgpot_tensor_free :used_name: rgpot_tensor_free .. rust:use:: rgpot_core::types::rgpot_force_input_t :used_name: rgpot_force_input_t .. rust:use:: rgpot_core::types::rgpot_force_out_t :used_name: rgpot_force_out_t .. rust:use:: eindir_core::ffi::eindir_status_t :used_name: eindir_status_t :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::EindirEvalFn :used_name: EindirEvalFn :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::EindirFreeFn :used_name: EindirFreeFn :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::EindirGradFn :used_name: EindirGradFn :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::eindir_objective_eval :used_name: eindir_objective_eval :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::eindir_objective_grad :used_name: eindir_objective_grad :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::eindir_objective_has_grad :used_name: eindir_objective_has_grad :reexport: rgpot_core::eindir .. rust:use:: eindir_core::ffi::eindir_objective_t :used_name: eindir_objective_t :reexport: rgpot_core::eindir .. rubric:: Re-exports * :rust:any:``eindir_core::ffi::eindir_status_t`` * :rust:any:``eindir_core::ffi::EindirEvalFn`` * :rust:any:``eindir_core::ffi::EindirFreeFn`` * :rust:any:``eindir_core::ffi::EindirGradFn`` * :rust:any:``eindir_core::ffi::eindir_objective_eval`` * :rust:any:``eindir_core::ffi::eindir_objective_grad`` * :rust:any:``eindir_core::ffi::eindir_objective_has_grad`` * :rust:any:``eindir_core::ffi::eindir_objective_t`` .. rubric:: Functions .. rust:function:: rgpot_core::eindir::rgpot_potential_free_eindir :index: 0 :vis: pub :layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_potential_free_eindir"},{"type":"punctuation","value":"("},{"type":"name","value":"pot"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"rgpot_potential_t","target":"rgpot_potential_t"},{"type":"punctuation","value":")"}] Free a potential created by ``rgpot_potential_new_eindir``. Calls ``pot_free_fn(pot_user_data)`` if provided, frees all owned arrays, then frees the struct. Do NOT call ``eindir_objective_free`` on the embedded base; call this function. .. rust:function:: rgpot_core::eindir::rgpot_potential_new_eindir :index: 0 :vis: pub :layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_potential_new_eindir"},{"type":"punctuation","value":"("},{"type":"name","value":"callback"},{"type":"punctuation","value":": "},{"type":"link","value":"PotentialCallback","target":"PotentialCallback"},{"type":"punctuation","value":", "},{"type":"name","value":"user_data"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"c_void","target":"c_void"},{"type":"punctuation","value":", "},{"type":"name","value":"free_fn"},{"type":"punctuation","value":": "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"punctuation","value":"("},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"c_void","target":"c_void"},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"},{"type":"punctuation","value":", "},{"type":"name","value":"n_atoms"},{"type":"punctuation","value":": "},{"type":"link","value":"usize","target":"usize"},{"type":"punctuation","value":", "},{"type":"name","value":"atomic_numbers"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"i32","target":"i32"},{"type":"punctuation","value":", "},{"type":"name","value":"box_matrix"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":", "},{"type":"name","value":"bounds_low"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":", "},{"type":"name","value":"bounds_high"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"rgpot_potential_t","target":"rgpot_potential_t"}] Create a potential that is ALSO a valid eindir objective. The returned pointer is simultaneously a ``rgpot_potential_t*`` and (via zero-cost cast to the first member) an ``eindir_objective_t*``. - ``callback``: the rgpot force/energy callback. - ``user_data`` / ``free_fn``: opaque context for the rgpot callback. - ``n_atoms``, ``atomic_numbers``, ``box_matrix``: molecular context. - ``bounds_low``, ``bounds_high``: f64 arrays of length ``n_atoms * 3`` (may be NULL; defaults to [-50, 50] per dimension). The caller must eventually pass the returned pointer to ``rgpot_potential_free``. .. rubric:: Structs and Unions .. rust:struct:: rgpot_core::eindir::rgpot_potential_t :index: 1 :vis: pub :toc: struct rgpot_potential_t :layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"rgpot_potential_t"}] Superset potential: embeds ``eindir_objective_t`` as its first member. Because ``base`` is first and both structs are ``#[repr(C)]``, casting a ``*mut rgpot_potential_t`` to ``*mut eindir_objective_t`` is defined behaviour at the C ABI. No conversion method is needed. .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::base :index: 2 :vis: pub :toc: base :layout: [{"type":"name","value":"base"},{"type":"punctuation","value":": "},{"type":"link","value":"eindir_objective_t","target":"eindir_objective_t"}] Embedded eindir base: the IS-A relationship lives here. MUST remain the first field. .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::callback :index: 2 :vis: pub :toc: callback :layout: [{"type":"name","value":"callback"},{"type":"punctuation","value":": "},{"type":"link","value":"PotentialCallback","target":"PotentialCallback"}] The underlying rgpot force/energy callback. .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::pot_user_data :index: 2 :vis: pub :toc: pot_user_data :layout: [{"type":"name","value":"pot_user_data"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"c_void","target":"c_void"}] Opaque context for ``callback`` (distinct from ``base.user_data``). .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::pot_free_fn :index: 2 :vis: pub :toc: pot_free_fn :layout: [{"type":"name","value":"pot_free_fn"},{"type":"punctuation","value":": "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"punctuation","value":"("},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"c_void","target":"c_void"},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"}] Optional destructor for ``pot_user_data``. .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::n_atoms :index: 2 :vis: pub :toc: n_atoms :layout: [{"type":"name","value":"n_atoms"},{"type":"punctuation","value":": "},{"type":"link","value":"usize","target":"usize"}] Atom count; set by ``rgpot_potential_new_eindir``. .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::atomic_numbers :index: 2 :vis: pub :toc: atomic_numbers :layout: [{"type":"name","value":"atomic_numbers"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"i32","target":"i32"}] Atomic numbers, heap-allocated (len = n_atoms), owned by this struct. .. rust:variable:: rgpot_core::eindir::rgpot_potential_t::box_matrix :index: 2 :vis: pub :toc: box_matrix :layout: [{"type":"name","value":"box_matrix"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"["},{"type":"link","value":"f64","target":"f64"},{"type":"punctuation","value":"; "},{"type":"literal","value":"9"},{"type":"punctuation","value":"]"}] Box matrix (column-major, 3x3), copied at construction. .. rubric:: Traits implemented .. rust:impl:: rgpot_core::eindir::rgpot_potential_t::Send :index: -1 :vis: pub :layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"impl"},{"type":"space"},{"type":"link","value":"Send","target":"Send"},{"type":"space"},{"type":"keyword","value":"for"},{"type":"space"},{"type":"link","value":"rgpot_potential_t","target":"rgpot_potential_t"}] :toc: impl Send for rgpot_potential_t