1.1.5. Computes, fixes, variables — LAMMPS documentation

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

# 1.1.5. Computes, fixes, variables

This section documents accessing or modifying data stored by computes, fixes, or variables in LAMMPS using the following functions:

- `lammps_extract_compute()`

- `lammps_extract_fix()`

- `lammps_extract_variable_datatype()`

- `lammps_extract_variable()`

- `lammps_set_variable()`

- `lammps_set_string_variable()`

- `lammps_set_internal_variable()`

- `lammps_variable_info()`

- `lammps_eval()`

- `lammps_clearstep_compute()`

- `lammps_addstep_compute_all()`

- `lammps_addstep_compute()`

void *lammps_extract_compute(void *handle, const char *id, int style, int type)

  Get pointer to data from a LAMMPS compute.

  This function returns a pointer to the location of data provided by a compute command instance identified by the compute-ID. Computes may provide global, per-atom, or local data, and those may be a scalar, a vector, or an array or they may provide the information about the dimensions of the respective data. Since computes may provide multiple kinds of data, it is required to set style and type flags representing what specific data is desired. This also determines to what kind of pointer the returned pointer needs to be cast to access the data correctly. The function returns `NULL` if the compute ID is not found or the requested data is not available or current. The following table lists the available options.

  Style (see `_LMP_STYLE_CONST`) | Type (see `_LMP_TYPE_CONST`) | Returned type | Returned data
  --- | --- | --- | ---
  LMP_STYLE_GLOBAL | LMP_TYPE_SCALAR | `double *` | Global scalar
  LMP_STYLE_GLOBAL | LMP_TYPE_VECTOR | `double *` | Global vector
  LMP_STYLE_GLOBAL | LMP_TYPE_ARRAY | `double **` | Global array
  LMP_STYLE_GLOBAL | LMP_SIZE_VECTOR | `int *` | Length of global vector
  LMP_STYLE_GLOBAL | LMP_SIZE_ROWS | `int *` | Rows of global array
  LMP_STYLE_GLOBAL | LMP_SIZE_COLS | `int *` | Columns of global array
  LMP_STYLE_ATOM | LMP_TYPE_VECTOR | `double *` | Per-atom value
  LMP_STYLE_ATOM | LMP_TYPE_ARRAY | `double **` | Per-atom vector
  LMP_STYLE_ATOM | LMP_SIZE_COLS | `int *` | Columns in per-atom array, 0 if vector
  LMP_STYLE_LOCAL | LMP_TYPE_VECTOR | `double *` | Local data vector
  LMP_STYLE_LOCAL | LMP_TYPE_ARRAY | `double **` | Local data array
  LMP_STYLE_LOCAL | LMP_SIZE_VECTOR | `int *` | Alias for LMP_SIZE_ROWS
  LMP_STYLE_LOCAL | LMP_SIZE_ROWS | `int *` | Number of local array rows or length of vector
  LMP_STYLE_LOCAL | LMP_SIZE_COLS | `int *` | Number of local array columns, 0 if vector

  Note

  If the compute’s data is not computed for the current step, the compute will be invoked. LAMMPS cannot easily check at that time, if it is valid to invoke a compute, so it may fail with an error. The caller has to check to avoid such an error.

  Warning

  The pointers returned by this function are generally not persistent since the computed data may be re-distributed, re-allocated, and re-ordered at every invocation. It is advisable to re-invoke this function before the data is accessed, or make a copy if the data shall be used after other LAMMPS commands have been issued.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - id – string with ID of the compute

    - style – constant indicating the style of data requested (global, per-atom, or local)

    - type – constant indicating type of data (scalar, vector, or array) or size of rows or columns

  Returns:

    pointer (cast to `void *`) to the location of the requested data or `NULL` if not found.

void *lammps_extract_fix(void *handle, const char *id, int style, int type, int nrow, int ncol)

  Get pointer to data from a LAMMPS fix.

  This function returns a pointer to data provided by a fix command instance identified by its fix-ID. Fixes may provide global, per-atom, or local data, and those may be a scalar, a vector, or an array, or they may provide the information about the dimensions of the respective data. Since individual fixes may provide multiple kinds of data, it is required to set style and type flags representing what specific data is desired. This also determines to what kind of pointer the returned pointer needs to be cast to access the data correctly. The function set the error status and returns `NULL` if the fix ID is not found or the requested data is not available.

  Accessing global data

  When requesting global data, the fix data can internally only be accessed one item at a time without access to the underlying pointer itself (it may also be computed on-the-fly). Thus this function allocates temporary storage for the requested data, copy the the data to it, and return a pointer to the location of the copy. Therefore the allocated storage needs to be freed with `lammps_free()` after its use to avoid a memory leak. Example:

      double *dptr = (double *) lammps_extract_fix(handle, name, LMP_STYLE_GLOBAL, LMP_TYPE_VECTOR, 0, 0);
      double value = *dptr;
      lammps_free((void *)dptr);

  Requesting rows, columns, or the entire global array

  In order to avoid the inefficient allocation and deallocation of temporary storage for single values, this functions accepts special values of -1 for the nrow and ncol arguments. For the negative values, the entire row, or column, or full array is copied to a (flat) block of storage and its pointer returned. This still is a copy and needs to be deallocated with `lammps_free()` as indicated in the note above. In case of requesting the whole array, the data is returned column by column, i.e. as d(c_0,r_0), d(c_0,r_1), … d(c_0, c_nrow-1), d(c_1,r_0), d(c_1,r_1), … d(c_ncol-1, r_nrow-1) for a total of nrow * ncol elements. Example use:

      int nrows = *(int *) lammps_extract_fix(handle, name, LMP_STYLE_GLOBAL, LMP_SIZE_ROWS, 0,0);
      int ncols = *(int *) lammps_extract_fix(handle, name, LMP_STYLE_GLOBAL, LMP_SIZE_COLS, 0,0);
      double *dptr = (double *) lammps_extract_fix(handle, name, LMP_STYLE_GLOBAL, LMP_TYPE_ARRAY, -1, -1);
      printf("values[%d][%d] = {\n", ncols, nrows);
      for (int j = 0; j < ncols; ++j) {
        printf(" { ");
        for (int i = 0; i < nrows; ++i) printf("%g, ", dvalue[j * nrows + i]);
        printf("},\n");
      }
      printf("};\n");
      lammps_free((void *)dptr);

  The following table lists the available options.

  Style (see `_LMP_STYLE_CONST`) | Type (see `_LMP_TYPE_CONST`) | Returned type | Returned data
  --- | --- | --- | ---
  LMP_STYLE_GLOBAL | LMP_TYPE_SCALAR | `double *` | Copy of global scalar
  LMP_STYLE_GLOBAL | LMP_TYPE_VECTOR | `double *` | Copy of global vector element at index nrow
  LMP_STYLE_GLOBAL | LMP_TYPE_ARRAY | `double *` | Copy of global array element at nrow, ncol
  LMP_STYLE_GLOBAL | LMP_SIZE_VECTOR | `int *` | Length of global vector
  LMP_STYLE_GLOBAL | LMP_SIZE_ROWS | `int *` | Rows in global array
  LMP_STYLE_GLOBAL | LMP_SIZE_COLS | `int *` | Columns in global array
  LMP_STYLE_ATOM | LMP_TYPE_VECTOR | `double *` | Per-atom value
  LMP_STYLE_ATOM | LMP_TYPE_ARRAY | `double **` | Per-atom vector
  LMP_STYLE_ATOM | LMP_SIZE_COLS | `int *` | Columns of per-atom array, 0 if vector
  LMP_STYLE_LOCAL | LMP_TYPE_VECTOR | `double *` | Local data vector
  LMP_STYLE_LOCAL | LMP_TYPE_ARRAY | `double **` | Local data array
  LMP_STYLE_LOCAL | LMP_SIZE_ROWS | `int *` | Number of local data rows
  LMP_STYLE_LOCAL | LMP_SIZE_COLS | `int *` | Number of local data columns

  Note

  LAMMPS cannot easily check if it is valid to access the data, so it may fail with an error and return a NULL pointer. The caller has to avoid such an error.

  Warning

  The pointers returned by this function for per-atom or local data are generally not persistent, since the computed data may be re-distributed, re-allocated, and re-ordered at every invocation of the fix. It is thus advisable to re-invoke this function before the data is accessed, or make a copy, if the data shall be used after other LAMMPS commands have been issued.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - id – string with ID of the fix

    - style – constant indicating the style of data requested (global, per-atom, or local)

    - type – constant indicating type of data (scalar, vector, or array) or size of rows or columns

    - nrow – row index (only used for global vectors and arrays), zero-based

    - ncol – column index (only used for global arrays), zero-based

  Returns:

    pointer (cast to `void *`) to the location of the requested data or `NULL` if not found.

int lammps_extract_variable_datatype(void *handle, const char *name)

  Get data type of a LAMMPS variable.

  Added in version 3Nov2022.

  This function returns an integer that encodes the data type of the variable with the specified name. See `_LMP_VAR_CONST` for valid values. Callers of `lammps_extract_variable()` can use this information to decide how to cast the `void *` pointer and access the data.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - name – string with the name of the extracted variable

  Returns:

    integer constant encoding the data type of the property or -1 if not found.

void *lammps_extract_variable(void *handle, const char *name, const char *group)

  Get pointer to data from a LAMMPS variable.

  This function returns a pointer to data from a LAMMPS variable command identified by its name. When the variable is either an equal-style compatible variable, a vector-style variable, or an atom-style variable, the variable is evaluated and the corresponding value(s) returned. Variables of style internal are compatible with equal-style variables and so are python-style variables, if they return a numeric value. For other variable styles, their string value is returned. The function returns `NULL` when a variable of the provided name is not found or of an incompatible style. The group argument is only used for atom-style variables and ignored otherwise, with one exception: for style vector, if group is “GET_VECTOR_SIZE”, the returned pointer will yield the length of the vector to be returned when dereferenced. This pointer must be deallocated after the value is read to avoid a memory leak. If group is set to `NULL` when extracting data from an atom-style variable, the group is assumed to be “all”.

  When requesting data from an equal-style or compatible variable this function allocates storage for a single double value, copies the returned value to it, and returns a pointer to the location of the copy. Therefore the allocated storage needs to be freed after its use to avoid a memory leak. Example:

      double *dptr = (double *) lammps_extract_variable(handle, name, NULL);
      double value = *dptr;
      lammps_free((void *)dptr);

  For atom-style variables, the return value is a pointer to an allocated block of storage of double of the length `atom->nlocal`. Since the data returned are a copy, the location will persist, but its content will not be updated in case the variable is re-evaluated. To avoid a memory leak, this pointer needs to be freed after use in the calling program.

  For vector-style variables, the returned pointer points to actual LAMMPS data and thus it should not be deallocated. Its length depends on the variable, compute, or fix data used to construct the vector-style variable. This length can be fetched by calling this function with group set to a non-NULL pointer (NULL returns the vector). In that case it will return the vector length as an allocated int pointer cast to a `void *` pointer. That pointer can be recast and dereferenced to an integer yielding the length of the vector. This pointer must be deallocated when finished with it to avoid memory leaks. Example:

      double *vectvals = (double *) lammps_extract_variable(handle, name, NULL);
      int *intptr = (int *) lammps_extract_variable(handle, name, 1);
      int vectlen = *intptr;
      lammps_free((void *)intptr);

  For other variable styles the returned pointer needs to be cast to a char pointer and it should not be deallocated. Example:

      const char *cptr = (const char *) lammps_extract_variable(handle,name,NULL);
      printf("The value of variable %s is %s\n", name, cptr);

  Note

  LAMMPS cannot easily check if it is valid to access the data referenced by the variables (e.g., computes, fixes, or thermodynamic info), so it may fail with an error. The caller has to make certain that the data is extracted only when it safe to evaluate the variable and thus an error or crash are avoided.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - name – name of the variable

    - group – group-ID for atom style variable or `NULL` or non-NULL to get vector length

  Returns:

    pointer (cast to `void *`) to the location of the requested data or `NULL` if not found.

int lammps_set_variable(void *handle, const char *name, const char *str)

  Set the value of a string-style variable.

  Deprecated since version 7Feb2024.

  This function assigns a new value from the string str to the string-style variable name. This is a way to directly change the string value of a LAMMPS variable that was previous defined with a variable name string command without using any LAMMPS commands to delete and redefine the variable.

  Returns -1 if a variable of that name does not exist or if it is not a string-style variable, otherwise 0.

  Warning

  This function is deprecated and `lammps_set_string_variable()` should be used instead.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - name – name of the variable

    - str – new value of the variable

  Returns:

    0 on success or -1 on failure

int lammps_set_string_variable(void *handle, const char *name, const char *str)

  Set the value of a string-style variable.

  Added in version 7Feb2024.

  This function assigns a new value from the string str to the string-style variable name. This is a way to directly change the string value of a LAMMPS variable that was previous defined with a variable name string command without using any LAMMPS commands to delete and redefine the variable.

  Returns -1 if a variable of that name does not exist or if it is not a string-style variable, otherwise 0.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - name – name of the variable

    - str – new value of the variable

  Returns:

    0 on success or -1 on failure

int lammps_set_internal_variable(void *handle, const char *name, double value)

  Set the value of an internal-style variable.

  Added in version 7Feb2024.

  This function assigns a new value from the floating point number value to the internal-style variable name. This is a way to directly change the numerical value of such a LAMMPS variable that was previous defined with a variable name internal command without using any LAMMPS commands to delete and redefine the variable.

  Returns -1 if a variable of that name does not exist or is not an internal-style variable, otherwise 0.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance

    - name – name of the variable

    - value – new value of the variable

  Returns:

    0 on success or -1 on failure

int lammps_variable_info(void *handle, int idx, char *buf, int bufsize)

  Retrieve informational string for a variable.

  Added in version 21Nov2023.

  This function copies a string with human readable information about a defined variable: name, style, current value(s) into the provided C-style string buffer. That is the same info as produced by the info variables command. The length of the buffer must be provided as buf_size argument. If the info exceeds the length of the buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to an empty string, otherwise 1.

  Parameters:

    - handle – pointer to a previously created LAMMPS instance cast to `void *`.

    - idx – index of the variable (0 <= idx < nvar)

    - buffer – string buffer to copy the info to

    - buf_size – size of the provided string buffer

  Returns:

    1 if successful, otherwise 0

double lammps_eval(void *handle, const char *expr)

  Evaluate an immediate variable expression

  Added in version 4Feb2025.

  This function takes a string with an expression that can be used for equal style variables, evaluates it and returns the resulting (scalar) value as a floating point number.

  See also

    `lammps_expand()`

  Parameters:

    - handle – pointer to a previously created LAMMPS instance cast to `void *`.

    - expr – string with expression

  Returns:

    result from expression

void lammps_clearstep_compute(void *handle)

  Clear whether a compute has been invoked.

  Added in version 4Feb2025: This function clears the invoked flag of all computes. Called everywhere that computes are used, before computes are invoked. The invoked flag is used to avoid re-invoking same compute multiple times and to flag computes that store invocation times as having been invoked

  See also

    `lammps_addstep_compute_all()` `lammps_addstep_compute()`

  Parameters:

    handle – pointer to a previously created LAMMPS instance cast to `void *`.

void lammps_addstep_compute_all(void *handle, void *nextstep)

  Add next timestep to all computes

  Added in version 4Feb2025: loop over all computes schedule next invocation for those that store invocation times called when not sure what computes will be needed on newstep do not loop only over n_timeflag, since may not be set yet

  See also

    `lammps_clearstep_compute()` `lammps_addstep_compute()`

  Parameters:

    - handle – pointer to a previously created LAMMPS instance cast to `void *`.

    - newstep – pointer to bigint of next timestep the compute will be invoked

void lammps_addstep_compute(void *handle, void *nextstep)

  Add next timestep to compute if it has been invoked in the current timestep

  Added in version 4Feb2025: loop over computes that store invocation times if its invoked flag set on this timestep, schedule next invocation called everywhere that computes are used, after computes are invoked

  See also

    `lammps_addstep_compute_all()` `lammps_clearstep_compute()`

  Parameters:

    - handle – pointer to a previously created LAMMPS instance cast to `void *`.

    - newstep – next timestep the compute will be invoked

enum LAMMPS_NS:: multitype::_LMP_DATATYPE_CONST

  Data type constants for extracting data from atoms, computes and fixes

  This enum must be kept in sync with the corresponding enum or constants in `python/lammps/constants.py`, `fortran/lammps.f90`, `tools/swig/lammps.i`, `src/library.h`, and `examples/COUPLE/plugin/liblammpsplugin.h`

  Values:

  enumerator LAMMPS_NONE

    no data type assigned (yet)

  enumerator LAMMPS_INT

    32-bit integer (array)

  enumerator LAMMPS_INT_2D

    two-dimensional 32-bit integer array

  enumerator LAMMPS_DOUBLE

    64-bit double (array)

  enumerator LAMMPS_DOUBLE_2D

    two-dimensional 64-bit double array

  enumerator LAMMPS_INT64

    64-bit integer (array)

  enumerator LAMMPS_INT64_2D

    two-dimensional 64-bit integer array

  enumerator LAMMPS_STRING

    C-String

enum _LMP_STYLE_CONST

  Style constants for extracting data from computes and fixes.

  Must be kept in sync with the equivalent constants in `python/lammps/constants.py`, `fortran/lammps.f90`, `tools/swig/lammps.i`, and `examples/COUPLE/plugin/liblammpsplugin.h`

  Values:

  enumerator LMP_STYLE_GLOBAL

    return global data

  enumerator LMP_STYLE_ATOM

    return per-atom data

  enumerator LMP_STYLE_LOCAL

    return local data

enum _LMP_TYPE_CONST

  Type and size constants for extracting data from computes and fixes.

  Must be kept in sync with the equivalent constants in `python/lammps/constants.py`, `fortran/lammps.f90`, `tools/swig/lammps.i`, and `examples/COUPLE/plugin/liblammpsplugin.h`

  Values:

  enumerator LMP_TYPE_SCALAR

    return scalar

  enumerator LMP_TYPE_VECTOR

    return vector

  enumerator LMP_TYPE_ARRAY

    return array

  enumerator LMP_SIZE_VECTOR

    return length of vector

  enumerator LMP_SIZE_ROWS

    return number of rows

  enumerator LMP_SIZE_COLS

    return number of columns

enum _LMP_VAR_CONST

  Variable style constants for extracting data from variables.

  Must be kept in sync with the equivalent constants in `python/lammps/constants.py`, `fortran/lammps.f90`, `tools/swig/lammps.i`, and `examples/COUPLE/plugin/liblammpsplugin.h`

  Values:

  enumerator LMP_VAR_EQUAL

    compatible with equal-style variables

  enumerator LMP_VAR_ATOM

    compatible with atom-style variables

  enumerator LMP_VAR_VECTOR

    compatible with vector-style variables

  enumerator LMP_VAR_STRING

    return value will be a string (catch-all)