C API Structure - Open-Quantum-Platform/openqp GitHub Wiki

Utilizing OpenQP through the C API

The C API for OpenQP is designed to facilitate interactions between C and Fortran, using an OpenQP handle (oqp_handle_t) to manage data and operations.

Example: Interfacing Between C and Fortran

C Side

The oqp_handle_t structure in C is defined as follows:

typedef double xyz_t[3];

typedef struct oqp_handle_t {
  void *inf;
  xyz_t *xyz;
  double *qn;
  double *mass;
  xyz_t *grad;
  struct molecule *mol_prop;
  struct energy_results *mol_energy;
  struct dft_parameters *dft;
  struct control_parameters *control;
} oqp_handle_t;

Fortran Side

The corresponding Fortran type is defined using the bind(C) attribute to ensure compatibility with the C structure:

type, bind(C) :: oqp_handle_t
  type(c_ptr) :: inf
  type(c_ptr) :: xyz
  type(c_ptr) :: qn
  type(c_ptr) :: mass
  type(c_ptr) :: grad
  type(c_ptr) :: mol_prop
  type(c_ptr) :: mol_energy
  type(c_ptr) :: dft
  type(c_ptr) :: control
end type

Overall Process of Utilizing OQP through the C API

1. Include the OQP Header

   To use the OQP library in your C code, include the OQP header file:

   #include "oqp.h"
   

2. Initialize the OQP Handle

   Initialize the OQP handle to manage your simulation:

   struct oqp_handle_t *oqp = oqp_init();
   

3. Set Up Parameters

   Configure the runtime options and molecular properties:

   /* Set runtime options */
   oqp->control->hamilton = 10; // HF
   oqp->control->scftype = 1;   // RHF
   oqp->control->maxit = 30;    // Number of SCF iterations
   oqp->control->conv = 1.0e-6; // SCF convergence threshold
   
   /* Set molecular properties */
   oqp->mol_prop->charge = 0;
   oqp->mol_prop->mult = 1;
   oqp->mol_prop->nelec = 2;
   oqp->mol_prop->nelec_A = 1;
   oqp->mol_prop->nelec_B = 1;
   oqp->mol_prop->nocc = 1;
   
   /* Set atomic coordinates and properties */
   int natoms = 2;
   double x[2] = {-0.64, 0.64};
   double y[2] = { 0.00, 0.00};
   double z[2] = { 0.00, 0.00};
   double q[2] = { 1.00, 1.00};
   double mass[2] = { 1.00, 1.00};
   
   /* Fill OQP internal data structures */
   oqp_set_atoms(oqp, natoms, x, y, z, q, mass);
   
   /* Add basis set to the molecule */
   apply_basis(oqp, &Cbas, &Clog, &Cshl);
   

4. Run the Calculation

   Perform various quantum chemical calculations using the configured OQP handle:

   /* Compute one-electron integrals */
   hsandt(oqp, &Clog, &Cshl, &Chst);
   
   /* Generate an initial guess for the density matrix */
   guess_huckel(oqp, &Clog, &Cshl, &Chst, &Cdmt);
   
   /* Execute the HF energy calculation */
   hf_dft_energy(oqp, &Clog, &Cshl, &Chst, &Cdmt, &Cmoe);
   

5. Retrieve the Results

   Access the results directly from the oqp handle and clean up resources when done:

   /* Example: Print the calculated energy */
   printf("RHF energy of the H2 molecule is: %f Hartree\n", oqp->mol_energy->energy);
   
   /* Clean up and destroy the OQP handle */
   oqp_clean(oqp);
   

This process outlines how to set up and run quantum chemical calculations using the Open Quantum Platform through its C API, ensuring a seamless integration between C and Fortran components.

Going back to Developer's Documentation