Requirements

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.

Downloading PUPIL

You can find the latest version of PUPIL here.

Building PUPIL

  1. 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.
  2. Unpack the PUPIL distribution:
    bash$ cd /usr/local
    bash$ tar zxvf pupil-v3_0_0.tar.gz
    This will create the pupil-v3_0_0 directory, with the PUPIL files in it.
  3. 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:
    export PUPIL_PATH=/usr/local/pupil-v3_0_0
  4. Configure PUPIL:
    bash$ cd $PUPIL_PATH
    bash$ ./configure
    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.
  5. Build and install the PUPIL binaries and libraries:
    bash$ make
    bash$ make install
  6. Add the PUPIL library path to the $LD_LIBRARY_PATH environment variable:
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PUPIL_PATH/lib
    Note: Java libraries may be are necessary to be specified on some platforms:
    export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib:$JAVA_HOME/jre/lib/$PROC:$JAVA_HOME/jre/lib/$PROC/server:$LD_LIBRARY_PATH
    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.

Building sander.PUPIL

Here we assume you have already installed and tested AmberTools14 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 sander.PUPIL executable:
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

Other Executables

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. For example:
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 system:
Amber
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 and inptraj.
Gaussian
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: TcTS.gjf.
Now we can start building the PUPIL input file.
  1. Load the PUPIL GUI
    bash$ $ $PUPIL_PATH/bin/pupil-gui & After a while, a screen like this should appear:
    PUPIL GUI
  2. Create a new simulation file:
    Click the "Simulation" menu. From the menu, select "New Simulation Input":
    New simulation input
    A window like the following will appear:
    New Simulation Box
    Simulation name:
    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.
    After setting those values, click "OK".
  3. Now we choose the QM program. In the GUI main window, click the "Gaussian" radio button. A window like the following should appear:

    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):

    PUPIL-GUI with QM molecule loaded
    Now, we can load the Amber input.

  4. Click in "Amber MD" on the "Molecular Dynamics" panel. A window like this will open:
    Amber Input Files
    Path to executable:
    Enter the path to the sander executable (e.g., /usr/local/pupil/pupil-v2.0.0/bin/sander).
    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 sander) extract information every N steps and save to a file named "output.xml" 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.
    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:
    PUPIL GUI showing the MM systemPUPIL 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.

  5. Click in "Manual Region Specification" on the "Domain Identification" panel. A window like this will open:
    Embedding rules dialog

    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:
    1. Click the "Add" button to create an entry in the table.
    2. Under the "Atom or Residue" column, select "RESIDUE" from the drop-down menu.
    3. Under the "Selection" column, type the residue number or the range of residue numbers (i.e., 372-373)
    4. Under the "QM type" column, select "Default" from the drop-down menu.
      Note: Only in case of assigning a single atom is allowed to specify different QM type than those of default type
  6. This will define all atoms in the listed residues as part of the QM zone.

    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 protein:
    • 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)
    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:
    1. Click the "Add" button to add an entry in the table.
    2. Under the "QM atom num" column, enter the atom number of the QM host.
    3. Under the "MM atom num" column, enter the atom number of the MM host.
    4. Under the "Link QM type" column, select, from the drop-down menu select "H".
    5. 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:
    1. Click the "Add" button to create a new entry in the table.
    2. Under the "Atom or Residue" column, select "RESIDUE"from the drop-down list.
    3. Under the "Selection" column, enter the range or residue numbers.
    4. 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.
    The external file with the partitioning rules specific for this tuturial can be found here.
    1. Click the "Load" button to add the new rules to the tables.
    2. Look for the embedRules.txt file in your filesystem.
    3. Click the "Ok" button to save the new loaded rules in the PUPIL GUI memory.
    At this point, your screen should look something like this:
    Embedding rules box, after filling

  7. Finally, click the "OK" button to go back to the mainscreen.
  8. 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.
  1. 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).
  2. 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
  3. Submit this file to your queue system or execute interactively to run the calculation.
That's it!

Created by Gustavo Seabra at March 20th, 2009 using Document made with KompoZer.
Last updated to PUPIL v3.0 by J. Torras at December 7th, 2014.
pupil-run