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:

lammps_extract_compute()
lammps_extract_fix()
lammps_extract_variable()
lammps_set_variable()

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_ROWS	`int *`	Number of local data rows
LMP_STYLE_LOCAL	LMP_SIZE_COLS	`int *`	Number of local data columns

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*, 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 or NULL 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 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. If set to NULL when extracting data from and 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 data returned is a pointer to an allocated block of storage of double of the length atom->nlocal. Since the data is returned 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 other variable styles the returned pointer needs to be cast to a char pointer.

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 or 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 and crash is 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 or NULL if not found.

int lammps_set_variable(void*, char*, char*)¶

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

enum _LMP_DATATYPE_CONST¶

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

Must be kept in sync with the equivalent constants in lammps/constants.py

Values:

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 lammps/constants.py

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 lammps/constants.py

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