3. Language
The scripting language in VIAMD is designed as a declarative language meaning we declare variables and assign them values through expressions. There is no explicit control flow such as for do/while. Every statement must end up being assigned to a variable. Variables that involve computations specific to molecular structures become properties that can be visualized in the different windows within VIAMD.
- string
- int
- float
- irange
- frange
- bitfield
- distribution
- volume
Arrays
Like most programming languages, this language supports selecting a subset from an array. This operation is performed using the bracket operator []
# select the first alanine residue
sel1 = resname("ALA")[1]
# select the last 4 alanine residue
sel2 = resname("ALA")[:4]
# select between the 3rd and 7th alanine residues
sel3 = resname("ALA")[3:7]Identifiers are variables that can be assigned values and later referenced in other expressions.
pi_half = PI / 2;
sel1 = resname("ALA");If the statement is 'constant', that is if the resulting value does not change
PI
TAU
E
Most functions have built-in visualizations to provide feedback on what action is performed or what atoms are involved. To visualize an expression, you hover it with your mouse. This will display the resulting type of the expression and if possible, visualize it.
Bitfields represent a set of atoms, every bitfield may also serve as a context for operations. Imagine the following scenario: we would like to compute the angle between three specific atoms within a certain residue type.
This can be realized by the usage of the keyword 'in' as shown in the following snippet:
# Computes the angle between atoms 1,2,3 within all residues named "ALA"
a1 = angle(1,2,3) in resname("ALA");The selection resname("ALA") returns an array of bitfields where each bitfield represents one matching structure (residues with the name "ALA"). The expression on the left-hand side of in is then evaluated once for each of the bitfields which serve as the context. This means that the indices (1,2,3) refer to local indices within the context. The operation (angle) returns a float result. Therefore when evaluated once for each of the N contexts, the resulting type of a1 is float[N].
This section provides a comprehensive list of all functions available in the language with a short description and example. Functions that have no arguments are shown with (void) as an argument list. For these functions the empty parenthesis is optional.
The selectors generate selections (bitfields) that can be used as input for property computations. The following selectors only depend on the current dataset and can thus be evaluated at compile time.
all (void) -> bitfield
Selects all atoms in the dataset
# selects all atoms
sel1 = all;
sel2 = all(); # The parenthesis is optional when we don't have any argumentsprotein (void) -> bitfield[N]
Selects all atoms in protein structures. Returns an array of bitfields of size N, where N is the number of proteins.
# selects all protein structures
sel1 = protein;
sel2 = protein();water (void) -> bitfield[N]
Selects all atoms which belong to water molecules. Returns an array of bitfields of size N, where N is the number of water molecules.
# selects all water structures
sel1 = water;
sel2 = water();ion (void) -> bitfield
Selects all monatomic ions. Monatomic ions are identified as non bonded single atom residues which have the following element types:
| element | type |
|---|---|
| Hydrogen | H+ / H- |
| Lithium | Li+ |
| Beryllium | Be2+ |
| Nitrogen | N3- |
| Oxygen | O2- |
| Flouride | F- |
| Sodium | Na+ |
| Magnesium | Mg2+ |
| Aluminium | Al3+ |
| Phosphorus | P3- |
| Sulfur | S2- |
| Chlorine | Cl- |
| Potassium | K+ |
| Calcium | Ca2+ |
| Chromium | Cr2+ / Cr3+ |
| Manganese | Mn2+ / Mn3+ |
| Iron | Fe2+ / Fe3+ |
| Cobalt | Co2+ / Co3+ |
| Copper | Cu1+ / Cu2+ |
| Zinc | Zn2+ |
| Selenium | Se2- |
| Bromine | Br- |
| Rubidium | Rb+ |
| Strontium | Sr2+ |
| Silver | Ag+ |
| Admium | Cd2+ |
| Tin | Sn2+ / Sn4+ |
| Iodine | I- |
| Cesium | Cs+ |
| Barium | Ba2+ |
| Mercury | Hg2+ |
| Lead | Pb2+ / Pb4+ |
# selects all ions
sel1 = ion;
sel2 = ion();type / name / label (string[]) -> bitfield
Selects atoms with a label matching the supplied argument string (case sensitive).
# selects all atoms named CA
sel1 = label("CA");
# selects all atoms named SA2
sel2 = name("SA2");element (string[] / int[] / irange[]) -> bitfield
Selects atoms with the element(s) specified within the argument.
# selects all carbon atoms
sel1 = element("C");
# selects all atoms wich have the atomic element number 8 (Oxygen)
sel2 = element(8);
# selects all atoms with elements from atomic element 1 through 3 (Hydrogen, Helium, Lithium)
sel3 = element(1:3);
# selects atoms with elements 1 through 4 or 8 or 31
sel4 = element({1:4, 8, 31});atom (int[] / irange[]) -> bitfield
Selects atoms with indices specified by the argument
# selects atoms 1 through 10
sel1 = atom(1:10);
# selects atoms 1, 5 and 10 through 20
sel2 = atom({1,5,10:20});resname (string[]) -> bitfield[N]
Selects all atoms in residues that have a residue name corresponding to the supplied argument. Returns an array of bitfields of size N, where N is the number of residues that had matching names.
# selects residues with the name ALA
sel1 = resname("ALA");
# selects residues with the name LYS or VAL
sel2 = resname({"LYS", "VAL"});residue (int[] / irange[]) -> bitfield[N]
Selects all atoms in residues that have a residue index corresponding to the supplied argument. Returns an array of bitfields of size N, where N is the number of residues that had matching indices. (Note: This is the index in which the residues are specified in the dataset. Which may differ from resid)
# selects residues 1 through 10
sel1 = residue(1:10);
# selects residues 1, 5, and 10 through 20
sel2 = residue({1,5,10:20});resid (int[] / irange[]) -> bitfield[N]
Selects all atoms in residues that have a residue id corresponding to the supplied argument. Returns an array of bitfields of size N, where N is the number of residues that had matching indices. (*Note: This is the id, not the index in which residues were supplied in the dataset.)
# selects residues with id 1 through 3
sel1 = resid(1:3);
# selects residues with id 1, 5, and 10 through 13
sel2 = resid({1,5,10:13});chain (int[] / irange[] / string[]) -> bitfield[N]
Selects all atoms in chains that match the supplied argument. Returns an array of bitfields of size N, where N is the number of chains that had matched. If an int or irange is supplied, this is matched against the index of the chain. If strings are supplied, this is matched to the label of the chains.
# selects chains with index 1 to 3
sel1 = chain(1:3);
# selects chains that have labels 'A', 'B' or 'C'.
sel2 = chain({'A','B','C'});Dynamic selectors are functions that generate selections (bitfields) but depend on the atomic positions and thus need to be re-evaluated for every trajectory frame.
within_x (frange) -> bitfield
within_xy (frange/frange) -> bitfield
within_xyz (frange/frange/frange) -> bitfield
Select all atoms with atomic positions (x,y,z) within a coordinate range.
# selects all atoms with x,y,w coordinates between 40 and 80 Å.
sel1 = within_xyz(40:80,40:80,40:80);
# selects all oxygen with y smaller than 30 Å and z greater than 60 Å.
sel2 = element('O') and within_yz(:30,:60);within (float / frange) -> bitfield
Select all atoms within a radius of a reference.
# selects all atoms within 5 Å of the first "ALA" residue of my system.
sel1 = within(5.0,resname("ALA")[1]);
# selects all water atoms within 5 Å of the residue named "AIN"
sel2 = water and within(5.0,resname("AIN"));
# selects all water residue within 5 Å of the residue named "AIN"
sel3 = residue(water and within(5.0,resname("AIN")));The following functions compute atomic/molecular properties and all depend on the atomic positions. Thus they need to be evaluated for every trajectory frame.
angle (float[3], float[3], float[3]) -> float
Computes the angle between three atoms.
# a1 is the angle between atom 1, 2 and 3.
a1 = angle(1,2,3);
# a2 is the angle between atom 1, 2 and 3 in all the residues named "ALA".
a2 = angle(1,2,3) in resname("ALA");com (float[3][] positions) -> float[3]
Computes the center of mass from a given set of positions.
# Define the center of mass of residue 1,4,6,9.
com_1469 = com(residue({1,4,6,9}));
# Define the center of mass of a protein.
com_prot = com(prot);coord_x (bitfield[N]) -> float[N]
coord_y (bitfield[N]) -> float[N]
coord_z (bitfield[N]) -> float[N]
Extract the coordinate of a bitfield.
# Extract the x component of the carbons of the system.
s1 = coord_x(element('C'));
# Extract the y coordinates of the residue 10.
s2 = coord_y(residue(10));
# Extract the z coordinated of all the sodium atom.
s3 = coord_z(resname("SOD"));count ((bitfield[N]) -> float[N]
Count the components of a dynamic selections.
# Count the atoms of water and within 5 Å of the residue named AIN.
c1 = count(water and within(5.0, resname("AIN")));
# or
c2 = count(water and within(5.0, resname("AIN")),'atom');
# Count the residues of water and within 5 Å of the residue named AIN.
c3 = count(water and within(5.0, resname("AIN")),'residue');density_x (bitfield[N]) -> float[N]
density_y (bitfield[N]) -> float[N]
density_z (bitfield[N]) -> float[N]
Computes the density (kg.m-3) of a bitfield along one direction of the box.
# Calculate the density of POPC along the x axis of the box
d_popc = density_x(resname("POPC"));
# Calculate the density of the hydrogen of water along the y axis of the box.
d_Oh = density_y(element('O') in resname("SOL"));
# Calculate the density of the first 10 atoms of resname POPC along the z axis of the box.
d_head = density_y(atom(1:0) in resname("POPC"));dihedral (float[3], float[3], float[3], float[3]) -> float Computes the dihedral angle between four atoms.
# d1 is the dihedral angle between atom 1, 2, 3 and 4.
d1 = dihedral(1,2,3,4);
# d2 is the dihedral angle between atom 1, 2 and 3 in all the residues named "ALA".
d2 = dihedral(1,2,3,4) in resname("ALA");distance (float[3], float[3]) -> float
Computes the distance between two atoms.
# d1 is the distance between 1 and 2.
d1 = distance(1,2);
# d2 is the distance between atom 1, 2 in all the residues named "ALA".
d2 = distance(1,2) in resname("ALA");distance_min (float[3][], float[3][]) -> float
Computes the minimun distance between two bitfield.
# d1 is the minimum distance between the protein and the aspirin molecule: resname("AIN")
d1 = distance_min(protein,resname("AIN");distance_max (float[3][], float[3][]) -> float
Computes the maximum distance between two bitfield.
# d2 is the maximum distance between the protein and the aspirin molecule: resname("AIN")
d2 = distance_min(protein,resname("AIN");distance_pair (float[3][N], float[3][M]) -> float[N*M]
Computes the distance pair between two bitfield.
# d1 is the distances between each atom of the protein and all the atoms of resname("AIN")
d1 = distance_pair(protein,resname("AIN"));
# d2 is the distances between each residue(com) of the protein and the com of resname("AIN")
d2 = distance_pair(residue(protein),com(resname("AIN")));rmsd (bitfield[N]) -> float[N]
Computes the rmsd of a bitfield.
# r1 is the rmsd of residue 23.
r1 = rmsd(residue(23));
# r2 comtains the rmsd of every water molecule.
r2 = rmsd(all) in resname("SOL");rdf (float[3][] reference_positions, float[3][] target_positions, float cutoff) -> distribution
Computes the radial distribution function from a set of given positions. The distance from each reference position to each target position is accumulated into a distribution.
# r1 is the rdf of the hydrogen atoms of water with respect to the com of water within 20 Å.
r1 = rdf(resname("SOL"), element('H') in resname("SOL"), 20.0);
# r2 is the rdf of the hydrogen atoms of water with respect to the oxygen of water within 20 Å.
r2 = rdf(element('O') in resname("SOL"), element('H') in resname("SOL"), 20.0); shape_weights (bitfield[N]) -> N * float,float,float
Extract the three shape space components: linear, planar and isotropic of a bitfield.
# lin, plan and iso are the percentage for the full system. Bitfield dimention 1.
{lin,plan,iso} = shape_weights(all);
# lin2, plan2 and iso2 are the percentage for each of the N PFT molecules. Bitfield dimention N.
{lin2,plan2,iso2} = transpose(shape_weights(resname("PFT")));sdf (bitfield[N] reference_structures, float[3][] target_positions, float cutoff) -> volume
Computes the spatial distribution function from a set of given reference structures. Each target position is transformed into the internal reference frame of each reference structure. The occurrence of each target position with respect to each reference frame is aggregated into a density volume.
# V1 is the sdf of the hydrogen atoms of water with respect to the com of water within 20 Å.
r1 = sdf(resname("SOL"), element('H') in resname("SOL"), 20.0);
# r2 is the sdf of the hydrogen atoms of water with respect to the residue 1, 2 and 3 within 20 Å.
r2 = sdf(join(residue(1:3)), element('H') in resname("SOL"), 20.0);
