refactor C library interface and add doxygen decorations

src/library.h

@@ -1,4 +1,4 @@
-/* -*- c++ -*- ----------------------------------------------------------
+/* -*- c -*- ------------------------------------------------------------
    LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
    http://lammps.sandia.gov, Sandia National Laboratories
    Steve Plimpton, sjplimp@sandia.gov
@@ -14,54 +14,123 @@
 #ifndef LAMMPS_LIBRARY_H
 #define LAMMPS_LIBRARY_H
 
-/*
+/* C style library interface to LAMMPS which allows to create and
-   C or Fortran style library interface to LAMMPS
+ * control instances of the LAMMPS C++ class and exchange data with it.
-   new LAMMPS-specific functions can be added
+ * The C bindings are the basis for the Python and Fortran modules.
-*/
+ *
+ * If needed, new LAMMPS-specific functions can be added to expose
+ * additional LAMMPS functionality to this library interface. */
 
-/*
+/* We follow the behavior of regular LAMMPS compilation and assume
- * Follow the behavior of regular LAMMPS compilation and assume
+ * -DLAMMPS_SMALLBIG when no define is set. */
- * -DLAMMPS_SMALLBIG when no define is set.
+
- */
+#if  !defined(LAMMPS_BIGBIG)     \
-#if !defined(LAMMPS_BIGBIG) && !defined(LAMMPS_SMALLBIG) && !defined(LAMMPS_SMALLSMALL)
+  && !defined(LAMMPS_SMALLBIG)   \
+  && !defined(LAMMPS_SMALLSMALL)
 #define LAMMPS_SMALLBIG
 #endif
 
+/* To allow including the library interface without MPI */
+
+#if !defined(LAMMPS_LIB_NO_MPI)
 #include <mpi.h>
+#endif
+
 #if defined(LAMMPS_BIGBIG) || defined(LAMMPS_SMALLBIG)
 #include <inttypes.h>  /* for int64_t */
 #endif
 
-/* ifdefs allow this file to be included in a C program */
+/** Style constants for extracting data from computes and fixes.
+ *
+ * Must be kept in sync with the equivalent constants in lammps.py */
+
+enum _LMP_STYLE_CONST {
+  LMP_STYLE_GLOBAL=0,           /*!< return global data */
+  LMP_STYLE_ATOM  =1,           /*!< return per-atom data */
+  LMP_STYLE_LOCAL =2            /*!< return local data */
+};
+
+/** Type and size constants for extracting data from computes and fixes.
+ *
+ * Must be kept in sync with the equivalent constants in lammps.py */
+
+enum _LMP_TYPE_CONST {
+  LMP_TYPE_SCALAR=0,            /*!< return scalar */
+  LMP_TYPE_VECTOR=1,            /*!< return vector */
+  LMP_TYPE_ARRAY =2,            /*!< return array */
+  LMP_SIZE_VECTOR=3,            /*!< return length of vector */
+  LMP_SIZE_ROWS  =4,            /*!< return number of rows */
+  LMP_SIZE_COLS  =5             /*!< return number of columns */
+};
+
+/* Ifdefs to allow this file to be included in C and C++ programs */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-void lammps_open(int, char **, MPI_Comm, void **);
+// ----------------------------------------------------------------------
-void lammps_open_no_mpi(int, char **, void **);
+// Library functions to create/destroy an instance of LAMMPS
-void lammps_close(void *);
+// ----------------------------------------------------------------------
-int  lammps_version(void *);
-void lammps_file(void *, char *);
-char *lammps_command(void *, char *);
-void lammps_commands_list(void *, int, char **);
-void lammps_commands_string(void *, char *);
-void lammps_free(void *);
 
-int lammps_extract_setting(void *, char *);
+#if !defined(LAMMPS_LIB_NO_MPI)
-void *lammps_extract_global(void *, char *);
+void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr);
-void lammps_extract_box(void *, double *, double *,
+#endif
-                        double *, double *, double *, int *, int *);
+void *lammps_open_no_mpi(int argc, char **argv, void **ptr);
-void *lammps_extract_atom(void *, char *);
+void *lammps_open_fortran(int argc, char **argv, int f_comm, void **ptr);
-void *lammps_extract_compute(void *, char *, int, int);
+void  lammps_close(void *handle);
-void *lammps_extract_fix(void *, char *, int, int, int, int);
+void  lammps_mpi_init();
-void *lammps_extract_variable(void *, char *, char *);
+void  lammps_mpi_finalize();
+void  lammps_free(void *ptr);
 
-double lammps_get_thermo(void *, char *);
+// ----------------------------------------------------------------------
-int lammps_get_natoms(void *);
+// Library functions to process commands
+// ----------------------------------------------------------------------
 
-int lammps_set_variable(void *, char *, char *);
+void  lammps_file(void *handle, const char *file);
-void lammps_reset_box(void *, double *, double *, double, double, double);
+
+char *lammps_command(void *handle, const char *cmd);
+void  lammps_commands_list(void *handle, int ncmd, const char **cmds);
+void  lammps_commands_string(void *handle, const char *str);
+
+// -----------------------------------------------------------------------
+// Library functions to extract info from LAMMPS or set data in LAMMPS
+// -----------------------------------------------------------------------
+
+int    lammps_version(void *handle);
+double lammps_get_natoms(void *handle);
+double lammps_get_thermo(void *handle, char *keyword);
+
+void   lammps_extract_box(void *handle, double *boxlo, double *boxhi,
+                          double *xy, double *yz, double *xz,
+                          int *pflags, int *boxflag);
+void   lammps_reset_box(void *handle, double *boxlo, double *boxhi,
+                        double xy, double yz, double xz);
+
+int    lammps_extract_setting(void *handle, char *keyword);
+void  *lammps_extract_global(void *handle, char *name);
+void  *lammps_extract_atom(void *handle, char *name);
+
+#if !defined(LAMMPS_BIGBIG)
+int    lammps_create_atoms(void *handle, int n, int *id, int *type,
+                           double *x, double *v, int *image, int bexpand);
+#else
+int    lammps_create_atoms(void *handle, int n, int64_t *id, int *type,
+                           double *x, double *v, int64_t* image, int bexpand);
+#endif
+
+// ----------------------------------------------------------------------
+// Library functions to access data from computes, fixes, variables in LAMMPS
+// ----------------------------------------------------------------------
+
+void *lammps_extract_compute(void *handle, char *id, int, int);
+void *lammps_extract_fix(void *handle, char *, int, int, int, int);
+void *lammps_extract_variable(void *handle, char *, char *);
+int   lammps_set_variable(void *, char *, char *);
+
+// ----------------------------------------------------------------------
+// Library functions for scatter/gather operations of data
+// ----------------------------------------------------------------------
 
 void lammps_gather_atoms(void *, char *, int, int, void *);
 void lammps_gather_atoms_concat(void *, char *, int, int, void *);
@@ -69,6 +138,46 @@ void lammps_gather_atoms_subset(void *, char *, int, int, int, int *, void *);
 void lammps_scatter_atoms(void *, char *, int, int, void *);
 void lammps_scatter_atoms_subset(void *, char *, int, int, int, int *, void *);
 
+// ----------------------------------------------------------------------
+// Library functions for retrieving configuration information
+// ----------------------------------------------------------------------
+
+int lammps_config_has_mpi_support();
+int lammps_config_has_package(char *);
+int lammps_config_package_count();
+int lammps_config_package_name(int, char *, int);
+int lammps_config_has_gzip_support();
+int lammps_config_has_png_support();
+int lammps_config_has_jpeg_support();
+int lammps_config_has_ffmpeg_support();
+int lammps_config_has_exceptions();
+
+int lammps_has_style(void *, char *, char *);
+int lammps_style_count(void *, char *);
+int lammps_style_name(void *, char *, int, char *, int);
+
+// ----------------------------------------------------------------------
+// Library functions for accessing neighbor lists
+// ----------------------------------------------------------------------
+
+int lammps_find_pair_neighlist(void*, char *, int, int, int);
+int lammps_find_fix_neighlist(void*, char *, int);
+int lammps_find_compute_neighlist(void*, char *, int);
+int lammps_neighlist_num_elements(void*, int);
+void lammps_neighlist_element_neighbors(void *, int, int, int *, int *, int ** );
+
+// ----------------------------------------------------------------------
+// Utility functions
+// ----------------------------------------------------------------------
+
+#if !defined(LAMMPS_BIGBIG)
+int lammps_encode_image_flags(int ix, int iy, int iz);
+void lammps_decode_image_flags(int image, int *flags);
+#else
+int64_t lammps_encode_image_flags(int ix, int iy, int iz);
+void lammps_decode_image_flags(int64_t image, int *flags);
+#endif
+
 #if defined(LAMMPS_BIGBIG)
 typedef void (*FixExternalFnPtr)(void *, int64_t, int, int64_t *, double **, double **);
 void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*);
@@ -79,49 +188,20 @@ void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*);
 typedef void (*FixExternalFnPtr)(void *, int, int, int *, double **, double **);
 void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*);
 #endif
-
+void lammps_fix_external_set_energy_global(void *, char *, double);
-int lammps_config_has_package(char * package_name);
+void lammps_fix_external_set_virial_global(void *, char *, double *);
-int lammps_config_package_count();
-int lammps_config_package_name(int index, char * buffer, int max_size);
-int lammps_config_has_gzip_support();
-int lammps_config_has_png_support();
-int lammps_config_has_jpeg_support();
-int lammps_config_has_ffmpeg_support();
-int lammps_config_has_exceptions();
-
-int lammps_has_style(void* ptr, char * category, char * name);
-int lammps_style_count(void* ptr, char * category);
-int lammps_style_name(void*ptr, char * category, int index, char * buffer, int max_size);
-
-int lammps_find_pair_neighlist(void* ptr, char * style, int exact, int nsub, int request);
-int lammps_find_fix_neighlist(void* ptr, char * id, int request);
-int lammps_find_compute_neighlist(void* ptr, char * id, int request);
-int lammps_neighlist_num_elements(void* ptr, int idx);
-void lammps_neighlist_element_neighbors(void * ptr, int idx, int element, int * iatom, int * numneigh, int ** neighbors);
-
-// lammps_create_atoms() takes tagint and imageint as args
-// ifdef insures they are compatible with rest of LAMMPS
-// caller must match to how LAMMPS library is built
-
-#ifdef LAMMPS_BIGBIG
-void lammps_create_atoms(void *, int, int64_t *, int *,
-                         double *, double *, int64_t *, int);
-#else
-void lammps_create_atoms(void *, int, int *, int *,
-                         double *, double *, int *, int);
-#endif
 
 #ifdef LAMMPS_EXCEPTIONS
-int lammps_has_error(void *);
+int lammps_has_error(void *handle);
-int lammps_get_last_error_message(void *, char *, int);
+int lammps_get_last_error_message(void *handle, char *buffer, int buf_size);
 #endif
 
-#undef LAMMPS
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* LAMMPS_LIBRARY_H */
+
 /* ERROR/WARNING messages:
 
 E: Library error: issuing LAMMPS command during run
@@ -172,3 +252,7 @@ W: Library warning in lammps_create_atoms, invalid total atoms %ld %ld
 UNDOCUMENTED
 
 */
+
+/* Local Variables:
+ * fill-column: 72
+ * End: */