From fcbbc51a33d5752f007a3aaa8563d847ab016718 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sat, 17 Oct 2020 23:50:49 -0400 Subject: [PATCH 01/37] add minimally tested swig wrapper for Lua, Perl5, Python, and Tcl --- cmake/CMakeLists.txt | 8 +++ swig/CMakeLists.txt | 55 +++++++++++++++ swig/lammps.i | 161 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 swig/CMakeLists.txt create mode 100644 swig/lammps.i diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 60ac3f70c0..e58bb73029 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -379,6 +379,14 @@ foreach(PKG_WITH_INCL KSPACE PYTHON VORONOI USER-COLVARS USER-MOLFILE USER-NETCD endif() endforeach() +# optionally enable building script wrappers using swig +option(WITH_SWIG "Build scripting language wrappers with SWIG" OFF) +if(WITH_SWIG) + get_filename_component(LAMMPS_SWIG_DIR ${LAMMPS_SOURCE_DIR}/../swig ABSOLUTE) + get_filename_component(LAMMPS_SWIG_BIN ${CMAKE_BINARY_DIR}/swig ABSOLUTE) + add_subdirectory(${LAMMPS_SWIG_DIR} ${LAMMPS_SWIG_BIN}) +endif() + set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)") separate_arguments(CMAKE_TUNE_FLAGS) foreach(_FLAG ${CMAKE_TUNE_FLAGS}) diff --git a/swig/CMakeLists.txt b/swig/CMakeLists.txt new file mode 100644 index 0000000000..18c6ac3195 --- /dev/null +++ b/swig/CMakeLists.txt @@ -0,0 +1,55 @@ +# CMake configuration for generating script language interfaces with swig + +# set minimum CMake version required and switch to new policies +cmake_minimum_required(VERSION 3.14) +if(POLICY CMP0078) + cmake_policy(SET CMP0078 NEW) +endif() +if(POLICY CMP0086) + cmake_policy(SET CMP0086 NEW) +endif() + +if(NOT BUILD_SHARED_LIBS) + error(FATAL_ERROR "Option BUILD_SHARED_LIBS must be enabled to use SWIG wrappers") +endif() + +find_package(SWIG REQUIRED) +include(${SWIG_USE_FILE}) + +option(BUILD_SWIG_LUA "Build Lua wrapper with SWIG" OFF) +option(BUILD_SWIG_PERL5 "Build Perl5 wrapper with SWIG" OFF) +option(BUILD_SWIG_PYTHON "Build Python wrapper with SWIG" OFF) +option(BUILD_SWIG_TCL "Build Tcl wrapper with SWIG" OFF) + +if(BUILD_SWIG_PYTHON) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME pylammps) + swig_add_library(pylammps TYPE MODULE LANGUAGE python SOURCES lammps.i) + find_package(Python REQUIRED COMPONENTS Development) + swig_link_libraries(pylammps PRIVATE lammps Python::Python) +endif() + +if(BUILD_SWIG_PERL5) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME pllammps) + swig_add_library(pllammps TYPE MODULE LANGUAGE perl5 SOURCES lammps.i) + find_package(PerlLibs REQUIRED 5.0) + target_compile_definitions(pllammps PRIVATE _LARGEFILE64_SOURCE) + target_include_directories(pllammps PRIVATE ${PERL_INCLUDE_PATH}) + swig_link_libraries(pllammps PRIVATE lammps ${PERL_LIBRARY}) +endif() + +if(BUILD_SWIG_LUA) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME lualammps) + swig_add_library(lualammps TYPE MODULE LANGUAGE lua SOURCES lammps.i) + find_package(Lua REQUIRED) + target_include_directories(lualammps PRIVATE ${LUA_INCLUDE_PATH}) + swig_link_libraries(lualammps PRIVATE lammps ${LUA_LIBRARY}) +endif() + +if(BUILD_SWIG_TCL) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME tcllammps) + swig_add_library(tcllammps TYPE MODULE LANGUAGE tcl SOURCES lammps.i) + find_package(TCL REQUIRED) + target_include_directories(tcllammps PRIVATE ${TCL_INCLUDE_PATH}) + swig_link_libraries(tcllammps PRIVATE lammps ${TCL_LIBRARY}) +endif() + diff --git a/swig/lammps.i b/swig/lammps.i new file mode 100644 index 0000000000..4ef6fdf994 --- /dev/null +++ b/swig/lammps.i @@ -0,0 +1,161 @@ +%{ +/* extern void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr); */ +extern void *lammps_open_no_mpi(int argc, char **argv, void **ptr); +extern void *lammps_open_fortran(int argc, char **argv, int f_comm); +extern void lammps_close(void *handle); +extern void lammps_mpi_init(); +extern void lammps_mpi_finalize(); +extern void lammps_free(void *ptr); +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 int lammps_version(void *handle); +extern void lammps_get_os_info(char *buffer, int buf_size); +extern void lammps_memory_usage(void *handle, double *meminfo); +extern int lammps_get_mpi_comm(void *handle); +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, + double *xy, double *yz, double *xz, + int *pflags, int *boxflag); +extern void lammps_reset_box(void *handle, double *boxlo, double *boxhi, + double xy, double yz, double xz); +extern int lammps_extract_setting(void *handle, const char *keyword); +extern void *lammps_extract_global(void *handle, const char *name); +extern void *lammps_extract_atom(void *handle, const char *name); +extern int lammps_extract_global_datatype(void *handle, const char *name); +extern int lammps_extract_atom_datatype(void *handle, const char *name); +/* extern int lammps_create_atoms(void *handle, int n, int *id, int *type, + extern int lammps_create_atoms(void *handle, int n, int64_t *id, int *type, */ +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_set_variable(void *, char *, char *); +extern void lammps_gather(void *, char *, int, int, void *); +extern void lammps_gather_concat(void *, char *, int, int, void *); +extern void lammps_gather_subset(void *, char *, int, int, int, int *, void *); +extern void lammps_scatter(void *, char *, int, int, void *); +extern void lammps_scatter_subset(void *, char *, int, int, int, int *, void *); +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 *); +extern void lammps_scatter_atoms(void *, char *, int, int, void *); +extern void lammps_scatter_atoms_subset(void *, char *, int, int, int, int *, void *); +extern int lammps_config_has_mpi_support(); +extern int lammps_config_has_package(const char *); +extern int lammps_config_package_count(); +extern int lammps_config_package_name(int, char *, int); +extern int lammps_config_has_gzip_support(); +extern int lammps_config_has_png_support(); +extern int lammps_config_has_jpeg_support(); +extern int lammps_config_has_ffmpeg_support(); +extern int lammps_config_has_exceptions(); +extern int lammps_has_style(void *, const char *, const char *); +extern int lammps_style_count(void *, const char *); +extern int lammps_style_name(void *, const char *, int, char *, int); +extern int lammps_has_id(void *, const char *, const char *); +extern int lammps_id_count(void *, const char *); +extern int lammps_id_name(void *, const char *, int, char *, int); +extern int lammps_find_pair_neighlist(void*, char *, int, int, int); +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_encode_image_flags(int ix, int iy, int iz); +extern void lammps_decode_image_flags(int image, int *flags); +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 void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*); +extern void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*); +extern void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*); +extern void lammps_fix_external_set_energy_global(void *, char *, double); +extern void lammps_fix_external_set_virial_global(void *, char *, double *); +*/ +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 void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr); */ +extern void *lammps_open_no_mpi(int argc, char **argv, void **ptr); +extern void *lammps_open_fortran(int argc, char **argv, int f_comm); +extern void lammps_close(void *handle); +extern void lammps_mpi_init(); +extern void lammps_mpi_finalize(); +extern void lammps_free(void *ptr); +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 int lammps_version(void *handle); +extern void lammps_get_os_info(char *buffer, int buf_size); +extern void lammps_memory_usage(void *handle, double *meminfo); +extern int lammps_get_mpi_comm(void *handle); +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, + double *xy, double *yz, double *xz, + int *pflags, int *boxflag); +extern void lammps_reset_box(void *handle, double *boxlo, double *boxhi, + double xy, double yz, double xz); +extern int lammps_extract_setting(void *handle, const char *keyword); +extern void *lammps_extract_global(void *handle, const char *name); +extern void *lammps_extract_atom(void *handle, const char *name); +extern int lammps_extract_global_datatype(void *handle, const char *name); +extern int lammps_extract_atom_datatype(void *handle, const char *name); +/* +extern int lammps_create_atoms(void *handle, int n, int *id, int *type, +extern int lammps_create_atoms(void *handle, int n, int64_t *id, int *type, */ +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_set_variable(void *, char *, char *); +extern void lammps_gather(void *, char *, int, int, void *); +extern void lammps_gather_concat(void *, char *, int, int, void *); +extern void lammps_gather_subset(void *, char *, int, int, int, int *, void *); +extern void lammps_scatter(void *, char *, int, int, void *); +extern void lammps_scatter_subset(void *, char *, int, int, int, int *, void *); +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 *); +extern void lammps_scatter_atoms(void *, char *, int, int, void *); +extern void lammps_scatter_atoms_subset(void *, char *, int, int, int, int *, void *); +extern int lammps_config_has_mpi_support(); +extern int lammps_config_has_package(const char *); +extern int lammps_config_package_count(); +extern int lammps_config_package_name(int, char *, int); +extern int lammps_config_has_gzip_support(); +extern int lammps_config_has_png_support(); +extern int lammps_config_has_jpeg_support(); +extern int lammps_config_has_ffmpeg_support(); +extern int lammps_config_has_exceptions(); +extern int lammps_has_style(void *, const char *, const char *); +extern int lammps_style_count(void *, const char *); +extern int lammps_style_name(void *, const char *, int, char *, int); +extern int lammps_has_id(void *, const char *, const char *); +extern int lammps_id_count(void *, const char *); +extern int lammps_id_name(void *, const char *, int, char *, int); +extern int lammps_find_pair_neighlist(void*, char *, int, int, int); +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_encode_image_flags(int ix, int iy, int iz); +extern void lammps_decode_image_flags(int image, int *flags); +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 void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*); +extern void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*); +extern void lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*); +extern void lammps_fix_external_set_energy_global(void *, char *, double); +extern void lammps_fix_external_set_virial_global(void *, char *, double *); +*/ +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); + From 58ceab93ec03f4da098b1f4d1e770cc34470f68f Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 00:45:04 -0400 Subject: [PATCH 02/37] include enumerators --- swig/lammps.i | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/swig/lammps.i b/swig/lammps.i index 4ef6fdf994..0e9ecb67e3 100644 --- a/swig/lammps.i +++ b/swig/lammps.i @@ -1,5 +1,41 @@ %{ -/* extern void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr); */ + +enum _LMP_DATATYPE_CONST { + LAMMPS_INT = 0, /*!< 32-bit integer (array) */ + LAMMPS_INT_2D = 1, /*!< two-dimensional 32-bit integer array */ + LAMMPS_DOUBLE = 2, /*!< 64-bit double (array) */ + LAMMPS_DOUBLE_2D = 3, /*!< two-dimensional 64-bit double array */ + LAMMPS_INT64 = 4, /*!< 64-bit integer (array) */ + LAMMPS_INT64_2D = 5, /*!< two-dimensional 64-bit integer array */ + LAMMPS_STRING = 6 /*!< C-String */ +}; + +/** 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 */ +}; + +/* + extern void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr); +*/ extern void *lammps_open_no_mpi(int argc, char **argv, void **ptr); extern void *lammps_open_fortran(int argc, char **argv, int f_comm); extern void lammps_close(void *handle); @@ -26,7 +62,9 @@ extern void *lammps_extract_global(void *handle, const char *name); extern void *lammps_extract_atom(void *handle, const char *name); extern int lammps_extract_global_datatype(void *handle, const char *name); extern int lammps_extract_atom_datatype(void *handle, const char *name); -/* extern int lammps_create_atoms(void *handle, int n, int *id, int *type, +extern int lammps_create_atoms(void *handle, int n, int *id, int *type, + double *x, double *v, int *image, int bexpand); +/* extern int lammps_create_atoms(void *handle, int n, int64_t *id, int *type, */ extern void *lammps_extract_compute(void *handle, char *id, int, int); extern void *lammps_extract_fix(void *handle, char *, int, int, int, int); @@ -106,8 +144,9 @@ extern void *lammps_extract_global(void *handle, const char *name); extern void *lammps_extract_atom(void *handle, const char *name); extern int lammps_extract_global_datatype(void *handle, const char *name); extern int lammps_extract_atom_datatype(void *handle, const char *name); -/* extern int lammps_create_atoms(void *handle, int n, int *id, int *type, + double *x, double *v, int *image, int bexpand); +/* extern int lammps_create_atoms(void *handle, int n, int64_t *id, int *type, */ extern void *lammps_extract_compute(void *handle, char *id, int, int); extern void *lammps_extract_fix(void *handle, char *, int, int, int, int); From 1ed735e311bcf3c00fb9a2d2fc436d15174737ce Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 00:45:21 -0400 Subject: [PATCH 03/37] add some minimal usage examples --- swig/run_lua_example.sh | 13 +++++++++++++ swig/run_perl_example.sh | 17 +++++++++++++++++ swig/run_python_example.sh | 17 +++++++++++++++++ swig/run_tcl_example.sh | 13 +++++++++++++ 4 files changed, 60 insertions(+) create mode 100755 swig/run_lua_example.sh create mode 100755 swig/run_perl_example.sh create mode 100755 swig/run_python_example.sh create mode 100755 swig/run_tcl_example.sh diff --git a/swig/run_lua_example.sh b/swig/run_lua_example.sh new file mode 100755 index 0000000000..beaa32cc2e --- /dev/null +++ b/swig/run_lua_example.sh @@ -0,0 +1,13 @@ +#!/bin/sh + +cat > example.lua < example.pl < example.py < example.tcl < Date: Sun, 18 Oct 2020 01:06:17 -0400 Subject: [PATCH 04/37] include enumerator constants into swig interface file --- swig/lammps.i | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/swig/lammps.i b/swig/lammps.i index 0e9ecb67e3..c4b79fee62 100644 --- a/swig/lammps.i +++ b/swig/lammps.i @@ -117,6 +117,40 @@ extern int lammps_has_error(void *handle); extern int lammps_get_last_error_message(void *handle, char *buffer, int buf_size); %} + +enum _LMP_DATATYPE_CONST { + LAMMPS_INT = 0, /*!< 32-bit integer (array) */ + LAMMPS_INT_2D = 1, /*!< two-dimensional 32-bit integer array */ + LAMMPS_DOUBLE = 2, /*!< 64-bit double (array) */ + LAMMPS_DOUBLE_2D = 3, /*!< two-dimensional 64-bit double array */ + LAMMPS_INT64 = 4, /*!< 64-bit integer (array) */ + LAMMPS_INT64_2D = 5, /*!< two-dimensional 64-bit integer array */ + LAMMPS_STRING = 6 /*!< C-String */ +}; + +/** 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 */ +}; + /* extern void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr); */ extern void *lammps_open_no_mpi(int argc, char **argv, void **ptr); extern void *lammps_open_fortran(int argc, char **argv, int f_comm); From 42116fc444829cce74bc7d043dbdb94f99139905 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 01:06:34 -0400 Subject: [PATCH 05/37] expand examples to include some LAMMPS commands --- swig/run_lua_example.sh | 7 +++++++ swig/run_perl_example.sh | 7 +++++++ swig/run_python_example.sh | 6 ++++++ swig/run_tcl_example.sh | 7 +++++++ 4 files changed, 27 insertions(+) diff --git a/swig/run_lua_example.sh b/swig/run_lua_example.sh index beaa32cc2e..4dc7bad2f8 100755 --- a/swig/run_lua_example.sh +++ b/swig/run_lua_example.sh @@ -6,7 +6,14 @@ require("lualammps") lmp = lualammps.lammps_open_no_mpi(0,nil,nil) ver = lualammps.lammps_version(lmp) +lualammps.lammps_command(lmp, "units real") +lualammps.lammps_command(lmp, "lattice fcc 2.5") +lualammps.lammps_command(lmp, "region box block -5 5 -5 5 -5 5") +lualammps.lammps_command(lmp, "create_box 1 box") +lualammps.lammps_command(lmp, "create_atoms 1 box") + print("LAMMPS version ", ver) +print("Number of created atoms: ", lualammps.lammps_get_natoms(lmp)) lualammps.lammps_close(lmp ) EOF diff --git a/swig/run_perl_example.sh b/swig/run_perl_example.sh index 2fb59fe885..2714bcba6f 100755 --- a/swig/run_perl_example.sh +++ b/swig/run_perl_example.sh @@ -6,7 +6,14 @@ use pllammps; \$lmp = pllammps::lammps_open_no_mpi(0,undef,undef); \$ver = pllammps::lammps_version(\$lmp); +pllammps::lammps_command(\$lmp, "units real"); +pllammps::lammps_command(\$lmp, "lattice fcc 2.5"); +pllammps::lammps_command(\$lmp, "region box block -5 5 -5 5 -5 5"); +pllammps::lammps_command(\$lmp, "create_box 1 box"); +pllammps::lammps_command(\$lmp, "create_atoms 1 box"); + print("LAMMPS version ",\$ver,"\n"); +print("Number of created atoms: ", pllammps::lammps_get_natoms(\$lmp), "\n"); pllammps::lammps_close(\$lmp) EOF diff --git a/swig/run_python_example.sh b/swig/run_python_example.sh index 7b2aefd5a5..a09f2f119e 100755 --- a/swig/run_python_example.sh +++ b/swig/run_python_example.sh @@ -5,8 +5,14 @@ from pylammps import * lmp = lammps_open_no_mpi(0,None,None) ver = lammps_version(lmp) +lammps_command(lmp, "units real") +lammps_command(lmp, "lattice fcc 2.5") +lammps_command(lmp, "region box block -5 5 -5 5 -5 5") +lammps_command(lmp, "create_box 1 box") +lammps_command(lmp, "create_atoms 1 box") print("LAMMPS version ",ver) +print("Number of created atoms: %g" % lammps_get_natoms(lmp)) lammps_close(lmp) EOF diff --git a/swig/run_tcl_example.sh b/swig/run_tcl_example.sh index a54bfa74f5..00ae2e7579 100755 --- a/swig/run_tcl_example.sh +++ b/swig/run_tcl_example.sh @@ -6,7 +6,14 @@ load ./tcllammps.so set lmp [lammps_open_no_mpi 0 NULL NULL ] set ver [lammps_version \$lmp] +lammps_command \$lmp "units real" +lammps_command \$lmp "lattice fcc 2.5" +lammps_command \$lmp "region box block -5 5 -5 5 -5 5" +lammps_command \$lmp "create_box 1 box" +lammps_command \$lmp "create_atoms 1 box" + puts "LAMMPS version \$ver" +puts [format "Number of created atoms: %g" [lammps_get_natoms \$lmp]] lammps_close \$lmp EOF From c376b8ffa5b4ccabf9f5d75fe8a69b715af065de Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 01:49:19 -0400 Subject: [PATCH 06/37] add java interface --- swig/CMakeLists.txt | 9 +++++++++ swig/run_java_example.sh | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100755 swig/run_java_example.sh diff --git a/swig/CMakeLists.txt b/swig/CMakeLists.txt index 18c6ac3195..cadafba076 100644 --- a/swig/CMakeLists.txt +++ b/swig/CMakeLists.txt @@ -16,11 +16,20 @@ endif() find_package(SWIG REQUIRED) include(${SWIG_USE_FILE}) +option(BUILD_SWIG_JAVA "Build Java JNI wrapper with SWIG" OFF) option(BUILD_SWIG_LUA "Build Lua wrapper with SWIG" OFF) option(BUILD_SWIG_PERL5 "Build Perl5 wrapper with SWIG" OFF) option(BUILD_SWIG_PYTHON "Build Python wrapper with SWIG" OFF) option(BUILD_SWIG_TCL "Build Tcl wrapper with SWIG" OFF) +if(BUILD_SWIG_JAVA) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME javalammps) + swig_add_library(javalammps TYPE MODULE LANGUAGE java SOURCES lammps.i) + find_package(JNI REQUIRED) + target_include_directories(javalammps PRIVATE ${JNI_INCLUDE_DIRS}) + swig_link_libraries(javalammps PRIVATE lammps ${JNI_LIBRARIES}) +endif() + if(BUILD_SWIG_PYTHON) set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME pylammps) swig_add_library(pylammps TYPE MODULE LANGUAGE python SOURCES lammps.i) diff --git a/swig/run_java_example.sh b/swig/run_java_example.sh new file mode 100755 index 0000000000..09975049dd --- /dev/null +++ b/swig/run_java_example.sh @@ -0,0 +1,34 @@ +#!/bin/sh + +cat > example.java < Date: Sun, 18 Oct 2020 01:56:18 -0400 Subject: [PATCH 07/37] simplify --- swig/run_java_example.sh | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/swig/run_java_example.sh b/swig/run_java_example.sh index 09975049dd..a0d57be7ff 100755 --- a/swig/run_java_example.sh +++ b/swig/run_java_example.sh @@ -16,10 +16,8 @@ public class example { javalammps.lammps_command(lmp, "create_box 1 box"); javalammps.lammps_command(lmp, "create_atoms 1 box"); - System.out.print("LAMMPS version "); - System.out.println(ver); - System.out.print("Number of created atoms: "); - System.out.println(javalammps.lammps_get_natoms(lmp)); + System.out.println("LAMMPS version " + ver); + System.out.println("Number of created atoms: " + javalammps.lammps_get_natoms(lmp)); javalammps.lammps_close(lmp); } } From c6690eed6c28a2ef7fa2f7e071aa997074f12972 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 02:16:06 -0400 Subject: [PATCH 08/37] add ruby to the fold --- swig/CMakeLists.txt | 31 ++++++++++++++++++++----------- swig/run_ruby_example.sh | 21 +++++++++++++++++++++ 2 files changed, 41 insertions(+), 11 deletions(-) create mode 100755 swig/run_ruby_example.sh diff --git a/swig/CMakeLists.txt b/swig/CMakeLists.txt index cadafba076..f9b9fc6ce4 100644 --- a/swig/CMakeLists.txt +++ b/swig/CMakeLists.txt @@ -20,6 +20,7 @@ option(BUILD_SWIG_JAVA "Build Java JNI wrapper with SWIG" OFF) option(BUILD_SWIG_LUA "Build Lua wrapper with SWIG" OFF) option(BUILD_SWIG_PERL5 "Build Perl5 wrapper with SWIG" OFF) option(BUILD_SWIG_PYTHON "Build Python wrapper with SWIG" OFF) +option(BUILD_SWIG_RUBY "Build Ruby wrapper with SWIG" OFF) option(BUILD_SWIG_TCL "Build Tcl wrapper with SWIG" OFF) if(BUILD_SWIG_JAVA) @@ -30,11 +31,12 @@ if(BUILD_SWIG_JAVA) swig_link_libraries(javalammps PRIVATE lammps ${JNI_LIBRARIES}) endif() -if(BUILD_SWIG_PYTHON) - set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME pylammps) - swig_add_library(pylammps TYPE MODULE LANGUAGE python SOURCES lammps.i) - find_package(Python REQUIRED COMPONENTS Development) - swig_link_libraries(pylammps PRIVATE lammps Python::Python) +if(BUILD_SWIG_LUA) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME lualammps) + swig_add_library(lualammps TYPE MODULE LANGUAGE lua SOURCES lammps.i) + find_package(Lua REQUIRED) + target_include_directories(lualammps PRIVATE ${LUA_INCLUDE_PATH}) + swig_link_libraries(lualammps PRIVATE lammps ${LUA_LIBRARY}) endif() if(BUILD_SWIG_PERL5) @@ -46,12 +48,19 @@ if(BUILD_SWIG_PERL5) swig_link_libraries(pllammps PRIVATE lammps ${PERL_LIBRARY}) endif() -if(BUILD_SWIG_LUA) - set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME lualammps) - swig_add_library(lualammps TYPE MODULE LANGUAGE lua SOURCES lammps.i) - find_package(Lua REQUIRED) - target_include_directories(lualammps PRIVATE ${LUA_INCLUDE_PATH}) - swig_link_libraries(lualammps PRIVATE lammps ${LUA_LIBRARY}) +if(BUILD_SWIG_PYTHON) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME pylammps) + swig_add_library(pylammps TYPE MODULE LANGUAGE python SOURCES lammps.i) + find_package(Python REQUIRED COMPONENTS Development) + swig_link_libraries(pylammps PRIVATE lammps Python::Python) +endif() + +if(BUILD_SWIG_RUBY) + set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME rubylammps) + swig_add_library(rubylammps TYPE MODULE LANGUAGE ruby SOURCES lammps.i) + find_package(Ruby REQUIRED) + target_include_directories(rubylammps PRIVATE ${RUBY_INCLUDE_DIRS}) + swig_link_libraries(rubylammps PRIVATE lammps ${RUBY_LIBRARY}) endif() if(BUILD_SWIG_TCL) diff --git a/swig/run_ruby_example.sh b/swig/run_ruby_example.sh new file mode 100755 index 0000000000..b5d3051be6 --- /dev/null +++ b/swig/run_ruby_example.sh @@ -0,0 +1,21 @@ +#!/bin/sh + +cat > example.rb < Date: Sun, 18 Oct 2020 08:11:20 -0400 Subject: [PATCH 09/37] copy example run scripts to the swig folder in the build tree --- swig/CMakeLists.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/swig/CMakeLists.txt b/swig/CMakeLists.txt index f9b9fc6ce4..86020cc3c2 100644 --- a/swig/CMakeLists.txt +++ b/swig/CMakeLists.txt @@ -29,6 +29,7 @@ if(BUILD_SWIG_JAVA) find_package(JNI REQUIRED) target_include_directories(javalammps PRIVATE ${JNI_INCLUDE_DIRS}) swig_link_libraries(javalammps PRIVATE lammps ${JNI_LIBRARIES}) + configure_file(run_java_example.sh run_java_example.sh COPYONLY) endif() if(BUILD_SWIG_LUA) @@ -37,6 +38,7 @@ if(BUILD_SWIG_LUA) find_package(Lua REQUIRED) target_include_directories(lualammps PRIVATE ${LUA_INCLUDE_PATH}) swig_link_libraries(lualammps PRIVATE lammps ${LUA_LIBRARY}) + configure_file(run_lua_example.sh run_lua_example.sh COPYONLY) endif() if(BUILD_SWIG_PERL5) @@ -46,6 +48,7 @@ if(BUILD_SWIG_PERL5) target_compile_definitions(pllammps PRIVATE _LARGEFILE64_SOURCE) target_include_directories(pllammps PRIVATE ${PERL_INCLUDE_PATH}) swig_link_libraries(pllammps PRIVATE lammps ${PERL_LIBRARY}) + configure_file(run_perl_example.sh run_perl_example.sh COPYONLY) endif() if(BUILD_SWIG_PYTHON) @@ -53,6 +56,7 @@ if(BUILD_SWIG_PYTHON) swig_add_library(pylammps TYPE MODULE LANGUAGE python SOURCES lammps.i) find_package(Python REQUIRED COMPONENTS Development) swig_link_libraries(pylammps PRIVATE lammps Python::Python) + configure_file(run_python_example.sh run_python_example.sh COPYONLY) endif() if(BUILD_SWIG_RUBY) @@ -61,6 +65,7 @@ if(BUILD_SWIG_RUBY) find_package(Ruby REQUIRED) target_include_directories(rubylammps PRIVATE ${RUBY_INCLUDE_DIRS}) swig_link_libraries(rubylammps PRIVATE lammps ${RUBY_LIBRARY}) + configure_file(run_ruby_example.sh run_ruby_example.sh COPYONLY) endif() if(BUILD_SWIG_TCL) @@ -69,5 +74,6 @@ if(BUILD_SWIG_TCL) find_package(TCL REQUIRED) target_include_directories(tcllammps PRIVATE ${TCL_INCLUDE_PATH}) swig_link_libraries(tcllammps PRIVATE lammps ${TCL_LIBRARY}) + configure_file(run_tcl_example.sh run_tcl_example.sh COPYONLY) endif() From 0685df3e6473f33b4d7fc50d2e66e7f17f4db019 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 08:12:08 -0400 Subject: [PATCH 10/37] add "clean-all" target to remove all content generated by build or example run scripts --- swig/CMakeLists.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/swig/CMakeLists.txt b/swig/CMakeLists.txt index 86020cc3c2..3e642cfbb1 100644 --- a/swig/CMakeLists.txt +++ b/swig/CMakeLists.txt @@ -23,6 +23,11 @@ option(BUILD_SWIG_PYTHON "Build Python wrapper with SWIG" OFF) option(BUILD_SWIG_RUBY "Build Ruby wrapper with SWIG" OFF) option(BUILD_SWIG_TCL "Build Tcl wrapper with SWIG" OFF) +add_custom_target(clean-all + COMMAND ${CMAKE_COMMAND} --build . --target clean + COMMAND ${CMAKE_COMMAND} -E remove example.* *.class *.java *.pm log.lammps + COMMAND ${CMAKE_COMMAND} -E remove_directory __pycache__) + if(BUILD_SWIG_JAVA) set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME javalammps) swig_add_library(javalammps TYPE MODULE LANGUAGE java SOURCES lammps.i) From 0f71c02059153007ebdfbe8096eaedd40ef31eef Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 08:12:29 -0400 Subject: [PATCH 11/37] suppress developer warnings --- swig/CMakeLists.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/swig/CMakeLists.txt b/swig/CMakeLists.txt index 3e642cfbb1..1dd682794d 100644 --- a/swig/CMakeLists.txt +++ b/swig/CMakeLists.txt @@ -1,6 +1,6 @@ -# CMake configuration for generating script language interfaces with swig +# CMake configuration for generating script language interfaces with SWIG -# set minimum CMake version required and switch to new policies +# set minimum CMake version required and switch to new policies for SWIG cmake_minimum_required(VERSION 3.14) if(POLICY CMP0078) cmake_policy(SET CMP0078 NEW) @@ -9,6 +9,10 @@ if(POLICY CMP0086) cmake_policy(SET CMP0086 NEW) endif() +# some of the find_package() scripts trigger developer warnings +# even though they are bundled with CMake; Suppress them +set(CMAKE_SUPPRESS_DEVELOPER_WARNINGS TRUE) + if(NOT BUILD_SHARED_LIBS) error(FATAL_ERROR "Option BUILD_SHARED_LIBS must be enabled to use SWIG wrappers") endif() From eab5d68a09275e526d26e63b3fd6113878d26048 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 08:19:20 -0400 Subject: [PATCH 12/37] move SWIG support to tools/swig folder --- cmake/CMakeLists.txt | 2 +- tools/README | 1 + {swig => tools/swig}/CMakeLists.txt | 0 {swig => tools/swig}/lammps.i | 0 {swig => tools/swig}/run_java_example.sh | 0 {swig => tools/swig}/run_lua_example.sh | 0 {swig => tools/swig}/run_perl_example.sh | 0 {swig => tools/swig}/run_python_example.sh | 0 {swig => tools/swig}/run_ruby_example.sh | 0 {swig => tools/swig}/run_tcl_example.sh | 0 10 files changed, 2 insertions(+), 1 deletion(-) rename {swig => tools/swig}/CMakeLists.txt (100%) rename {swig => tools/swig}/lammps.i (100%) rename {swig => tools/swig}/run_java_example.sh (100%) rename {swig => tools/swig}/run_lua_example.sh (100%) rename {swig => tools/swig}/run_perl_example.sh (100%) rename {swig => tools/swig}/run_python_example.sh (100%) rename {swig => tools/swig}/run_ruby_example.sh (100%) rename {swig => tools/swig}/run_tcl_example.sh (100%) diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index e58bb73029..981dfb17a3 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -382,7 +382,7 @@ endforeach() # optionally enable building script wrappers using swig option(WITH_SWIG "Build scripting language wrappers with SWIG" OFF) if(WITH_SWIG) - get_filename_component(LAMMPS_SWIG_DIR ${LAMMPS_SOURCE_DIR}/../swig ABSOLUTE) + get_filename_component(LAMMPS_SWIG_DIR ${LAMMPS_SOURCE_DIR}/../tools/swig ABSOLUTE) get_filename_component(LAMMPS_SWIG_BIN ${CMAKE_BINARY_DIR}/swig ABSOLUTE) add_subdirectory(${LAMMPS_SWIG_DIR} ${LAMMPS_SWIG_BIN}) endif() diff --git a/tools/README b/tools/README index e98e552b61..af9a699145 100644 --- a/tools/README +++ b/tools/README @@ -46,6 +46,7 @@ replica tool to reorder LAMMPS replica trajectories according to singularity Singularity container descriptions suitable for LAMMPS development smd convert Smooth Mach Dynamics triangles to VTK spin perform a cubic polynomial interpolation of a GNEB MEP +swig SWIG generated script language wrappers for the LAMMPS C library interface valgrind suppression files for use with valgrind's memcheck tool vim add-ons to VIM editor for editing LAMMPS input scripts xmgrace a collection of scripts to generate xmgrace plots diff --git a/swig/CMakeLists.txt b/tools/swig/CMakeLists.txt similarity index 100% rename from swig/CMakeLists.txt rename to tools/swig/CMakeLists.txt diff --git a/swig/lammps.i b/tools/swig/lammps.i similarity index 100% rename from swig/lammps.i rename to tools/swig/lammps.i diff --git a/swig/run_java_example.sh b/tools/swig/run_java_example.sh similarity index 100% rename from swig/run_java_example.sh rename to tools/swig/run_java_example.sh diff --git a/swig/run_lua_example.sh b/tools/swig/run_lua_example.sh similarity index 100% rename from swig/run_lua_example.sh rename to tools/swig/run_lua_example.sh diff --git a/swig/run_perl_example.sh b/tools/swig/run_perl_example.sh similarity index 100% rename from swig/run_perl_example.sh rename to tools/swig/run_perl_example.sh diff --git a/swig/run_python_example.sh b/tools/swig/run_python_example.sh similarity index 100% rename from swig/run_python_example.sh rename to tools/swig/run_python_example.sh diff --git a/swig/run_ruby_example.sh b/tools/swig/run_ruby_example.sh similarity index 100% rename from swig/run_ruby_example.sh rename to tools/swig/run_ruby_example.sh diff --git a/swig/run_tcl_example.sh b/tools/swig/run_tcl_example.sh similarity index 100% rename from swig/run_tcl_example.sh rename to tools/swig/run_tcl_example.sh From 97767d0a3c8a08970efa996d9427505dd86fb594 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 18 Oct 2020 12:40:17 -0400 Subject: [PATCH 13/37] add some support functions to cast pointers and get values from pointers --- tools/swig/lammps.i | 11 ++++++++++- tools/swig/run_lua_example.sh | 3 ++- tools/swig/run_perl_example.sh | 1 + tools/swig/run_python_example.sh | 1 + tools/swig/run_tcl_example.sh | 2 ++ 5 files changed, 16 insertions(+), 2 deletions(-) diff --git a/tools/swig/lammps.i b/tools/swig/lammps.i index c4b79fee62..2e0659a00d 100644 --- a/tools/swig/lammps.i +++ b/tools/swig/lammps.i @@ -1,5 +1,14 @@ -%{ +%include "cpointer.i" +%include "carrays.i" +%include "cdata.i" +%array_functions(char, charp); +%pointer_functions(int, intp); +%pointer_functions(double, doublep); +%pointer_cast(void *, int *, void_to_int); +%pointer_cast(void *, double *, void_to_double); + +%{ enum _LMP_DATATYPE_CONST { LAMMPS_INT = 0, /*!< 32-bit integer (array) */ LAMMPS_INT_2D = 1, /*!< two-dimensional 32-bit integer array */ diff --git a/tools/swig/run_lua_example.sh b/tools/swig/run_lua_example.sh index 4dc7bad2f8..4cfd7ec586 100755 --- a/tools/swig/run_lua_example.sh +++ b/tools/swig/run_lua_example.sh @@ -14,7 +14,8 @@ lualammps.lammps_command(lmp, "create_atoms 1 box") print("LAMMPS version ", ver) print("Number of created atoms: ", lualammps.lammps_get_natoms(lmp)) -lualammps.lammps_close(lmp ) +print("Current size of timestep: ", lualammps.doublep_value(lualammps.void_to_double(lualammps.lammps_extract_global(lmp,"dt")))) +lualammps.lammps_close(lmp) EOF lua example.lua diff --git a/tools/swig/run_perl_example.sh b/tools/swig/run_perl_example.sh index 2714bcba6f..689fa0e10a 100755 --- a/tools/swig/run_perl_example.sh +++ b/tools/swig/run_perl_example.sh @@ -14,6 +14,7 @@ pllammps::lammps_command(\$lmp, "create_atoms 1 box"); print("LAMMPS version ",\$ver,"\n"); print("Number of created atoms: ", pllammps::lammps_get_natoms(\$lmp), "\n"); +print("Current size of timestep: ", pllammps::doublep_value(pllammps::void_to_double(pllammps::lammps_extract_global(\$lmp,"dt"))), "\n"); pllammps::lammps_close(\$lmp) EOF diff --git a/tools/swig/run_python_example.sh b/tools/swig/run_python_example.sh index a09f2f119e..7b7f97c99e 100755 --- a/tools/swig/run_python_example.sh +++ b/tools/swig/run_python_example.sh @@ -13,6 +13,7 @@ lammps_command(lmp, "create_atoms 1 box") print("LAMMPS version ",ver) print("Number of created atoms: %g" % lammps_get_natoms(lmp)) +print("Current size of timestep: %g" % doublep_value(void_to_double(lammps_extract_global(lmp,'dt')))) lammps_close(lmp) EOF diff --git a/tools/swig/run_tcl_example.sh b/tools/swig/run_tcl_example.sh index 00ae2e7579..5f9a3bc77f 100755 --- a/tools/swig/run_tcl_example.sh +++ b/tools/swig/run_tcl_example.sh @@ -12,8 +12,10 @@ lammps_command \$lmp "region box block -5 5 -5 5 -5 5" lammps_command \$lmp "create_box 1 box" lammps_command \$lmp "create_atoms 1 box" +set dt [doublep_value [void_to_double [lammps_extract_global \$lmp dt]]] puts "LAMMPS version \$ver" puts [format "Number of created atoms: %g" [lammps_get_natoms \$lmp]] +puts "Current size of timestep: \$dt" lammps_close \$lmp EOF From f74203fb330468c2557f20df51ec3515553fd418 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 19 Oct 2020 01:00:02 -0400 Subject: [PATCH 14/37] start adding documentation about SWIG wrapping to the manual --- doc/src/Tools.rst | 112 ++++++++++++++++++++ doc/utils/sphinx-config/false_positives.txt | 2 + 2 files changed, 114 insertions(+) diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 8c68ad4c73..7a9429339c 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -94,6 +94,7 @@ Miscellaneous tools * :ref:`kate ` * :ref:`LAMMPS shell ` * :ref:`singularity ` + * :ref:`SWIG ` * :ref:`vim ` ---------- @@ -874,6 +875,117 @@ For more details please see the README.md file in that folder. ---------- +.. _swig: + +SWIG wrapper generation tool +---------------------------------------- + +The `SWIG tool `_ provides an automated way to build +wrappers around a :doc:`C language library interface ` so that +the compiled language code can be called from a scripted programming +language or similar like: C#/Mono, Lua, Java, JavaScript, Perl, Python, +R, Ruby, Tcl, and more. + +What is included +^^^^^^^^^^^^^^^^ + +We provide here an "interface file", ``lammps.i`` file that has the +content of the ``library.h`` adapted so SWIG can process it. That will +create wrappers for all the functions that are present in the LAMMPS C +library interface. Please note that not all kinds of C functions will +work natively in script languages. Some additional support functions to +provide storage as compatible pointers, access data returned from a +pointer or convert pointers from a void type to some other are +required. Some suitable definitions are included. In the case of +Python, a :doc:`ctypes based lammps module ` already +exists, that is object oriented while SWIG will generate a 1:1 +translation of the functions in the interface file. + +Building the wrapper +^^^^^^^^^^^^^^^^^^^^ + +When using CMake, the build steps for building a wrapper +module are integrated for the languages: Java, Lua, +Perl5, Python, Ruby, and Tcl. These require that the +LAMMPS library is build as a shared library and all +necessary development headers and libraries are present. + +.. code-block:: bash + + -D WITH_SWIG=on # to enable building any SWIG wrapper + -D BUILD_SWIG_JAVA=on # to enable building the Java wrapper + -D BUILD_SWIG_LUA=on # to enable building the Lua wrapper + -D BUILD_SWIG_PERL5=on # to enable building the Perl 5.x wrapper + -D BUILD_SWIG_PYTHON=on # to enable building the Python wrapper + -D BUILD_SWIG_RUBY=on # to enable building the Ruby wrapper + -D BUILD_SWIG_TCL=on # to enable building the Tcl wrapper + + +Manual building allows a little more flexibility. E.g. +with Tcl one can build and use a dynamically loaded object with: + +.. code-block:: bash + + $ swig -tcl -module tcllammps lammps.i + $ gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \ + lammps_wrap.c -L ../src/ -llammps + $ tclsh + +Or one can build a new extended Tcl shell command with the wrapped +functions included with: + +.. code-block:: bash + + $ swig -tcl -module tcllammps lammps.i + $ gcc -o tcllammps tclmain.c lammps_wrap.c -Xlinker -export-dynamic \ + -DHAVE_CONFIG_H $(pkgconf --cflags tcl) \ + $(pkgconf --libs tcl) + +With the file ``tclmain.c`` containing: + +.. code-block:: c + + #include + int AppInit(Tcl_Interp *interp) { + if (Tcl_Init(interp) == TCL_ERROR) return TCL_ERROR; + Tcl_SetVar(interp,"tcl_rcFileName","~/.wishrc",TCL_GLOBAL_ONLY); + return TCL_OK; + } + + int main(int argc, char *argv[]) { + Tcl_Main(argc, argv, AppInit); + return 0; + } + + +Utility functions +^^^^^^^^^^^^^^^^^ + +Definitions for several utility functions required to manage and access +data passed or returned as pointers are included. + +Usage example Tcl +^^^^^^^^^^^^^^^^^ + +.. code-block:: tcl + + % load ./tcllammps.so + % set lmp [lammps_open_no_mpi 0 NULL NULL] + % lammps_command $lmp "units real" + % lammps_command $lmp "lattice fcc 2.5" + % lammps_command $lmp "region box block -5 5 -5 5 -5 5" + % lammps_command $lmp "create_box 1 box" + % lammps_command $lmp "create_atoms 1 box" + % + % set dt [doublep_value [voidp_to_doublep [lammps_extract_global $lmp dt]]] + % puts "LAMMPS version $ver" + % puts [format "Number of created atoms: %g" [lammps_get_natoms $lmp]] + % puts "Current size of timestep: $dt" + % puts "LAMMPS version: [lammps_version $lmp]" + % lammps_close $lmp + +---------- + .. _vim: vim tool diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 2c17f93df4..3ef0b904eb 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -1713,6 +1713,7 @@ lsfftw ltbbmalloc lubricateU lucy +Lua Luding Lussetti Lustig @@ -3035,6 +3036,7 @@ taubi tb tchain Tchain +Tcl Tcom tcsh tdamp From 5a70ee8a40bfb7c6be943ac7aa535af61c1e75bf Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 19 Oct 2020 01:00:31 -0400 Subject: [PATCH 15/37] make names of custom data functions consistent --- tools/swig/lammps.i | 17 ++++++++++++----- tools/swig/run_lua_example.sh | 2 +- tools/swig/run_perl_example.sh | 2 +- tools/swig/run_python_example.sh | 2 +- tools/swig/run_ruby_example.sh | 1 + tools/swig/run_tcl_example.sh | 2 +- 6 files changed, 17 insertions(+), 9 deletions(-) diff --git a/tools/swig/lammps.i b/tools/swig/lammps.i index 2e0659a00d..47c0e45e19 100644 --- a/tools/swig/lammps.i +++ b/tools/swig/lammps.i @@ -2,11 +2,18 @@ %include "carrays.i" %include "cdata.i" -%array_functions(char, charp); -%pointer_functions(int, intp); -%pointer_functions(double, doublep); -%pointer_cast(void *, int *, void_to_int); -%pointer_cast(void *, double *, void_to_double); +%array_functions(char, char_p); + +%pointer_functions(int, int_p); +%pointer_functions(int, int64_p); +%pointer_functions(double, double_p); + +%pointer_cast(void *, int *, void_p_to_int_p); +%pointer_cast(void *, int **, void_p_to_int2d_p); +%pointer_cast(void *, int *, void_p_to_int64_p); +%pointer_cast(void *, int **, void_p_to_int64_2d_p); +%pointer_cast(void *, double *, void_p_to_double_p); +%pointer_cast(void *, double **, void_p_to_double_2d_p); %{ enum _LMP_DATATYPE_CONST { diff --git a/tools/swig/run_lua_example.sh b/tools/swig/run_lua_example.sh index 4cfd7ec586..0e2e74039b 100755 --- a/tools/swig/run_lua_example.sh +++ b/tools/swig/run_lua_example.sh @@ -14,7 +14,7 @@ lualammps.lammps_command(lmp, "create_atoms 1 box") print("LAMMPS version ", ver) print("Number of created atoms: ", lualammps.lammps_get_natoms(lmp)) -print("Current size of timestep: ", lualammps.doublep_value(lualammps.void_to_double(lualammps.lammps_extract_global(lmp,"dt")))) +print("Current size of timestep: ", lualammps.double_p_value(lualammps.void_p_to_double_p(lualammps.lammps_extract_global(lmp,"dt")))) lualammps.lammps_close(lmp) EOF diff --git a/tools/swig/run_perl_example.sh b/tools/swig/run_perl_example.sh index 689fa0e10a..54c7b5b326 100755 --- a/tools/swig/run_perl_example.sh +++ b/tools/swig/run_perl_example.sh @@ -14,7 +14,7 @@ pllammps::lammps_command(\$lmp, "create_atoms 1 box"); print("LAMMPS version ",\$ver,"\n"); print("Number of created atoms: ", pllammps::lammps_get_natoms(\$lmp), "\n"); -print("Current size of timestep: ", pllammps::doublep_value(pllammps::void_to_double(pllammps::lammps_extract_global(\$lmp,"dt"))), "\n"); +print("Current size of timestep: ", pllammps::double_p_value(pllammps::void_p_to_double_p(pllammps::lammps_extract_global(\$lmp,"dt"))), "\n"); pllammps::lammps_close(\$lmp) EOF diff --git a/tools/swig/run_python_example.sh b/tools/swig/run_python_example.sh index 7b7f97c99e..5ca5bca1cb 100755 --- a/tools/swig/run_python_example.sh +++ b/tools/swig/run_python_example.sh @@ -13,7 +13,7 @@ lammps_command(lmp, "create_atoms 1 box") print("LAMMPS version ",ver) print("Number of created atoms: %g" % lammps_get_natoms(lmp)) -print("Current size of timestep: %g" % doublep_value(void_to_double(lammps_extract_global(lmp,'dt')))) +print("Current size of timestep: %g" % double_p_value(void_p_to_double_p(lammps_extract_global(lmp,'dt')))) lammps_close(lmp) EOF diff --git a/tools/swig/run_ruby_example.sh b/tools/swig/run_ruby_example.sh index b5d3051be6..ff946ba501 100755 --- a/tools/swig/run_ruby_example.sh +++ b/tools/swig/run_ruby_example.sh @@ -14,6 +14,7 @@ Rubylammps.lammps_command(lmp, "create_atoms 1 box") print("LAMMPS version ", ver, "\n") print("Number of created atoms: ", Rubylammps.lammps_get_natoms(lmp), "\n") +print("Current size of timestep: ", Rubylammps.double_p_value(Rubylammps.void_p_to_double_p(Rubylammps.lammps_extract_global(lmp,"dt"))), "\n") Rubylammps.lammps_close(lmp) EOF diff --git a/tools/swig/run_tcl_example.sh b/tools/swig/run_tcl_example.sh index 5f9a3bc77f..363391e5a7 100755 --- a/tools/swig/run_tcl_example.sh +++ b/tools/swig/run_tcl_example.sh @@ -12,7 +12,7 @@ lammps_command \$lmp "region box block -5 5 -5 5 -5 5" lammps_command \$lmp "create_box 1 box" lammps_command \$lmp "create_atoms 1 box" -set dt [doublep_value [void_to_double [lammps_extract_global \$lmp dt]]] +set dt [double_p_value [void_p_to_double_p [lammps_extract_global \$lmp dt]]] puts "LAMMPS version \$ver" puts [format "Number of created atoms: %g" [lammps_get_natoms \$lmp]] puts "Current size of timestep: \$dt" From 8c5ac3d49c04e3a316b4d73fea9d9a50cec0ffb5 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 19 Oct 2020 01:01:06 -0400 Subject: [PATCH 16/37] add README file to SWIG tool --- tools/swig/README | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 tools/swig/README diff --git a/tools/swig/README b/tools/swig/README new file mode 100644 index 0000000000..1f30ecdc7e --- /dev/null +++ b/tools/swig/README @@ -0,0 +1,50 @@ +SWIG generated script library wrappers + +The "swig" tool and library ( http://swig.org ) +offers an automated way to incorporate compiled code +modules into scripting languages. It processes the +function prototypes in C and generates wrappers for +a variety of scripting languages from it. + +We provide here an "interface file", "lammps.i" file +that has the content of the "library.h" adapted so SWIG +can process it. Please note that not all kinds of C +interfaces can be automatically translated, so you +would have to add custom functions. In the case of +python, a ctypes based lammps module already exists, +that is object oriented while SWIG will generate a 1:1 +translation of the functions in the interface file. + +When using CMake, the build steps for building a wrapper +module are integrated for the languages: java, lua, +perl5, python, ruby, and tcl. These require that the +LAMMPS library is build as a shared library and all +necessary development headers and libraries are present. + +Manual building allows a little more flexibility. E.g. +with Tcl one can build and use a dynamically loaded object with: + +$ swig -tcl -module tcllammps lammps.i +$ gcc -fPIC -shared $(pkgconfig --cflags tcl) -o tcllammps.so lammps_wrap.c -L ../src/ -llammps +$ tclsh +% load ./tcllammps.so +% set lmp [lammps_open_no_mpi 0 NULL NULL] +% puts "LAMMPS version: [lammps_version $lmp] +% lammps_close $lmp + +Equivalently with Python the manual steps are: + +$ swig -python -module pylammps lammps.i +$ gcc -fPIC -shared $(pkgconfig --cflags python) -o _pylammps.so lammps_wrap.c -L ../src/ -llammps +$ python +% from pylammps import * + + + +You may need to set or extend the LD_LIBRARY_PATH environment +variable to include the folder where the LAMMPS shared library +file is located, if it is not found automatically. + + +For details on how to build the wrappers for other +individual http://swig.org/doc.html From c891b9dca6047e5e908e7a67390727bb3bb7ee4f Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 19 Oct 2020 01:01:27 -0400 Subject: [PATCH 17/37] add simple main function for building a static Tcl shell executable --- tools/swig/tclmain.c | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 tools/swig/tclmain.c diff --git a/tools/swig/tclmain.c b/tools/swig/tclmain.c new file mode 100644 index 0000000000..2d3335a9a7 --- /dev/null +++ b/tools/swig/tclmain.c @@ -0,0 +1,11 @@ +#include +int AppInit(Tcl_Interp *interp) { + if (Tcl_Init(interp) == TCL_ERROR) return TCL_ERROR; + Tcl_SetVar(interp,"tcl_rcFileName","~/.wishrc",TCL_GLOBAL_ONLY); + return TCL_OK; +} + +int main(int argc, char *argv[]) { + Tcl_Main(argc, argv, AppInit); + return 0; +} From 7297ed31159e79ba5893c1d88085ed897e26d768 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 19 Oct 2020 21:56:40 -0400 Subject: [PATCH 18/37] apply stack-protector fix required by newer versions of MinGW, e.g. on Fedora 33 --- cmake/presets/mingw-cross.cmake | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cmake/presets/mingw-cross.cmake b/cmake/presets/mingw-cross.cmake index d187586df8..32b17d43c2 100644 --- a/cmake/presets/mingw-cross.cmake +++ b/cmake/presets/mingw-cross.cmake @@ -23,7 +23,7 @@ set(DOWNLOAD_VORO ON CACHE BOOL "" FORCE) set(DOWNLOAD_EIGEN3 ON CACHE BOOL "" FORCE) set(LAMMPS_MEMALIGN "0" CACHE STRING "" FORCE) set(CMAKE_TUNE_FLAGS "-Wno-missing-include-dirs" CACHE STRING "" FORCE) -set(CMAKE_EXE_LINKER_FLAGS "-Wl,--enable-stdcall-fixup" CACHE STRING "" FORCE) -set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--enable-stdcall-fixup" CACHE STRING "" FORCE) +set(CMAKE_EXE_LINKER_FLAGS "-Wl,--enable-stdcall-fixup,--as-needed,-lssp" CACHE STRING "" FORCE) +set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--enable-stdcall-fixup,--as-needed,-lssp" CACHE STRING "" FORCE) set(BUILD_TOOLS ON CACHE BOOL "" FORCE) set(CMAKE_INSTALL_PREFIX "${CMAKE_CURRENT_BINARY_DIR}/lammps-installer") From 6c826823fe1a8587ab224c418f6d38dfe04e422d Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 11:42:23 -0400 Subject: [PATCH 19/37] update SWIG support readme --- tools/swig/README | 71 +++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 43 deletions(-) diff --git a/tools/swig/README b/tools/swig/README index 1f30ecdc7e..ef53e38081 100644 --- a/tools/swig/README +++ b/tools/swig/README @@ -1,50 +1,35 @@ SWIG generated script library wrappers -The "swig" tool and library ( http://swig.org ) -offers an automated way to incorporate compiled code -modules into scripting languages. It processes the -function prototypes in C and generates wrappers for -a variety of scripting languages from it. +The SWIG tool ( http://swig.org ) offers an automated way to incorporate +compiled code modules into scripting languages. It processes the +function prototypes in C and generates wrappers for a wide variety of +scripting languages from it. -We provide here an "interface file", "lammps.i" file -that has the content of the "library.h" adapted so SWIG -can process it. Please note that not all kinds of C -interfaces can be automatically translated, so you -would have to add custom functions. In the case of -python, a ctypes based lammps module already exists, -that is object oriented while SWIG will generate a 1:1 +We provide here an "interface file", "lammps.i", that has the content of +the "library.h" adapted so SWIG can process it. Please note that not +all kinds of C functions can be automatically translated, so you would +have to add custom functions to be able to utilize them. A few functions +for converting pointers and accessing arrays are predefined. We provide +the files here on an "as is" basis to help people getting started, but +not as a fully tested and supported feature of the distribution. Any +contributions to complete this are, of course, welcome. + +In the case of Python, a fully supported and complete wrapper already +exists in the "lammps" module in the "python" folder. This wrapper is +based on Ctypes and is object oriented while SWIG will generate a 1:1 translation of the functions in the interface file. -When using CMake, the build steps for building a wrapper -module are integrated for the languages: java, lua, -perl5, python, ruby, and tcl. These require that the -LAMMPS library is build as a shared library and all -necessary development headers and libraries are present. +When using the CMake build system, steps for building wrapper modules +are integrated for the languages: Java, Lua, Perl5, Python, Ruby, and +Tcl and can be selected during the configuration step. These require +that the LAMMPS library is build as a shared library and all necessary +development headers and libraries of the selected script languages are +present. To demonstrate the resulting wrappers, several example shell +scripts (run_*_example.sh) are provided that contain commands to create +an example script file and to demonstrate the use of the wrapped library +functions in the respective programming language. -Manual building allows a little more flexibility. E.g. -with Tcl one can build and use a dynamically loaded object with: +For details on how to build and adjust wrappers for individual +languages please refer to the SWIG documentation at http://swig.org/doc.html -$ swig -tcl -module tcllammps lammps.i -$ gcc -fPIC -shared $(pkgconfig --cflags tcl) -o tcllammps.so lammps_wrap.c -L ../src/ -llammps -$ tclsh -% load ./tcllammps.so -% set lmp [lammps_open_no_mpi 0 NULL NULL] -% puts "LAMMPS version: [lammps_version $lmp] -% lammps_close $lmp - -Equivalently with Python the manual steps are: - -$ swig -python -module pylammps lammps.i -$ gcc -fPIC -shared $(pkgconfig --cflags python) -o _pylammps.so lammps_wrap.c -L ../src/ -llammps -$ python -% from pylammps import * - - - -You may need to set or extend the LD_LIBRARY_PATH environment -variable to include the folder where the LAMMPS shared library -file is located, if it is not found automatically. - - -For details on how to build the wrappers for other -individual http://swig.org/doc.html +This functionality has been tested on Fedora 32 with SWIG 4.0.1. From 3ad397dd60c7a38670fcb23b83f4e2806f1a5a36 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 11:43:03 -0400 Subject: [PATCH 20/37] implement some more data access functions and handle passing string buffers --- tools/swig/lammps.i | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/tools/swig/lammps.i b/tools/swig/lammps.i index 47c0e45e19..e28240b8ef 100644 --- a/tools/swig/lammps.i +++ b/tools/swig/lammps.i @@ -1,13 +1,16 @@ %include "cpointer.i" %include "carrays.i" %include "cdata.i" - -%array_functions(char, char_p); +%include "cstring.i" %pointer_functions(int, int_p); %pointer_functions(int, int64_p); %pointer_functions(double, double_p); +%array_functions(char, char_1d); +%array_functions(int, int_1d); +%array_functions(double, double_1d); + %pointer_cast(void *, int *, void_p_to_int_p); %pointer_cast(void *, int **, void_p_to_int2d_p); %pointer_cast(void *, int *, void_p_to_int64_p); @@ -15,7 +18,10 @@ %pointer_cast(void *, double *, void_p_to_double_p); %pointer_cast(void *, double **, void_p_to_double_2d_p); +%cstring_output_maxsize(char *buffer, int buf_size); + %{ + enum _LMP_DATATYPE_CONST { LAMMPS_INT = 0, /*!< 32-bit integer (array) */ LAMMPS_INT_2D = 1, /*!< two-dimensional 32-bit integer array */ @@ -107,10 +113,10 @@ extern int lammps_config_has_ffmpeg_support(); extern int lammps_config_has_exceptions(); extern int lammps_has_style(void *, const char *, const char *); extern int lammps_style_count(void *, const char *); -extern int lammps_style_name(void *, const char *, int, char *, int); +extern int lammps_style_name(void *, const char *, int, char *buffer, int buf_size); extern int lammps_has_id(void *, const char *, const char *); extern int lammps_id_count(void *, const char *); -extern int lammps_id_name(void *, const char *, int, char *, int); +extern int lammps_id_name(void *, const char *, int, char *buffer, int buf_size); extern int lammps_find_pair_neighlist(void*, char *, int, int, int); extern int lammps_find_fix_neighlist(void*, char *, int); extern int lammps_find_compute_neighlist(void*, char *, int); @@ -133,7 +139,6 @@ extern int lammps_has_error(void *handle); extern int lammps_get_last_error_message(void *handle, char *buffer, int buf_size); %} - enum _LMP_DATATYPE_CONST { LAMMPS_INT = 0, /*!< 32-bit integer (array) */ LAMMPS_INT_2D = 1, /*!< two-dimensional 32-bit integer array */ @@ -223,10 +228,10 @@ extern int lammps_config_has_ffmpeg_support(); extern int lammps_config_has_exceptions(); extern int lammps_has_style(void *, const char *, const char *); extern int lammps_style_count(void *, const char *); -extern int lammps_style_name(void *, const char *, int, char *, int); +extern int lammps_style_name(void *, const char *, int, char *buffer, int buf_size); extern int lammps_has_id(void *, const char *, const char *); extern int lammps_id_count(void *, const char *); -extern int lammps_id_name(void *, const char *, int, char *, int); +extern int lammps_id_name(void *, const char *, int, char *buffer, int buf_size); extern int lammps_find_pair_neighlist(void*, char *, int, int, int); extern int lammps_find_fix_neighlist(void*, char *, int); extern int lammps_find_compute_neighlist(void*, char *, int); From bc1d325930d046def177dcc15f440c55fe692635 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 15:57:02 -0400 Subject: [PATCH 21/37] dmonstrate data access functions --- tools/swig/run_java_example.sh | 25 ++++++++++++++++ tools/swig/run_lua_example.sh | 38 ++++++++++++++++++++++++ tools/swig/run_perl_example.sh | 41 +++++++++++++++++++++++-- tools/swig/run_python_example.sh | 33 +++++++++++++++++++++ tools/swig/run_ruby_example.sh | 51 +++++++++++++++++++++++++++----- tools/swig/run_tcl_example.sh | 33 +++++++++++++++++++++ 6 files changed, 210 insertions(+), 11 deletions(-) diff --git a/tools/swig/run_java_example.sh b/tools/swig/run_java_example.sh index a0d57be7ff..422481fa5f 100755 --- a/tools/swig/run_java_example.sh +++ b/tools/swig/run_java_example.sh @@ -10,12 +10,37 @@ public class example { SWIGTYPE_p_void lmp = javalammps.lammps_open_no_mpi(0, null, null); int ver = javalammps.lammps_version(lmp); + int npair_styles = javalammps.lammps_style_count(lmp, "pair"); + System.out.println("LAMMPS includes " + npair_styles + " pair styles"); + javalammps.lammps_command(lmp, "units real"); javalammps.lammps_command(lmp, "lattice fcc 2.5"); javalammps.lammps_command(lmp, "region box block -5 5 -5 5 -5 5"); javalammps.lammps_command(lmp, "create_box 1 box"); javalammps.lammps_command(lmp, "create_atoms 1 box"); + SWIGTYPE_p_double boxlo_p = javalammps.new_double_1d(3); + SWIGTYPE_p_double boxhi_p = javalammps.new_double_1d(3); + SWIGTYPE_p_double xy_p = javalammps.new_double_p(); + SWIGTYPE_p_double yz_p = javalammps.new_double_p(); + SWIGTYPE_p_double xz_p = javalammps.new_double_p(); + SWIGTYPE_p_int pflags_p = javalammps.new_int_1d(3); + SWIGTYPE_p_int boxflag_p = javalammps.new_int_p(); + + javalammps.lammps_extract_box(lmp, boxlo_p, boxhi_p, xy_p, yz_p, xz_p, pflags_p, boxflag_p); + System.out.println("boxlo: " + javalammps.double_1d_getitem(boxlo_p, 0) + " " + javalammps.double_1d_getitem(boxlo_p, 1) + " " + javalammps.double_1d_getitem(boxlo_p, 2)); + System.out.println("boxhi: " + javalammps.double_1d_getitem(boxhi_p, 0) + " " + javalammps.double_1d_getitem(boxhi_p, 1) + " " + javalammps.double_1d_getitem(boxhi_p, 2)); + System.out.println("xy/yz/xz: " + javalammps.double_p_value(xy_p) + " " + javalammps.double_p_value(yz_p) + " " + javalammps.double_p_value(xz_p)); + System.out.println("periodicity: " + javalammps.int_1d_getitem(pflags_p, 0) + " " + javalammps.int_1d_getitem(pflags_p, 1) + " " + javalammps.int_1d_getitem(pflags_p, 2)); + System.out.println("boxflag: " + javalammps.int_p_value(boxflag_p)); + javalammps.delete_double_1d(boxlo_p); + javalammps.delete_double_1d(boxhi_p); + javalammps.delete_int_1d(pflags_p); + javalammps.delete_double_p(xy_p); + javalammps.delete_double_p(yz_p); + javalammps.delete_double_p(xz_p); + javalammps.delete_int_p(boxflag_p); + System.out.println("LAMMPS version " + ver); System.out.println("Number of created atoms: " + javalammps.lammps_get_natoms(lmp)); javalammps.lammps_close(lmp); diff --git a/tools/swig/run_lua_example.sh b/tools/swig/run_lua_example.sh index 0e2e74039b..3bb5e36b78 100755 --- a/tools/swig/run_lua_example.sh +++ b/tools/swig/run_lua_example.sh @@ -3,15 +3,53 @@ cat > example.lua < example.pl < example.py < example.rb < example.tcl < Date: Tue, 20 Oct 2020 16:37:30 -0400 Subject: [PATCH 22/37] SWIG support documentation update --- doc/src/Tools.rst | 69 ++++++++++++++++++++++++++++++----------------- tools/swig/README | 23 ++++++++-------- 2 files changed, 56 insertions(+), 36 deletions(-) diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 8af7afd7f6..34faaad485 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -94,7 +94,7 @@ Miscellaneous tools * :ref:`kate ` * :ref:`LAMMPS shell ` * :ref:`singularity ` - * :ref:`SWIG ` + * :ref:`SWIG interface ` * :ref:`vim ` ---------- @@ -560,6 +560,8 @@ More details about this are in the `readline documentation `_ provides an automated way to build -wrappers around a :doc:`C language library interface ` so that -the compiled language code can be called from a scripted programming -language or similar like: C#/Mono, Lua, Java, JavaScript, Perl, Python, -R, Ruby, Tcl, and more. +The `SWIG tool `_ offers a mostly automated way to +incorporate compiled code modules into scripting languages. It +processes the function prototypes in C and generates wrappers for a wide +variety of scripting languages from it. Thus it can also be applied to +the :doc:`C language library interface ` of LAMMPS so that +build a wrapper that allows to call LAMMPS from programming languages +like: C#/Mono, Lua, Java, JavaScript, Perl, Python, R, Ruby, Tcl, and +more. What is included ^^^^^^^^^^^^^^^^ -We provide here an "interface file", ``lammps.i`` file that has the -content of the ``library.h`` adapted so SWIG can process it. That will +We provide here an "interface file", ``lammps.i``, that has the content +of the ``library.h`` file adapted so SWIG can process it. That will create wrappers for all the functions that are present in the LAMMPS C -library interface. Please note that not all kinds of C functions will -work natively in script languages. Some additional support functions to -provide storage as compatible pointers, access data returned from a -pointer or convert pointers from a void type to some other are -required. Some suitable definitions are included. In the case of -Python, a :doc:`ctypes based lammps module ` already -exists, that is object oriented while SWIG will generate a 1:1 -translation of the functions in the interface file. +library interface. Please note that not all kinds of C functions can be +automatically translated, so you would have to add custom functions to +be able to utilize those where the automatic translation does not work. +A few functions for converting pointers and accessing arrays are +predefined. We provide the file here on an "as is" basis to help people +getting started, but not as a fully tested and supported feature of the +LAMMPS distribution. Any contributions to complete this are, of course, +welcome. Please also note, that for the case of creating a Python wrapper, +a fully supported :doc:`Ctypes based lammps module ` +already exists. That module is designed to be object oriented while +SWIG will generate a 1:1 translation of the functions in the interface file. Building the wrapper ^^^^^^^^^^^^^^^^^^^^ @@ -959,16 +967,27 @@ With the file ``tclmain.c`` containing: return 0; } - Utility functions ^^^^^^^^^^^^^^^^^ Definitions for several utility functions required to manage and access -data passed or returned as pointers are included. - -Usage example Tcl -^^^^^^^^^^^^^^^^^ +data passed or returned as pointers are included in the ``lammps.i`` +file. So most of the functionality of the library interface should be +accessible. What works and what does not depends a bit on the +individual language for which the wrappers are built and how well SWIG +supports those. The `SWIG documentation `_ +has very detailed instructions and recommendations. +Usage examples +^^^^^^^^^^^^^^ + +The ``tools/swig`` folder has multiple shell scripts, ``run__example.sh`` +that will create a small example script and demonstrates how to load +the wrapper and run LAMMPS through it in the corresponding programming +language. + +For illustration purposes below is a part of the Tcl example script. + .. code-block:: tcl % load ./tcllammps.so diff --git a/tools/swig/README b/tools/swig/README index ef53e38081..77950bbb9f 100644 --- a/tools/swig/README +++ b/tools/swig/README @@ -1,18 +1,19 @@ SWIG generated script library wrappers -The SWIG tool ( http://swig.org ) offers an automated way to incorporate -compiled code modules into scripting languages. It processes the -function prototypes in C and generates wrappers for a wide variety of -scripting languages from it. +The SWIG tool ( http://swig.org ) offers a mostly automated way to +incorporate compiled code modules into scripting languages. It +processes the function prototypes in C and generates wrappers for a wide +variety of scripting languages from it. We provide here an "interface file", "lammps.i", that has the content of -the "library.h" adapted so SWIG can process it. Please note that not -all kinds of C functions can be automatically translated, so you would -have to add custom functions to be able to utilize them. A few functions -for converting pointers and accessing arrays are predefined. We provide -the files here on an "as is" basis to help people getting started, but -not as a fully tested and supported feature of the distribution. Any -contributions to complete this are, of course, welcome. +the "library.h" file adapted so SWIG can process it. Please note that +not all kinds of C functions can be automatically translated, so you +would have to add custom functions to be able to utilize them. A few +functions for converting pointers and accessing arrays are predefined. +We provide the files here on an "as is" basis to help people getting +started, but not as a fully tested and supported feature of the +distribution. Any contributions to complete this are, of course, +welcome. In the case of Python, a fully supported and complete wrapper already exists in the "lammps" module in the "python" folder. This wrapper is From b9a57899a657ad5b5d07266d8ac4a2363e3cbde7 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 16:46:21 -0400 Subject: [PATCH 23/37] whitespace fix --- doc/src/Tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 34faaad485..e4f2af269a 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -977,7 +977,7 @@ accessible. What works and what does not depends a bit on the individual language for which the wrappers are built and how well SWIG supports those. The `SWIG documentation `_ has very detailed instructions and recommendations. - + Usage examples ^^^^^^^^^^^^^^ From faf67662d56c4a64a9ebfb64cd91616eb932d9f2 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 16:47:56 -0400 Subject: [PATCH 24/37] fix typo --- doc/src/Tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index e4f2af269a..3e7446545b 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -982,7 +982,7 @@ Usage examples ^^^^^^^^^^^^^^ The ``tools/swig`` folder has multiple shell scripts, ``run__example.sh`` -that will create a small example script and demonstrates how to load +that will create a small example script and demonstrate how to load the wrapper and run LAMMPS through it in the corresponding programming language. From 515f1d9eadd25a4f41bf41342867cc68d9454373 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 17:38:03 -0400 Subject: [PATCH 25/37] make module search path commands consistent --- tools/swig/run_java_example.sh | 4 ++-- tools/swig/run_lua_example.sh | 2 +- tools/swig/run_perl_example.sh | 2 +- tools/swig/run_python_example.sh | 4 ++-- tools/swig/run_ruby_example.sh | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/tools/swig/run_java_example.sh b/tools/swig/run_java_example.sh index 422481fa5f..c84be3527b 100755 --- a/tools/swig/run_java_example.sh +++ b/tools/swig/run_java_example.sh @@ -48,8 +48,8 @@ public class example { } EOF -CLASSPATH=$PWD:${CLASSPATH-${PWD}} -LD_LIBRARY_PATH=$PWD:${LD_LIBARARY_PATH-${PWD}} +CLASSPATH=${PWD}:${CLASSPATH-${PWD}} +LD_LIBRARY_PATH=${PWD}:${LD_LIBARARY_PATH-${PWD}} export CLASSPATH LD_LIBRARY_PATH diff --git a/tools/swig/run_lua_example.sh b/tools/swig/run_lua_example.sh index 3bb5e36b78..2951345b94 100755 --- a/tools/swig/run_lua_example.sh +++ b/tools/swig/run_lua_example.sh @@ -18,7 +18,7 @@ print("LAMMPS includes ", npair_styles, " pair styles") -- this also does not work (see above) -- for i = 0, 10, 1 do -- res = lualammps.lammps_style_name(lmp, 'pair', i, 128) --- print("Pair style ",i, ': ', res[1]) +-- print("Pair style ",i, ': ', res[1]) -- end lualammps.lammps_command(lmp, "units real") diff --git a/tools/swig/run_perl_example.sh b/tools/swig/run_perl_example.sh index ead75cbd01..e87bc3c81f 100755 --- a/tools/swig/run_perl_example.sh +++ b/tools/swig/run_perl_example.sh @@ -53,7 +53,7 @@ print "Current size of timestep: ", pllammps::double_p_value(pllammps::void_p_to pllammps::lammps_close(\$lmp) EOF -PERL5LIB=$PWD:${PERL5LIB-PWD} +PERL5LIB=${PWD}:${PERL5LIB-${PWD}} export PERL5LIB diff --git a/tools/swig/run_python_example.sh b/tools/swig/run_python_example.sh index 97fdf8d987..1aef042e0a 100755 --- a/tools/swig/run_python_example.sh +++ b/tools/swig/run_python_example.sh @@ -50,8 +50,8 @@ print("Current size of timestep: %g" % double_p_value(void_p_to_double_p(lammps_ lammps_close(lmp) EOF -PYTHONPATH=$PWD:${PYTHON_PATH-PWD} +PYTHONPATH=${PWD}:${PYTHONPATH-${PWD}} -export PYTHON_PATH +export PYTHONPATH python example.py diff --git a/tools/swig/run_ruby_example.sh b/tools/swig/run_ruby_example.sh index aaafb62fed..48ad863138 100755 --- a/tools/swig/run_ruby_example.sh +++ b/tools/swig/run_ruby_example.sh @@ -53,5 +53,5 @@ print('Current size of timestep: ', Rubylammps.double_p_value(Rubylammps.void_p_ Rubylammps.lammps_close(lmp) EOF -export RUBYLIB=$PWD:${RUBYLIB-${PWD}} +export RUBYLIB=${PWD}:${RUBYLIB-${PWD}} ruby example.rb From 7db669df4013efb41eb455eef692982afba4d40e Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 18:29:16 -0400 Subject: [PATCH 26/37] add support to also build an extended tcl shell as opposed to dynamically loading the extension --- tools/swig/CMakeLists.txt | 4 +++ tools/swig/lammps.i | 4 +++ tools/swig/run_tcl_example.sh | 62 +++++++++++++++++++++++++++++++++++ tools/swig/tcldummy.c | 5 +++ tools/swig/tclmain.c | 11 ------- 5 files changed, 75 insertions(+), 11 deletions(-) create mode 100644 tools/swig/tcldummy.c delete mode 100644 tools/swig/tclmain.c diff --git a/tools/swig/CMakeLists.txt b/tools/swig/CMakeLists.txt index 1dd682794d..e818152c03 100644 --- a/tools/swig/CMakeLists.txt +++ b/tools/swig/CMakeLists.txt @@ -84,5 +84,9 @@ if(BUILD_SWIG_TCL) target_include_directories(tcllammps PRIVATE ${TCL_INCLUDE_PATH}) swig_link_libraries(tcllammps PRIVATE lammps ${TCL_LIBRARY}) configure_file(run_tcl_example.sh run_tcl_example.sh COPYONLY) + swig_add_library(libtcllammps TYPE STATIC LANGUAGE tcl SOURCES lammps.i) + add_executable(tcllmpsh tcldummy.c) + target_include_directories(tcllmpsh PRIVATE ${TCL_INCLUDE_PATH}) + target_link_libraries(tcllmpsh PRIVATE libtcllammps lammps ${TCL_LIBRARY}) endif() diff --git a/tools/swig/lammps.i b/tools/swig/lammps.i index e28240b8ef..9358140a08 100644 --- a/tools/swig/lammps.i +++ b/tools/swig/lammps.i @@ -3,6 +3,10 @@ %include "cdata.i" %include "cstring.i" +#ifdef SWIGTCL +%include "tclsh.i" +#endif + %pointer_functions(int, int_p); %pointer_functions(int, int64_p); %pointer_functions(double, double_p); diff --git a/tools/swig/run_tcl_example.sh b/tools/swig/run_tcl_example.sh index b3949192e6..03263ce286 100755 --- a/tools/swig/run_tcl_example.sh +++ b/tools/swig/run_tcl_example.sh @@ -53,3 +53,65 @@ lammps_close \$lmp EOF tclsh example.tcl + +# now try again with static extended shell +echo '=====================================================================' + +if [ ! -f tcllmpsh ] +then \ + echo "Need to compile 'tcllmpsh' first for this script to work" + exit 1 +fi + +cat > example.tcllmp < -int AppInit(Tcl_Interp *interp) { - if (Tcl_Init(interp) == TCL_ERROR) return TCL_ERROR; - Tcl_SetVar(interp,"tcl_rcFileName","~/.wishrc",TCL_GLOBAL_ONLY); - return TCL_OK; -} - -int main(int argc, char *argv[]) { - Tcl_Main(argc, argv, AppInit); - return 0; -} From fe7628f954db41b9a41b4d3758b55b5ddb1becc1 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 18:29:43 -0400 Subject: [PATCH 27/37] add check that that extension module is compiled before running example scripts --- tools/swig/run_java_example.sh | 6 ++++++ tools/swig/run_lua_example.sh | 6 ++++++ tools/swig/run_perl_example.sh | 6 ++++++ tools/swig/run_python_example.sh | 6 ++++++ tools/swig/run_ruby_example.sh | 6 ++++++ tools/swig/run_tcl_example.sh | 6 ++++++ 6 files changed, 36 insertions(+) diff --git a/tools/swig/run_java_example.sh b/tools/swig/run_java_example.sh index c84be3527b..2f5b28bdce 100755 --- a/tools/swig/run_java_example.sh +++ b/tools/swig/run_java_example.sh @@ -1,5 +1,11 @@ #!/bin/sh +if [ ! -f libjavalammps.so ] +then \ + echo "Need to compile 'libjavalammps.so' first for this script to work" + exit 1 +fi + cat > example.java < example.lua < example.pl < example.py < example.rb < example.tcl < Date: Tue, 20 Oct 2020 18:30:19 -0400 Subject: [PATCH 28/37] replace explicit clean-all target with added properties --- tools/swig/CMakeLists.txt | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/tools/swig/CMakeLists.txt b/tools/swig/CMakeLists.txt index e818152c03..3b8cb9e5fc 100644 --- a/tools/swig/CMakeLists.txt +++ b/tools/swig/CMakeLists.txt @@ -27,10 +27,16 @@ option(BUILD_SWIG_PYTHON "Build Python wrapper with SWIG" OFF) option(BUILD_SWIG_RUBY "Build Ruby wrapper with SWIG" OFF) option(BUILD_SWIG_TCL "Build Tcl wrapper with SWIG" OFF) -add_custom_target(clean-all - COMMAND ${CMAKE_COMMAND} --build . --target clean - COMMAND ${CMAKE_COMMAND} -E remove example.* *.class *.java *.pm log.lammps - COMMAND ${CMAKE_COMMAND} -E remove_directory __pycache__) +set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES + pllammps.pm __pycache__ log.lammps + example.class example.java example.lua example.pl example.py example.rb example.tcl example.tcllmp + javalammps.class javalammpsJNI.class javalammps.java javalammpsJNI.java + _LMP_DATATYPE_CONST.class _LMP_STYLE_CONST.class _LMP_TYPE_CONST.class + _LMP_DATATYPE_CONST.java _LMP_STYLE_CONST.java _LMP_TYPE_CONST.java + SWIGTYPE_p_double.class SWIGTYPE_p_int.class SWIGTYPE_p_p_char.class SWIGTYPE_p_p_double.class + SWIGTYPE_p_p_int.class SWIGTYPE_p_p_void.class SWIGTYPE_p_void.class + SWIGTYPE_p_double.java SWIGTYPE_p_int.java SWIGTYPE_p_p_char.java SWIGTYPE_p_p_double.java + SWIGTYPE_p_p_int.java SWIGTYPE_p_p_void.java SWIGTYPE_p_void.java) if(BUILD_SWIG_JAVA) set_property(SOURCE lammps.i PROPERTY SWIG_MODULE_NAME javalammps) From 0547425482023eea5803f0339c309b8354fb9ccc Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 18:30:32 -0400 Subject: [PATCH 29/37] a few more small fixes --- tools/swig/CMakeLists.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tools/swig/CMakeLists.txt b/tools/swig/CMakeLists.txt index 3b8cb9e5fc..1431b42d6e 100644 --- a/tools/swig/CMakeLists.txt +++ b/tools/swig/CMakeLists.txt @@ -8,13 +8,14 @@ endif() if(POLICY CMP0086) cmake_policy(SET CMP0086 NEW) endif() +enable_language(C) # some of the find_package() scripts trigger developer warnings # even though they are bundled with CMake; Suppress them set(CMAKE_SUPPRESS_DEVELOPER_WARNINGS TRUE) if(NOT BUILD_SHARED_LIBS) - error(FATAL_ERROR "Option BUILD_SHARED_LIBS must be enabled to use SWIG wrappers") + message(FATAL_ERROR "Option BUILD_SHARED_LIBS must be enabled to use SWIG wrappers") endif() find_package(SWIG REQUIRED) From 1b358603c274b0546ae27ae021990cfd754de080 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 18:52:53 -0400 Subject: [PATCH 30/37] simplify --- cmake/CMakeLists.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 981dfb17a3..42e6d12ffb 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -383,8 +383,7 @@ endforeach() option(WITH_SWIG "Build scripting language wrappers with SWIG" OFF) if(WITH_SWIG) get_filename_component(LAMMPS_SWIG_DIR ${LAMMPS_SOURCE_DIR}/../tools/swig ABSOLUTE) - get_filename_component(LAMMPS_SWIG_BIN ${CMAKE_BINARY_DIR}/swig ABSOLUTE) - add_subdirectory(${LAMMPS_SWIG_DIR} ${LAMMPS_SWIG_BIN}) + add_subdirectory(${LAMMPS_SWIG_DIR} swig) endif() set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)") From ad50db1febe6044714f0f6ad51e2f430fab58e61 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 18:53:29 -0400 Subject: [PATCH 31/37] use a different/cleaner approach to build an extended Tcl shell --- tools/swig/CMakeLists.txt | 5 +++-- tools/swig/lammps.i | 4 ---- tools/swig/lammps_shell.i | 2 ++ 3 files changed, 5 insertions(+), 6 deletions(-) create mode 100644 tools/swig/lammps_shell.i diff --git a/tools/swig/CMakeLists.txt b/tools/swig/CMakeLists.txt index 1431b42d6e..b17b8c23e4 100644 --- a/tools/swig/CMakeLists.txt +++ b/tools/swig/CMakeLists.txt @@ -91,9 +91,10 @@ if(BUILD_SWIG_TCL) target_include_directories(tcllammps PRIVATE ${TCL_INCLUDE_PATH}) swig_link_libraries(tcllammps PRIVATE lammps ${TCL_LIBRARY}) configure_file(run_tcl_example.sh run_tcl_example.sh COPYONLY) - swig_add_library(libtcllammps TYPE STATIC LANGUAGE tcl SOURCES lammps.i) + set_property(SOURCE lammps_shell.i PROPERTY SWIG_MODULE_NAME tcllmpsh) + swig_add_library(libtcllmpsh TYPE STATIC LANGUAGE tcl SOURCES lammps_shell.i) add_executable(tcllmpsh tcldummy.c) target_include_directories(tcllmpsh PRIVATE ${TCL_INCLUDE_PATH}) - target_link_libraries(tcllmpsh PRIVATE libtcllammps lammps ${TCL_LIBRARY}) + target_link_libraries(tcllmpsh PRIVATE libtcllmpsh lammps ${TCL_LIBRARY}) endif() diff --git a/tools/swig/lammps.i b/tools/swig/lammps.i index 9358140a08..e28240b8ef 100644 --- a/tools/swig/lammps.i +++ b/tools/swig/lammps.i @@ -3,10 +3,6 @@ %include "cdata.i" %include "cstring.i" -#ifdef SWIGTCL -%include "tclsh.i" -#endif - %pointer_functions(int, int_p); %pointer_functions(int, int64_p); %pointer_functions(double, double_p); diff --git a/tools/swig/lammps_shell.i b/tools/swig/lammps_shell.i new file mode 100644 index 0000000000..d6b6dbccf3 --- /dev/null +++ b/tools/swig/lammps_shell.i @@ -0,0 +1,2 @@ +%include "tclsh.i" +%include "lammps.i" From a8c0142621a208796a760c56f643c1cb9f1cd0ea Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 21:22:39 -0400 Subject: [PATCH 32/37] update docs for building SWIG Tcl wrapper --- doc/src/Tools.rst | 31 ++++++++++--------------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 3e7446545b..8f0c06adec 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -931,8 +931,9 @@ necessary development headers and libraries are present. -D BUILD_SWIG_TCL=on # to enable building the Tcl wrapper -Manual building allows a little more flexibility. E.g. -with Tcl one can build and use a dynamically loaded object with: +Manual building allows a little more flexibility. E.g. one can choose +the name of the module and build and use a dynamically loaded object +for Tcl with: .. code-block:: bash @@ -941,31 +942,19 @@ with Tcl one can build and use a dynamically loaded object with: lammps_wrap.c -L ../src/ -llammps $ tclsh -Or one can build a new extended Tcl shell command with the wrapped +Or one can build an extended Tcl shell command with the wrapped functions included with: .. code-block:: bash - $ swig -tcl -module tcllammps lammps.i - $ gcc -o tcllammps tclmain.c lammps_wrap.c -Xlinker -export-dynamic \ + $ swig -tcl -module tcllmps lammps_shell.i + $ gcc -o tcllmpsh lammps_wrap.c -Xlinker -export-dynamic \ -DHAVE_CONFIG_H $(pkgconf --cflags tcl) \ - $(pkgconf --libs tcl) + $(pkgconf --libs tcl) -L ../src -llammps -With the file ``tclmain.c`` containing: - -.. code-block:: c - - #include - int AppInit(Tcl_Interp *interp) { - if (Tcl_Init(interp) == TCL_ERROR) return TCL_ERROR; - Tcl_SetVar(interp,"tcl_rcFileName","~/.wishrc",TCL_GLOBAL_ONLY); - return TCL_OK; - } - - int main(int argc, char *argv[]) { - Tcl_Main(argc, argv, AppInit); - return 0; - } +In both cases it is assumed that the LAMMPS library was compiled +as a shared library in the ``src`` folder. Otherwise the last +part of the commands needs to be adjusted. Utility functions ^^^^^^^^^^^^^^^^^ From de40b3e63733d1b95c2e78251869da50df3dc32d Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 20 Oct 2020 21:24:02 -0400 Subject: [PATCH 33/37] remove trailing whitespace --- doc/src/Python_examples.rst | 2 +- doc/src/pair_eam.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/src/Python_examples.rst b/doc/src/Python_examples.rst index 60184bc450..7466b52ba9 100644 --- a/doc/src/Python_examples.rst +++ b/doc/src/Python_examples.rst @@ -21,7 +21,7 @@ distribution. +------------------------+--------------------------------------------------------------------+ | ``gui.py`` | GUI go/stop/temperature-slider to control LAMMPS | +------------------------+--------------------------------------------------------------------+ -| ``plot.py`` | real-time temperature plot with GnuPlot via Pizza.py | +| ``plot.py`` | real-time temperature plot with GnuPlot via Pizza.py | +------------------------+--------------------------------------------------------------------+ | ``viz_TOOL.py`` | real-time viz via some viz package | +------------------------+--------------------------------------------------------------------+ diff --git a/doc/src/pair_eam.rst b/doc/src/pair_eam.rst index e2b6957032..7d0c191375 100644 --- a/doc/src/pair_eam.rst +++ b/doc/src/pair_eam.rst @@ -345,9 +345,9 @@ given by \rho_{\alpha\beta} (r_{ij})\right) + \frac{1}{2} \sum_{j \neq i} \phi_{\alpha\beta} (r_{ij}) -where :math:`\rho_{\alpha\beta}` refers to the density contributed +where :math:`\rho_{\alpha\beta}` refers to the density contributed by a neighbor atom J of element :math:`\beta` at the site of atom I -of element :math:`\alpha`. +of element :math:`\alpha`. This has the same form as the EAM formula above, except that rho is now a functional specific to the elements of both atoms I and J, so that different elements can contribute differently to the total @@ -408,7 +408,7 @@ each with the following format: The units of these quantities in line 1 are the same as for *setfl* files. Note that the rho(r) arrays in Finnis/Sinclair can be -asymmetric (:math:`\rho_{\alpha\beta} (r) \neq \rho_{\beta\alpha} (r)` ) +asymmetric (:math:`\rho_{\alpha\beta} (r) \neq \rho_{\beta\alpha} (r)` ) so there are Nelements\^2 of them listed in the file. Following the Nelements sections, Nr values for each pair potential From cc9059618397545c3a5de86e1f355984d8ebe84d Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 21 Oct 2020 10:49:01 -0400 Subject: [PATCH 34/37] fix link to documentation --- src/USER-MISC/README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/USER-MISC/README b/src/USER-MISC/README index ffb1210efa..f98268762f 100644 --- a/src/USER-MISC/README +++ b/src/USER-MISC/README @@ -6,7 +6,7 @@ More information about each feature can be found by reading its doc page in the LAMMPS doc directory. The doc page which lists all LAMMPS input script commands is as follows: -doc/Section_commands.html, subsection 3.5 +doc/Commands_all.html User-contributed features are listed at the bottom of the fix, compute, pair, etc sections. From de8149154a30078393f40c288ecc2653e214a162 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 21 Oct 2020 10:56:52 -0400 Subject: [PATCH 35/37] fix broken internal links in the manual --- doc/src/Modify_compute.rst | 4 ++-- doc/src/compute_angle.rst | 4 ++-- doc/src/fix_nh_uef.rst | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/src/Modify_compute.rst b/doc/src/Modify_compute.rst index 8fad775b3a..e910d6f8e2 100644 --- a/doc/src/Modify_compute.rst +++ b/doc/src/Modify_compute.rst @@ -53,5 +53,5 @@ in two stages: the callback function is registered with the pair style and then called from the Pair::ev_tally() function, which is called for each pair after force and energy has been computed for this pair. Then the tallied values are retrieved with the standard compute_scalar or -compute_vector or compute_peratom methods. The USER-TALLY package -provides *examples*\ _compute_tally.html for utilizing this mechanism. +compute_vector or compute_peratom methods. The :doc:`compute styles in the USER-TALLY package ` +provide *examples* for utilizing this mechanism. diff --git a/doc/src/compute_angle.rst b/doc/src/compute_angle.rst index d028cdec99..f3e5ee93c0 100644 --- a/doc/src/compute_angle.rst +++ b/doc/src/compute_angle.rst @@ -24,8 +24,8 @@ Description """"""""""" Define a computation that extracts the angle energy calculated by each -of the angle sub-styles used in the "angle_style -hybrid" angle_hybrid.html command. These values are made accessible +of the angle sub-styles used in the doc:`angle_style hybrid ` +command. These values are made accessible for output or further processing by other commands. The group specified for this command is ignored. diff --git a/doc/src/fix_nh_uef.rst b/doc/src/fix_nh_uef.rst index 1c1e7a11d2..74e61472c6 100644 --- a/doc/src/fix_nh_uef.rst +++ b/doc/src/fix_nh_uef.rst @@ -222,9 +222,9 @@ Default """"""" The default keyword values specific to this fix are exy = xyz, strain -= 0 0. The remaining defaults are the same as for *fix -npt*\ _fix_nh.html except tchain = 1. The reason for this change is -given in :doc:`fix nvt/sllod `. += 0 0. The remaining defaults are the same as for :doc:`fix npt ` +except tchain = 1. The reason for this change is given in +:doc:`fix nvt/sllod `. ---------- From 0a30398d1fb3818c9226fab4d41189cffea54847 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 21 Oct 2020 11:10:26 -0400 Subject: [PATCH 36/37] get rid of obsolete README note. We have long ago fixed the aliasing issue in Coulomb tabulation --- examples/peptide/README | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 examples/peptide/README diff --git a/examples/peptide/README b/examples/peptide/README deleted file mode 100644 index a4338e09df..0000000000 --- a/examples/peptide/README +++ /dev/null @@ -1,8 +0,0 @@ -If you get bogus, large energies on timestep 0 when you run this -example in.peptide, you likely have a machine/compiler problem with -the pair_style "long" potentials which use Coulombic tabling by -default. - -See the "Additional build tips" sub-section of the manual in -Section_start.html in the "Making LAMMPS" section for details and -suggestions on how to work around this issue. From 2ed11f55d6dac3dfa1768bd2171c078fd4392a6c Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 21 Oct 2020 11:12:13 -0400 Subject: [PATCH 37/37] fix URLs to documentation files --- examples/COUPLE/README | 26 +++++++++++++------------- examples/COUPLE/lammps_mc/README | 14 +++++++------- examples/COUPLE/lammps_nwchem/README | 12 ++++++------ examples/COUPLE/lammps_spparks/README | 10 +++++----- examples/COUPLE/lammps_vasp/README | 12 ++++++------ examples/README | 2 +- examples/USER/misc/ipi/README | 2 +- examples/message/README | 23 +++++++++++------------ 8 files changed, 50 insertions(+), 51 deletions(-) diff --git a/examples/COUPLE/README b/examples/COUPLE/README index 5a9f297b0f..a7053ade2f 100644 --- a/examples/COUPLE/README +++ b/examples/COUPLE/README @@ -11,11 +11,11 @@ library. See these sections of the LAMMPS manual for details: -Build LAMMPS as a library (doc/Build_basics.html) -Link LAMMPS as a library to another code (doc/Build_link.html) -Coupling LAMMPS to other codes (doc/Howto_couple.html) -Using LAMMPS in client/server mode (doc/Howto_client_server.html) -Library interface to LAMMPS (doc/Howto_library.html) +Build LAMMPS as a library (doc/html/Build_basics.html) +Link LAMMPS as a library to another code (doc/html/Build_link.html) +Coupling LAMMPS to other codes (doc/html/Howto_couple.html) +Using LAMMPS in client/server mode (doc/html/Howto_client_server.html) +Library interface to LAMMPS (doc/html/Howto_library.html) The library interface to LAMMPS is in src/library.cpp. Routines can be easily added to this file so an external program can perform the @@ -25,23 +25,23 @@ LAMMPS tasks desired. These are the sub-directories included in this directory: -simple simple example of driver code calling LAMMPS as a lib -multiple example of driver code calling multiple instances of LAMMPS +simple simple example of driver code calling LAMMPS as a lib +multiple example of driver code calling multiple instances of LAMMPS plugin example for loading LAMMPS at runtime from a shared library lammps_mc client/server coupling of Monte Carlo client with LAMMPS server for energy evaluation lammps_nwchem client/server coupling of LAMMPS client with NWChem quantum DFT as server for quantum forces -lammps_quest MD with quantum forces, coupling to Quest DFT code -lammps_spparks grain-growth Monte Carlo with strain via MD, - coupling to SPPARKS kinetic MC code +lammps_quest MD with quantum forces, coupling to Quest DFT code +lammps_spparks grain-growth Monte Carlo with strain via MD, + coupling to SPPARKS kinetic MC code lammps_vasp client/server coupling of LAMMPS client with VASP quantum DFT as server for quantum forces -library collection of useful inter-code communication routines +library collection of useful inter-code communication routines fortran a simple wrapper on the LAMMPS library API that - can be called from Fortran + can be called from Fortran fortran2 a more sophisticated wrapper on the LAMMPS library API that - can be called from Fortran + can be called from Fortran fortran_dftb wrapper written by Nir Goldman (LLNL), as an extension to fortran2, used for calling LAMMPS from Fortran DFTB+ tight-binding code diff --git a/examples/COUPLE/lammps_mc/README b/examples/COUPLE/lammps_mc/README index c201a6351c..4aed39dc8e 100644 --- a/examples/COUPLE/lammps_mc/README +++ b/examples/COUPLE/lammps_mc/README @@ -1,8 +1,8 @@ Sample Monte Carlo (MC) wrapper on LAMMPS via client/server coupling -See the MESSAGE package (doc/Section_messages.html#MESSAGE) -and Section_howto.html#howto10 for more details on how -client/server coupling works in LAMMPS. +See the MESSAGE package documentation Build_extras.html#message +and Build_extras.html#message for more details on how client/server +coupling works in LAMMPS. In this dir, the mc.cpp/h files are a standalone "client" MC code. It should be run on a single processor, though it could become a parallel @@ -94,18 +94,18 @@ background. File mode of messaging: % mpirun -np 1 mc in.mc file tmp.couple -% mpirun -np 1 lmp_mpi -v mode file < in.mc.server +% mpirun -np 1 lmp_mpi -v mode file -in in.mc.server % mpirun -np 1 mc in.mc file tmp.couple -% mpirun -np 4 lmp_mpi -v mode file < in.mc.server +% mpirun -np 4 lmp_mpi -v mode file -in in.mc.server ZMQ mode of messaging: % mpirun -np 1 mc in.mc zmq localhost:5555 -% mpirun -np 1 lmp_mpi -v mode zmq < in.mc.server +% mpirun -np 1 lmp_mpi -v mode zmq -in in.mc.server % mpirun -np 1 mc in.mc zmq localhost:5555 -% mpirun -np 4 lmp_mpi -v mode zmq < in.mc.server +% mpirun -np 4 lmp_mpi -v mode zmq -in in.mc.server -------------- diff --git a/examples/COUPLE/lammps_nwchem/README b/examples/COUPLE/lammps_nwchem/README index cb5c5b58cf..fc0f0cf868 100644 --- a/examples/COUPLE/lammps_nwchem/README +++ b/examples/COUPLE/lammps_nwchem/README @@ -1,7 +1,7 @@ Sample LAMMPS MD wrapper on NWChem via client/server coupling -See the MESSAGE package (doc/Section_messages.html#MESSAGE) and -Section_howto.html#howto10 for more details on how client/server +See the MESSAGE package documentation Build_extras.html#message +and Build_extras.html#message for more details on how client/server coupling works in LAMMPS. In this dir, the nwchem_wrap.py is a wrapper on the NWChem electronic @@ -182,16 +182,16 @@ background. File mode of messaging: -% mpirun -np 1 lmp_mpi -v mode file < in.client.W +% mpirun -np 1 lmp_mpi -v mode file -in in.client.W % python nwchem_wrap.py file pw w.nw -% mpirun -np 2 lmp_mpi -v mode file < in.client.h2o +% mpirun -np 2 lmp_mpi -v mode file -in in.client.h2o % python nwchem_wrap.py file ao h2o.nw ZMQ mode of messaging: -% mpirun -np 1 lmp_mpi -v mode zmq < in.client.W +% mpirun -np 1 lmp_mpi -v mode zmq -in in.client.W % python nwchem_wrap.py zmq pw w.nw -% mpirun -np 2 lmp_mpi -v mode zmq < in.client.h2o +% mpirun -np 2 lmp_mpi -v mode zmq -in in.client.h2o % python nwchem_wrap.py zmq ao h2o.nw diff --git a/examples/COUPLE/lammps_spparks/README b/examples/COUPLE/lammps_spparks/README index fc31de5f0b..c8365ae8e8 100644 --- a/examples/COUPLE/lammps_spparks/README +++ b/examples/COUPLE/lammps_spparks/README @@ -16,11 +16,11 @@ Lennard-Jones sigma between particles of different types that is larger than the sigma between particles of the same type (interior to grains). -lmpspk.cpp main program - it links LAMMPS and SPPARKS as libraries -in.spparks SPPARKS input script, without the run command -lmppath.h contains path to LAMMPS home directory -spkpath.h contains path to SPPARKS home directory +lmpspk.cpp main program + it links LAMMPS and SPPARKS as libraries +in.spparks SPPARKS input script, without the run command +lmppath.h contains path to LAMMPS home directory +spkpath.h contains path to SPPARKS home directory After editing the Makefile, lmppath.h, and spkpath.h to make them suitable for your box, type: diff --git a/examples/COUPLE/lammps_vasp/README b/examples/COUPLE/lammps_vasp/README index e942d52535..d81a5326e6 100644 --- a/examples/COUPLE/lammps_vasp/README +++ b/examples/COUPLE/lammps_vasp/README @@ -1,8 +1,8 @@ Sample LAMMPS MD wrapper on VASP quantum DFT via client/server coupling -See the MESSAGE package (doc/Section_messages.html#MESSAGE) and -Section_howto.html#howto10 for more details on how client/server +See the MESSAGE package documentation Build_extras.html#message +and Build_extras.html#message for more details on how client/server coupling works in LAMMPS. In this dir, the vasp_wrap.py is a wrapper on the VASP quantum DFT @@ -134,16 +134,16 @@ background. File mode of messaging: -% mpirun -np 1 lmp_mpi -v mode file < in.client.W +% mpirun -np 1 lmp_mpi -v mode file -in in.client.W % python vasp_wrap.py file POSCAR_W -% mpirun -np 2 lmp_mpi -v mode file < in.client.W +% mpirun -np 2 lmp_mpi -v mode file -in in.client.W % python vasp_wrap.py file POSCAR_W ZMQ mode of messaging: -% mpirun -np 1 lmp_mpi -v mode zmq < in.client.W +% mpirun -np 1 lmp_mpi -v mode zmq -in in.client.W % python vasp_wrap.py zmq POSCAR_W -% mpirun -np 2 lmp_mpi -v mode zmq < in.client.W +% mpirun -np 2 lmp_mpi -v mode zmq -in in.client.W % python vasp_wrap.py zmq POSCAR_W diff --git a/examples/README b/examples/README index 2ec7dc7a82..7eaa63bbd1 100644 --- a/examples/README +++ b/examples/README @@ -179,7 +179,7 @@ the same simulation in different unit systems. The USER directory contains subdirectories of user-provided example scripts for ser packages. See the README files in those directories -for more info. See the doc/Section_start.html file for more info +for more info. See the doc/html/Build_package.html file for more info about installing and building user packages. The VISCOSITY directory has example scripts for computing the diff --git a/examples/USER/misc/ipi/README b/examples/USER/misc/ipi/README index c3ecdea88d..d093cea4c5 100644 --- a/examples/USER/misc/ipi/README +++ b/examples/USER/misc/ipi/README @@ -36,7 +36,7 @@ In a separate terminal, then, you should run LAMMPS compiled to provide fix_ipi functionalities. ```bash - $LAMMPS < in.graphene + $LAMMPS -in in.graphene ``` You can run multiple instances of LAMMPS if you want to exploit the diff --git a/examples/message/README b/examples/message/README index 6cd99d5c09..6db735803e 100644 --- a/examples/message/README +++ b/examples/message/README @@ -11,9 +11,8 @@ LAMMPS as the server, e.g. a quantum code computing quantum forces, so that ab initio MD could be performed. See an example of the latter in examples/COUPLE/lammps_vasp. -See the doc pages for the "MESSAGE package" -(Package_details.html#PKG-MESSAGE) and "Howto client/server" -(Howto_client_server.html) for more details on how client/server +See the MESSAGE package documentation Build_extras.html#message +and Build_extras.html#message for more details on how client/server coupling works in LAMMPS. -------------- @@ -30,7 +29,7 @@ You can also run the in.message scripts with an NPT integrator instead of NVE, if you comment/uncomment the correct lines. The client and server script define a "mode" variable -which can be set to file, zmq, mpi/one, or mpi/two, +which can be set to file, zmq, mpi/one, or mpi/two, as illustrated below. -------------- @@ -38,8 +37,8 @@ as illustrated below. To run this problem in the traditional way (no client/server coupling) do one of these: -% lmp_serial < in.message -% mpirun -np 4 lmp_mpi < in.message +% lmp_serial -in in.message +% mpirun -np 4 lmp_mpi -in in.message Or run with in.message.tilt. @@ -87,14 +86,14 @@ runs listed below. File or ZMQ or mpi/two modes of messaging: -% mpirun -np 1 lmp_mpi -v mode file -log log.client < in.message.client & -% mpirun -np 2 lmp_mpi -v mode file -log log.server < in.message.server +% mpirun -np 1 lmp_mpi -v mode file -log log.client -in in.message.client & +% mpirun -np 2 lmp_mpi -v mode file -log log.server -in in.message.server -% mpirun -np 4 lmp_mpi -v mode zmq -log log.client < in.message.client & -% mpirun -np 1 lmp_mpi -v mode zmq -log log.server < in.message.server +% mpirun -np 4 lmp_mpi -v mode zmq -log log.client -in in.message.client & +% mpirun -np 1 lmp_mpi -v mode zmq -log log.server -in in.message.server -% mpirun -np 2 lmp_mpi -v mode mpitwo -log log.client < in.message.client & -% mpirun -np 4 lmp_mpi -v mode mpitwo -log log.server < in.message.server +% mpirun -np 2 lmp_mpi -v mode mpitwo -log log.client -in in.message.client & +% mpirun -np 4 lmp_mpi -v mode mpitwo -log log.server -in in.message.server Or run with in.message.tilt.client/server. Don't run the tilt files with the "file" mode; they run too slow.