From 635b7c04a58422af2d7cfa8eebe09fd59ff31fa7 Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Fri, 18 Sep 2020 14:49:25 -0400 Subject: [PATCH] Update docs and docstrings --- doc/src/pg_lib_properties.rst | 11 ++++++ doc/src/pg_python.rst | 19 ++++++++++ python/lammps.py | 68 +++++++++++++++++++++-------------- src/library.cpp | 17 ++++++--- src/library.h | 14 ++++---- 5 files changed, 92 insertions(+), 37 deletions(-) diff --git a/doc/src/pg_lib_properties.rst b/doc/src/pg_lib_properties.rst index 256ed1cf82..bf36dcb8b1 100644 --- a/doc/src/pg_lib_properties.rst +++ b/doc/src/pg_lib_properties.rst @@ -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 diff --git a/doc/src/pg_python.rst b/doc/src/pg_python.rst index 7b084a3461..87310d43e7 100644 --- a/doc/src/pg_python.rst +++ b/doc/src/pg_python.rst @@ -359,6 +359,10 @@ The :py:mod:`lammps` module additionally contains several constants and the :py:class:`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 ` 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 ` 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 ` 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: diff --git a/python/lammps.py b/python/lammps.py index 7e06de6c99..832a7f3d4d 100644 --- a/python/lammps.py +++ b/python/lammps.py @@ -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) diff --git a/src/library.cpp b/src/library.cpp index f03b7556dd..6ee0c20b8c 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -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) { diff --git a/src/library.h b/src/library.h index 66dfd18205..2ddad86baa 100644 --- a/src/library.h +++ b/src/library.h @@ -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.