Tutorials

You will need the GNU c++ compiler. Once you have downloaded the source package to your computer, uncompress the gz file and run make from the PL directory:

$ tar xvfz PL-0.9.4-src.tar.gz
$ cd PL-0.9.4-src
$ make -f Makefile.linux
...

If the compilation proceeds without errors, the PL library file will be created in the bin directory:

$ ls bin
libPL.so*

To install the library, type (as root user):

$ make -f Makefile.linux install
mkdir /usr/lib/ -p
cp ./bin/* /usr/lib/
mkdir /usr/include/PL -p
cp ./include/*.h /usr/include/PL

This operation will install the header files as well. The default library installation directoy is /usr/lib and the default include directory is /usr/include/PL. To change them, edit the variables LIB_INSTALL_DIR and INC_INSTALL_DIR in Makefile.linux.

The PL plugins also require the the GNU c++ compiler. The plugins source package includes a master Makefile that will compile all the calculation and IO plugins. Alternatively, each plugin can be compiled separately by calling make from the corresponding plugin directory. See the following example:

$ tar xvfz PL-plugins-0.9.4-src.tar.gz
$ cd PL-plugins-0.9.4-src
$ make -f Makefile.linux
...
$ make clean
$ cd io/FASTAread
$ make -f Makefile.linux
...

The plugins need to be linked against code included in the PL source tree, and the individual Makefile of each plugin specify /usr/src/PL as the PL source directory. Change the value of the variable PL_SRC_DIR to use a different directory. Also, running make install will copy the library files to /usr/lib/PL. Edit the variable INSTALL_DIR to change this default.

The PL can be used interactively from Perl or Python (and, in principle, from any scripting language supported by SWIG). The first step consists to create the wrappers and library files so that the Perl and Python interpreters can load the PL as a valid module. In order to complete this step, SWIG has to be installed in your computer. All the configuration files and scripts are already included in the PL source package, and the following steps should be enough to get Perl:

$ cd PL-0.9.4-src/wrap/perl
$ ./create_wrapper
Creating C and perl wrappers...
Compiling perl library...
DONE.
$ ./install_wrapper

and Python support:

$ cd PL-0.9.4-src/wrap/python
$ ./create_wrapper
Creating C and python wrappers...
Compiling python library...
DONE.
$ ./install_wrapper

Once that the Perl and Python modules have been installed, the entire PL API can be used from any of these languages:

$ perl
use PL;
print PL::plVersion();
0.9.4
$

In this section we will focus in the Python usage. First it should be noted that for the Python interpreter to correctly load the PL module, the location of the module has to be added to the PYTHONPATH environmental variable, by issuing the following command before running Python:

export PYTHONPATH=/usr/lib/python2.3/site-packages/PL

An alternative and more convenient solution is to add the export line to the file ~/.bashrc, to initialize PYTHONPATH every time you login to your account.

Once inside the Python interpreter, run the following instructions to check that the PL module was properly installed:

>>> from PL import *
>>> print plVersion()
0.9.4
>>>

Suppose that we want to load a pdb file, rotate a dihedral angle and then to save the modified structure in a new pdb. We could proceed as follows:

>>> plLoadBondsList('/usr/share/PL/Connectivity.par')
0
>>> plLoadStrFromFile('./test.pdb', \ 
                      '/usr/lib/PL/io/libPDBread.so', \
                      true, false, true, false)
0
>>> print 'Phi angle of residue 10 is',plBondAngle(0, 9, plBD(0, 9, PHI))
Phi angle of residue 10 is -96.2711797041
>>> plSetBondAngle(0, 9, plBD(0, 9, PHI), 90.0, false)
>>> print 'New phi angle of residue 10 is',plBondAngle(0, 9, plBD(0, 9, PHI))
New phi angle of residue 10 is 90.0
>>> plSaveStrToFile('./test-new.pdb', \
                    '/usr/lib/PL/io/libPDBwrite.so', \
                    true, true, false, false, true)
0

The first instruction, plLoadBondsList('/usr/share/PL/Connectivity.par'), loads the atom connectivity information needed by the PL to construct the bonds in the protein molecule. The Connectivity.par file can be found in the PL/par directory of the PL source package, and it will be installed to /usr/share/PL by running the install.linux script (also found in PL/par). If the atom connectivity is not loeaded, trying to rotate dihedral bonds will generate a segfault, since the bonds will not be defined. It is important to keep in mind that this type of errors (bound checking, validity of configuration files) are still unhandled by the PL. It is assumed in this example that the plugins to read and write pdb files were copied in the /usr/lib/PL/io directory, but any other location could be used instead.

The procedural API of the PL is entirely compatible with standard ANSI C. Two header files should be included from any C program from which the PL functions will be called: PL.h and MoleculeConst.h. A simple C program using the PL:

/* test.c */
#include "stdio.h"
#include "PL/MoleculeConst.h"
#include "PL/PL.h"

int main()
{
    printf("PL version: %s\n", plVersion());
    printf("PHI constant: %i\n", PHI);
}