Merge pull request #2362 from akohlmey/library-progguide (16544400) · Commits · 郑智淋 / lammps

doc/src/pg_lib_config.rst

+45 −3

Original line number	Diff line number	Diff line
		Retrieving LAMMPS configuration information
		===========================================

		The following library functions can be used to query the
		LAMMPS library about compile time settings and included
		packages and styles.
		The following library functions can be used to query the LAMMPS library
		about compile time settings and included packages and styles. This
		enables programs that use the library interface to run LAMMPS
		simulations to determine, whether the linked LAMMPS library is compatible
		with the requirements of the application without crashing during the
		LAMMPS functions (e.g. due to missing pair styles from packages) or to
		choose between different options (e.g. whether to use ``lj/cut``,
		``lj/cut/opt``, ``lj/cut/omp`` or ``lj/cut/intel``). Most of the
		functions can be called directly without first creating a LAMMPS
		instance. While crashes within LAMMPS may be recovered from through
		enabling :ref:`exceptions <exceptions>`, avoiding them proactively is
		a safer approach.

		.. code-block:: C
		:caption: Example for using configuration settings functions

		#include "library.h"
		#include <stdio.h>

		int main(int argc, char **argv)
		{
		void *handle;

		handle = lammps_open_no_mpi(0, NULL, NULL);
		lammps_file(handle, "in.missing");
		if (lammps_has_error(handle)) {
		char errmsg[256];
		int errtype;
		errtype = lammps_get_last_error_message(handle, errmsg, 256);
		fprintf(stderr, "LAMMPS failed with error: %s\n", errmsg);
		return 1;
		}
		/* write compressed dump file depending on available of options */
		if (lammps_has_style(handle, "dump", "atom/zstd")) {
		lammps_command(handle, "dump d1 all atom/zstd 100 dump.zst");
		} else if (lammps_has_style(handle, "dump", "atom/gz")) {
		lammps_command(handle, "dump d1 all atom/gz 100 dump.gz");
		} else if (lammps_config_has_gzip_support()) {
		lammps_command(handle, "dump d1 all atom 100 dump.gz");
		} else {
		lammps_command(handle, "dump d1 all atom 100 dump");
		}
		lammps_close(handle);
		return 0;
		}

		-----------------------

doc/src/pg_lib_properties.rst

+30 −2

Original line number	Diff line number	Diff line
		@@ -2,8 +2,8 @@ Retrieving or setting LAMMPS system properties
		==============================================

		The library interface allows to extract different kinds of information
		about the active simulation instance and also to modify some of them.
		This allows to combine MD simulation steps with other processing and
		about the active simulation instance and also to modify some of it.
		This enables combining MD simulation steps with other processing and
		simulation methods computed in the calling code or another code that is
		coupled to LAMMPS via the library interface. In some cases the data
		returned is direct reference to the original data inside LAMMPS cast
		@@ -14,6 +14,34 @@ is the per-processor local data and indexed accordingly. These arrays
		can change sizes and order at every neighbor list rebuild and atom sort
		event as atoms are migrating between sub-domains.

		.. code-block:: C

		#include "library.h"
		#include <stdio.h>

		int main(int argc, char **argv)
		{
		void *handle;
		int i;

		handle = lammps_open_no_mpi(0, NULL, NULL);
		lammps_file(handle,"in.sysinit");
		printf("running simulation with %g atoms\n",
		lammps_get_natoms(handle));

		lammps_command(handle,"run 1000 post no");

		for (i=0; i < 10; ++i) {
		lammps_command(handle,"run 100 pre no post no");
		printf("PE = %g\nKE = %g\n",
		lammps_get_thermo(handle,"pe"),
		lammps_get_thermo(handle,"ke"));
		}
		lammps_close(handle);
		return 0;
		}


		-----------------------

		.. doxygenfunction:: lammps_version

src/atom.cpp

+1 −1

Original line number	Diff line number	Diff line
		@@ -2508,7 +2508,7 @@ length of the data area, and a short description.
		Typically the name of the pointer variable returned
		* \return pointer to the requested data cast to ``void `` or NULL /

		void Atom::extract(char name)
		void Atom::extract(const char name)
		{
		// --------------------------------------------------------------------
		// 4th customization section: customize by adding new variable name

src/atom.h

+1 −1

Original line number	Diff line number	Diff line
		@@ -331,7 +331,7 @@ class Atom : protected Pointers {

		virtual void sync_modify(ExecutionSpace, unsigned int, unsigned int) {}

		void extract(char );
		void extract(const char );

		inline int* get_map_array() {return map_array;};
		inline int get_map_size() {return map_tag_max+1;};

src/library.cpp

+21 −19

Original line number	Diff line number	Diff line
		@@ -616,7 +616,7 @@ a double, so it can also return information that is computed on-the-fly.
		* \param keyword string with the name of the thermo keyword
		* \return value of the requested thermo property or 0.0 */

		double lammps_get_thermo(void handle, char keyword)
		double lammps_get_thermo(void handle, const char keyword)
		{
		LAMMPS lmp = (LAMMPS ) handle;
		double dval = 0.0;
		@@ -807,7 +807,7 @@ recognized, the function returns -1. Please also see :cpp:func:`lammps_extract_
		* \param keyword string with the name of the thermo keyword
		* \return value of the queried setting or -1 if unknown */

		int lammps_extract_setting(void * handle, char *keyword)
		int lammps_extract_setting(void handle, const char keyword)
		{
		LAMMPS lmp = (LAMMPS ) handle;

		@@ -865,7 +865,8 @@ Please also see :cpp:func:`lammps_extract_setting`,
		This table lists the supported names, their data types, length of the
		data area, and a short description. The ``bigint`` type may be defined
		to be either an ``int`` or an ``int64_t``. This is selected at
		:ref:`compile time <size>`.
		:ref:`compile time <size>` and can be queried through calling
		:cpp:func:`lammps_extract_setting`.

		.. list-table::
		:header-rows: 1
		@@ -1073,7 +1074,7 @@ to be either an ``int`` or an ``int64_t``. This is selected at
		* \return pointer (cast to ``void *``) to the location of the
		requested property. NULL if name is not known. */

		void lammps_extract_global(void handle, char *name)
		void lammps_extract_global(void handle, const char *name)
		{
		LAMMPS lmp = (LAMMPS ) handle;

		@@ -1165,7 +1166,7 @@ of the :cpp:func:`Atom::extract() <LAMMPS_NS::Atom::extract>` function.
		* \return pointer (cast to ``void *``) to the location of the
		* requested data or ``NULL`` if not found. */

		void lammps_extract_atom(void handle, char *name)
		void lammps_extract_atom(void handle, const char *name)
		{
		LAMMPS lmp = (LAMMPS ) handle;
		return lmp->atom->extract(name);
		@@ -3724,7 +3725,7 @@ specific :doc:`LAMMPS package <Packages>` provided as argument.
		* \param name string with the name of the package
		* \return 1 if included, 0 if not.
		*/
		int lammps_config_has_package(char * name) {
		int lammps_config_has_package(const char *name) {
		return Info::has_package(name) ? 1 : 0;
		}

		@@ -3792,10 +3793,10 @@ Valid categories are: atom\ , integrate\ , minimize\ ,
		* \param name name of the style
		* \return 1 if included, 0 if not.
		*/
		int lammps_has_style(void * handle, char * category, char * name) {
		int lammps_has_style(void handle, const char category, const char *name) {
		LAMMPS lmp = (LAMMPS ) handle;
		Info info(lmp);
		return info.has_style(category, name) ? 0 : 1;
		return info.has_style(category, name) ? 1 : 0;
		}

		/* ---------------------------------------------------------------------- */
		@@ -3813,7 +3814,7 @@ categories.
		* \param category category of styles
		* \return number of styles in category
		*/
		int lammps_style_count(void * handle, char * category) {
		int lammps_style_count(void handle, const char category) {
		LAMMPS lmp = (LAMMPS ) handle;
		Info info(lmp);
		return info.get_available_styles(category).size();
		@@ -3839,7 +3840,8 @@ Please see :cpp:func:`lammps_has_style` for a list of valid categories.
		* \param buf_size size of the provided string buffer
		* \return 1 if successful, otherwise 0
		*/
		int lammps_style_name(void* handle, char * category, int idx, char * buffer, int buf_size) {
		int lammps_style_name(void handle, const char category, int idx,
		char *buffer, int buf_size) {
		LAMMPS lmp = (LAMMPS ) handle;
		Info info(lmp);
		auto styles = info.get_available_styles(category);

Admin message