The following implicit global variables and functions are defined from the c++ code, and are accessible from the code you will write within you Lua input script.

They will allow you to write functions for (1) defining your metastable states or (2) collecting observables.

implicit variables (read only) :

lua natoms : number of atoms of the system, read from OMM XML files.

mpi_rank_id : the id of the MPI process working on this file.

mpi_num_ranks : the total number of MPI processes running.

epot,ekin,etot : 3 variables containing the values of the potential, kinetic and total energies (kcal/mol), of the system for the current simulation time.

timeStep : the MD timeStep, read from OMM XML files.

referenceTime : the reference clock time, simulation will stop when referenceTime >= (numSteps*timestep), where timestep is defined within the xml OMM integrator file.

temperature : T of the system in Kelvin, initial value read from OMM XML files ; use get_temperature() for instantaneous values.

implicit functions :

exit_from_lua() : call this if it is required to finish the simulation from the lua script : it will terminate MPI properly and flush I/O files ; but it won't perform a DB backup so do it manually before.

get_coordinates(n) : function returning a tuple x,y,z containing the coordinates of atom n (in nm); NOTE n is indexed in Lua style starting from 1, internally it will be accessed as (n-1) i.e. C++ style.

get_velocities(n) : function returning a tuple vx,vy,vz containing the velocities of atom n (in nm/picosecond); NOTE n is indexed in Lua style starting from 1, internally it will be accessed as (n-1) i.e. C++ style.

get_all_coordinates() : function returning a table crds containing a safe read-only copy of the coordinates access by using : crds.x[i] crds.y[i] crds.z[i] for respectively getting x,y,z coordinates of atom i; NOTE lua indexing, starting from 1.

get_all_velocities() : same as gel_all_coordinates but for velocities ; returns a table vels such that the access is : vels.x[i], etc.

get_all_crdvels() : returns a 2-tuple crds,vels containing coordinates and vels : internally it calls the 2 above defined functions.

get_pbc() : returns periodic boundary conditions as a table pbc with members pbc.a pbc.b pbc.c, each being a xyz vector (i.e. pbc.a.x pbc.a.y pbc.a.z) .

set_pbc(pbc) : set the openmm periodic boundary conditions to be used, the argument is a table pbc as described above.

NOTE the following 3 functions are possibly slow (especially if a copy to a OCL or CUDA device is required), use rarely for performance.

set_all_coordinates(crds) : uses a crds tables (as described above) and use it for setting c++/openMM coordinates.

set_all_velocities(vels) : the same with velocities.

set_all_crdvels(crds,vels) : does with one function only what the 2 above defined do.

get_mass(n) : function returning the mass of atom n in a.m.u.; NOTE n is indexed in Lua style starting from 1, internally it will be accessed as (n-1) i.e. C++ style.

get_temperature() : get instantaneous value of the temperature in K.

get_COM() : function returning the center of mass of the system as a tuple x,y,z.

get_COM_idxs(idxs) : function returning the center of mass of a subset of the system as a tuple x,y,z; NOTE this time idxs is indexed directly in C++ style for example get_COM_idxs({1,2,3}) to get COM of atoms 1, 2 and 3 (C++ : atoms 0, 1, 2).

get_minimised_energy(tolerance,maxSteps) : this function returns the minimised energy of the system, using the OpenMM L-BFGS minimiser. NOTE that coordinates are not affected, it just returns the minimum epot of the bassin in which dynamics currently evolves. It returns a 3-tuple ep,ek,et (potential, kinetic and total energy).

get_minimised_crdvels(tolerance,maxSteps) : this function returns a 2-tuple (crds,vels) containing a copy of coordinates and velocities after minimisation. crds and vels are both tables with x,y,z members, each of size natoms, : e.g. crds.x[i] returns the x coordinate of atom i, idem for vels.x[i]. NOTE that C++/OpenMM coordinates are not modified if modifying this table : this is a safe read-only copy. NOTE lua indexing, starting from 1

get_minimised_energy_crdvels(tolerance,maxSteps) : this returns a 5-tuple (ep,ek,et,crds,vels). This does the same as the two previous functions but with only one call

hr_timer() : returns a variable representing a c++ high precision timer : can be used for measuring execution time. NOTE Do not try to modify it or even read it, it should only be used as argument for the following hr_timediff_* functions.

hr_timediff_ns(before,after) : returns the time difference in nanoseconds between two hr_timer() 'before' and 'after' : usage:

     local bf = hr_timer()
     function_to_profile()
     local af = hr_timer()
     print('Exec. time of function function_to_profile() is (ns) : ',hr_timediff_ns(bf,af))

hr_timediff_us() and hr_timediff_ms() : same as above but exec time is returned respectively in microseconds and milliseconds.