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

1.1.2. Executing commands

This section documents the following functions:

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 LAMMPS act on a series of input file commands that are either read from a file or passed as strings. For example, this allows setup of a problem from an input script, and then running it in stages while performing other operations in between or concurrently. The caller can interleave the LAMMPS function calls with operations it performs, such as calls to extract information from or set information within LAMMPS, or calls to another code’s library.

Just as with input script parsing comments can be included in the file or strings, and expansion of variables with ${name} or $(expression) syntax is performed. Below is a short example using some of these functions.

/* define to make the otherwise hidden prototype for "lammps_open()" visible */
#define LAMMPS_LIB_MPI
#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;
}
void lammps_file(void *handle, const char *file)

Process LAMMPS input from a file.

This function processes commands in the file pointed to by filename line by line and thus functions very similar to the include command. The function returns when the end of the file is reached and the commands have completed.

The actual work is done by the functions Input::file(const char *) and Input::file().

Parameters:

  • handle – pointer to a previously created LAMMPS instance

  • filename – name of a file with LAMMPS input

char *lammps_command(void *handle, const char *cmd)

Process a single LAMMPS input command from a string.

This function tells LAMMPS to execute the single command in the string cmd. The entire string is considered as command and need not have a (final) newline character. Newline characters in the body of the string, however, will be treated as part of the command and will not start a second command. The function lammps_commands_string() processes a string with multiple command lines.

The function returns the name of the command on success or NULL when passing a string without a command.

Parameters:

  • handle – pointer to a previously created LAMMPS instance

  • cmd – string with a single LAMMPS command

Returns:

string with parsed command name or NULL

void lammps_commands_list(void *handle, int ncmd, const char **cmds)

Process multiple LAMMPS input commands from list of strings.

This function processes multiple commands from a list of strings by first concatenating the individual strings in cmds into a single string, inserting newline characters as needed. The combined string is passed to lammps_commands_string() for processing.

Parameters:

  • handle – pointer to a previously created LAMMPS instance

  • ncmd – number of lines in cmds

  • cmds – list of strings with LAMMPS commands

void lammps_commands_string(void *handle, const char *str)

Process a block of LAMMPS input commands from a single string.

This function processes a multi-line string similar to a block of commands from a file. The string may have multiple lines (separated by newline characters) and also single commands may be distributed over multiple lines with continuation characters (’&’). Those lines are combined by removing the ‘&’ and the following newline character. After this processing the string is handed to LAMMPS for parsing and executing.

Added in version 21Nov2023: The command is now able to process long strings with triple quotes and loops using jump SELF <label>.

Parameters:

  • handle – pointer to a previously created LAMMPS instance

  • str – string with block of LAMMPS input commands