1.4.1. Using the C++ API directly — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# 1.4.1. 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.

# 1.4.2. Creating or deleting a LAMMPS object

When using the LAMMPS library interfaces, the core task is to create an instance of the `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:

    #include "lammps.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 ID: " << lmp->num_ver << std::endl;
        // delete LAMMPS instance
        delete lmp;

        // stop MPI environment
        MPI_Finalize();
        return 0;
    }

This minimal example only requires to include the `lammps.h` header file since it only accesses a non-pointer member of the LAMMPS class.

# 1.4.3. 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 `Input` class an instance of which is a member of the `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:

    #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;
    }