update swig interface file for recent changes to the library interface

tools/swig/lammps.i

@@ -22,6 +22,11 @@
 
 %{
 
+/** Data type constants for extracting data from atoms, computes and fixes
+ *
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
+
 enum _LMP_DATATYPE_CONST {
   LAMMPS_INT       = 0,     /*!< 32-bit integer (array) */
   LAMMPS_INT_2D    = 1,     /*!< two-dimensional 32-bit integer array */
@@ -34,25 +39,52 @@ enum _LMP_DATATYPE_CONST {
 
 /** Style constants for extracting data from computes and fixes.
  *
- * Must be kept in sync with the equivalent constants in lammps/constants.py */
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
 
 enum _LMP_STYLE_CONST {
-  LMP_STYLE_GLOBAL=0,           /*!< return global data */
+  LMP_STYLE_GLOBAL = 0,     /*!< return global data */
-  LMP_STYLE_ATOM  =1,           /*!< return per-atom data */
+  LMP_STYLE_ATOM   = 1,     /*!< return per-atom data */
-  LMP_STYLE_LOCAL =2            /*!< return local 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/constants.py */
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
 
 enum _LMP_TYPE_CONST {
-  LMP_TYPE_SCALAR=0,            /*!< return scalar */
+  LMP_TYPE_SCALAR = 0,      /*!< return scalar */
-  LMP_TYPE_VECTOR=1,            /*!< return vector */
+  LMP_TYPE_VECTOR = 1,      /*!< return vector */
-  LMP_TYPE_ARRAY =2,            /*!< return array */
+  LMP_TYPE_ARRAY  = 2,      /*!< return array */
-  LMP_SIZE_VECTOR=3,            /*!< return length of vector */
+  LMP_SIZE_VECTOR = 3,      /*!< return length of vector */
-  LMP_SIZE_ROWS  =4,            /*!< return number of rows */
+  LMP_SIZE_ROWS   = 4,      /*!< return number of rows */
-  LMP_SIZE_COLS  =5             /*!< return number of columns */
+  LMP_SIZE_COLS   = 5       /*!< return number of columns */
+};
+
+/** Error codes to select the suitable function in the Error class
+ *
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
+
+enum _LMP_ERROR_CONST {
+  LMP_ERROR_WARNING  = 0,   /*!< call Error::warning() */
+  LMP_ERROR_ONE      = 1,   /*!< called from one MPI rank */
+  LMP_ERROR_ALL      = 2,   /*!< called from all MPI ranks */
+  LMP_ERROR_WORLD    = 4,   /*!< error on Comm::world */
+  LMP_ERROR_UNIVERSE = 8    /*!< error on Comm::universe */
+};
+
+/** Variable style constants for extracting data from variables.
+ *
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
+
+enum _LMP_VAR_CONST {
+  LMP_VAR_EQUAL  = 0,       /*!< compatible with equal-style variables */
+  LMP_VAR_ATOM   = 1,       /*!< compatible with atom-style variables */
+  LMP_VAR_VECTOR = 2,       /*!< compatible with vector-style variables */
+  LMP_VAR_STRING = 3        /*!< return value will be a string (catch-all) */
 };
 
 /*
@@ -65,10 +97,13 @@ extern void   lammps_mpi_init();
 extern void   lammps_mpi_finalize();
 extern void   lammps_kokkos_finalize();
 extern void   lammps_python_finalize();
+extern void   lammps_error(void *handle, int error_type, const char *error_text);
+
 extern void   lammps_file(void *handle, const char *file);
 extern char  *lammps_command(void *handle, const char *cmd);
 extern void   lammps_commands_list(void *handle, int ncmd, const char **cmds);
 extern void   lammps_commands_string(void *handle, const char *str);
+
 extern double lammps_get_natoms(void *handle);
 extern double lammps_get_thermo(void *handle, const char *keyword);
 extern void   lammps_extract_box(void *handle, double *boxlo, double *boxhi,
@@ -81,12 +116,16 @@ extern int    lammps_get_mpi_comm(void *handle);
 extern int    lammps_extract_setting(void *handle, const char *keyword);
 extern int    lammps_extract_global_datatype(void *handle, const char *name);
 extern void  *lammps_extract_global(void *handle, const char *name);
+
 extern int    lammps_extract_atom_datatype(void *handle, const char *name);
 extern void  *lammps_extract_atom(void *handle, const char *name);
+
 extern void  *lammps_extract_compute(void *handle, char *id, int, int);
 extern void  *lammps_extract_fix(void *handle, char *, int, int, int, int);
 extern void  *lammps_extract_variable(void *handle, char *, char *);
+extern int    lammps_extract_variable_datatype(void *handle, const char *name);
 extern int    lammps_set_variable(void *, char *, char *);
+
 extern void   lammps_gather_atoms(void *, char *, int, int, void *);
 extern void   lammps_gather_atoms_concat(void *, char *, int, int, void *);
 extern void   lammps_gather_atoms_subset(void *, char *, int, int, int, int *, void *);
@@ -107,6 +146,7 @@ extern int    lammps_find_fix_neighlist(void*, char *, int);
 extern int    lammps_find_compute_neighlist(void*, char *, int);
 extern int    lammps_neighlist_num_elements(void*, int);
 extern void   lammps_neighlist_element_neighbors(void *, int, int, int *, int *, int ** );
+
 extern int    lammps_version(void *handle);
 extern void   lammps_get_os_info(char *buffer, int buf_size);
 extern int    lammps_config_has_mpi_support();
@@ -151,15 +191,21 @@ extern void   lammps_fix_external_set_virial_global(void *handle, const char *id
 extern void   lammps_fix_external_set_vector_length(void *handle, const char *id, int len);
 extern void   lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val);
 
+extern void   lammps_flush_buffers(void *ptr);
 extern void   lammps_free(void *ptr);
 extern int    lammps_is_running(void *handle);
 extern void   lammps_force_timeout(void *handle);
 extern int    lammps_has_error(void *handle);
 extern int    lammps_get_last_error_message(void *handle, char *buffer, int buf_size);
+extern int    lammps_python_api_version();
 
-extern void   lammps_flush_buffers(void *ptr);
 %}
 
+/** Data type constants for extracting data from atoms, computes and fixes
+ *
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
+
 enum _LMP_DATATYPE_CONST {
   LAMMPS_INT       = 0,     /*!< 32-bit integer (array) */
   LAMMPS_INT_2D    = 1,     /*!< two-dimensional 32-bit integer array */
@@ -172,25 +218,52 @@ enum _LMP_DATATYPE_CONST {
 
 /** Style constants for extracting data from computes and fixes.
  *
- * Must be kept in sync with the equivalent constants in lammps/constants.py */
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
 
 enum _LMP_STYLE_CONST {
-  LMP_STYLE_GLOBAL=0,           /*!< return global data */
+  LMP_STYLE_GLOBAL = 0,     /*!< return global data */
-  LMP_STYLE_ATOM  =1,           /*!< return per-atom data */
+  LMP_STYLE_ATOM   = 1,     /*!< return per-atom data */
-  LMP_STYLE_LOCAL =2            /*!< return local 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/constants.py */
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
 
 enum _LMP_TYPE_CONST {
-  LMP_TYPE_SCALAR=0,            /*!< return scalar */
+  LMP_TYPE_SCALAR = 0,      /*!< return scalar */
-  LMP_TYPE_VECTOR=1,            /*!< return vector */
+  LMP_TYPE_VECTOR = 1,      /*!< return vector */
-  LMP_TYPE_ARRAY =2,            /*!< return array */
+  LMP_TYPE_ARRAY  = 2,      /*!< return array */
-  LMP_SIZE_VECTOR=3,            /*!< return length of vector */
+  LMP_SIZE_VECTOR = 3,      /*!< return length of vector */
-  LMP_SIZE_ROWS  =4,            /*!< return number of rows */
+  LMP_SIZE_ROWS   = 4,      /*!< return number of rows */
-  LMP_SIZE_COLS  =5             /*!< return number of columns */
+  LMP_SIZE_COLS   = 5       /*!< return number of columns */
+};
+
+/** Error codes to select the suitable function in the Error class
+ *
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
+
+enum _LMP_ERROR_CONST {
+  LMP_ERROR_WARNING  = 0,   /*!< call Error::warning() */
+  LMP_ERROR_ONE      = 1,   /*!< called from one MPI rank */
+  LMP_ERROR_ALL      = 2,   /*!< called from all MPI ranks */
+  LMP_ERROR_WORLD    = 4,   /*!< error on Comm::world */
+  LMP_ERROR_UNIVERSE = 8    /*!< error on Comm::universe */
+};
+
+/** Variable style constants for extracting data from variables.
+ *
+ * Must be kept in sync with the equivalent constants in src/library.h,
+ * python/lammps/constants.py, and fortran/lammps.f90 */
+
+enum _LMP_VAR_CONST {
+  LMP_VAR_EQUAL  = 0,       /*!< compatible with equal-style variables */
+  LMP_VAR_ATOM   = 1,       /*!< compatible with atom-style variables */
+  LMP_VAR_VECTOR = 2,       /*!< compatible with vector-style variables */
+  LMP_VAR_STRING = 3        /*!< return value will be a string (catch-all) */
 };
 
 /*
@@ -203,10 +276,13 @@ extern void   lammps_mpi_init();
 extern void   lammps_mpi_finalize();
 extern void   lammps_kokkos_finalize();
 extern void   lammps_python_finalize();
+extern void   lammps_error(void *handle, int error_type, const char *error_text);
+
 extern void   lammps_file(void *handle, const char *file);
 extern char  *lammps_command(void *handle, const char *cmd);
 extern void   lammps_commands_list(void *handle, int ncmd, const char **cmds);
 extern void   lammps_commands_string(void *handle, const char *str);
+
 extern double lammps_get_natoms(void *handle);
 extern double lammps_get_thermo(void *handle, const char *keyword);
 extern void   lammps_extract_box(void *handle, double *boxlo, double *boxhi,
@@ -219,12 +295,16 @@ extern int    lammps_get_mpi_comm(void *handle);
 extern int    lammps_extract_setting(void *handle, const char *keyword);
 extern int    lammps_extract_global_datatype(void *handle, const char *name);
 extern void  *lammps_extract_global(void *handle, const char *name);
+
 extern int    lammps_extract_atom_datatype(void *handle, const char *name);
 extern void  *lammps_extract_atom(void *handle, const char *name);
+
 extern void  *lammps_extract_compute(void *handle, char *id, int, int);
 extern void  *lammps_extract_fix(void *handle, char *, int, int, int, int);
 extern void  *lammps_extract_variable(void *handle, char *, char *);
+extern int    lammps_extract_variable_datatype(void *handle, const char *name);
 extern int    lammps_set_variable(void *, char *, char *);
+
 extern void   lammps_gather_atoms(void *, char *, int, int, void *);
 extern void   lammps_gather_atoms_concat(void *, char *, int, int, void *);
 extern void   lammps_gather_atoms_subset(void *, char *, int, int, int, int *, void *);
@@ -245,6 +325,7 @@ extern int    lammps_find_fix_neighlist(void*, char *, int);
 extern int    lammps_find_compute_neighlist(void*, char *, int);
 extern int    lammps_neighlist_num_elements(void*, int);
 extern void   lammps_neighlist_element_neighbors(void *, int, int, int *, int *, int ** );
+
 extern int    lammps_version(void *handle);
 extern void   lammps_get_os_info(char *buffer, int buf_size);
 extern int    lammps_config_has_mpi_support();
@@ -268,14 +349,20 @@ extern int    lammps_id_name(void *, const char *, int, char *buffer, int buf_si
 extern int    lammps_plugin_count();
 extern int    lammps_plugin_name(int, char *, char *, int);
 /*
-extern int lammps_encode_image_flags(int ix, int iy, int iz);
+ * Have not found a good way to map these functions in a general way.
-extern void lammps_decode_image_flags(int image, int *flags);
+ * So some individual customization for the specific use case and compilation is needed.
-extern int64_t lammps_encode_image_flags(int ix, int iy, int iz);
+ *
-extern void lammps_decode_image_flags(int64_t image, int *flags);
+  extern int lammps_encode_image_flags(int ix, int iy, int iz);
-typedef void (*FixExternalFnPtr)(void *, int64_t, int, int64_t *, double **, double **);
+  extern void lammps_decode_image_flags(int image, int *flags);
-extern  void lammps_set_fix_external_callback(void *handle, const char *id, FixExternalFnPtr funcptr, void *ptr);
+  extern int64_t lammps_encode_image_flags(int ix, int iy, int iz);
-extern  void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double *eng);
+  extern void lammps_decode_image_flags(int64_t image, int *flags);
-extern void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double **virial);
+
+ * Supporting the fix external callback mechanism will require extra code specific to the application.
+  typedef void (*FixExternalFnPtr)(void *, int64_t, int, int64_t *, double **, double **);
+  extern  void lammps_set_fix_external_callback(void *handle, const char *id, FixExternalFnPtr funcptr, void *ptr);
+ * these two functions can only be used from the callback, so we don't support them either
+  extern  void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double *eng);
+  extern void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double **virial);
 */
 extern double **lammps_fix_external_get_force(void *handle, const char *id);
 extern void   lammps_fix_external_set_energy_global(void *handle, const char *id, double eng);
@@ -283,12 +370,12 @@ extern void   lammps_fix_external_set_virial_global(void *handle, const char *id
 extern void   lammps_fix_external_set_vector_length(void *handle, const char *id, int len);
 extern void   lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val);
 
+extern void   lammps_flush_buffers(void *ptr);
 extern void   lammps_free(void *ptr);
 extern int    lammps_is_running(void *handle);
 extern void   lammps_force_timeout(void *handle);
 extern int    lammps_has_error(void *handle);
 extern int    lammps_get_last_error_message(void *handle, char *buffer, int buf_size);
+extern int    lammps_python_api_version();
 
-extern void   lammps_flush_buffers(void *ptr);
+/* last revised on 3 October 2022 */
-
-/* last revised on 4 February 2022 */