d-SEAMS: Lua Function Documentation (original) (raw)

In the functions.lua file, lua functions are called, which are registered on the C++ side to inferface with the C++ functions. Here, we document the lua functions currently available to the user.

Currently Registered Lua Functions

The workflows for quasi-two-dimensional ice, quasi-one-dimensional ice and bulk systems are separated. The Lua functions for each work-flow are registered in different blocks in the C++ code.

Common Functions

The following Lua functions interface to the same C++ functions in every work-flow code block.

• readFrameOnlyOne: interfaces with sinp::readLammpsTrjreduced
  The input variables are:
  • trajectory - The name of the lammps trajectory file to be read in, obtained from the config.yml file.
  • frame - The current frame number whose information will be read in.
  • resCloud - The outputted molSys::PointCloud, which has been passed to the Lua side.
  • atomType - The type ID of the desired type of atoms. Defined in vars.lua in the examples.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
  • sliceLowerLimits - Contains the lower limits of the slice. If isSlice false, this will be ignored.
  • sliceUpperLimits - Contains the upper limits of the slice. If isSlice false, this will be ignored.
    This function returns the resCloud molSys::PointCloud.
• neighborList: interfaces with nneigh::neighListO
  The input variables are:
  • cutoffRadius - The name of the lammps trajectory file to be read in, obtained from the config.yml file.
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • atomType - The type ID of the desired type of atoms. Defined in vars.lua in the examples.
    This function returns the nList vector of vectors for the neighbour list (by atom ID).
• getHbondNetwork: interfaces with bond::populateHbonds
  The input variables are:
  • trajectory - The name of the lammps trajectory file to be read in, obtained from the config.yml file.
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID.
  • frame - The current frame number whose information will be read in.
  • hydrogenAtomType - The type ID of the hydrogen atoms. Defined in vars.lua in the examples.
    This function returns the hbnList vector of vectors for the hydrogen-bonded neighbour list (by atom ID).
• bondNetworkByIndex: interfaces with nneigh::neighbourListByIndex
  The input variables are:
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID.
    This function returns the hbnList vector of vectors for the row-ordered full neighbour list, by index, NOT atom ID.
• getPrimitiveRings: interfaces with primitive::ringNetwork
  The input variables are:
  • hbnList - Row-ordered neighbour list by index (and NOT the atom ID).
  • maxDepth - The maximum depth upto which rings will be searched. This means that rings larger than maxDepth in length will not be generated.
    This function returns the rings vector of vectors for the primitive rings; each ring contains the atom indices of the ring members.

Quasi-Two-Dimensional Ice

• ringAnalysis: interfaces with ring::polygonRingAnalysis
  The input variables are:
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • rings - Row-ordered vector of vectors for rings of a single type. Registered on the Lua side.
  • nList - Row-ordered neighbour list by index.
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • maxDepth - The maximum depth upto which rings will be searched. This means that rings larger than maxDepth in length will not be generated.
  • confiningSheetArea - Area calculated using the two significant dimensions of the quasi-two-dimensional sheet. Defined in vars.lua.
• calcRDF: interfaces with rdf2::rdf2Danalysis_AA
  The input variables are:
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • rdf - Vector containing the RDF values. Must be passed to Lua.
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • rdfCutoff - Cutoff for the RDF. This should not be greater than half the box length. Defined in vars.lua.
  • binwidth - Width of the bin for histogramming. Defined in vars.lua.
  • targetFrame - The first frame for RDF binning. Defined in vars.lua.
  • finalFrame - The final frame for RDF binning. Defined in vars.lua.
    This function returns the hbnList vector of vectors for the hydrogen-bonded neighbour list (by atom ID).

Quasi-One-Dimensional Ice

• prismAnalysis: interfaces with ring::prismAnalysis
  The input variables are:
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • rings - Row-ordered vector of vectors for rings of a single type. Registered on the Lua side.
  • nList - Row-ordered neighbour list by index.
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • maxDepth - The maximum depth upto which rings will be searched. This means that rings larger than maxDepth in length will not be generated.
  • confiningSheetArea - Area calculated using the two significant dimensions of the quasi-two-dimensional sheet. Defined in vars.lua.

Bulk Systems

• readFrame: interfaces with sinp::readLammpsTrjO
  The input variables are:
  • trajectory - The name of the lammps trajectory file to be read in, obtained from the config.yml file.
  • frame - The current frame number whose information will be read in.
  • resCloud - The molSys::PointCloud for the current frame, which has been passed to the Lua side.
  • oxygenAtomType - The type ID of the Oxygen atoms in the LAMMPS trajectory file. Defined in vars.lua in the examples.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
  • sliceLowerLimits - Contains the lower limits of the slice. If isSlice false, this will be ignored.
  • sliceUpperLimits - Contains the upper limits of the slice. If isSlice false, this will be ignored.
    This function returns the resCloud molSys::PointCloud.
• chillPlus_cij: interfaces with chill::getCorrelPlus
  This function uses the CHILL+ algorithm.
  The input variables are:
  • resCloud - The molSys::PointCloud, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID. Passed to the Lua side.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
    This function returns the resCloud molSys::PointCloud.
• chillPlus_iceType: interfaces with chill::getIceTypePlus
  This function is for the CHILL+ algorithm.
  The input variables are:
  • resCloud - The molSys::PointCloud, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID. Passed to the Lua side.
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
    This function returns the resCloud molSys::PointCloud.
• chill_cij: interfaces with chill::getCorrel
  This function uses the CHILL algorithm.
  The input variables are:
  • resCloud - The outputted molSys::PointCloud, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID. Passed to the Lua side.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
    This function returns the resCloud molSys::PointCloud.
• chill_iceType: interfaces with chill::getIceType
  This function is for the CHILL algorithm.
  The input variables are:
  • resCloud - The outputted molSys::PointCloud, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID. Passed to the Lua side.
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
    This function returns the resCloud molSys::PointCloud.
• percentage_Ice: interfaces with chill::printIceType
  This function is for the CHILL algorithm.
  The input variables are:
  • resCloud - The molSys::PointCloud, which has been passed to the Lua side.
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • isSlice - This decides whether a slice will be created (true) or not (false). Defined in vars.lua.
  • outputFileName - File name of the output file, to which the per-particle ice types will be written out. Defined in vars.lua.
    This function returns the resCloud molSys::PointCloud.
• clusterAnalysis: interfaces with clump::clusterAnalysis
  The input variables are:
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • iceCloud - The molSys::PointCloud for the desired largest ice cluster, which has been passed to the Lua side.
  • resCloud - The molSys::PointCloud for all the particles read in, for the current frame, which has been passed to the Lua side.
  • nList - Row-ordered neighbour list by atom ID. Passed to the Lua side.
  • iceNeighbourList - Row-ordered neighbour list by atom index, not ID, according to the iceCloud atoms. Defined in vars.lua.
  • cutoff - Cutoff for the nearest neighbours. Passed to the Lua side.
  • bopAnalysis - This determines which method to use for determining the ice-like nature of the particles. This can be "q6" or "chill", for using the \(Q_6\) parameter or CHILL algorithm, respectively. Defined in vars.lua.
    This function returns the iceCloud molSys::PointCloud for the largest ice cluster.
• recenterCluster: interfaces with clump::recenterClusterCloud
  The input variables are:
  • iceCloud - The molSys::PointCloud for particles in the largest ice cluster, which has been passed to the Lua side.
  • iceNeighbourList - Row-ordered neighbour list by atom index, not ID, according to the iceCloud atoms. Defined in vars.lua.
• bulkTopologicalNetworkCriterion: interfaces with ring::topoBulkAnalysis
  The input variables are:
  • outDir - The string to the output directory, in which files will be written out. Defined in vars.lua.
  • rings - Row-ordered vector of vectors for rings of a single type. Registered on the Lua side.
  • nList - Row-ordered neighbour list by index. Passed to the Lua side.
  • resCloud - The input molSys::PointCloud, which has been passed to the Lua side.
  • printCages - Flag for printing the information of each cage in the frame (true) or not printing the coordinates/connectivity of each cage (false). Defined in vars.lua.

Extending d-SEAMS

d-SEAMS can be extended by writing C++ functions in pre-existing header files or by creating header files of your own.

Registering Lua Functions

In order to call a C++ function from the Lua script, the corresponding Lua function must be registered. This can be done simply in the main.cpp file:

lua.set_function("luaFuncName", cppFuncName);

where luaFuncName is the name of the lua function and cppFuncName is the name of the corresponding C++ function. It should be noted that default arguments must be provided explicitly when the luaFuncName function is called on the Lua side, or else the program will break with an error.

Passing Variables to Lua

If a C++ struct or variable is to be defined or passed to the Lua side, then the variable must be defined using the following syntax inside main.cpp :

lua["luaStruct"] = &cppStruct;

lua["luaVecOfVectors"] = &cppVecOfVectors;

lua["luaString"] = myString;

C++ structs, vectors of vectors and other objects must be passed by reference. This need not be done for strings.