Add autodoc for lammps.lammps and lammps.NeighList

doc/src/Python_library.rst

@@ -9,7 +9,7 @@ below assumes you have first imported the "lammps" module in your
 Python script, as follows:
 
 
-.. parsed-literal::
+.. code-block:: Python
 
    from lammps import lammps
 
@@ -23,7 +23,7 @@ The python/examples directory has Python scripts which show how Python
 can run LAMMPS, grab data, change it, and put it back into LAMMPS.
 
 
-.. parsed-literal::
+.. code-block:: Python
 
    lmp = lammps()           # create a LAMMPS object using the default liblammps.so library
                             # 4 optional args are allowed: name, cmdargs, ptr, comm
@@ -100,7 +100,7 @@ can run LAMMPS, grab data, change it, and put it back into LAMMPS.
 The lines
 
 
-.. parsed-literal::
+.. code-block:: Python
 
    from lammps import lammps
    lmp = lammps()
@@ -117,7 +117,7 @@ prompt.
 If the ptr argument is set like this:
 
 
-.. parsed-literal::
+.. code-block:: Python
 
    lmp = lammps(ptr=lmpptr)
 
@@ -134,7 +134,7 @@ Note that you can create multiple LAMMPS objects in your Python
 script, and coordinate and run multiple simulations, e.g.
 
 
-.. parsed-literal::
+.. code-block:: Python
 
    from lammps import lammps
    lmp1 = lammps()
@@ -230,7 +230,7 @@ ctypes vector of ints or doubles, allocated and initialized something
 like this:
 
 
-.. parsed-literal::
+.. code-block:: Python
 
    from ctypes import \*
    natoms = lmp.get_natoms()
@@ -265,6 +265,15 @@ following steps:
   Python script.
 
 
+----------
+
+.. autoclass:: lammps.lammps
+   :members:
+   :no-undoc-members:
+
+.. autoclass:: lammps.NeighList
+   :members:
+   :no-undoc-members:
 
 .. _lws: http://lammps.sandia.gov
 .. _ld: Manual.html

doc/txt/Python_library.txt

@@ -1,256 +0,0 @@
-"Higher level section"_Python_head.html - "LAMMPS WWW Site"_lws -
-"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
-
-:link(lws,http://lammps.sandia.gov)
-:link(ld,Manual.html)
-:link(lc,Commands_all.html)
-
-:line
-
-Python library interface :h3
-
-As described previously, 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, as follows:
-
-from lammps import lammps :pre
-
-These are the methods defined by the lammps module.  If you look at
-the files src/library.cpp and src/library.h you will see they
-correspond one-to-one with calls you can make to the LAMMPS library
-from a C++ or C or Fortran program, and which are described on the
-"Howto library"_Howto_library.html doc page.
-
-The python/examples directory has Python scripts which show how Python
-can run LAMMPS, grab data, change it, and put it back into LAMMPS.
-
-lmp = lammps()           # create a LAMMPS object using the default liblammps.so library
-                         # 4 optional args are allowed: name, cmdargs, ptr, comm
-lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object
-lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later
-lmp = lammps(name="g++")   # create a LAMMPS object using the liblammps_g++.so library
-lmp = lammps(name="g++",cmdargs=list)    # add LAMMPS command-line args, e.g. list = \["-echo","screen"\] :pre
-
-lmp.close()              # destroy a LAMMPS object :pre
-
-version = lmp.version()  # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902 :pre
-
-lmp.file(file)           # run an entire input script, file = "in.lj"
-lmp.command(cmd)         # invoke a single LAMMPS command, cmd = "run 100"
-lmp.commands_list(cmdlist)     # invoke commands in cmdlist = ["run 10", "run 20"]
-lmp.commands_string(multicmd)  # invoke commands in multicmd = "run 10\nrun 20" :pre
-
-size = lmp.extract_setting(name)     # return data type info :pre
-
-xlo = lmp.extract_global(name,type)  # extract a global quantity
-                                     # name = "boxxlo", "nlocal", etc
-                                     # type = 0 = int
-                                     #        1 = double :pre
-
-boxlo,boxhi,xy,yz,xz,periodicity,box_change = lmp.extract_box()  # extract box info :pre
-
-coords = lmp.extract_atom(name,type)      # extract a per-atom quantity
-                                          # 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
-                                          # style = 0 = global data
-                                          #         1 = per-atom data
-                                          #         2 = local data
-                                          # type = 0 = scalar
-                                          #        1 = vector
-                                          #        2 = array
-                                          # i,j = indices of value in global vector or array :pre
-
-var = lmp.extract_variable(name,group,flag)  # extract value(s) from a variable
-                                             # name = name of variable
-                                             # group = group ID (ignored for equal-style variables)
-                                             # flag = 0 = equal-style variable
-                                             #        1 = atom-style variable :pre
-
-value = lmp.get_thermo(name)              # return current value of a thermo keyword
-natoms = lmp.get_natoms()                 # total # of atoms as int :pre
-
-flag = lmp.set_variable(name,value)       # set existing named string-style variable to value, flag = 0 if successful
-lmp.reset_box(boxlo,boxhi,xy,yz,xz)       # reset the simulation box size :pre
-
-data = lmp.gather_atoms(name,type,count)  # return per-atom property of all atoms gathered into data, ordered by atom ID
-                                          # name = "x", "charge", "type", etc
-data = lmp.gather_atoms_concat(name,type,count)  # ditto, but concatenated atom values from each proc (unordered)
-data = lmp.gather_atoms_subset(name,type,count,ndata,ids)  # ditto, but for subset of Ndata atoms with IDs :pre
-
-lmp.scatter_atoms(name,type,count,data)   # scatter per-atom property to all atoms from data, ordered by atom ID
-                                          # name = "x", "charge", "type", etc
-                                          # count = # of per-atom values, 1 or 3, etc :pre
-lmp.scatter_atoms_subset(name,type,count,ndata,ids,data)  # ditto, but for subset of Ndata atoms with IDs :pre
-
-lmp.create_atoms(n,ids,types,x,v,image,shrinkexceed)   # create N atoms with IDs, types, x, v, and image flags :pre
-
-:line
-
-The lines
-
-from lammps import lammps
-lmp = lammps() :pre
-
-create an instance of LAMMPS, wrapped in a Python class by the lammps
-Python module, and return an instance of the Python class as lmp.  It
-is used to make all subsequent calls to the LAMMPS library.
-
-Additional arguments to lammps() can be used to tell Python the name
-of the shared library to load or to pass arguments to the LAMMPS
-instance, the same as if LAMMPS were launched from a command-line
-prompt.
-
-If the ptr argument is set like this:
-
-lmp = lammps(ptr=lmpptr) :pre
-
-then lmpptr must be an argument passed to Python via the LAMMPS
-"python"_python.html command, when it is used to define a Python
-function that is invoked by the LAMMPS input script.  This mode of
-calling Python from LAMMPS is described in the "Python
-call"_Python_call.html doc page.  The variable lmpptr refers to the
-instance of LAMMPS that called the embedded Python interpreter.  Using
-it as an argument to lammps() allows the returned Python class
-instance "lmp" to make calls to that instance of LAMMPS.  See the
-"python"_python.html command doc page for examples using this syntax.
-
-Note that you can create multiple LAMMPS objects in your Python
-script, and coordinate and run multiple simulations, e.g.
-
-from lammps import lammps
-lmp1 = lammps()
-lmp2 = lammps()
-lmp1.file("in.file1")
-lmp2.file("in.file2") :pre
-
-The file(), command(), commands_list(), commands_string() methods
-allow an input script, a single command, or multiple commands to be
-invoked.
-
-The extract_setting(), extract_global(), extract_box(),
-extract_atom(), extract_compute(), extract_fix(), and
-extract_variable() methods return values or pointers to data
-structures internal to LAMMPS.
-
-For extract_global() see the src/library.cpp file for the list of
-valid names.  New names could easily be added.  A double or integer is
-returned.  You need to specify the appropriate data type via the type
-argument.
-
-For extract_atom(), a pointer to internal LAMMPS atom-based data is
-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 if the property you want is not
-listed.  A pointer to a vector of doubles or integers, or a pointer to
-an array of doubles (double **) 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 calculated by the compute or fix can be accessed.  What is
-returned depends on whether the compute or fix calculates a scalar or
-vector or array.  For a scalar, a single double value is returned.  If
-the compute or fix calculates a vector or array, a pointer to the
-internal LAMMPS data is returned, which you can use via normal Python
-subscripting.  The one exception is that for a fix that calculates a
-global vector or array, a single double value from the vector or array
-is returned, indexed by I (vector) or I and J (array).  I,J are
-zero-based indices.  The I,J arguments can be left out if not needed.
-See the "Howto output"_Howto_output.html doc page for a discussion of
-global, per-atom, and local data, and of scalar, vector, and array
-data types.  See the doc pages for individual "computes"_compute.html
-and "fixes"_fix.html for a description of what they calculate and
-store.
-
-For extract_variable(), an "equal-style or atom-style
-variable"_variable.html is evaluated and its result returned.
-
-For equal-style variables a single double value is returned and the
-group argument is ignored.  For atom-style variables, a vector of
-doubles is returned, one value per atom, which you can use via normal
-Python subscripting. The values will be zero for atoms not in the
-specified group.
-
-The get_thermo() method returns the current value of a thermo
-keyword as a float.
-
-The get_natoms() method returns the total number of atoms in the
-simulation, as an int.
-
-The set_variable() method sets an existing string-style variable to a
-new string value, so that subsequent LAMMPS commands can access the
-variable.
-
-The reset_box() method resets the size and shape of the simulation
-box, e.g. as part of restoring a previously extracted and saved state
-of a simulation.
-
-The gather methods collect peratom info of the requested type (atom
-coords, atom types, forces, etc) from all processors, and returns the
-same vector of values to each calling processor.  The scatter
-functions do the inverse.  They distribute a vector of peratom values,
-passed by all calling processors, to individual atoms, which may be
-owned by different processors.
-
-Note that the data returned by the gather methods,
-e.g. gather_atoms("x"), 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) Gather_atoms() orders the atoms
-by atom ID while extract_atom() does not.  (3) Gather_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.
-
-For the scatter methods, the array of coordinates passed to must be a
-ctypes vector of ints or doubles, allocated and initialized something
-like this:
-
-from ctypes import *
-natoms = lmp.get_natoms()
-n3 = 3*natoms
-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.scatter_atoms("x",1,3,x) :pre
-
-Alternatively, you can just change values in the vector returned by
-the gather methods, since they are also ctypes vectors.
-
-:line
-
-As noted above, these Python class methods correspond one-to-one with
-the functions in the LAMMPS library interface in src/library.cpp and
-library.h.  This means you can extend the Python wrapper via the
-following steps:
-
-Add a new interface function to src/library.cpp and
-src/library.h. :ulb,l
-
-Rebuild LAMMPS as a shared library. :l
-
-Add a wrapper method to python/lammps.py for this interface
-function. :l
-
-You should now be able to invoke the new interface function from a
-Python script. :l
-:ule

doc/utils/sphinx-config/conf.py

@@ -30,7 +30,9 @@ import os
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.mathjax', 'sphinx.ext.imgmath'
+    'sphinx.ext.mathjax',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.autodoc',
 ]
 # 2017-12-07: commented out, since this package is broken with Sphinx 16.x
 #             yet we can no longer use Sphinx 15.x, since that breaks with
@@ -323,3 +325,5 @@ import LAMMPSLexer
 from sphinx.highlighting import lexers
 
 lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True)
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '../../../python'))