Loading doc/src/Manual.txt +2 −2 Original line number Diff line number Diff line <!-- HTML_ONLY --> <HEAD> <TITLE>LAMMPS Users Manual</TITLE> <META NAME="docnumber" CONTENT="19 Oct 2016 version"> <META NAME="docnumber" CONTENT="27 Oct 2016 version"> <META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories"> <META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License."> </HEAD> Loading @@ -21,7 +21,7 @@ <H1></H1> LAMMPS Documentation :c,h3 19 Oct 2016 version :c,h4 27 Oct 2016 version :c,h4 Version info: :h4 Loading doc/src/Section_howto.txt +55 −33 Original line number Diff line number Diff line Loading @@ -1864,8 +1864,8 @@ void lammps_close(void *) int lammps_version(void *) void lammps_file(void *, char *) char *lammps_command(void *, char *) char *lammps_commands_list(void *, int, char **) char *lammps_commands_concatenated(void *, char *) void lammps_commands_list(void *, int, char **) void lammps_commands_string(void *, char *) void lammps_free(void *) :pre The lammps_open() function is used to initialize LAMMPS, passing in a Loading Loading @@ -1901,51 +1901,66 @@ changes to the LAMMPS command syntax between versions. The returned LAMMPS version code is an integer (e.g. 2 Sep 2015 results in 20150902) that grows with every new LAMMPS version. The lammps_file(), lammps_command(), lammps_commands_list(), lammps_commands_concatenated() functions are used to pass one or more commands to LAMMPS to execute as if they were coming from an input script. The lammps_file(), lammps_command(), lammps_commands_list(), and lammps_commands_string() functions are used to pass one or more commands to LAMMPS to execute, the same as if they were coming from an input script. Via these functions, the calling code can read or generate a series of LAMMPS commands one or multiple at a time and pass it thru the library interface to setup a problem and then run it in stages. The caller can interleave the command function calls with operations it performs, calls to extract information from or set information within LAMMPS, or calls to another code's library. The lammps_file() function passes the filename of an input script. The lammps_command() function passes a single command as a string. The lammps_commands_multiple() function passes multiple commands in a char** list. The lammps_commands_concatentaed() function passes multiple commands concatenated into one long string, separated by newline characters. A single command can be spread across multiple lines, if the last printable character of all but the last line is "&", the same as if the lines appeared in an input script. Via these library functions, the calling code can read or generate a series of LAMMPS commands one or multiple at a time and pass it thru the library interface to setup a problem and then run it, interleaving the command function calls with operations performed within the faller, calls to extract information from LAMMPS, or calls to another code's library. The lammps_free() is a clean-up function to free memory that the library allocated previously. The lammps_commands_list() function passes multiple commands in a char** list. In both lammps_command() and lammps_commands_list(), individual commands may or may not have a trailing newline. The lammps_commands_string() function passes multiple commands concatenated into one long string, separated by newline characters. In both lammps_commands_list() and lammps_commands_string(), a single command can be spread across multiple lines, if the last printable character of all but the last line is "&", the same as if the lines appeared in an input script. The lammps_free() function is a clean-up function to free memory that the library allocated previously via other function calls. See comments in src/library.cpp file for which other functions need this clean-up. Library.cpp also contains these functions for extracting information from LAMMPS and setting value within LAMMPS. Again, see the documentation in the src/library.cpp file for details: documentation in the src/library.cpp file for details, including which quantities can be queried by name: void *lammps_extract_global(void *, char *) void *lammps_extract_atom(void *, char *) void *lammps_extract_compute(void *, char *, int, int) void *lammps_extract_fix(void *, char *, int, int, int, int) void *lammps_extract_variable(void *, char *, char *) void *lammps_extract_variable(void *, char *, char *) :pre int lammps_set_variable(void *, char *, char *) double lammps_get_thermo(void *, char *) double lammps_get_thermo(void *, char *) :pre int lammps_get_natoms(void *) void lammps_gather_atoms(void *, double *) void lammps_scatter_atoms(void *, double *) :pre void lammps_create_atoms(void *, int, tagint *, int *, double *, double *) :pre The extract functions return a pointer to various global or per-atom quantities stored in LAMMPS or to values calculated by a compute, fix, or variable. The pointer returned by the extract_global() function can be used as a permanent reference to a value which may change. For the other extract functions, the underlying storage may be reallocated as LAMMPS runs, so you need to re-call the function to assure a current pointer or returned value(s). These functions can extract various global or per-atom quantities from LAMMPS as well as values calculated by a compute, fix, or variable. The lammps_set_variable() function can set an existing string-style variable to a new value, so that subsequent LAMMPS commands can access the variable. The lammps_get_thermo() function returns the current value of a thermo keyword. The lammps_set_variable() function can set an existing string-style variable to a new string value, so that subsequent LAMMPS commands can access the variable. The lammps_get_thermo() function returns the current value of a thermo keyword as a double. The lammps_get_natoms() function returns the total number of atoms in the system and can be used by the caller to allocate space for the Loading @@ -1956,15 +1971,22 @@ returns a full list to each calling processor. The scatter function does the inverse. It distributes the same kinds of values, passed by the caller, to each atom owned by individual processors. The lammps_create_atoms() function takes a list of N atoms as input with atom types and coords (required), an optionally atom IDs and velocities. It uses the coords of each atom to assign it as a new atom to the processor that owns it. Additional properties for the new atoms can be assigned via the lammps_scatter_atoms() or lammps_extract_atom() functions. The examples/COUPLE and python directories have example C++ and C and Python codes which show how a driver code can link to LAMMPS as a library, run LAMMPS on a subset of processors, grab data from LAMMPS, change it, and put it back into LAMMPS. NOTE: You can write your own additional functions as needed to define NOTE: You can write code for additional functions as needed to define how your code talks to LAMMPS and add them to src/library.cpp and src/library.h, as well as to the "Python interface"_Section_python.html. The routines you add can access or interface"_Section_python.html. The added functions can access or change any LAMMPS data you wish. :line Loading doc/src/Section_python.txt +5 −3 Original line number Diff line number Diff line Loading @@ -550,7 +550,8 @@ version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 20 lmp.file(file) # run an entire input script, file = "in.lj" lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" :pre lmp.commands_list(cmdlist) # invoke commands in cmdlist lmp.commands_list(cmdlist) # invoke commands in cmdlist = ["run 10", "run 20"] lmp.commands_string(multicmd) # invoke commands in multicmd = "run 10\nrun 20" xlo = lmp.extract_global(name,type) # extract a global quantity # name = "boxxlo", "nlocal", etc Loading Loading @@ -631,8 +632,9 @@ lmp2 = lammps() lmp1.file("in.file1") lmp2.file("in.file2") :pre The file() and command() methods allow an input script or single commands to be invoked. The file(), command(), commands_list(), commands_string() methods allow an input script, a single command, or multiple commands to be invoked. The extract_global(), extract_atom(), extract_compute(), extract_fix(), and extract_variable() methods return values or Loading examples/COUPLE/simple/in.lj +2 −0 Original line number Diff line number Diff line Loading @@ -20,4 +20,6 @@ neigh_modify delay 0 every 20 check no fix 1 all nve variable fx atom fx run 10 examples/COUPLE/simple/simple.c +60 −11 Original line number Diff line number Diff line Loading @@ -71,8 +71,8 @@ int main(int narg, char **arg) (could just send it to proc 0 of comm_lammps and let it Bcast) all LAMMPS procs call lammps_command() on the line */ void *ptr; if (lammps == 1) lammps_open(0,NULL,comm_lammps,&ptr); void *lmp = NULL; if (lammps == 1) lammps_open(0,NULL,comm_lammps,&lmp); int n; char line[1024]; Loading @@ -85,7 +85,7 @@ int main(int narg, char **arg) MPI_Bcast(&n,1,MPI_INT,0,MPI_COMM_WORLD); if (n == 0) break; MPI_Bcast(line,n,MPI_CHAR,0,MPI_COMM_WORLD); if (lammps == 1) lammps_command(ptr,line); if (lammps == 1) lammps_command(lmp,line); } /* run 10 more steps Loading @@ -94,23 +94,72 @@ int main(int narg, char **arg) put coords back into LAMMPS run a single step with changed coords */ double *x = NULL; double *v = NULL; if (lammps == 1) { lammps_command(ptr,"run 10"); lammps_command(lmp,"run 10"); int natoms = lammps_get_natoms(ptr); double *x = (double *) malloc(3*natoms*sizeof(double)); lammps_gather_atoms(ptr,"x",1,3,x); int natoms = lammps_get_natoms(lmp); x = (double *) malloc(3*natoms*sizeof(double)); lammps_gather_atoms(lmp,"x",1,3,x); v = (double *) malloc(3*natoms*sizeof(double)); lammps_gather_atoms(lmp,"v",1,3,v); double epsilon = 0.1; x[0] += epsilon; lammps_scatter_atoms(ptr,"x",1,3,x); free(x); lammps_scatter_atoms(lmp,"x",1,3,x); lammps_command(lmp,"run 1"); } // extract force on single atom two different ways if (lammps == 1) { double **f = (double **) lammps_extract_atom(lmp,"f"); printf("Force on 1 atom via extract_atom: %g\n",f[0][0]); double *fx = (double *) lammps_extract_variable(lmp,"fx","all"); printf("Force on 1 atom via extract_variable: %g\n",fx[0]); } lammps_command(ptr,"run 1"); /* use commands_string() and commands_list() to invoke more commands */ char *strtwo = "run 10\nrun 20"; if (lammps == 1) lammps_commands_string(lmp,strtwo); char *cmds[2]; cmds[0] = "run 10"; cmds[1] = "run 20"; if (lammps == 1) lammps_commands_list(lmp,2,cmds); /* delete all atoms create_atoms() to create new ones with old coords, vels initial thermo should be same as step 20 */ int *type = NULL; if (lammps == 1) { int natoms = lammps_get_natoms(lmp); type = (int *) malloc(natoms*sizeof(double)); int i; for (i = 0; i < natoms; i++) type[i] = 1; lammps_command(lmp,"delete_atoms group all"); lammps_create_atoms(lmp,natoms,NULL,type,x,v); lammps_command(lmp,"run 10"); } if (lammps == 1) lammps_close(ptr); if (x) free(x); if (v) free(v); if (type) free(type); // close down LAMMPS lammps_close(lmp); /* close down MPI */ if (lammps == 1) MPI_Comm_free(&comm_lammps); MPI_Barrier(MPI_COMM_WORLD); MPI_Finalize(); } Loading
doc/src/Manual.txt +2 −2 Original line number Diff line number Diff line <!-- HTML_ONLY --> <HEAD> <TITLE>LAMMPS Users Manual</TITLE> <META NAME="docnumber" CONTENT="19 Oct 2016 version"> <META NAME="docnumber" CONTENT="27 Oct 2016 version"> <META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories"> <META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License."> </HEAD> Loading @@ -21,7 +21,7 @@ <H1></H1> LAMMPS Documentation :c,h3 19 Oct 2016 version :c,h4 27 Oct 2016 version :c,h4 Version info: :h4 Loading
doc/src/Section_howto.txt +55 −33 Original line number Diff line number Diff line Loading @@ -1864,8 +1864,8 @@ void lammps_close(void *) int lammps_version(void *) void lammps_file(void *, char *) char *lammps_command(void *, char *) char *lammps_commands_list(void *, int, char **) char *lammps_commands_concatenated(void *, char *) void lammps_commands_list(void *, int, char **) void lammps_commands_string(void *, char *) void lammps_free(void *) :pre The lammps_open() function is used to initialize LAMMPS, passing in a Loading Loading @@ -1901,51 +1901,66 @@ changes to the LAMMPS command syntax between versions. The returned LAMMPS version code is an integer (e.g. 2 Sep 2015 results in 20150902) that grows with every new LAMMPS version. The lammps_file(), lammps_command(), lammps_commands_list(), lammps_commands_concatenated() functions are used to pass one or more commands to LAMMPS to execute as if they were coming from an input script. The lammps_file(), lammps_command(), lammps_commands_list(), and lammps_commands_string() functions are used to pass one or more commands to LAMMPS to execute, the same as if they were coming from an input script. Via these functions, the calling code can read or generate a series of LAMMPS commands one or multiple at a time and pass it thru the library interface to setup a problem and then run it in stages. The caller can interleave the command function calls with operations it performs, calls to extract information from or set information within LAMMPS, or calls to another code's library. The lammps_file() function passes the filename of an input script. The lammps_command() function passes a single command as a string. The lammps_commands_multiple() function passes multiple commands in a char** list. The lammps_commands_concatentaed() function passes multiple commands concatenated into one long string, separated by newline characters. A single command can be spread across multiple lines, if the last printable character of all but the last line is "&", the same as if the lines appeared in an input script. Via these library functions, the calling code can read or generate a series of LAMMPS commands one or multiple at a time and pass it thru the library interface to setup a problem and then run it, interleaving the command function calls with operations performed within the faller, calls to extract information from LAMMPS, or calls to another code's library. The lammps_free() is a clean-up function to free memory that the library allocated previously. The lammps_commands_list() function passes multiple commands in a char** list. In both lammps_command() and lammps_commands_list(), individual commands may or may not have a trailing newline. The lammps_commands_string() function passes multiple commands concatenated into one long string, separated by newline characters. In both lammps_commands_list() and lammps_commands_string(), a single command can be spread across multiple lines, if the last printable character of all but the last line is "&", the same as if the lines appeared in an input script. The lammps_free() function is a clean-up function to free memory that the library allocated previously via other function calls. See comments in src/library.cpp file for which other functions need this clean-up. Library.cpp also contains these functions for extracting information from LAMMPS and setting value within LAMMPS. Again, see the documentation in the src/library.cpp file for details: documentation in the src/library.cpp file for details, including which quantities can be queried by name: void *lammps_extract_global(void *, char *) void *lammps_extract_atom(void *, char *) void *lammps_extract_compute(void *, char *, int, int) void *lammps_extract_fix(void *, char *, int, int, int, int) void *lammps_extract_variable(void *, char *, char *) void *lammps_extract_variable(void *, char *, char *) :pre int lammps_set_variable(void *, char *, char *) double lammps_get_thermo(void *, char *) double lammps_get_thermo(void *, char *) :pre int lammps_get_natoms(void *) void lammps_gather_atoms(void *, double *) void lammps_scatter_atoms(void *, double *) :pre void lammps_create_atoms(void *, int, tagint *, int *, double *, double *) :pre The extract functions return a pointer to various global or per-atom quantities stored in LAMMPS or to values calculated by a compute, fix, or variable. The pointer returned by the extract_global() function can be used as a permanent reference to a value which may change. For the other extract functions, the underlying storage may be reallocated as LAMMPS runs, so you need to re-call the function to assure a current pointer or returned value(s). These functions can extract various global or per-atom quantities from LAMMPS as well as values calculated by a compute, fix, or variable. The lammps_set_variable() function can set an existing string-style variable to a new value, so that subsequent LAMMPS commands can access the variable. The lammps_get_thermo() function returns the current value of a thermo keyword. The lammps_set_variable() function can set an existing string-style variable to a new string value, so that subsequent LAMMPS commands can access the variable. The lammps_get_thermo() function returns the current value of a thermo keyword as a double. The lammps_get_natoms() function returns the total number of atoms in the system and can be used by the caller to allocate space for the Loading @@ -1956,15 +1971,22 @@ returns a full list to each calling processor. The scatter function does the inverse. It distributes the same kinds of values, passed by the caller, to each atom owned by individual processors. The lammps_create_atoms() function takes a list of N atoms as input with atom types and coords (required), an optionally atom IDs and velocities. It uses the coords of each atom to assign it as a new atom to the processor that owns it. Additional properties for the new atoms can be assigned via the lammps_scatter_atoms() or lammps_extract_atom() functions. The examples/COUPLE and python directories have example C++ and C and Python codes which show how a driver code can link to LAMMPS as a library, run LAMMPS on a subset of processors, grab data from LAMMPS, change it, and put it back into LAMMPS. NOTE: You can write your own additional functions as needed to define NOTE: You can write code for additional functions as needed to define how your code talks to LAMMPS and add them to src/library.cpp and src/library.h, as well as to the "Python interface"_Section_python.html. The routines you add can access or interface"_Section_python.html. The added functions can access or change any LAMMPS data you wish. :line Loading
doc/src/Section_python.txt +5 −3 Original line number Diff line number Diff line Loading @@ -550,7 +550,8 @@ version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 20 lmp.file(file) # run an entire input script, file = "in.lj" lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" :pre lmp.commands_list(cmdlist) # invoke commands in cmdlist lmp.commands_list(cmdlist) # invoke commands in cmdlist = ["run 10", "run 20"] lmp.commands_string(multicmd) # invoke commands in multicmd = "run 10\nrun 20" xlo = lmp.extract_global(name,type) # extract a global quantity # name = "boxxlo", "nlocal", etc Loading Loading @@ -631,8 +632,9 @@ lmp2 = lammps() lmp1.file("in.file1") lmp2.file("in.file2") :pre The file() and command() methods allow an input script or single commands to be invoked. The file(), command(), commands_list(), commands_string() methods allow an input script, a single command, or multiple commands to be invoked. The extract_global(), extract_atom(), extract_compute(), extract_fix(), and extract_variable() methods return values or Loading
examples/COUPLE/simple/in.lj +2 −0 Original line number Diff line number Diff line Loading @@ -20,4 +20,6 @@ neigh_modify delay 0 every 20 check no fix 1 all nve variable fx atom fx run 10
examples/COUPLE/simple/simple.c +60 −11 Original line number Diff line number Diff line Loading @@ -71,8 +71,8 @@ int main(int narg, char **arg) (could just send it to proc 0 of comm_lammps and let it Bcast) all LAMMPS procs call lammps_command() on the line */ void *ptr; if (lammps == 1) lammps_open(0,NULL,comm_lammps,&ptr); void *lmp = NULL; if (lammps == 1) lammps_open(0,NULL,comm_lammps,&lmp); int n; char line[1024]; Loading @@ -85,7 +85,7 @@ int main(int narg, char **arg) MPI_Bcast(&n,1,MPI_INT,0,MPI_COMM_WORLD); if (n == 0) break; MPI_Bcast(line,n,MPI_CHAR,0,MPI_COMM_WORLD); if (lammps == 1) lammps_command(ptr,line); if (lammps == 1) lammps_command(lmp,line); } /* run 10 more steps Loading @@ -94,23 +94,72 @@ int main(int narg, char **arg) put coords back into LAMMPS run a single step with changed coords */ double *x = NULL; double *v = NULL; if (lammps == 1) { lammps_command(ptr,"run 10"); lammps_command(lmp,"run 10"); int natoms = lammps_get_natoms(ptr); double *x = (double *) malloc(3*natoms*sizeof(double)); lammps_gather_atoms(ptr,"x",1,3,x); int natoms = lammps_get_natoms(lmp); x = (double *) malloc(3*natoms*sizeof(double)); lammps_gather_atoms(lmp,"x",1,3,x); v = (double *) malloc(3*natoms*sizeof(double)); lammps_gather_atoms(lmp,"v",1,3,v); double epsilon = 0.1; x[0] += epsilon; lammps_scatter_atoms(ptr,"x",1,3,x); free(x); lammps_scatter_atoms(lmp,"x",1,3,x); lammps_command(lmp,"run 1"); } // extract force on single atom two different ways if (lammps == 1) { double **f = (double **) lammps_extract_atom(lmp,"f"); printf("Force on 1 atom via extract_atom: %g\n",f[0][0]); double *fx = (double *) lammps_extract_variable(lmp,"fx","all"); printf("Force on 1 atom via extract_variable: %g\n",fx[0]); } lammps_command(ptr,"run 1"); /* use commands_string() and commands_list() to invoke more commands */ char *strtwo = "run 10\nrun 20"; if (lammps == 1) lammps_commands_string(lmp,strtwo); char *cmds[2]; cmds[0] = "run 10"; cmds[1] = "run 20"; if (lammps == 1) lammps_commands_list(lmp,2,cmds); /* delete all atoms create_atoms() to create new ones with old coords, vels initial thermo should be same as step 20 */ int *type = NULL; if (lammps == 1) { int natoms = lammps_get_natoms(lmp); type = (int *) malloc(natoms*sizeof(double)); int i; for (i = 0; i < natoms; i++) type[i] = 1; lammps_command(lmp,"delete_atoms group all"); lammps_create_atoms(lmp,natoms,NULL,type,x,v); lammps_command(lmp,"run 10"); } if (lammps == 1) lammps_close(ptr); if (x) free(x); if (v) free(v); if (type) free(type); // close down LAMMPS lammps_close(lmp); /* close down MPI */ if (lammps == 1) MPI_Comm_free(&comm_lammps); MPI_Barrier(MPI_COMM_WORLD); MPI_Finalize(); }
