External engine C ABI¶
CppCore/rgpot/ExternalPot/external_potentials.h declares the C constructors of
the LAMMPS, GROMACS and OpenMM shifted Lennard-Jones potentials.
CppCore/rgpot/ExternalPot/ExternalPot.cc implements them in librgpot.
Positions and cells are Angstrom, energies eV and forces eV/Angstrom at this
interface.
A box is nine doubles, the lattice vectors as rows.
Every call that can fail takes err and err_len.
On failure it writes a message of at most
err_len - 1 characters and a terminating null into err; a null err or an err_len
of 0 writes nothing.
Types¶
rgpot_external_potential¶
- Inputs
none; an opaque handle from one of the constructors.
- Units
none.
- Outputs
none.
- Errors
none.
One handle holds one potential. Each potential serialises the force calls of its own instance with a mutex.
Unit factors¶
rgpot_md_kj_per_ev¶
double rgpot_md_kj_per_ev(void);
- Inputs
none.
- Units
kJ/mol per eV.
- Outputs
the elementary charge times the Avogadro number divided by 1000, from the exact 2019 SI values in
CppCore/rgpot/ExternalPot/md_units.hpp.- Errors
none; the call cannot fail.
rgpot_md_nm_per_angstrom¶
double rgpot_md_nm_per_angstrom(void);
- Inputs
none.
- Units
nm per Angstrom.
- Outputs
0.1.
- Errors
none; the call cannot fail.
Constructors¶
rgpot_lammps_potential¶
rgpot_external_potential *rgpot_lammps_potential(const char *engine_path,
double u0, double cutoff,
double psi, char *err,
size_t err_len);
- Inputs
engine_path, the engine library, or null or empty to search.u0is the well depth,cutoffthe cutoff andpsithe zero crossing of the 12-6 potential.erranderr_lenreceive a failure message.- Units
u0is eV;cutoffandpsiare Angstrom.- Outputs
a new handle, freed with
rgpot_external_potential_free. The constructor opens the engine library, resolvesrgpot_engine_create,rgpot_engine_destroyandrgpot_engine_force, and callsrgpot_engine_createwith the three doublesu0,cutoff,psiin eV and Angstrom. Every force call goes torgpot_engine_force. A non-emptyengine_pathis the only library tried. Otherwise the constructor triesRGPOT_LAMMPS_ENGINE, thenLAMMPS_ENGINEwhen they are set and not empty, thenliblammps_engine.soandliblj_engine.sothrough the dynamic linker’s search path (.dylibon macOS,.dllon Windows).- Errors
returns null and writes
errwhenu0,cutofforpsiis not positive and finite (“u0, cutoff and psi must be positive and finite (eV and Angstrom)”). Returns null and writeserrwhen no candidate opens with all three symbols (“engine library was not opened: “ and the reason for each candidate) or whenrgpot_engine_createreturns null (its message, or “rgpotenginecreatefailed”).
rgpot_gromacs_potential¶
rgpot_external_potential *rgpot_gromacs_potential(const char *engine_path,
double u0, double cutoff,
double psi, char *err,
size_t err_len);
- Inputs
engine_path, a library, or null or empty to evaluate in process;u0,cutoff,psi,erranderr_lenas inrgpot_lammps_potential.- Units
u0is eV;cutoffandpsiare Angstrom. The constructor stores them once as kJ/mol and nm.- Outputs
a new handle, freed with
rgpot_external_potential_free. Without a library the force is the in-processLJPotwithu0,cutoffandpsi. With a library the constructor resolvesrgpot_engine_create,rgpot_engine_destroyandrgpot_md_native_force, and callsrgpot_engine_createwith the three doubles in kJ/mol and nm. Each force call then passes positions and box in nm torgpot_md_native_forceand converts the kJ/mol energy and the (kJ/mol)/nm forces back to eV and eV/Angstrom.- Errors
returns null and writes
errfor au0,cutofforpsithat is not positive and finite, a library that does not open or lacks one of the three symbols, or a failedrgpot_engine_create, with the messages ofrgpot_lammps_potential.
rgpot_openmm_potential¶
rgpot_external_potential *rgpot_openmm_potential(const char *engine_path,
double u0, double cutoff,
double psi, char *err,
size_t err_len);
- Inputs
as
rgpot_gromacs_potential.- Units
u0is eV;cutoffandpsiare Angstrom, stored once as kJ/mol and nm.- Outputs
a new handle that behaves as the one from
rgpot_gromacs_potential, with the OpenMM potential type.- Errors
as
rgpot_gromacs_potential.
Evaluation¶
rgpot_external_potential_free¶
void rgpot_external_potential_free(rgpot_external_potential *pot);
- Inputs
pot, a handle from a constructor, or null.- Units
none.
- Outputs
destroys the potential, calls the engine’s
rgpot_engine_destroywhen there is one, and closes its library.- Errors
none; a null
potis ignored.
rgpot_external_potential_energy_forces¶
int rgpot_external_potential_energy_forces(
rgpot_external_potential *pot, const double *xyz, const int *atomic_numbers,
size_t n, const double *box9, double *forces, double *energy, char *err,
size_t err_len);
- Inputs
pot,xyz(3 * ndoubles, row-majorx y zper atom),atomic_numbers(nints),box9(nine doubles, lattice vectors as rows),forces(room for3 * ndoubles),energy,erranderr_len.box9must not be null, also whennis 0.- Units
xyzandbox9are Angstrom,\*energyis eV andforceseV/Angstrom.- Outputs
returns 0 and writes
\*energyand the3 * nforces, row-major likexyz. The variance the engine reports is not returned.- Errors
returns 1 and writes “energyforcesneeds a potential and a geometry” for a null
pot,energyorbox9, or, whenn > 0, a nullxyz,atomic_numbersorforces. Returns 1 and writes the message when the evaluation throws, for example “rgpotengineforcefailed” or “rgpotmdnativeforcefailed” when the engine returns nonzero.
Example¶
The GROMACS potential evaluated in process, a dimer 1.5 Angstrom apart.
#include <stdio.h>
#include "rgpot/ExternalPot/external_potentials.h"
int main(void) {
char err[256] = "";
rgpot_external_potential *pot = rgpot_gromacs_potential(NULL, 1.0, 8.0, 1.0, err, sizeof err);
if (pot == NULL) {
fprintf(stderr, "%s\n", err);
return 1;
}
const double xyz[6] = {0.0, 0.0, 0.0, 1.5, 0.0, 0.0};
const int z[2] = {1, 1};
const double box9[9] = {20.0, 0.0, 0.0, 0.0, 20.0, 0.0, 0.0, 0.0, 20.0};
double forces[6];
double energy = 0.0;
const int rc = rgpot_external_potential_energy_forces(pot, xyz, z, 2, box9, forces, &energy,
err, sizeof err);
rgpot_external_potential_free(pot);
if (rc != 0) {
fprintf(stderr, "%s\n", err);
return 1;
}
if (!(energy < 0.0) || forces[0] != -forces[3]) {
return 1;
}
printf("%.10f eV, %.6f eV/Angstrom\n", energy, forces[0]);
printf("%.6f kJ/mol per eV, %.1f nm per Angstrom\n", rgpot_md_kj_per_ev(),
rgpot_md_nm_per_angstrom());
return 0;
}