Amber/PUPIL/Gaussian Tutorial

[Top]
Requirements
Downloading PUPIL
Building PUPIL
Building sander.PUPIL
Other Executables
Building PUPIL's input
Running a Calculation

Requirements

Java version 1.11 or higher: We recommend the Oracle JDK, 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.
Cmake 15.0 and upper: You can download the most recent version here
Tutorial files: You can download all the necessary tuturial files in a tar.gz format.

Downloading PUPIL

You can find the latest version of PUPIL here.

Building PUPIL

Download the latest version of PUPIL from here, and put it in a directory of your choice. Here, we will suppose you put the source code in /home/user , the building directory in /home/user/build, and the installed PUPIL binaries in /usr/local/pupil-v4_0.
Unpack the PUPIL distribution:
bash$ cd /home/user bash$ tar zxvf pupil-v4_0.tar.gz This will create the pupil-v4_0 directory, with the PUPIL files in it.
Create the "PUPIL_PATH" environment variable, pointing it to the directory where PUPIL will be installed:
bash$ export PUPIL_PATH=/usr/local/pupil-v4_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-v4_0
Create a build directory and go into it:
bash$ mkdir /home/user/build bash$ cd /home/user/build
Build PUPIL: bash$ cmake ../pupil-4.0 -DCOMPILER=”GNU” -DCMAKE_INSTALL_PREFIX=/usr/local/pupil-v4_0 The -DCMAKE_INSTALL_PREFIX option allows you to change the install location (default: /usr/local); The -DCOMPILER option makes possible to change between GNU and INTEL compilers.
Build and install the PUPIL binaries and libraries:
bash$ make bash$ make install
Add the PUPIL library path to the $PATH and $LD_LIBRARY_PATH environment variables:
export PATH=$PATH:$PUPIL_PATH/bin:$PUPIL_PATH/lib
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:$JAVA_HOME/lib:$JAVA_HOME/lib/server:$LD_LIBRARY_PATH
where $JAVA_HOME is a variable with the full path to the Java installation (or equivalent). Check your Java installation for specific details.

Building sander.PUPIL

Here we assume you have already installed and tested AmberTools22 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, you can recompile AmberTools using cmake utility. The external PUPIL libraries will be recognized by the Amber installation procedure to obtain the sander.PUPIL executable.
Move to the AMBER build directory, allocated on the top directory of the uncompressed file, and run the following script (Cmake must be installed in your operanting system):


    bash$ ./run_cmake

If the cmake build report looks OK you can run the next commands.
To see if amber compilation have find the pupil libraries (remember that you should add the $PUPIL_PATH/lib to the $PATH and $LD_LIBRARY_PATH environament variables) at the end of the cmake build you should see a section called 3rd Party Libraries, and in the subsection “using installed” you should find a line listing pupil as a 3rd party library. If it doesn’t appear it means that the initial configuration by cmake has not worked.
Then you can proceed with the compilation and installation of the binaries.


    bash$ make install 

    bash$ source /path/to/Amber/Install/dir/amber.sh

This will create the sander.PUPIL executable located in the $AMBERHOME/bin directory.
You will need now 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/g09 $PUPIL_PATH/bin/gaussian

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 in your 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.

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:

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.

Java Memory:

Java memory should be modified in case of very big simulated system only.

After setting those values, click "OK".

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 g09 Linux file (e.g. /usr/local/pupil-v4.0/bin/gaussian)

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

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. Input file diferences are set by selecting either the g03 version or later ones (gaussian).

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:

Path to executable:

Enter the path to the sander executable (e.g., /usr/local/pupil-v4.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 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:

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

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:

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 drop-down list.
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.
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 tables.
Look for the embedRules.txt file in your filesystem.
Click the "Ok" button to save the new loaded rules in the PUPIL GUI memory.

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.

That's it!

Created by Gustavo Seabra at March 20th, 2009 using

.
Last updated to PUPIL v4.0 at August 1st, 2022.

Using PUPIL to postprocess a MD trajectory obtained by Amber using a QM method from Gaussian09 In this tutorial, we will build the inputs necessary to use PUPIL to postprocess a trajectory previously obtained using Amber, now using a QM method from the Gaussian09 program. Our test trajectory is actually made of only two structures for the Tripanosoma cruzi trans-sialidase enzyme, which we will postprocess in Gaussian using HF/3-21G*.
[Top] Requirements Downloading PUPIL Building PUPIL Building sander.PUPIL Other Executables Building PUPIL's input Running a Calculation	Requirements Java version 1.11 or higher We recommend the Oracle JDK, 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. Cmake 15.0 and upper You can download the most recent version here Tutorial files You can download all the necessary tuturial files in a tar.gz format. Downloading PUPIL You can find the latest version of PUPIL here. Building PUPIL Download the latest version of PUPIL from here, and put it in a directory of your choice. Here, we will suppose you put the source code in /home/user , the building directory in /home/user/build, and the installed PUPIL binaries in /usr/local/pupil-v4_0. Unpack the PUPIL distribution: `bash$ cd /home/user bash$ tar zxvf pupil-v4_0.tar.gz` This will create the pupil-v4_0 directory, with the PUPIL files in it. Create the "PUPIL_PATH" environment variable, pointing it to the directory where PUPIL will be installed: `bash$ export PUPIL_PATH=/usr/local/pupil-v4_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-v4_0 Create a build directory and go into it: `bash$ mkdir /home/user/build bash$ cd /home/user/build` Build PUPIL: `bash$ cmake ../pupil-4.0 -DCOMPILER=”GNU” -DCMAKE_INSTALL_PREFIX=/usr/local/pupil-v4_0` The -DCMAKE_INSTALL_PREFIX option allows you to change the install location (default: /usr/local); The -DCOMPILER option makes possible to change between GNU and INTEL compilers. Build and install the PUPIL binaries and libraries: `bash$ make bash$ make install` Add the PUPIL library path to the $PATH and $LD_LIBRARY_PATH environment variables: export PATH=$PATH:$PUPIL_PATH/bin:$PUPIL_PATH/lib 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:$JAVA_HOME/lib:$JAVA_HOME/lib/server:$LD_LIBRARY_PATH where $JAVA_HOME is a variable with the full path to the Java installation (or equivalent). Check your Java installation for specific details. Building sander.PUPIL Here we assume you have already installed and tested AmberTools22 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, you can recompile AmberTools using cmake utility. The external PUPIL libraries will be recognized by the Amber installation procedure to obtain the sander.PUPIL executable. Move to the AMBER build directory, allocated on the top directory of the uncompressed file, and run the following script (Cmake must be installed in your operanting system): `bash$ ./run_cmake` If the cmake build report looks OK you can run the next commands. To see if amber compilation have find the pupil libraries (remember that you should add the $PUPIL_PATH/lib to the $PATH and $LD_LIBRARY_PATH environament variables) at the end of the cmake build you should see a section called 3rd Party Libraries, and in the subsection “using installed” you should find a line listing pupil as a 3rd party library. If it doesn’t appear it means that the initial configuration by cmake has not worked. Then you can proceed with the compilation and installation of the binaries. `bash$ make install bash$ source /path/to/Amber/Install/dir/amber.sh` This will create the sander.PUPIL executable located in the $AMBERHOME/bin directory. You will need now 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/g09 $PUPIL_PATH/bin/gaussian` 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 in your 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. 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: 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. Java Memory: Java memory should be modified in case of very big simulated system only. After setting those values, click "OK". 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 g09 Linux file (e.g. /usr/local/pupil-v4.0/bin/gaussian) 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 RMI: 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. Input file diferences are set by selecting either the g03 version or later ones (gaussian). 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: Path to executable: Enter the path to the sander executable (e.g., /usr/local/pupil-v4.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 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: 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 drop-down menu. 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 drop-down menu. Note: Only in case of assigning a single atom is allowed to specify different QM type than those of default type 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: 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 drop-down list. 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. 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 tables. Look for the embedRules.txt file in your filesystem. 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: 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. That's it!
Created by Gustavo Seabra at March 20th, 2009 using . Last updated to PUPIL v4.0 at August 1st, 2022.

Using PUPIL to postprocess a MD trajectory obtained by Amber using a QM method from Gaussian09