 |
(Version: 04 Mar 2021)
|
|
|
(Version: 04 Mar 2021)
|
|
Playmol is designed to execute scripts containing the commands described below. Click in the command name for detailed description and examples. In all examples, the units of measurement employed for physically meaningful values are those corresponding to LAMMPS real units.
| Command | Description |
|---|---|
| define | defines a variable for further substitution |
| for/next | executes commands repeatedly while changing the value of a variable |
| if/then/else | executes commands conditionally or selects between two command sequences |
| atom_type | creates an atom type with given name and parameters |
| mass | specifies the mass of atoms of a given type |
| diameter | specifies the diameter of atoms of a given type |
| bond_type | defines parameters for bonds between atoms of two given types |
| angle_type | defines parameters for angles involving atoms of three given types |
| dihedral_type | defines parameters for dihedrals involving atoms of four given types |
| improper_type | defines parameters for impropers involving atoms of four given types |
| atom | creates an atom with given name and type |
| charge | specifies the charge of a given atom |
| bond | creates chemical bonds and automatically detects angles and dihedrals |
| improper | creates an improper involving four given atoms or search for impropers |
| extra | creates an extra bond, angle, or dihedral involving given atoms |
| rigid_body | selects a set of atoms to be marked as a rigid body |
| mixing_rule | defines mixing rules for pairs of atom types |
| link | links two atoms (and fuses their molecules) without actually bonding them |
| unlink | removes an existing link (and splits the corresponding molecule) |
| build | guesses atom positions from provided geometric information |
| prefix/suffix | defines default prefixes or suffixes for atom types and atoms |
| box | defines the properties of a simulation box |
| velocity | defines parameters for genarating Maxwell-Boltzmann atomic velocities |
| align | aligns the principal axes of a molecule to the Cartesian axes |
| packmol | executes Packmol in order to create a packed molecular system |
| write | saves system info in different file formats (including LAMMPS and OpenMM) |
| include | includes commands from another script |
| reset | resets a list of entities together with its dependent lists |
| shell | executes an external shell command |
| quit | interrupts the execution of a Playmol script |
Syntax:
define <variable> as <string>
Description:
This command defines a variable whose value (a character string) is intended for substitution in forthcoming commands.
The parameter variable the must be a single character string containing only letters (A-Z or a-z), numbers (0-9), and underscores (_). The first character must necessarily be a letter. Important: variable names are case-sensitive.
The parameter value must be a single character string with no comment tags (#).
Substitution is instructed in forthcoming commands by either preceding the variable name with a symbol "$" or enclosing it between symbols "${" and "}", with no spacing. Every time the symbol "$" is found in a command, Playmol will admit that a variable is being referred to. The actual command will only be issued after all variables have been replaced by their values.
Example:
In the example above, an atom type named C is defined with parameters 0.0914 and 3.95. Then, two atoms named C1 and C2 are created, both of type C.
See also:
for/next, if/then/else, atom_type, atom
Syntax:
for <variable> from <min> to <max>
commands
next
or
for <variable> from <max> downto <min>
commands
next
or
for <variable> in <string-list>
commands
next
Description:
This command repeatedly executes a sequence of command-lines between the for and next statements while the value of a variable changes in accordance with a specified range or list.
The parameter variable the must be a valid variable name, that is, the first character must be a letter (A-Z or a-z) and the remaining characters can be letters (A-Z or a-z), numbers (0-9) or underscores (_).
The parameters min and max can be either two integer numbers with max ≥ min or two single characters with max not preceding min in the ASCII character table. If the corresponding condition is not met, then the command-lines between for and next will be ignored. Otherwise, these command-lines will be executed repeatedly, with the value of variable ranging either from min up to max or from max down to min, depending on the chosen syntax (see above).
The parameter string-list is a list of character strings separated by spaces and/or tabs. If the list is empty, then the command-lines between for and next will be ignored. Otherwise, these command-lines with be executed repeatedly, with the value of variable turning into the entries of string-list, one at a time and in the order they appear in the list.
Examples:
In the example above, the units of a united-atom n-alkane molecule are defined and named as C1, C2, C3, etc. It is assumed that variable N (the number of carbon atoms) has already been defined.
In the example above, the files water.xyz, ethanol.xyz, and glycerol.xyz are employed as inputs for the build command.
See also:
Syntax:
if <condition> then
commands
endif
or
if <condition> then
commands
else
commands
endif
Description:
This command conditionally executes a sequence of command-lines or selects between two given sequences of command-lines.
The parameter condition can be either 1 (true) or 0 (false). If any value other than these two is passed, an error message is produced. In practice, condition might be the result of a variable substitution or a logical expression evaluation (see the Playmol Basics section for details).
If the first syntax above is used (that is, without the else statement), then the command-lines between if and endif will be executed if condition = 1 or ignored if condition == 0. Otherwise, if the second syntax is chosen, then the executed command-lines will either be those between if and else if condition = 1 or those between else and endif if condition = 0.
Example:
In the example above, the attribute list of the atom type CH3 will depend on the number of carbon atoms (N) of the n-alkane molecule. Ethane and propane have their own parameters, while n-butane and superior alkanes share the same parameters.
See also:
Syntax:
atom_type <id> [<model>] <attribute-list>
Description:
This command defines an atom type with its related attributes. At least one atom type must necessarily be defined before any atom is created and before any bond_type, angle_type, dihedral_type, or improper_type is defined.
The parameter id must be a single string with no comment tags (#) and no wildcard characters (* or ?). If a type-related prefix/suffix has been previously activated, then the actual atom type identifier will contain such prefix and/or suffix added to id. Distinct atom types cannot have the same identifier.
The parameter model is the name of a model for computing non-bonded interactions between atoms of type id. This parameter is optional, but its presence might be required by other commands. For instance, when a LAMMPS data file is created using the command write with keyword lmp/models, the parameter model must be present in the definitions of all employed atom types. In this case, model must be a LAMMPS pair style.
The parameter attribute-list can be a sequence of strings containing any characters, except comment tags (#). When a LAMMPS data file is generated using the command write, then the content of attribute-list is assumed to be the parameters of the LAMMPS pair style associated with the atom type in question.
Examples:
In the example above, atom types O and H are defined with Lennard-Jones parameters epsilon and sigma, respectively, corresponding to the SPC water model. This can be used to generate a LAMMPS configuration file associated with the pair style lj/cut/coul/long, for instance.
In the example above, united-atom types TraPPE-CH3 and TraPPE-CH2 are defined Lennard-Jones parameters epsilon and sigma, respectively, corresponding to the TraPPE force field. An explicit pair style specification lj/cut is done, supposing that a pair style hybrid or hybrid/overlay will be employed in LAMMPS.
See also:
atom, bond_type, angle_type, dihedral_type, improper_type, prefix/suffix, mixing_rule
Syntax:
mass <type> <value>
or
mass <type> <symbol>
Description:
This command defines the mass of atoms of a given type.
The parameter type is an atom_type identifier. Wildcard characters (* or ?) can be used so that the same mass value is assigned to multiple atom types. If a type-related prefix/suffix has been previously activated, then the actual atom type identifier will contain such prefix and/or suffix added to type. Important: the presence of wildcards makes a mass value applicable to atom types defined either beforehand or afterwards.
The parameter value must be a non-negative real number.
The parameter symbol must either be a valid, case-sensitive atomic symbol or EP (standing for extra particle). In the former case, Playmol will assign a mass value equal to the atomic mass in Daltons. In the latter case, Playmol will assign a mass value equal to zero.
An atom will only be created if a mass value (primarily) or a chemical element has been previously defined to its corresponding atom type.
Examples:
In the example above, a mass value of 14.0 is assigned to atom type CH2 and a mass value of 1.0079 is assigned to all atoms types whose identifiers start with H.
See also:
Syntax:
diameter <type> <value>
Description:
This command defines the diameter of atoms of a given type.
The parameter type is an atom_type identifier. Wildcard characters (* or ?) can be used so that the same diameter value is assigned to multiple atom types. If a type-related prefix/suffix has been previously activated, then the actual atom type identifier will contain such prefix and/or suffix added to type. Distinct atom types cannot have the same identifier. Important: the presence of wildcards makes a diameter value applicable to atom types defined either beforehand or afterwards.
It is not necessary to define a diameter for every atom type. This is only required if one wishes to setup atom-specific distance tolerances when creating a molecular packing with the packmol command, thus superseding its parameter tolerance.
Examples:
In the example above, a diameter value of 3.0 is assigned to atom type CH2 and a diameter value of 2.0 is assigned to all atoms types whose identifiers start with H.
See also:
Syntax:
bond_type <type-1> <type-2> [<model>] <attribute-list>
Description:
This command defines a bond type and its related attributes. At least one bond type must be defined before any chemical bond is created. A bond type is identified by the types of the two atoms involved.
The parameters type-1 and type-2 are identifiers of previously defined atom types. Either order type-1 type-2 or type-2 type-1 will result in the same bond type. Wildcard characters (? and *) can be used to refer to multiple atom types. If a type-related prefix/suffix has been previously activated, then each actual atom type identifier will contain such prefix and/or suffix added to type-x.
The parameter model is the name of a model for computing bond-stretching interactions between bonded atoms of type-1 and type-2. This parameter is optional, but its presence might be required by other commands. For instance, when a LAMMPS data file is created using the command write with keyword lmp/models, the parameter model must be present in the definitions of all employed bond types. In this case, model must be a LAMMPS bond style.
The parameter attribute-list can be a sequence of strings containing any characters, except comment tags (#). When a LAMMPS data file is generated using the command write, then the content of attribute-list is assumed to be the parameters of the LAMMPS bond style associated with the bond type in question.
Playmol is able to resolve ambiguities in definitions of bond types. When several ambiguous bond types fit to a defined bond or extra bond, Playmol will classify them according to the number N of wildcard-containing identifiers (N = 0, 1, or 2). Then, it will simultaneously assign to the bond all those types with the smallest found value of N. Multiple assignments are useful, for instance, when the stretching potential model is a sum of instances of a given LAMMPS bond style, each one with a distinct set of parameter values.
Examples:
In the example above, the given attributes will be associated with every bond involving atoms whose types have identifiers starting with CH.
See also:
atom_type, bond, write, prefix/suffix, extra
Syntax:
angle_type <type-1> <type-2> <type-3> [<model>] <attribute-list>
Description:
This command defines an angle type and its related attributes. An angle type is identified by the types of the three atoms involved.
The parameters type-1, type-2, and type-3 are identifiers of previously defined atom types. Either order type-1 type-2 type-3 or type-3 type-2 type-1 will result in the same angle type. Wildcard characters (? and *) can be used to refer to multiple atom types. If a type-related prefix/suffix has been previously activated, then each actual atom type identifier will contain such prefix and/or suffix added to type-x.
The parameter model is the name of a model for computing angle-bending interactions between bonded atoms of type-1, type-2, and type-3. This parameter is optional, but its presence might be required by other commands. For instance, when a LAMMPS data file is created using the command write with keyword lmp/models, the parameter model must be present in the definitions of all employed angle types. In this case, model must be a LAMMPS angle style.
The parameter attribute-list can be a sequence of strings containing any characters, except comment tags (#). When a LAMMPS data file is generated using the command write, then the content of attribute-list is assumed to be the parameters of the LAMMPS angle style associated with the angle type in question.
Playmol detects angles automatically when chemical bonds are created. If a detected angle fits to a previously defined angle type, then Playmol will add it to a list of angles to be used later on, for instance, in the creation of a LAMMPS data file. If the corresponding angle type does not exist at the moment a new angle is detected, then Playmol will ignore such angle and produce a warning message. Besides the automatic detection, an angle can also be explicitly created using the extra command.
Playmol is able to resolve ambiguities in definitions of angle types. When several ambiguous angle types fit to a detected angle or defined extra angle, Playmol will classify them according to the number N of wildcard-containing identifiers (N = 0, 1, 2, or 3). Then, it will simultaneously assign to the angle all those types with the smallest found value of N. Multiple assignments are useful, for instance, when the bending potential model is a sum of instances of a given LAMMPS angle style, each one with a distinct set of parameter values.
Examples:
In the example above, the given attributes will be associated with every detected or specified angle that involves three consecutive atoms whose type identifiers are CH3 CH2 CH2 or CH2 CH2 CH3.
See also:
atom_type, write, prefix/suffix, extra
Syntax:
dihedral_type <type-1> <type-2> <type-3> <type-4> [<model>] <attribute-list>
Description:
This command defines a dihedral type and its related attributes. A dihedral type is identified by the types of the four atoms involved.
The parameters type-1, type-2, type-3, and type-4 are identifiers of previously defined atom types. The order of such identifiers is relevant in the case of dihedral types, that is, if the same identifiers are disposed in the inverse order, they will denote different dihedral types. Wildcard characters (? and *) can be used to refer to multiple atom types. If a type-related prefix/suffix has been previously activated, then each actual atom type identifier will contain such prefix and/or suffix added to type-x.
The parameter model is the name of a model for computing torsional interactions between bonded atoms of type-1, type-2, type-3, and type-4. This parameter is optional, but its presence might be required by other commands. For instance, when a LAMMPS data file is created using the command write with keyword lmp/models, the parameter model must be present in the definitions of all employed dihedral types. In this case, model must be a LAMMPS dihedral style.
The parameter attribute-list can be a sequence of strings containing any characters, except comment tags (#). When a LAMMPS data file is generated using the command write, then the content of attribute-list is assumed to be the parameters of the LAMMPS dihedral style associated with the dihedral type in question.
Playmol detects dihedrals automatically when chemical bonds are created. If a detected dihedral fits to a previously defined dihedral type, then Playmol will add it to a list of dihedrals to be used later on, for instance, in the creation of a LAMMPS data file. If the corresponding dihedral type does not exist at the moment a new dihedral is detected, then Playmol will ignore such dihedral and produce a warning message. Besides the automatic detection, a dihedral can also be explicitly created using the extra command.
Playmol is able to resolve ambiguities in definitions of dihedral types. When several ambiguous dihedral types fit to a detected dihedral or defined extra dihedral, Playmol will classify them according to the number N of wildcard-containing identifiers (N = 0, 1, 2, 3, or 4). Then, it will simultaneously assign to the dihedral all those types with the smallest found value of N. Multiple assignments are useful, for instance, when the torsional potential model is a sum of instances of a given LAMMPS dihedral style, each one with a distinct set of parameter values.
NOTE: Because the direction of identifiers is relevant in the definition of a dihedral type, a direction conflict might occur when multiple dihedral types are simultaneously assigned to a detected or defined dihedral. Such a conflict takes place when all the following three conditions are met:
Combinations of conditions (1) and (3) are okay. Playmol automatically solves a combination of (2) and (3) by flipping the new dihedral before inclusion. It also solves automatically a combination of (1) and (2) by including a flipped dihedral in addition to the original one. However, Playmol will only throw a warning message when faced with a combination of all three conditions. In this case, the user can try to solve the conflict by manually flipping the dihedral types that cause condition (2), for instance.
Examples:
In the example above, the given attributes will be associated with every detected or specified dihedral that involves four consecutive atoms whose type identifiers are CH3 CH2 CH2 CH2, in this specific order.
See also:
atom_type, write, prefix/suffix, extra
Syntax:
improper_type <type-1> <type-2> <type-3> <type-4> [<model>] <attribute-list>
Description:
This command defines an improper type and its related attributes. An improper type is identified by the types of the four atoms involved.
The parameters type-1, type-2, type-3, and type-4 are identifiers of previously defined atom types. The order of such identifiers is relevant in the case of improper types, that is, if the same identifiers are disposed in the inverse order, they will denote different improper types. Wildcard characters (? and *) can be used to refer to multiple atom types. If a type-related prefix/suffix has been previously activated, then each actual atom type identifier will contain such prefix and/or suffix added to type-x.
The parameter model is the name of a model for computing improper dihedral interactions between bonded atoms of type-1, type-2, type-3, and type-4. This parameter is optional, but its presence might be required by other commands. For instance, when a LAMMPS data file is created using the command write with keyword lmp/models, the parameter model must be present in the definitions of all employed improper types. In this case, model must be a LAMMPS improper style.
The parameter attribute-list can be a sequence of strings containing any characters, except comment tags (#). When a LAMMPS data file is generated using the command write, then the content of attribute-list is assumed to be the parameters of the LAMMPS improper style associated with the improper type in question.
In contrast to angles and proper dihedrals, impropers are not automatically detected as bonds are defined. This is so because there are distinct possible definitions of improper dihedrals. Impropers can be manually created by using the improper command, which requires the previous definition of a fitting improper type. Playmol is also able to find all impropers of a specific kind by using the keyword search in the improper command.
Playmol is able to resolve ambiguities in definitions of improper types. When several ambiguous improper types fit to a defined improper, Playmol will classify them according to the number N of wildcard-containing identifiers (N = 0, 1, 2, 3, or 4). Then, it will simultaneously assign to the improper all those types with the smallest found value of N. Multiple assignments are useful, for instance, when the torsional potential model is a sum of instances of a given LAMMPS improper style, each one with a distinct set of parameter values.
NOTE: Improper types are only assigned to an improper if they match the atom types of the improper atoms in the exact order they are defined.
Examples:
In the example above, the given attributes will be associated with every detected or specified improper that involves four atoms whose type identifiers are c2 c2 na c3, in this specific order.
See also:
atom_type, improper, write, prefix/suffix, extra
Syntax:
atom <id> <type> [<charge>]
Description:
This command creates an atom of a given type.
The parameter id must be a single character string with no comment tags (#) and no wildcard characters (* or ?). If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to id. The same identifier cannot be assigned to distinct atoms.
The parameter type is the identifier of a previously defined atom type. A unique identifier must be provided, with no use of wildcard characters (* or ?). If a type-related prefix/suffix has been previously activated, then each actual atom type identifier will contain such prefix and/or suffix added to type-x. The specified atom type must have a [mass] (or element) already defined to it.
The optional parameter charge is the total or partial charge of the specified atom. Note that one can omit this parameter and assign the charge afterwards using the command charge, which has the advantage of admitting wildcards in order to perform multiple charge assignments simultaneously.
When an atom is created, a new monoatomic molecule is automatically detected. If there are, for instance, N already existing molecules, the new monoatomic molecule will receive an index N+1. If a bond involving this atom is created afterwards, then such monoatomic molecule will no longer exist.
Examples:
See also:
Syntax:
charge <atom> <value>
Description:
This command defines the electric charge (total or partial) of an atom.
The parameter atom is an atom identifier. If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom. Wildcard characters (* or ?) can be used to simultaneously assign the same charge to multiple atoms. Important: the presence of wildcards makes a charge value applicable to atoms defined either beforehand or afterwards.
If an atom has no explicitly defined charge, then it will be considered as neutral.
Examples:
In the example above, a change value of -1.0 is assigned to all atoms whose identifiers start with the letter O.
See also:
Syntax:
bond <atom-1> <atom-2> [<atom-3> <atom-4> ...]
Description:
This command creates chemical bonds between atoms.
The parameter atom-x is the identifier of a previously created atom. A unique identifier must be provided, with no use of wildcard characters (* or ?).
Parameters atom-1 and atom-2 are mandatory. Additional parameters atom-x (for x > 2) are optional. In any case, atom-1 is the central atom to which all other atoms will be connected. If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom-x.
If a bond is created between atoms that belong to the same molecule, then a cyclic structure is formed and the number of molecules does not change. However, if the two atoms belong to distinct molecules, then these molecules are fused together and the number of molecules is decreased. Supposing that the fused molecules have indices i and j, the index of the new molecule will be min(i,j). In order to keep a consistent sequence, all existing molecules whose indexes are greater than max(i,j) will have their indexes decreased in one unit.
New angles and new dihedrals are detected automatically when a bond is created. If a detected structure fits to a previously defined type, then Playmol will add it to a list to be used later on, for instance, in the creation of a LAMMPS data file. If the corresponding type does not exist at the moment a new structure is detected, then Playmol will ignore such structure and produce a warning message.
After chemical bonds have been created, one can visualize the current list of molecules by invoking the command write with the summary format.
Examples:
In the example above, two chemical bonds O-_H1_ and O-_H2_ are created. Then, a command write is issued and Playmol execution is interrupted, so that the user can visualize the updated list of molecules.
See also:
bond_type, atom, atom_type, write, quit
Syntax:
improper <atom-1> <atom-2> <atom-3> <atom-4>
or
improper search
Description:
This command either creates an improper involving the specified atoms or search for impropers of a specific kind.
Important: Unlike angles and proper dihedrals, impropers are not detected automatically when the command bond is executed. This is so because improper dihedrals can be defined in several distinct ways.
Each parameter atom-x is the identifier of a previously created atom. A unique identifier must be provided, with no use of wildcard characters (* or ?). If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom-x. When an improper is defined explicitly (first syntax above), a previously defined improper_type matching the four atoms in the specified order is required.
Using the keyword search (second syntax above), Playmol will search for all molecular substructures composed of four atoms I, J, K, and L so that atom I is simultaneously bonded to atoms J, K, and L, such as depicted below.
J
\
I ── L
/
K
Once Playmol finds a substructure of this type, it will assign the indexes J, K, and L to the atoms in accordance with the alphabetical order of their types. Then, it will look for a previously defined improper_type whose four identifiers fit to the types of these atoms, testing different arrangements until the first fitting improper_type is found or until all possible arrangements have been tested unsuccessfully. The sequence of tests is:
I, J, K, LI, J, L, KI, K, J, LI, K, L, JI, L, J, KI, L, K, JAn improper will be added only if a fitting improper_type is found.
Examples:
In the example above, an improper type is defined for atoms of types c, ca, ca, and oh. After that, Playmol sweeps all molecules searching for impropers of this type.
See also:
Syntax:
rigid_body <atom-1> <atom-2> [<atom-3> <atom-4> ...]
Description:
This command selects a set of atoms to be marked as a rigid body.
Each parameter atom-x is the identifier of a previously created atom. A unique identifier must be provided, with no use of wildcard characters (* or ?). If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom-x. A rigid body must contain at least two atoms.
Each parameter atom-x must be distinct from all others in the same body and from all others which belong to previously defined rigid bodies.
Examples:
In the example above, a benzene molecule is created and all its carbon atoms are grouped together as a single body.
See also:
Syntax:
mixing_rule <type-1> <type-2> [<rule-1> <rule-2> ...]
Description:
This command defines mixing rules for defining attributes related to pairs of atom types. This will have a practical effect, for instance, when a LAMMPS data file is generated using the command write with either option lammps or lmp/models.
The parameters type-1 and type-2 are identifiers of previously defined atom types. Either order type-1 type-2 or type-2 type-1 will result in the same mixing rule. Wildcard characters (? and *) can be used to refer to multiple atom types. If a type-related prefix/suffix has been previously activated, then each actual atom type identifier will contain such prefix and/or suffix added to type-x.
The parameter rule-x is either a literal attribute or a keyword. If it is a literal attribute, then this will be the x-th attribute of the specified atom-type pair. If it is one of the keywords described below, a mixing rule will be used to combine the x-th attribute of type-1 with the x-th attribute of type-2. This requires that both atom types actually have a numerical-valued x-th attribute, otherwise [Playmol] will stop and throw an error message. The possible keywords are:
NOTE: If several mixing rules fit to a given pair of atom types, Playmol will select the first mixing rule with the minimum number of type identifiers containing wildcards.
Examples:
In the example above, a mixing rule is defined for all pairs of atom types whose identifiers begin with a letter "C". The parameter rule-1 is a literal attribute (lj/cut), while the parameters rule-2 and rule-3 are keywords for defining combination rules.
See also:
atom_type, prefix/suffix, write
Syntax:
extra bond <atom-1> <atom-2>
or
extra angle <atom-1> <atom-2> <atom-3>
or
extra dihedral <atom-1> <atom-2> <atom-3> <atom-4>
Description:
This command creates an extra structure (bond, angle, dihedral) involving the specified atoms. In the case of an extra angle or extra dihedral, all specified atoms must belong to the same molecule.
The parameter atom-x is the identifier of a previously created atom. A unique identifier must be provided, with no use of wildcard characters (* or ?). A corresponding structure type (that is, bond_type, angle_type, or dihedral_type) must have been previously defined. If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom-x.
Important: Playmol DOES NOT automatically search for angles and dihedrals when a chemical bond is created with the command extra.
NOTE: extra structures are only required by some molecular models that define unconventional bonds, angles, or dihedrals, such as those that involve atoms which are not actually bonded in a molecule, for example. Most models, however, will involve only automatically detectable angles and dihedrals.
Examples:
See also:
bond_type, angle_type, dihedral_type, atom
Syntax:
link <atom-1> <atom-2> [<atom-3> <atom-4> ...]
Description:
This command creates a virtual link between the specified atoms. If these atoms belong to distinct molecules, then such molecules will be fused together, but without actually creating a chemical bond between the linked atoms.
The parameter atom-x is the identifier of a previously created atom. A unique identifier must be provided, with no use of wildcard characters (* or ?). If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom-x.
Parameters atom-1 and atom-2 are mandatory. Additional parameters atom-x (for x > 2) are optional. In any case, atom-1 is the central atom to which all other atoms will be linked.
NOTE: sometimes, it is useful to consider two molecules as if they were a single one. For instance, when ions are present, one might want to consider an anion/cation pair as a single rigid structure, so that they can be packed together using the packmol command. After that, one can remove the link using the unlink command before writing down the produced configuration as, for instance, a LAMMPS data file.
Examples:
See also:
Syntax:
unlink <atom-1> <atom-2>
Description:
This command removes a previously defined link between the specified atoms. If such link is the only connection between two otherwise independent parts of a molecule, then such molecule will be disassembled accordingly. If necessary, the list of atomic coordinates of instantiated molecules will be rearranged in order to keep contiguousness for the atoms of each molecule.
The parameter atom-x is the identifier of a previously created atom. A unique identifier must be provided, with no use of wildcard characters (* or ?). If an atom-related prefix/suffix has been previously activated, then the actual atom identifier will contain such prefix and/or suffix added to atom-x. The two identifiers must correspond to a previously created link.
NOTE: sometimes, it is useful to consider two molecules as if they were a single one. For instance, when ions are present, one might want to consider an anion/cation pair as a single rigid structure, so that they can be packed together using the packmol command. After that, one can remove the link using the unlink command before writing down the produced configuration as, for instance, a LAMMPS data file.
Examples:
See also:
Syntax:
build [<file>]
Description:
This command reads geometric information and uses them to determine atomic coordinates for one or more molecules.
The optional parameter file is the name of a text file containing geometric information, whose required format is described below. If it is omitted, then the geometric information must be provided in the subsequent lines. In this sense, issuing the command build <file> is equivalent to issuing build, followed by include <file>.
The geometric information that Playmol expects to receive has the following format:
Allocation of atom-I at the origin:
<atom-I>
Coordinates x, y, and z of atom-I:
<atom-I> <x> <y> <z>
The length of a bond formed by atoms I and J:
<atom-I> <atom-J> <length>
The length of a bond formed by atoms I and J and the angle (in degrees) between the bonds formed by atoms I, J, and K:
<atom-I> <atom-J> <length> <atom-K> <angle>
The length of a bond formed by atoms I and J, the angle (in degrees) between the bonds formed by atoms I, J, and K, and the torsion angle (in degrees) of the proper dihedral formed by atoms I, J, K, and L:
<atom-I> <atom-J> <length> <atom-K> <angle> <atom-L> <torsion>
An active atom-related prefix/suffix will apply to every parameter atom-x present in the assignments described above. In all cases, atom I is the one whose coordinates are being assigned, while atoms J, K, and L must be atoms whose coordinates have already been assigned (please see the examples below).
Every molecule must be instantiated at once, meaning that the geometric information regarding all atoms of a given molecule must be provided contiguously. However, no particular order is required. Multiple molecules of one or more compounds can be instantiated either using separate build constructs or a unique build constructs with all atoms together.
Note that the ubiquitous xyz file format can be used to provide geometric information for the build constraint, given that:
The N subsequent lines contain the following four fields separated by spaces and/or tabs:
<atom-id> <x> <y> <z>
Therefore, one can use an external software to generate the atomic coordinates (e.g., Avogadro), save them in the xyz file format, and replace the usual element symbols by atom identifiers.
The list of molecular structures created via build can be employed later on as prototypes for replication and packing with the packmol command. They can also be directly employed to produce a simulation box when the command write is invoked. In this case, the origin of the Cartesian space will be located at the center of the simulation box.
Examples:
In the example above, the geometric information of one or more copies of a water molecule is read from the file H2O.info.
In the example above, the atomic coordinates of a water molecule are guessed by positioning the oxygen atom at the origin, defining the lengths of the oxygen-hydrogen bonds as 0.9572 Å, and then defining the hydrogen-oxygen-hydrogen angle as 104.52 degrees.
In the example above, a united-atom cis-2-pentene molecule (C1-C2=C3-C4-C5) is defined. The length of the double bond is 1.33 Å and that of the single bonds is 1.54 Å. All bond-bending angles are 114 degrees. The torsional angle of the dihedral C1-C2=C3-C4 is zero (cis) and that of the dihedral C2=C3-C4-C5 is 180 degrees (trans). In the end, a configuration file is written down and vmd is involved in a new terminal window for visualization.
See also:
atom, bond, box, write, include
Syntax:
prefix <target> <string>
or
suffix <target> <string>
Description:
This commands activates/deactivates a prefix or a suffix to be added to every atom_type identifier or to every atom identifier in subsequent commands.
The parameter target indicates which type of identifier will be modified by the activated prefix or suffix. If target = types, then the prefix/suffix will be applied to every atom_type identifier in subsequent commands. Otherwise, if target = atoms, then the prefix/suffix will be applied to every atom identifier in subsequent commands.
The parameter string must be a single character string with no comment tags (#) and no wildcard characters (* or ?). Such string will be used in subsequent commands as a prefix or suffix for atom_type identifiers or for atom identifiers, depending on the specified parameter target. If string = none, then no prefix/suffix will be added for the specified target in subsequent commands. Therefore, using string = none deactivates a currently active prefix or suffix.
Prefixes and suffixes can be simultaneously active.
The following commands are affected by the prefix types and suffix types commands:
The following commands are affected by the prefix atoms and suffix atoms commands:
Note: an active, atom-related prefix/suffix will NOT be automatically applied to arguments of the mol() function. Therefore, molecule specifications within the commands align and packmol require manual inclusion of prefixes and/or suffixes.
Examples:
The example above creates two atoms whose identifiers are H2O-H1 and H2O-H2. Both atoms are of the same type HA.
See also:
Syntax:
box lengths <lx> <ly> <lz>
or
box angles <alpha> <beta> <gamma>
or
box volume <value> [aspect <ax> <ay> <az>]
or
box density <value> [aspect <ax> <ay> <az>]
Description:
This command specifies the side lengths, the angles, the volume, or the density of a simulation box.
The parameters lx, ly, and lz are the lengths of the simulation box edges in the three spatial directions.
The parameters alpha, beta, and gamma are the angles, in degrees, between edge vectors of a non-orthogonal box (alpha between ly and lz, beta between lx and lz, and gamma between lx and ly). The command box angles requires that a command box lengths has been previously issued.
The parameter value is either the volume or the density of the simulation box, depending on the kind of specification.
The optional keyword aspect with parameters ax, ay, and az can be used to determine the relative box sizes in the three spatial directions (the absolute values of these three parameters are meaningless). If the keyword aspect is omitted, Playmol will consider a cubic box.
Important: when the box density is specified, Playmol will automatically calculate the box side lengths when necessary. For this, it will sweep the whole list of molecular structures defined via build and packmol commands in order to determine the total mass of the system. Playmol will not perform any unit conversion. Consequently, the specified density value must be consistent with the mass and length units used in other commands. For instance, if LAMMPS real units are considered (mass in g/mol and lengths in Å), then the density must be provided in Da/ų (Daltons per cubic Angstrom). In this case, values originally in g/cm³ must be multiplied by 0.60221413.
When building a simulation box, Playmol considers that its geometric center is in the origin of the Cartesian space. Playmol does not check whether the previously specified atomic coordinates fit inside this box.
Examples:
The example above specifies a cubic simulation box.
The example above is completely equivalent to the preceding one, since the default aspect is cubic.
The example above specifies a simulation box with density equal to 0.602214 in LAMMPS real units. The box is twice as elongated in the z direction as in the other two directions.
The example above specifies a non-orthogonal simulation box that can be used to simulate a hexagonal lattice system (lx = ly ≠ lz and alpha = beta ≠ gamma).
See also:
Syntax:
velocity <seed> <kT>
Description:
This command tells Playmol to include atom velocities in some output files created via write and specifies the parameters used to generate the velocity vectors. The affected file formats are lammps and emdee.
The parameter seed must be a positive integer number, which will seed a pseudo-random number generator. For a given set of atoms with specified masses, different values of seed will produce distinct sets of velocity vectors.
The parameter kT is the temperature multiplied by the Boltzmann constant, which witll determine the atomic speeds. The velocity vector elements for an atom with mass m will be randomly generated from a normal distribution with mean zero and standard deviation equal to sqrt(kT/m). Therefore, the units of kT must be chosen accordingly. For instance, if LAMMPS real units are employed, then the appropriate value of the Boltzmann constant is 8.31451E-7 # Da.Ų/(fs².K).
Examples:
See also:
Syntax:
align <molecule> <axis-1> <axis-2>
Description:
This command aligns the principal axes of a given molecule with the system's Cartesian axes. The principal axes are defined as those for which the molecule's inertia tensor is diagonal. The inertia tensor is obtained as if all atoms had the same mass.
The parameter molecule specifies the molecule to be aligned with the Cartesian axes. This specification can be done in either of the following ways:
mol(atom), where atom is the identifier of an existing atom. Such identifier must be tightly placed inside the parentheses (that is, without any spaces and/or tabs). Note that an active, atom-related prefix/suffix will be applied automatically to atom.Except in a few special cases, the specified molecule must have already been instantiated (see the Playmol Basics section). In this case, the first set of atomic coordinates previously provided for such molecule will be employed. The special cases, which might not require previous instantiation, are: (1) monoatomic molecules, (2) diatomic molecules whose involved bond_type describes a harmonic potential, and (3) triatomic molecules whose involved bond_type and angle_type both describe harmonic potentials. In these cases, Playmol will consider the second bond_type's attribute as an equilibrium distance and the second angle_type's attribute as an equilibrium angle (in degrees).
The parameter axis-1 must be equal to x, y, or z, and specifies the Cartesian axis with which the molecule will be aligned considering its most elongated principal axis.
The parameter axis-2 must also be equal to x, y, or z, but different from axis-1. It specifies the Cartesian axis with which the molecule will be aligned considering its second most elongated principal axis. Of course, the shortest principal axis will be aligned to the Cartesian axis not explicitly specified in the command align.
Examples:
The example above aligns the most elongated principal axis of molecule 1 to the Cartesian axis x, and its second most elongated principal axis to axis z.
See also:
Syntax:
packmol <keyword> <arguments> [<keyword> <arguments> ...]
Keywords and arguments:
Description:
This command invokes the Packmol package to:
The keywords seed, diameter, and nloops change the values of some parameters that affect the behavior of Packmol.
The parameter iseed is a seed for Packmol's pseudo-random number generator. Even with all other parameters unchanged, different values of iseed will produce distinct random packings. It must be an integer number and its default value is 1234.
The parameter D is the default atom diameter, that is, the diameter to be assigned to all atom types except those whose diameters have been explicitly defined using the diameter command. It must be a nonnegative real number and its default value is 2.5. This might be a suitable value for all-atom models when distances are expressed in Angstroms.
The parameter N is the maximum number of iterations allowed for the Packmol algorithm. If this number is exceeded, then a packing attempt is considered as unsuccessful. It must be a positive integer number and its default value is 50.
The parameter factor is a diameter reduction factor. It must satisfy 0.0 < factor ≤ 1.0 and its default value is 1.0. If factor = 1.0, then Packmol will be invoked only once with the specified atom diameters and will produce an error message if the packing attempt fails. Otherwise, Packmol will be invoked as many times as necessary to achieve a successful packing, with all atom diameters being iteratively multiplied by the value of factor at each new attempt.
The keywords fix, copy, and pack require specifying an existing molecule. Except in a few special cases, such molecule must have already been instantiated (see the Playmol Basics section). In this case, the first sets of atomic coordinates previously provided for such molecule will be used to define a rigid-body that can undergo replications, translations, and rotations. The special cases, which might not require previous instantiation, are: (1) monoatomic molecules, (2) diatomic molecules whose involved bond_type describes a harmonic potential, and (3) triatomic molecules whose involved bond_type and angle_type both describe harmonic potentials. In these cases, Playmol will consider the second bond_type's attribute as an equilibrium distance and the second angle_type's attribute as an equilibrium angle (in degrees).
A molecule specification for the fix/copy/pack keywords can be done in either of the following ways:
packmol action command (see below).mol(atom), where atom is the identifier of an existing atom. Such identifier must be tightly placed inside the parentheses (that is, without any spaces and/or tabs). At the moment of a packmol action command, the function will return the index of the compound that contains the specified atom. Note that an active, atom-related prefix/suffix will be applied automatically to atom.The usage of each keyword fix, copy, or pack is:
fix <molecule> <x> <y> <z>
This makes a copy of a molecule and, while keeping the original orientation, places its geometric center at the provided coordinate (x, y, z).
copy <molecule> <N>
This makes N copies of a molecule in random positions, but keeping the original orientation (i.e. all N copies will be aligned to each other in the final packing). This is useful for facilitating the packing of elongated molecules.
pack <molecule> <N>
This makes N copies of a molecule in random positions and with random orientations.
The keyword action is used to create Packmol input files or to execute Packmol. The following options are available:
action execute
This option executes Packmol in order to build the desired molecular packing. It requires the previous definition of a simulation box. Moreover, it requires that at least one keyword fix copy, or pack has appeared in a previous packmol command or appears in the same packmol command, either before or after the keyword action. If the parameter retry is currently equal to 1.0 (its default value), then Packmol will do only one packing attempt with the specified tolerance and produce a warning message in case such attempt fails. If retry is smaller than 1.0, then Packmol will keep trying until a successful attempt is achieved, with tolerance being iteratively multiplied by the retry value at each new attempt. IMPORTANT: if the packing succeeds, then the current list of atomic coordinates is replaced by the new coordinates generated by Packmol. After that, the command write can be used to create a LAMMPS data file with the attained packing.
action setup
This option generates an input file named packmol.inp and coordinate files molecule-x.inp, where x is an index for each involved molecule. These files are prepared for running Packmol externally in order to generate a file packmol-output.xyz containing the final packing if the algorithm succeeds with the given tolerance. For illustration, one may notice that a successful use of the packmol command with options retry 1.0 action execute would have exactly the same result as the following sequence of commands:
Nevertheless, the real usefulness of the option setup is to allow the file packmol.inp to be manually edited so that some additional constraints can be imposed. The user is referred to Packmol User's Guide for additional information. The Packmol algorithm is described in Ref. [4].
Examples:
The example above uses Packmol to create a random packing of molecules with density equal to 0.602214 Da/ų (1.0 g/cm³) in which one copy of molecule 1 is centered at the origin and 1000 copies of molecule 2 are packed with random positions and random orientations. The desired minimum intermolecular atomic distance is initially set to 3.0 Å, but Packmol will keep reducing the tolerance in 90% until the packing is successful. Finally, a LAMMPS data file is generated.
See also:
reset, diameter, box, build, write, bond_type, angle_type
Syntax:
write <format> [<file>] [keyword value keyword value...]
Description:
This command writes down the molecular system in a file or in the standard output device.
The parameter format must be one of the following options:
The optional parameter file is the name of the file which will contain the system info. If it is omitted, the info will be written in the standard output unit (the computer screen, in most cases).
Examples:
Syntax:
include <file>
Description:
This command redirects Playmol to read and execute commands from another script.
Examples:
See also:
Syntax:
reset <list>
Description:
This command resets one or more lists of entities previously created. The resettable lists are those in the table below.
| Index | List |
|---|---|
| 1 | atom types |
| 2 | masses |
| 3 | diameters |
| 4 | bond types |
| 5 | angle types |
| 6 | dihedral types |
| 7 | improper types |
| 8 | atoms |
| 9 | charges |
| 10 | bonds |
| 11 | angles |
| 12 | dihedrals |
| 13 | impropers |
| 14 | links |
| 15 | atomic coordinates |
| 16 | packmol fix/copy/pack specifications |
The parameter list must be one of the following options:
See also:
Syntax:
shell <command>
Description:
This command executes an external shell command.
Example:
The example above uses Linux command mv to rename a file from packmol.inp to system.inp and then executes Packmol using it as input.
See also:
Syntax:
quit [all]
Description:
This command interrupts the execution of a Playmol script, thus being useful for debugging purposes.
The optional keyword all forces Playmol to stop completely. In the absence of the keyword, the command quit has the same behavior of a normal end of file. For instance, if the script has been invoked by another script via the include command, execution of the invoking script continues.
Example:
The example above writes a summary of the current molecular system and then quits Playmol.
See also:
1.8.17
