Output from a command inside the input script

Commands and variables can be referenced via id_ID and v_ID, respectively. Here ID is the id name as chosen by the user. Next, these references can be used to access more specific internal data of the command or variable. To understand how to use the output from commands and variables, it is important to understand that output data has a dimension and a style.

Data dimension: scalar, vector and matrix

Any output can come in three dimensions: as a scalar (single value), as a vector (1D array of values) or as a matrix (2D array of values). The documentation page for a command or variable that generates data will specify the dimension of the output: scalar, vector, matrix.

When a quantity is accessed, as in many of the output commands discussed below, it can be referenced via the following bracket notation. Note that the leading “id_” would be replaced by “v_” for a variable.

For some commands (mesh, mesh_modules, check_timestep, set_velocity) elements can be accessed through a property_name. This makes it easier to access specific properties, as it is not required to know which position (I,J) represents a specific property.

id_ID	entire scalar, vector, or matrix
id_ID[I]	element (I) of a vector, vector (I) of a matrix
id_ID[I][J]	element (I,J) of a matrix
id_ID.property_name	property of a command (returns a scalar)

In other words, using one bracket reduces the dimension of the data once (vector -> scalar, matrix -> vector). Using two brackets reduces the dimension twice (matrix -> scalar). Thus a command that uses scalar values as input can typically also process elements of a vector or a matrix.

Data style: global, per-atom and local

Various output-related commands work with three different styles of data: global, per-atom, or local. A global datum is one or more system-wide values, e.g. the temperature of the system. A per-atom datum is one or more values per atom, e.g. the kinetic energy of each atom. Local datums are calculated by each processor based on the atoms it owns, but there may be zero or more per atom, e.g. a list of bond distances.

Examples of common use

The check_timestep command stores a global vector with 2 components. There are two way to access the properties of this command and assign it to a variable, as shown in the example below:

check_timestep id check_ts rayleigh_fraction 10% hertz_fraction 10%
variable ts_rayleigh1 equal check_ts.rayleigh
variable ts_rayleigh2 equal check_ts[1]

A mesh can define one or more mesh_modules. The resulting mesh object stores a global vector (the size depends on the chosen mesh modules), which can be used with the write_to_file command, as shown in the example below:

mesh_module 6dof id 6dof center_of_mass (0, 0, 0) velocity (0, 0, -0.5) mass 40 moment_of_inertia principal (0.266666, 0.266666, 0.2666666) off_diagonal (0, 0, 0) angular_momentum (1, 0, 0)
mesh id cube material m1 file meshes/cube.stl mesh_modules {6dof}
write_to_file file coord.txt string "id_cube.xcm id_cube.ycm id_cube.zcm id_cube.quat1 id_cube.quat2 id_cube.quat3 id_cube.quat4 id_cube.angle_x id_cube.angle_y id_cube.angle_z" write_every_time 0.01

NB: Note that the mesh properties can also be accessed by the square brackets, where the array position depends on the activated mesh modules.

The set_velocity command can be used to fix one or more components of the (angular) velocity of a particle selection (by particle_group, region, or material). The command computes 6 global scalars of the force/torque components, used to push/rotate the particles in the desired direction. These forces (fx, fy, fz) and torques (tx, ty, tz) can be written to the status output by the status_style command, see the example below:

set_velocity id myVel velocity (0,0,0) omega (0,0,0)
status_style all {time, step, id_myVel.fx, id_myVel.fy, id_myVel.fz, id_myVel.tx, id_myVel.ty, id_myVel.tz}

NB: Note that the set_velocity properties can not be accessed by square brackets.