add more existing programmer guide docs

Using the C++ API directly

**************************

Using the C++ classes of the LAMMPS library is lacking some of the

convenience of the C library API, but it allows a more direct access to

simulation data and thus more low-level manipulations and tighter

integration of LAMMPS into another code.  While for the complete C

library API is provided in the ``library.h`` header file, for using

the C++ API it is required to include the individual header files

defining the individual classes in use.  Typically the name of the

class and the name of the header follow some simple rule.  Examples

are given below.

Creating or deleting a LAMMPS object

*************************************

When using the LAMMPS library interfaces, the core task is to create an

instance of the :cpp:class:`LAMMPS_NS::LAMMPS` class.  In C++ this can

be done directly through the ``new`` operator.  All further operations

are then initiated through calling member functions of some of the

components of the LAMMPS class or accessing their data members.  The

destruction of the LAMMPS instance is correspondingly initiated by using

the ``delete`` operator.  Here is a simple example:

.. code-block:: c++

   #include "lammps.h"

   #include "universe.h"

   #include <mpi.h>

   #include <iostream>

   int main(int argc, char **argv)

   {

       LAMMPS_NS::LAMMPS *lmp;

       // custom argument vector for LAMMPS library

       const char *lmpargv[] {"liblammps", "-log", "none"};

       int lmpargc = sizeof(lmpargv)/sizeof(const char *);

       // explicitly initialize MPI

       MPI_Init(&argc, &argv);

       // create LAMMPS instance

       lmp = new LAMMPS_NS::LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);

       // output numerical version string

       std::cout << "LAMMPS version: " << lmp->universe->num_ver << std::endl;

       // delete LAMMPS instance

       delete lmp;

       // stop MPI environment

       MPI_Finalize();

       return 0;

   }

Please note that this requires to include the ``lammps.h`` header for accessing

the members of the LAMMPS class and then the ``universe.h`` header for accessing the ``num_ver`` member of the :cpp:class:`Universe` class.

Executing LAMMPS commands

*************************

Once a LAMMPS instance is created by your C++ code, you need to set up a

simulation and that is most conveniently done by "driving" it through

issuing commands like you would do when running a LAMMPS simulation from

an input script. Processing of input in LAMMPS is handled by the

:cpp:class:`Input <LAMMPS_NS::Input>` class an instance of which is a

member of the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class.  You have

two options: reading commands from a file, or executing a single

command from a string. See below for a small example:

.. code-block:: c++

   #include "lammps.h"

   #include "input.h"

   #include <mpi.h>

   using namespace LAMMPS_NS;

   int main(int argc, char **argv)

   {

       const char *lmpargv[] {"liblammps", "-log", "none"};

       int lmpargc = sizeof(lmpargv)/sizeof(const char *);

       MPI_Init(&argc, &argv);

       LAMMPS *lmp = new LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);

       lmp->input->file("in.melt");

       lmp->input->one("run 100 post no");

       delete lmp;

       return 0;

   }

Adding code to the Library interface

====================================

The functionality of the LAMMPS library interface has historically

always been motivated by the needs of its users and functions were

added or expanded as they were needed and used.  Contributions to

the interface are always welcome.  However with a refactoring of

the library interface and its documentation that started in 2020,

there are now a few requirements for inclusion of changes.

  - New functions should be orthogonal to existing ones and not

    implement functionality that can already be achieved with the

    existing APIs.

  - All changes and additions should be documented with

    `Doxygen <https://doxgygen.org>`_ style comments and references

    to those functions added to the corresponding files in the

    ``doc/src`` folder.

  - If possible, new unit tests to test those new features should

    be added.

  - The new feature should also be implemented and documented for

    the Python and Fortran modules.

  - All additions should work and be compatible with ``-DLAMMPS_BIGBIG``,

    ``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` and compiling

    with and without MPI support.

  - The ``library.h`` file should be kept compatible to C code at

    a level similar to C89. Its interfaces may not reference any

    custom data types (e.g. ``bigint``, ``tagint``, and so on) only

    known inside of LAMMPS.

  - only C style comments, not C++ style

Please note, that these are *not* *strict* requirements, but the

LAMMPS developers appreciate if they are followed closely and will

assist with implementing what is missing.

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.

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

.. doxygenfunction:: lammps_config_has_mpi_support

   :project: progguide

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

.. doxygenfunction:: lammps_config_has_gzip_support

   :project: progguide

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

.. doxygenfunction:: lammps_config_has_png_support

   :project: progguide

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

.. doxygenfunction:: lammps_config_has_jpeg_support

   :project: progguide

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

.. doxygenfunction:: lammps_config_has_ffmpeg_support

   :project: progguide

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

.. doxygenfunction:: lammps_config_has_exceptions

   :project: progguide

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

.. doxygenfunction:: lammps_config_has_package

   :project: progguide

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

.. doxygenfunction:: lammps_config_package_count

   :project: progguide

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

.. doxygenfunction:: lammps_config_package_name

   :project: progguide

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

.. doxygenfunction:: lammps_has_style

   :project: progguide

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

.. doxygenfunction:: lammps_style_count

   :project: progguide

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

.. doxygenfunction:: lammps_style_name

   :project: progguide

Creating or deleting a LAMMPS object

====================================

The :cpp:func:`lammps_open` and :cpp:func:`lammps_open_no_mpi`

functions are used to create and initialize a

:cpp:func:`LAMMPS` instance.  The calling program has to

provide a handle where a reference to this instance can be stored and

which has to be used in all subsequent function calls until that

instance is destroyed by calling :cpp:func:`lammps_close`.

Here is a simple example demonstrating its use:

.. code-block:: C

   #include "library.h"

   #include <stdio.h>

   int main(int argc, char **argv)

   {

     void *handle;

     int version;

     const char *lmpargv[] = { "liblammps", "-log", "none"};

     int lmpargc = sizeof(lmpargv)/sizeof(const char *);

     /* create LAMMPS instance */

     handle = lammps_open_no_mpi(lmpargc, lmpargv, NULL);

     if (handle == NULL) {

       printf("LAMMPS initialization failed");

       lammps_mpi_finalize();

       return 1;

     }

     /* get and print numerical version code */

     version = lammps_version(handle);

     printf("LAMMPS Version: %d\n",version);

     /* delete LAMMPS instance and shut down MPI */

     lammps_close(handle);

     lammps_mpi_finalize();

     return 0;

   }

The LAMMPS library will be using the MPI library it was compiled with

and will either run on all processors in the ``MPI_COMM_WORLD``

communicator or on the set of processors in the communicator given in

the ``comm`` argument of :cpp:func:`lammps_open`.  This means

the calling code can run LAMMPS on all or a subset of processors.  For

example, a wrapper code might decide to alternate between LAMMPS and

another code, allowing them both to run on all the processors.  Or it

might allocate part of the processors to LAMMPS and the rest to the

other code by creating a custom communicator with ``MPI_Comm_split()``

and running both codes concurrently before syncing them up periodically.

Or it might instantiate multiple instances of LAMMPS to perform

different calculations and either alternate between them, run them

concurrently on split communicators, or run them one after the other.

The :cpp:func:`lammps_open` function may be called multiple

times for this latter purpose.

The :cpp:func:`lammps_close` function is used to shut down

the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class pointed to by the handle

passed as an argument and free all its memory. This has to be called for

every instance created with any of the :cpp:func:`lammps_open` functions.  It will, however, **not** call

``MPI_Finalize()``, since that may only be called once.  See

:cpp:func:`lammps_mpi_finalize` for an alternative to calling

``MPI_Finalize()`` explicitly in the calling program.

The :cpp:func:`lammps_free` function is a clean-up

function to free memory that the library allocated previously

via other function calls.  See below for notes in the descriptions

of the individual commands where such memory buffers were allocated.

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

.. doxygenfunction:: lammps_open

   :project: progguide

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

.. doxygenfunction:: lammps_open_no_mpi

   :project: progguide

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

.. doxygenfunction:: lammps_open_fortran

   :project: progguide

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

.. doxygenfunction:: lammps_close

   :project: progguide

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

.. doxygenfunction:: lammps_mpi_init

   :project: progguide

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

.. doxygenfunction:: lammps_mpi_finalize

   :project: progguide

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

.. doxygenfunction:: lammps_free

   :project: progguide

Executing LAMMPS commands

=========================

Once a LAMMPS instance is created, there are multiple ways to "drive" a

simulation.  In most cases it is easiest to process single or multiple

LAMMPS commands like in an input file.  This can be done through reading

a file or passing single commands or lists of commands or blocks of

commands with the following functions.

Via these functions, the calling code can have the LAMMPS instance act

on a series of :doc:`input file commands <Commands_all>` that are either

read from a file or passed as strings.  This for, for example, allows to

setup a problem from a template file and then run it in stages while

performing other operations in between or concurrently.  The caller can

interleave the LAMMPS function calls with operations it performs, calls

to extract information from or set information within LAMMPS, or calls

to another code's library.

Also equivalent to regular :doc:`input script parsing <Commands_parse>`

is the handling of comments and expansion of variables with ``${name}``

or ``$(expression)`` syntax before the commands are parsed and

executed. Below is a short example using some of these functions.

.. code-block:: C

   #include "library.h"

   #include <mpi.h>

   #include <stdio.h>

   int main(int argc, char **argv)

   {

     void *handle;

     int i;

     MPI_Init(&argc, &argv);

     handle = lammps_open(0, NULL, MPI_COMM_WORLD, NULL);

     lammps_file(handle,"in.sysinit");

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

     for (i=0; i < 100; ++i) {

       lammps_commands_string(handle,"run 100 pre no post no\n"

                                     "print 'PE = $(pe)'\n"

                                     "print 'KE = $(ke)'\n");

     }

     lammps_close(handle);

     MPI_Finalize();

     return 0;

   }

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

.. doxygenfunction:: lammps_file

   :project: progguide

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

.. doxygenfunction:: lammps_command

   :project: progguide

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

.. doxygenfunction:: lammps_commands_list

   :project: progguide

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

.. doxygenfunction:: lammps_commands_string

   :project: progguide