\(\renewcommand{\AA}{\text{Å}}\)
1.1.5. Compute, fixes, variables
This section documents accessing or modifying data stored by computes, fixes, or variables in LAMMPS using the following functions:
-
void *lammps_extract_compute(void *handle, const char*, int, int)
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 using 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 orNULL
if not found.
-
void *lammps_extract_fix(void *handle, const char*, int, int, int, int)
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 returns
NULL
if the fix ID is not found or the requested data is not available.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
When requesting global data, the fix data can only be accessed one item at a time without access to the pointer itself. Thus this function will allocate storage for a single double value, copy 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_fix(handle,name,0,1,0,0); double value = *dptr; lammps_free((void *)dptr);
Note
LAMMPS cannot easily check if it is valid to access the data, so it may fail with an error. 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)
ncol – column index (only used for global arrays)
- Returns:
pointer (cast to
void *
) to the location of the requested data orNULL
if not found.
-
int lammps_extract_variable_datatype(void *handle, const char *name)
Get data type of a LAMMPS variable.
New 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 oflammps_extract_variable()
can use this information to decide how to cast thevoid *
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*, const char*)
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 toNULL
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 is to actual LAMMPS data. The pointer 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 the constant “LMP_SIZE_VECTOR”, which returns a
void *
pointer that can be dereferenced to an integer that is the length of the vector. This pointer needs to be deallocated when finished with it to avoid memory leaks.For other variable styles the returned pointer needs to be cast to a char pointer. It should not be deallocated.
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 are 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
- Returns:
pointer (cast to
void *
) to the location of the requested data orNULL
if not found.
-
int lammps_set_variable(void *handle, char *name, char *str)
Set the value of a string-style variable.
This function assigns a new value from the string str to the string-style variable name. Returns -1 if a variable of that name does not exist or 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_variable_info(void *handle, int idx, char *buf, int bufsize)
Retrieve informational string for a variable.
New in version TBD.
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
-
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
, andexamples/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
-
enumerator LAMMPS_NONE
-
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
, andexamples/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
-
enumerator LMP_STYLE_GLOBAL
-
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
, andexamples/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
-
enumerator LMP_TYPE_SCALAR
-
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
, andexamples/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)
-
enumerator LMP_VAR_EQUAL