ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs and docstrings

Browse Source
This commit is contained in:
Richard Berger
2020-09-18 14:49:25 -04:00
parent 449513703b
commit 635b7c04a5
5 changed files with 92 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
doc/src/pg_lib_properties.rst
View File

@ -84,11 +84,22 @@ event as atoms are migrating between sub-domains.
-----------------------
.. doxygenfunction:: lammps_extract_global_datatype
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_global
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_atom_datatype
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_atom
:project: progguide

19
doc/src/pg_python.rst
View File

@ -359,6 +359,10 @@ The :py:mod:`lammps` module additionally contains several constants
and the :py:class:`NeighList <lammps.NeighList>` class:
.. _py_data_constants:
Data Types
----------
.. py:data:: LAMMPS_INT, LAMMPS_INT_2D, LAMMPS_DOUBLE, LAMMPS_DOUBLE_2D, LAMMPS_INT64, LAMMPS_INT64_2D, LAMMPS_STRING
:type: int
@ -369,6 +373,10 @@ and the :py:class:`NeighList <lammps.NeighList>` class:
C library interface.
.. _py_style_constants:
Style Constants
---------------
.. py:data:: LMP_STYLE_GLOBAL, LMP_STYLE_ATOM, LMP_STYLE_LOCAL
:type: int
@ -378,6 +386,10 @@ and the :py:class:`NeighList <lammps.NeighList>` class:
:py:func:`lammps.extract_compute` and :py:func:`lammps.extract_fix`.
.. _py_type_constants:
Type Constants
--------------
.. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
:type: int
@ -387,12 +399,19 @@ and the :py:class:`NeighList <lammps.NeighList>` class:
:py:func:`lammps.extract_compute` and :py:func:`lammps.extract_fix`.
.. _py_var_constants:
Variable Style Constants
------------------------
.. py:data:: LMP_VAR_EQUAL, LMP_VAR_ATOM
:type: int
Constants in the :py:mod:`lammps` module to select what style of
variable to query when calling :py:func:`lammps.extract_variable`.
Classes representing internal objects
-------------------------------------
.. autoclass:: lammps.NeighList
:members:
:no-undoc-members:

68
python/lammps.py
View File

@ -486,11 +486,12 @@ class lammps(object):
function of the C-library interface. Its documentation includes a
list of the supported keywords and their data types.
Since Python needs to know the data type to be able to interpret
the result, by default, this function will try to auto-detect the datatype
by asking the library. You can also force a specific datatype. For
that purpose the :py:mod:`lammps` module contains the constants
``LAMMPS_INT``, ``LAMMPS_DOUBLE``, ``LAMMPS_BIGINT``,
``LAMMPS_TAGINT``, and ``LAMMPS_STRING``.
the result, by default, this function will try to auto-detect the data
type by asking the library. You can also force a specific data type.
For that purpose the :py:mod:`lammps` module contains the constants
``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``,
``LAMMPS_DOUBLE_2D``, ``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and
``LAMMPS_STRING``.
This function returns ``None`` if either the keyword is not
recognized, or an invalid data type constant is used.
@ -505,7 +506,7 @@ class lammps(object):
:param name: name of the property
:type name: string
:param dtype: type of the returned data
:param dtype: type of the returned data (see :ref:`py_data_constants`)
:type dtype: int, optional
:param nelem: number of elements in array
:type nelem: int, optional
@ -887,7 +888,8 @@ class lammps(object):
recognized. Otherwise it will return a positive integer value that
corresponds to one of the constants define in the :py:mod:`lammps` module:
``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``, ``LAMMPS_DOUBLE_2D``,
``LAMMPS_BIGINT``, ``LAMMPS_TAGINT``, ``LAMMPS_TAGINT2D``, and ``LAMMPS_STRING``.
``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``. These values
are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
:param name: name of the property
:type name: string
@ -911,19 +913,20 @@ class lammps(object):
of values. The :cpp:func:`lammps_extract_global` documentation
includes a list of the supported keywords and their data types.
Since Python needs to know the data type to be able to interpret
the result, by default, this function will try to auto-detect the datatype
the result, by default, this function will try to auto-detect the data type
by asking the library. You can also force a specific data type. For that
purpose the :py:mod:`lammps` module contains the constants ``LAMMPS_INT``,
``LAMMPS_DOUBLE``, ``LAMMPS_INT64``, and ``LAMMPS_STRING``.
``LAMMPS_DOUBLE``, ``LAMMPS_INT64``, and ``LAMMPS_STRING``. These values
are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
This function returns ``None`` if either the keyword is not recognized,
or an invalid data type constant is used.
:param name: name of the property
:type name: string
:param dtype: type of the returned data
:param dtype: data type of the returned data (see :ref:`py_data_constants`)
:type dtype: int, optional
:return: value of the property
:rtype: integer or double or string or None
:return: value of the property or None
:rtype: int, float, or NoneType
"""
if dtype == LAMMPS_AUTODETECT:
dtype = self.extract_global_datatype(name)
@ -933,19 +936,22 @@ class lammps(object):
if dtype == LAMMPS_INT:
self.lib.lammps_extract_global.restype = POINTER(c_int32)
elif dtype == LAMMPS_DOUBLE:
self.lib.lammps_extract_global.restype = POINTER(c_double)
target_type = int
elif dtype == LAMMPS_INT64:
self.lib.lammps_extract_global.restype = POINTER(c_int64)
target_type = int
elif dtype == LAMMPS_DOUBLE:
self.lib.lammps_extract_global.restype = POINTER(c_double)
target_type = float
elif dtype == LAMMPS_STRING:
self.lib.lammps_extract_global.restype = c_char_p
ptr = self.lib.lammps_extract_global(self.lmp, name)
return str(ptr,'ascii')
else: return None
target_type = lambda x: str(x, 'ascii')
ptr = self.lib.lammps_extract_global(self.lmp, name)
if ptr: return ptr[0]
else: return None
if ptr:
return target_type(ptr[0])
return None
# -------------------------------------------------------------------------
# extract per-atom info datatype
@ -957,14 +963,15 @@ class lammps(object):
function of the C-library interface. Its documentation includes a
list of the supported keywords.
This function returns ``None`` if the keyword is not
recognized. Otherwise it will return a positive integer value that
recognized. Otherwise it will return an integer value that
corresponds to one of the constants define in the :py:mod:`lammps` module:
``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``, ``LAMMPS_DOUBLE_2D``,
``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``.
``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``. These values
are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
:param name: name of the property
:type name: string
:return: datatype of per-atom property
:return: data type of per-atom property (see :ref:`py_data_constants`)
:rtype: int
"""
if name: name = name.encode()
@ -985,7 +992,8 @@ class lammps(object):
by asking the library. You can also force a specific data type. For
that purpose the :py:mod:`lammps` module contains the constants
``LAMMPS_INT``, ``LAMMPS_INT_2D``, ``LAMMPS_DOUBLE``, ``LAMMPS_DOUBLE_2D``,
``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``.
``LAMMPS_INT64``, ``LAMMPS_INT64_2D``, and ``LAMMPS_STRING``. These values
are equivalent to the ones defined in :cpp:enum:`_LMP_DATATYPE_CONST`.
This function returns ``None`` if either the keyword is not
recognized, or an invalid data type constant is used.
@ -1000,10 +1008,13 @@ class lammps(object):
:param name: name of the property
:type name: string
:param dtype: type of the returned data
:param dtype: data type of the returned data (see :ref:`py_data_constants`)
:type dtype: int, optional
:return: requested data
:rtype: pointer to integer or double or None
:return: requested data or ``None``
:rtype: ctypes.POINTER(ctypes.c_int32), ctypes.POINTER(ctypes.POINTER(ctypes.c_int32)),
ctypes.POINTER(ctypes.c_int64), ctypes.POINTER(ctypes.POINTER(ctypes.c_int64)),
ctypes.POINTER(ctypes.c_double), ctypes.POINTER(ctypes.POINTER(ctypes.c_double)),
or NoneType
"""
if dtype == LAMMPS_AUTODETECT:
dtype = self.extract_atom_datatype(name)
@ -1970,6 +1981,11 @@ class Atom(object):
# -------------------------------------------------------------------------
class Atom2D(Atom):
"""
A wrapper class then represents a single 2D atom inside of LAMMPS
It provides access to properties of the atom and allows you to change some of them.
"""
def __init__(self, pylammps_instance, index):
super(Atom2D, self).__init__(pylammps_instance, index)

17
src/library.cpp
View File

@ -1208,9 +1208,13 @@ void *lammps_extract_atom(void *handle, const char *name)
/** Get data type of internal global LAMMPS variables or arrays.
*
* TODO
\verbatim embed:rst
This function returns an integer that encodes the data type of the global
property with the specified name. See :cpp:enum:`_LMP_DATATYPE_CONST` for valid
values. Callers of :cpp:func:`lammps_extract_global` can use this information
to then decide how to cast the (void*) pointer and access the data.
.. versionadded:: 18Sep2020
\endverbatim
@ -1218,7 +1222,7 @@ void *lammps_extract_atom(void *handle, const char *name)
* \param handle pointer to a previously created LAMMPS instance
* \param name string with the name of the extracted property
* \return integer constant encoding the data type of the property
or -1 if not found. */
* or -1 if not found. */
int lammps_extract_global_datatype(void *handle, const char *name)
{
@ -1288,9 +1292,13 @@ int lammps_extract_global_datatype(void *handle, const char *name)
/** Get data type of a LAMMPS per-atom property
*
* TODO
\verbatim embed:rst
This function returns an integer that encodes the data type of the per-atom
property with the specified name. See :cpp:enum:`_LMP_DATATYPE_CONST` for valid
values. Callers of :cpp:func:`lammps_extract_atom` can use this information
to then decide how to cast the (void*) pointer and access the data.
.. versionadded:: 18Sep2020
\endverbatim
@ -1298,7 +1306,8 @@ int lammps_extract_global_datatype(void *handle, const char *name)
* \param handle pointer to a previously created LAMMPS instance
* \param name string with the name of the extracted property
* \return integer constant encoding the data type of the property
* or -1 if not found. */
* or -1 if not found.
* */
int lammps_extract_atom_datatype(void *handle, const char *name)
{

14
src/library.h
View File

@ -45,13 +45,13 @@
* Must be kept in sync with the equivalent constants in lammps.py */
enum _LMP_DATATYPE_CONST {
LAMMPS_INT = 0,
LAMMPS_INT_2D = 1,
LAMMPS_DOUBLE = 2,
LAMMPS_DOUBLE_2D = 3,
LAMMPS_INT64 = 4,
LAMMPS_INT64_2D = 5,
LAMMPS_STRING = 6
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.