diff --git a/doc/Section_python.html b/doc/Section_python.html index f6882e422c..0b60c25101 100644 --- a/doc/Section_python.html +++ b/doc/Section_python.html @@ -335,16 +335,9 @@ Python on a single processor, not in parallel. the source code for which is in python/lammps.py, which creates a "lammps" object, with a set of methods that can be invoked on that object. The sample Python code below assumes you have first imported -the "lammps" module in your Python script. You can also include its -settings as follows, which are useful in test return values from some -of the methods described below: +the "lammps" module in your Python script, as follows: 

from lammps import lammps 
-from lammps import LMPINT as INT
-from lammps import LMPDOUBLE as DOUBLE
-from lammps import LMPIPTR as IPTR
-from lammps import LMPDPTR as DPTR
-from lammps import LMPDPTRPTR as DPTRPTR

These are the methods defined by the lammps module. If you look at the file src/library.cpp you will see that they correspond @@ -362,16 +355,20 @@ lmp = lammps("g++",list) lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" 

xlo = lmp.extract_global(name,type)  # extract a global quantity
-                                    # name = "boxxlo", "nlocal", etc
-				     # type = INT or DOUBLE 
+                                     # name = "boxxlo", "nlocal", etc
+				     # type = 0 = int
+				     #        1 = double 
 
coords = lmp.extract_atom(name,type)      # extract a per-atom quantity
-                                         # name = "x", "type", etc
-				          # type = IPTR or DPTR or DPTRPTR 
+                                          # name = "x", "type", etc
+				          # type = 0 = vector of ints
+				          #        1 = array of ints
+				          #        2 = vector of doubles
+				          #        3 = array of doubles 
 
eng = lmp.extract_compute(id,style,type)  # extract value(s) from a compute
 v3 = lmp.extract_fix(id,style,type,i,j)   # extract value(s) from a fix
-                                         # id = ID of compute or fix
+                                          # id = ID of compute or fix
 					  # style = 0 = global data
 					  #	    1 = per-atom data
 					  #         2 = local data
@@ -387,8 +384,12 @@ v3 = lmp.extract_fix(id,style,type,i,j)   # extract value(s) from a fix
 					     #        1 = atom-style variable 
 
natoms = lmp.get_natoms()                 # total # of atoms as int
-x = lmp.get_coords()                      # return coords of all atoms in x
-lmp.put_coords(x)                         # set all atom coords via x 
+data = lmp.gather_atoms(name,type,count)  # return atom attribute of all atoms gathered into data, ordered by atom ID
+                                          # name = "x", "charge", "type", etc
+                                          # count = # of per-atom values, 1 or 3, etc
+lmp.scatter_atoms(name,type,count,data)   # scatter atom attribute of all atoms from data, ordered by atom ID
+                                          # name = "x", "charge", "type", etc
+                                          # count = # of per-atom values, 1 or 3, etc
@@ -427,8 +428,8 @@ returned, which you can use via normal Python subscripting. See the extract() method in the src/atom.cpp file for a list of valid names. Again, new names could easily be added. A pointer to a vector of doubles or integers, or a pointer to an array of doubles (double **) -is returned. You need to specify the appropriate data type via the -type argument. +or integers (int **) is returned. You need to specify the appropriate +data type via the type argument.

For extract_compute() and extract_fix(), the global, per-atom, or local data calulated by the compute or fix can be accessed. What is @@ -456,58 +457,57 @@ Python subscripting. The values will be zero for atoms not in the specified group.

The get_natoms() method returns the total number of atoms in the -simulation, as an int. Note that extract_global("natoms") returns the -same value, but as a double, which is the way LAMMPS stores it to -allow for systems with more atoms than can be stored in an int (> 2 -billion). +simulation, as an int.

-

The get_coords() method returns an ctypes vector of doubles of length -3*natoms, for the coordinates of all the atoms in the simulation, -ordered by x,y,z and then by atom ID (see code for put_coords() -below). The array can be used via normal Python subscripting. If -atom IDs are not consecutively ordered within LAMMPS, a None is -returned as indication of an error. +

The gather_atoms() method returns a ctypes vector of ints or doubles +as specified by type, of length count*natoms, for the property of all +the atoms in the simulation specified by name, ordered by count and +then by atom ID. The vector can be used via normal Python +subscripting. If atom IDs are not consecutively ordered within +LAMMPS, a None is returned as indication of an error.

-

Note that the data structure get_coords() returns is different from -the data structure returned by extract_atom("x") in four ways. (1) -Get_coords() returns a vector which you index as x[i]; +

Note that the data structure gather_atoms("x") returns is different +from the data structure returned by extract_atom("x") in four ways. +(1) Gather_atoms() returns a vector which you index as x[i]; extract_atom() returns an array which you index as x[i][j]. (2) -Get_coords() orders the atoms by atom ID while extract_atom() does -not. (3) Get_coords() returns a list of all atoms in the simulation; -extract_atoms() returns just the atoms local to each processor. (4) -Finally, the get_coords() data structure is a copy of the atom coords -stored internally in LAMMPS, whereas extract_atom returns an array -that points directly to the internal data. This means you can change -values inside LAMMPS from Python by assigning a new values to the -extract_atom() array. To do this with the get_atoms() vector, you -need to change values in the vector, then invoke the put_coords() -method. +Gather_atoms() orders the atoms by atom ID while extract_atom() does +not. (3) Gathert_atoms() returns a list of all atoms in the +simulation; extract_atoms() returns just the atoms local to each +processor. (4) Finally, the gather_atoms() data structure is a copy +of the atom coords stored internally in LAMMPS, whereas extract_atom() +returns an array that effectively points directly to the internal +data. This means you can change values inside LAMMPS from Python by +assigning a new values to the extract_atom() array. To do this with +the gather_atoms() vector, you need to change values in the vector, +then invoke the scatter_atoms() method.

-

The put_coords() method takes a vector of coordinates for all atoms in -the simulation, assumed to be ordered by x,y,z and then by atom ID, -and uses the values to overwrite the corresponding coordinates for -each atom inside LAMMPS. This requires LAMMPS to have its "map" -option enabled; see the atom_modify command for -details. If it is not or if atom IDs are not consecutively ordered, -no coordinates are reset, +

The scatter_atoms() method takes a vector of ints or doubles as +specified by type, of length count*natoms, for the property of all the +atoms in the simulation specified by name, ordered by bount and then +by atom ID. It uses the vector of data to overwrite the corresponding +properties for each atom inside LAMMPS. This requires LAMMPS to have +its "map" option enabled; see the atom_modify +command for details. If it is not, or if atom IDs are not +consecutively ordered, no coordinates are reset.

-

The array of coordinates passed to put_coords() must be a ctypes -vector of doubles, allocated and initialized something like this: +

The array of coordinates passed to scatter_atoms() must be a ctypes +vector of ints or doubles, allocated and initialized something like +this: 

from ctypes import *
-natoms = lmp.get_atoms()
+natoms = lmp.get_natoms()
 n3 = 3*natoms
-x = (c_double*n3)()
+x = (n3*c_double)()
 x0 = x coord of atom with ID 1
 x1 = y coord of atom with ID 1
 x2 = z coord of atom with ID 1
 x3 = x coord of atom with ID 2
 ...
 xn3-1 = z coord of atom with ID natoms
-lmp.put_coords(x) 
+lmp.scatter_coords("x",1,3,x)

Alternatively, you can just change values in the vector returned by -get_coords(), since it is a ctypes vector of doubles. +gather_atoms("x",1,3), since it is a ctypes vector of doubles.

diff --git a/doc/Section_python.txt b/doc/Section_python.txt index 8631798377..8041bf10c4 100644 --- a/doc/Section_python.txt +++ b/doc/Section_python.txt @@ -330,16 +330,9 @@ The Python interface to LAMMPS consists of a Python "lammps" module, the source code for which is in python/lammps.py, which creates a "lammps" object, with a set of methods that can be invoked on that object. The sample Python code below assumes you have first imported -the "lammps" module in your Python script. You can also include its -settings as follows, which are useful in test return values from some -of the methods described below: +the "lammps" module in your Python script, as follows: -from lammps import lammps -from lammps import LMPINT as INT -from lammps import LMPDOUBLE as DOUBLE -from lammps import LMPIPTR as IPTR -from lammps import LMPDPTR as DPTR -from lammps import LMPDPTRPTR as DPTRPTR :pre +from lammps import lammps :pre These are the methods defined by the lammps module. If you look at the file src/library.cpp you will see that they correspond @@ -357,16 +350,20 @@ lmp.file(file) # run an entire input script, file = "in.lj" lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100" :pre xlo = lmp.extract_global(name,type) # extract a global quantity - # name = "boxxlo", "nlocal", etc - # type = INT or DOUBLE :pre + # name = "boxxlo", "nlocal", etc + # type = 0 = int + # 1 = double :pre coords = lmp.extract_atom(name,type) # extract a per-atom quantity - # name = "x", "type", etc - # type = IPTR or DPTR or DPTRPTR :pre + # name = "x", "type", etc + # type = 0 = vector of ints + # 1 = array of ints + # 2 = vector of doubles + # 3 = array of doubles :pre eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix - # id = ID of compute or fix + # id = ID of compute or fix # style = 0 = global data # 1 = per-atom data # 2 = local data @@ -382,8 +379,12 @@ var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable # 1 = atom-style variable :pre natoms = lmp.get_natoms() # total # of atoms as int -x = lmp.get_coords() # return coords of all atoms in x -lmp.put_coords(x) # set all atom coords via x :pre +data = lmp.gather_atoms(name,type,count) # return atom attribute of all atoms gathered into data, ordered by atom ID + # name = "x", "charge", "type", etc + # count = # of per-atom values, 1 or 3, etc +lmp.scatter_atoms(name,type,count,data) # scatter atom attribute of all atoms from data, ordered by atom ID + # name = "x", "charge", "type", etc + # count = # of per-atom values, 1 or 3, etc :pre :line @@ -422,8 +423,8 @@ returned, which you can use via normal Python subscripting. See the extract() method in the src/atom.cpp file for a list of valid names. Again, new names could easily be added. A pointer to a vector of doubles or integers, or a pointer to an array of doubles (double **) -is returned. You need to specify the appropriate data type via the -type argument. +or integers (int **) is returned. You need to specify the appropriate +data type via the type argument. For extract_compute() and extract_fix(), the global, per-atom, or local data calulated by the compute or fix can be accessed. What is @@ -451,58 +452,57 @@ Python subscripting. The values will be zero for atoms not in the specified group. The get_natoms() method returns the total number of atoms in the -simulation, as an int. Note that extract_global("natoms") returns the -same value, but as a double, which is the way LAMMPS stores it to -allow for systems with more atoms than can be stored in an int (> 2 -billion). +simulation, as an int. -The get_coords() method returns an ctypes vector of doubles of length -3*natoms, for the coordinates of all the atoms in the simulation, -ordered by x,y,z and then by atom ID (see code for put_coords() -below). The array can be used via normal Python subscripting. If -atom IDs are not consecutively ordered within LAMMPS, a None is -returned as indication of an error. +The gather_atoms() method returns a ctypes vector of ints or doubles +as specified by type, of length count*natoms, for the property of all +the atoms in the simulation specified by name, ordered by count and +then by atom ID. The vector can be used via normal Python +subscripting. If atom IDs are not consecutively ordered within +LAMMPS, a None is returned as indication of an error. -Note that the data structure get_coords() returns is different from -the data structure returned by extract_atom("x") in four ways. (1) -Get_coords() returns a vector which you index as x\[i\]; +Note that the data structure gather_atoms("x") returns is different +from the data structure returned by extract_atom("x") in four ways. +(1) Gather_atoms() returns a vector which you index as x\[i\]; extract_atom() returns an array which you index as x\[i\]\[j\]. (2) -Get_coords() orders the atoms by atom ID while extract_atom() does -not. (3) Get_coords() returns a list of all atoms in the simulation; -extract_atoms() returns just the atoms local to each processor. (4) -Finally, the get_coords() data structure is a copy of the atom coords -stored internally in LAMMPS, whereas extract_atom returns an array -that points directly to the internal data. This means you can change -values inside LAMMPS from Python by assigning a new values to the -extract_atom() array. To do this with the get_atoms() vector, you -need to change values in the vector, then invoke the put_coords() -method. +Gather_atoms() orders the atoms by atom ID while extract_atom() does +not. (3) Gathert_atoms() returns a list of all atoms in the +simulation; extract_atoms() returns just the atoms local to each +processor. (4) Finally, the gather_atoms() data structure is a copy +of the atom coords stored internally in LAMMPS, whereas extract_atom() +returns an array that effectively points directly to the internal +data. This means you can change values inside LAMMPS from Python by +assigning a new values to the extract_atom() array. To do this with +the gather_atoms() vector, you need to change values in the vector, +then invoke the scatter_atoms() method. -The put_coords() method takes a vector of coordinates for all atoms in -the simulation, assumed to be ordered by x,y,z and then by atom ID, -and uses the values to overwrite the corresponding coordinates for -each atom inside LAMMPS. This requires LAMMPS to have its "map" -option enabled; see the "atom_modify"_atom_modify.html command for -details. If it is not or if atom IDs are not consecutively ordered, -no coordinates are reset, +The scatter_atoms() method takes a vector of ints or doubles as +specified by type, of length count*natoms, for the property of all the +atoms in the simulation specified by name, ordered by bount and then +by atom ID. It uses the vector of data to overwrite the corresponding +properties for each atom inside LAMMPS. This requires LAMMPS to have +its "map" option enabled; see the "atom_modify"_atom_modify.html +command for details. If it is not, or if atom IDs are not +consecutively ordered, no coordinates are reset. -The array of coordinates passed to put_coords() must be a ctypes -vector of doubles, allocated and initialized something like this: +The array of coordinates passed to scatter_atoms() must be a ctypes +vector of ints or doubles, allocated and initialized something like +this: from ctypes import * -natoms = lmp.get_atoms() +natoms = lmp.get_natoms() n3 = 3*natoms -x = (c_double*n3)() +x = (n3*c_double)() x[0] = x coord of atom with ID 1 x[1] = y coord of atom with ID 1 x[2] = z coord of atom with ID 1 x[3] = x coord of atom with ID 2 ... x[n3-1] = z coord of atom with ID natoms -lmp.put_coords(x) :pre +lmp.scatter_coords("x",1,3,x) :pre Alternatively, you can just change values in the vector returned by -get_coords(), since it is a ctypes vector of doubles. +gather_atoms("x",1,3), since it is a ctypes vector of doubles. :line