- Java version 1.7 or higher
- We recommend the Oracle JRockit (old BEA JRockit), which can be downloaded for free
from the Oracle website.
- Apache ant builder
- Ant, which stands for "Another Neat Tool",
is a Java-based build tool. You will need it to build the
PUPIL system. You can find it here.
- C and Fortran compilers and GNU Make (gmake)
- Most likely, you already have these installed on your system.
You can find the latest version of PUPIL here
- Download the latest version of PUPIL from here,
and put it in a directory of your choice. Here, we will suppose you put it in /usr/local.
Unpack the PUPIL distribution:
bash$ cd /usr/local
This will create the pupil-v3_0_0
directory, with the PUPIL files in it.
bash$ tar zxvf pupil-v3_0_0.tar.gz
Create the "PUPIL_PATH"
environment variable, pointing it to that directory:
bash$ export PUPIL_PATH=/usr/local/pupil-v3_0_0
Note: "PUPIL_PATH" must be
set in your environment whenever you use PUPIL. You can set it automatically each
time you start a new shell by adding the following
line to your .bashrc file:
bash$ cd $PUPIL_PATH
Configure command allows several options to refine the configuration of PUPIL.
Thus, with the --prefix option you can change the install location
(default: /usr/local), and using the --with [executable] option you can
specify where the calculation unit executables will be located.
Also, environment variables such as CC and FC can be set to choice of compiler.
See all available options running the command ./configure --help.
Build and install the PUPIL binaries and libraries:
bash$ make install
Add the PUPIL library path to the $LD_LIBRARY_PATH environment variable:
Note: Java libraries may be are necessary to be specified on some platforms:
where $JAVA_HOME is a variable with the full path to the Java installation (or equivalent)
and $PROC is the type of processor in your computer.
Check your Java installation for specific details.
Here we assume you have already installed and tested
package, independently of PUPIL.
If not, please go back to the Amber installation and make sure you have
a properly working serial version of sander
program before continuing.
Now that you have the PUPIL libraries installed, compile the
bash$ cd $AMBERHOME/AmberTools/src/sander
bash$ make clean
bash$ make $AMBERHOME/bin/sander.PUPIL
Alternatively you can compile all additional stand-alone programs (which
also includes sander.PUPIL) by executing the following command:
bash$ make all_serial_programs
This will create the sander.PUPIL executable,
which you can move to the $AMBERHOME/bin
directory, or to any other place you want.
You will now need to tell PUPIL where to find this executable. PUPIL
will look for a file called sander
in the $PUPIL_PATH/bin
directory. So, you can either copy the sander.PUPIL
executable there with the new name:
bash$ cp $AMBERHOME/bin/sander.PUPIL $PUPIL_PATH/bin/sander
or create a symbolic link there:
bash$ ln -s $AMBERHOME/bin/sander.PUPIL $PUPIL_PATH/bin/sander
To use the Amber/PUPIL/Gaussian interface, you must also tell PUPIL
where to look for the gaussian executable. As with the
sander executable, PUPIL will expect this file to be in $PUPIL_PATH/bin,
but you may create symbolic links in that directory to the real files.
bash$ ln -s /share/local/bin/g03-64 $PUPIL_PATH/bin/g03
After that, you should be ready to start running Amber/PUPIL/Gaussian calculations.
Building PUPIL's input
Now that you have PUPIL properly installed, the PUPIL input may be created.
But before you start, you must have working Amber and Gaussian files for your
- Those are exactly the same files you would use in a regular
Amber calculation. Since we are postprocessing a trajectory, the files
you need are inpcrd, prmtop, mdin
All you need is a working Gaussian input file with all the atom
types that may enter the QM zone inyour system. The easiest way
to do that is to create a Gaussian input file containing your quantum
zone. If you want to use different basis sets for different atoms in
your system, make sure to have a special label for each different
atom/basis set combination you are using. This input file does not need
to contain point charges, or any other definition for the classical
part of the system. In this case, the Gaussian input file includes
the enzyme residues Ash 59, Glu 230, Tyr 342 and the ligand, sialic
acid, represented in Amber by the residues OME372 and 1SA373:
Now we can start building the PUPIL input file.
- Load the PUPIL GUI
bash$ $ $PUPIL_PATH/bin/pupil-gui &
After a while, a screen like this should appear:
Create a new simulation file:
Click the "Simulation" menu. From the menu, select "New Simulation Input":
A window like the following will appear:
- Simulation name:
After setting those values, click "OK".
- Here you can enter anything as the simulation name.
For now, let's use "TcTS".
- Base directory:
- Enter the directory where the simulation is located.
We can enter ".", the current directory.
- Log level:
- Defines the verbosity of the AppServer.log file.
Leave Normal log printing, allowing the user
to follow the simulation's progress.
- Max number of Java threads:
- Defines the number of threads used by threaded parts of Java code
Leave this option as it is. At present, no calculation
takes advantage of this facility and it was deactivated.
- Java Memory:
- Java memory should be modified in case of very big simulated system only.
Now we choose the QM program. In the GUI main window, click the
"Gaussian" radio button. A window like the following should
- Path to executable:
- Enter the path to the g03Linux file (e.g. /usr/local/pupil-v2.0.0/bin/g03)
- Run application in parallel using MPI:
- This quantity is applicable only to programs that use MPI for
parallelization. Do not check this box here.
- Save output and error files at this interval (steps):
- It save the information written by the QM CU to standard
output and standard error every so many steps.
Leave unchecked this option.
- Use periodic boundaries:
- If checked, this box tells PUPIL that the MD calculation is using
periodic boundaries, and that PUPIL should wrap the coordinates
around the QM system before sending them to the QM program. In our
case, we are using a gas phase calculation, so just leave it unchecked.
- Use Cyclic QM through CORBA:
- This applies only for QM packages that are integrated with PUPIL
at source code level. Since Gaussian is not such a package, you
should leave this box unchecked.
- Use the Chain Rule for pairs of link atoms:
- Tells PUPIL to use the chain rule to distribute the forces over both
atoms in a link-atom pair. If we were doing a real MD simulation, we
would check that. But since we are only interested in postprocessing for
energies, we will leave it unchecked.
- Apply a post-QM Coulomb force correction to MM atoms:
- Tells PUPIL to use its routines to calculate the force over
the MM atoms due to their interactions with the QM electronic density.
Important when we need the forces over the MM zone and those forces are not
automatically provided by the QM program. Again, since we are just
postprocessing the file for energies, we don't need this option.
- Total charge of the MM embedding zone:
- Net charge of the classical region. Enter "0".
- Gaussian version:
- Select your Gaussian version from the Combo box.
- Gaussian Job File:
- Enter the path to the "TcTS.gjf" file.
- Save formatted checkpoint files at this interval (steps):
- It save the Gaussian checkpoint files every so many steps.
Check this option and enter "1".
- Other required files:
- No additional files are required. Leave this field empty.
After filling this information, click "OK", and PUPIL will parse the input file. The space
on the right side of the GUI window should now show the QM system, as
read from the Gaussian file. In the end, your window should look like
that (you can rotate the molecule for a better view):
Now, we can load the Amber input.
Click in "Amber MD" on the "Molecular Dynamics" panel.
A window like this will open:
When you are done, press "OK" and PUPIL will parse the
sander input files. The image in the right-hand pane should now show the
whole MM system:
- Path to executable:
- Enter the path to the sander executable (e.g.,
- Number of Processors:
- This is similar to the QM part. Since the QM calculation
takes most of the time, we haven't created an MPI version of
sander.PUPIL. This field should therefore be set to 0.
- MD steps to extract results:
- The Amber simulation will automatically write results to the
mdout file. The number
here tells PUPIL to (independently from
extract information every N steps and save to a file named
Put anything you want in this field, but remember this test case
only has 2 steps!
- File locations:
- Here you can set the location of a number of input files for amber,
depending on the type of calculation you are doing. For this calculation,
we will specify the paths to mdin, prmtop, inpcrd, and inptraj, leaving the
remaining paths empty.
PUPIL GUI showing the MM system
Now, PUPIL has all the information it needs to compile a translation
table between QM and MM input files, i.e., the table that will map
each QM atom to its MM counterpart.
Click in "Manual Region Specification" on the "Domain Identification" panel.
A window like this will open:
This will define all atoms in the listed residues as part of the
- Partitioning Rules:
This dialogue box provides the user with the option to assign, by means of a
specific set of rules, a fixed quantum zone and its embedding.
Note that all atoms in the entire system must be
accounted for here, in one pane or another. The dialogue box allows the user
to differentiate between three Zones (or Regions),
namely the QUANTUM, CLASSICAL, and STATIC-CHARGE regions. Each particle must be
assigned to one of these three regions. Notice that all the rules belonging to
an specified zone will be considered in the given order from the bunch of
particles that are yet to be assigned. So, in this tutorial the use of Direct
Assignment Rules and the Fixed-link Pairs Rules is being used by filling the
first three boxes to define its partitioning zones:
- Specification of QM region:
This box allows user specify all atoms/residues belonging entirely to
the Quantum zone. In this case, those residues are numbers 59, 230, 342,
372 and 373. For each one of these, do the following:
- Click the "Add" button to create an entry in the table.
Under the "Atom or Residue" column, select "RESIDUE" from the
Under the "Selection" column, type the residue number or the
range of residue numbers (i.e., 372-373)
Under the "QM type" column, select "Default" from the
Note: Only in case of assigning a single atom is allowed
to specify different QM type than those of default type
- Specification of the Fixed Link Pairs:
- The residues defined above, being entirely QM, were easy to define.
Residues 372 and 373 represent the enzyme substrate, and are not
covalently connected to the enzyme. On the other hand, residues Ash 59,
Glu 230 and Tyr 342 are each connected to two other residues in the
Thus, there are six covalent bonds between the QM and MM regions.
To complete the valences of the QM atoms at the boundary, each
MM atom that is connected to one or more QM atoms will be replaced,
for the purposes of the QM calculation, by a QM "link atom", usually
a hydrogen atom, although another element could be used. For the
purposes of the MM calculation, the original MM atom type is used.
The user should specify both MM host and QM host for each one of
"link-pairs" and the QM type of the new QM "link atom". By default,
the "link-atom" will be located at the CLASSICAL zone and evaluated
after rules belonging to QUANTUM zone; the criteria are specified in
this pane. For each of the link-pair, do:
- Ash 59 is connected to Phe58:C and Asn60:N.
- Phe58:C as MM atom (num. 917) with Ash59:N as QM atom (num. 919)
- Asn60:N as MM atom (num. 932) with Ash59:C as QM atom (num. 930)
- Glu 230 is connected to Ser229:C and Pro231:N.
- Ser229:C as MM atom (num. 3521) with Glu230:N as QM atom (num. 3523)
- Pro231:N as MM atom (num. 3538) with Glu230:C as QM atom (num. 3536)
- Tyr 342 is connected to Ala341:C and Ser343:N.
- Ala341:C as MM atom (num. 5312) with Tyr342:N as QM atom (num. 5314)
- Ser343:N as MM atom (num. 5335) with Tyr342:C as QM atom (num. 5333)
- Click the "Add" button to add an entry in the table.
- Under the "QM atom num" column, enter the atom number of the QM host.
- Under the "MM atom num" column, enter the atom number of the MM host.
- Under the "Link QM type" column, select, from the drop-down
menu select "H".
- Under the "Link dist. to QM" column, enter "1.0"
For example, on the first "link-pair", we are basically telling
PUPIL to create a new "link atom" using a QM hydrogen atom. That hydrogen
atom is to be positioned at 1.0 Å distance from the QM host atom (919)
along the bond direction between atoms 919 and 917.
- Specification of MM Regions.
- At this point, we have defined all quantum atoms as well as the
link QM atoms connecting quantum and classical zones; now, all
remaining atoms have to be defined as MM atoms (as a point charges
in an elestrostatic embedding scheme). We will achieve this by
assigning these to the STATIC-CHARGE zone using either range of atom
numbers or range of residue numbers. For those residues that have been
partially assigned previously to any of the previous zones, only
remaining particles will be assigned.
For each one of remaining residues (i.e., 1-58, 60-229, 231-341,
and 343-371), do the following:
- Click the "Add" button to create a new entry in the table.
- Under the "Atom or Residue" column, select "RESIDUE"from the
- Under the "Selection" column, enter the range or residue numbers.
- Under the "MM Type" column, select "Default" from the drop down list.
Either range and residues always have to be assigned the default MM type.
- Saving/Loading Partitioning Rules.
- Alternativelly to previous section, this new capability allows the
user either load or save partitioning rules from/to an external file in
order to create, transfer, and edit partitioning rules easily between
different simulations. Thus, the user can edit an external file with any
of their favourite text editor and then load directly in the Manual
Partitioning Rules dialog. See PUPIL manual in order to get more details
of the external file sintax.
At this point, your screen should look something like this:
The external file with the partitioning rules specific for this tuturial
can be found here.
- Click the "Load" button to add the new rules to the
- Look for the embedRules.txt file
in your filesystem.
- Click the "Ok" button to save the new loaded rules in the PUPIL GUI
Finally, click the "OK" button to go back to the mainscreen.
Choose Save (from the File menu) to save the simulation input file with
the name of your preference, for instance "data.xml".
That's it. Now you have the simulation file with all the information
you need to run an Amber/PUPIL/Gaussian calculation. The next step is
to run it.
Running a Calculation
To run the calculation, do the following steps.
- Copy the pupil-run.sh
script from the $PUPIL_PATH/bin
directory to the directory where you intend to run the calculation.
This should be where the data.xml
file is located. Note that you should copy pupil-run.sh,
rather than make a symbolic link to it, because the pupil-run.sh
provided is a template which must be edited before being executed (see below).
Edit the pupil-run.sh
file to conform to your queues directives (e.g., PBS directives). Depending
on your machine, you may also need to add a "cd <directory
path>" at the beginning of this file, etc.
Alternatively, you can create an specific shell to prepare your queue system,
adding the pupil-run.sh.
command or just run interactively in your workstation
bash$ pupil-run.sh ./data.xml
- Submit this file to your queue system or execute interactively to run the calculation.