Installation

Downloading and installing PAML

PAML for Linux

1. Clone the PAML GitHub repository here to download the latest version.

2. Now, follow the commands below:

   # Move to the cloned repository. Make sure you have cloned it in the correct
   # location of your local disk.
   cd paml
   # If there are executable files for Windows, you may remove them.
   rm bin/*.exe
   # Move to the `src` directory to compile the software.
   cd src
   make -f Makefile
   # List all the compiled programs that are part of PAML and
   # remove unnecessary files.
   ls -lF
   rm *.o
   # Create a `bin` directory, which you can then export to your PATH.
   mkdir ../bin
   # Move the compiled programs to `bin`.
   mv baseml basemlg chi2 codeml evolver infinitesites mcmctree pamp yn00 ../bin
   # Test that you can run some PAML programs such as BASEML, CODEML, or evolver.
   bin/baseml
   bin/codeml
   bin/evolver

Exporting paths (Linux)

Now, you can either export the path to this bin directory or include the executable files in a general bin directory for all the software that you have on your local disk, e.g., ~/bin. Whatever you decide to do, please modify your path to include the folder with the PAML programs in the initialization file for the shell. You can use more /etc/passwd to see which shell you run. Below, you can find some notes for the C shell and bash shell. There are other shells, but these two are commonly used.

• If you see /bin/csh for your account in the /etc/passwd file, you are running the C shell, and the initialization file is .cshrc in your root folder.

  • You can use more .cshrc to see its content if it is present. Use a text editor (such as vim, emacs, nano, etc.) to edit (or create, if one does not exist) the file, by running something like this:

    emacs .cshrc

  • Now, insert the following line:

    # Please change <path_to_bin> with the path on your system.
    set path = ($path . <path_to_bin>/bin)

  • The different fields are separated by spaces. Here, . means the current folder, and ~/ means your root folder, and $path is whatever folders are already in the path.

• If you see /bin/bash in the file /etc/passwd for your account, you are running the bash shell, and the initialization file is ~/.bashrc or ~/bash_profile (type ls -a ~ to see whether you have one or another in your home directory, ~).

  • Now, use a text editor to open file ~/.bashrc and insert the following line:

    # Please change <path_to_bin> with the path on your sysyem.
    export PATH=<path_to_bin>/bin:$PATH

  • The command above changes the environment variable PATH. The different fields are separated by colon :, without spaces. If the file does not exist, please create one (e.g., run touch ~/.bashrc on the terminal).

• After you have changed and saved the initialization file, every time you start a new shell, the path is automatically set for you. You can then cd to the folder which contains your data files and run PAML programs there. If the path is properly set, you will be able to run any of the PAML programs by just typing the file name (e.g., unless you have modified the executable file names, mcmctree, codeml, etc.).

PAML for Mac OS X

• Mac OS X with M1/M2/M3 chips: if you have one of the new macOS, you may be experiencing some issues (e.g., segmentation fault, trace trap) when running either the pre-compiled binaries from the latest release or your own compiled binaries using the corresponding source code. Linux/Windows binaries seem to automatically initialise to 0 some values that are related to memory access. Nevertheless, arm64-based devices seem to initialise those values differently (or they are stricter) as they have risc processors. This issue is related to the use of strcpy(t,s);, which copies source string s to target string t, when s and t are the same string at the same address. The source code in the dev branch has been fixed to account for this issue, but not yet been merged as of 2024/08/23. If you have one of the latest macOS and experience this issue, please do the following:

  1. Go to the dev branch in the PAML GitHub repository.
  2. Then, please press the green button <> Code, which will download the source code in the dev branch. At the end of the download, you should see a zip file called paml-dev.zip saved in the directory you specified.
  3. Now, decompress the file and follow the same instructions given in the installation procedures for Linux:

      # Move to the cloned repository.
      cd paml-dev
      # If there are executable files for Windows, you may remove them.
      rm bin/*.exe
      # Move to the `src` directory to compile the software.
      cd src
      make -f Makefile
      # List all the compiled programs that are part of PAML and
      # remove unnecessary files.
      ls -lF
      rm *.o
      # Create a `bin` directory, which you can then export to your PATH.
      mkdir ../bin
      # Move the compiled programs to `bin`.
      mv baseml basemlg chi2 codeml evolver infinitesites mcmctree pamp yn00 ../bin
      # Test that you can run some PAML programs such as BASEML, CODEML, or evolver.
      bin/baseml
      bin/codeml
      bin/evolver
      ```
  

Note

If you want to clone the repository from the terminal, make sure that you use git checkout to change branches!

• Mac OSX prior to M1/M2/M3 chips: if you have an older macOS prior to M1/M2/M3 chips, you should not experience segmentation fault issues when running either the pre-compiled binaries from the latest release or your own compiled binaries using the corresponding source code. Nevertheless, if you have any problems, please follow the instructions given above for Mac OS X with M1/M2/M3 (i.e., compile the source code from the dev branch).

Exporting paths (Mac OS X)

Some macOS users may have ~/.profile instead of ~/.bashrc as Linux users (see above). In that case, follow the same instructions as above but replace all ~/.bashrc with ~/.profile. If you have the Z shell and, perhaps, file ~/.zshrc, you can follow the recommendations given below based on the procedure that has proved successful for some PAML users:

• Open a terminal and open two tabs.

• Type ls -a ~ in "tab 1". If you do not see a file called ~/.profile listed, then you will need to create it. You can then type touch ~/.profile. This will be the file that you will use to export the programs to the global path. E.g., you could open it with your preferred text editor and type :

  # Please change <path_to_bin> with the path on your sysyem.
  export PATH=<path_to_bin>/bin:$PATH

• In "tab 1", please check that you have a file called ~/.zshrc (i.e., ls -a ~). If not, please create one (i.e., touch ~/.zshrc), open it with your preferred text editor, and add this line:

  [[ -e ~/.profile ]] && emulate sh -c 'source ~/.profile'

  Now, save the file with your preferred text editor and source the changes (i.e., run first source ~/.profile, then source ~/.zshrc).

• Next, open a new terminal and try to see if you can run any PAML program (e.g., type mcmctree, codeml, baseml; any of the programs that are part of PAML) which path you tried to export. If that works, then you have managed to export the path to PAML programs! If you experience any problems (e.g., commands such as cd or ls stopped working), then go back to the first terminal (i.e., terminal with "tab 1" where you modified files ~/.profile and ~/.zshrc) but, this time, go to "tab 2", which you should have already opened before making any changes in "tab 1". Now, we shall be able to recover the original files without changes (i.e., type source ~/.profile and source ~/.zshrc, which should not include the changes you made in "tab 1"). If you did not create them, just create empty ones (i.e., touch ~/.profile and touch ~/.zshrc) and source again. If you open a third terminal or a third tab, the problem should now be solved! Then, try again and make sure there are no typos in the path you type!

PAML for Windows 10 or later

To download the latest stable version of PAML, please go to the releases and download the compressed file that best suits your needs (i.e., pre-compiled binaries or source code for your operating system).

If you want to download the latest code available for PAML, you can clone the PAML GitHub repository here. You can download a zip compressed file to automatically start the download, and then decompress it on your local disk. Alternatively, you can use the command line:

# Open a terminal on the location where you want to save
# the PAML software.
git clone https://github.com/abacus-gene/paml.git

Now, you can use either the Windows Linux Subsystem, the Git Bash, or other alternatives to start a command-line shell that you may have installed on your PC to compile the PAML programs:

# Open a terminal where you have cloned the PAML repository
cd paml
cd src
make -f Makefile
# List all the compiled programs that are part of PAML and
# remove unnecessary files
ls -lF
rm *.o
# Create a `bin` directory, which you can then export to your PATH.
mkdir ../bin
# Move the compiled programs to `bin`
mv baseml basemlg chi2 codeml evolver infinitesites mcmctree pamp yn00 ../bin

Exporting paths (WSL)

If you export the PATH to the directory bin, you will be able to run the programs from any location of your local disk without needing to type the absolute path. Please note that, if you are a WSL users (i.e., you have the Windows Subsystem for Linux installed on your PC), your path will always start with mnt/c as the WSL is installed as a mountable disk. The easiest way to find the path to a program is to use a terminal to navigate to the directory where it was installed (i.e., use cd). Once you are there, type pwd. Then, you can use your favourite text editor to modify the ~/.bashrc as explained above for Linux users above.

Old compiled versions of PAML

The instructions below explain how to download older versions of PAML compatible with Mac OS X (G5 compiler) and Windows 9x/NT/2000/XP/Vista 7.

We have decided to keep this section in case users need to follow the installation steps for the OSs detailed above. Nevertheless, we discourage the installation of older versions as they are out of date. Users may follow the step-by-step installation/compilation guidelines below, but always using the latest version of the PAML software available here.

Old PAML versions for Mac OS X

Important

Please note that you should always download the latest PAML version from the PAML GitHub repository. The notes below are for an earlier version, PAML v4.8a.

A compiled version for Mac OS X of an older version of PAML can be downloaded from the following link: PAML v4.8a. If you have the latest latest versions of Mac OS X, please follow the instructions above to install PAML v4.8a -- please note that it may not work due to software incompatibilities.

Warning

Please use the instructions below only if you are trying to install an older version of PAML on older versions of Mac OS X. Please note that we always recommend to use the latest stable version of PAML; these instructions are kept here for the record.

If you have a G5 or if you would like to compile the programs in the PAML software yourself, please follow the notes below.

We assume that the Apple XCODE is now automatically installed on your macOS. Otherwise, you will have to download and install the macOS XCODE system, which includes the C compiler. Without a C compiler, you will get a "Command not found" error when you type gcc or cc at the command terminal.

1. Download the archive provided in this link.

2. Open a command terminal (Applications > Utilities > Terminal).

3. Remove the .exe files from the bin/ folder.

4. Compile and run the programs from the terminal as follows:

   • Open up the file Makefile in the src/ folder and add # at the beginning of the following line to comment it out:

     CFLAGS = -O4 -funroll-loops -fomit-frame-pointer -finline-functions
     

   • Delete the # at the beginning of the line for either G5 or intel, depending on your machine, to uncomment the line.

   • For Mac OS X G5 uncomment the following line:

     CFLAGS = -mcpu=G5 -O4 -funroll-loops -fomit-frame-pointer -finline-functions
     

   • For Mac OS X intel uncomment the following line:

     CFLAGS = -march=pentium-m -O4 -funroll-loops -fomit-frame-pointer -finline-functions
     

5. VERY IMPORTANT: Please save the file and compile after the programs are successfully compiled, delete the .o files and move the executables to the bin/ folder as follows:

   rm *.o
   mv baseml basemlg codeml pamp evolver yn00 chi2 ../bin

You may want to mv the executables into the bin/ folder on your accounts rather than the PAML main folder. And finally, if your current folder is not on your search path, you will have to add ./ in front of the executable file name; that is, use ./codeml to run CODEML. See the notes for UNIX systems above.

Old PAML versions for Windows 9x/NT/2000/XP/Vista 7

Important

Please note that you should always download the latest PAML version from the PAML GitHub repository. The notes below are for an earlier version, PAML v4.9j. If you would like to use the latest stable version on Windows, you can either download the pre-compiled binaries or the source code from the latest PAML release. If you want to install PAML from source code, please follow the details given above.

To download the executable files for an earlier version of PAML, PAML v4.9j, please download the compressed file following this link. If you have the latest latest Linux distros or Windows 10 or later, please follow the instructions above for each corresponding operating system to install PAML v4.9j -- please note that it may not work due to software incompatibilities.

Warning

Please use the instructions below only if you are trying to install an older version of PAML on Windows 9x/NT/2000/XP/Vista 7. Please note that we always recommend to use the latest stable version of PAML; these instructions are kept here for the record.

1. Download and save the archive paml4.9j.tgz on your local disk. Make sure the extension of the file (tgz) did not change with the download.

2. Unpack the archive into a folder (e.g., with Winzip or 7-zip). Remember the name of the folder.

3. The Windows executables are in paml4.9j/bin/ (you may see \ instead of / to separate the directories, i.e., paml4.9j\bin\). You may want to create a folder for local programs and move the PAML executables there. Below, you can find some notes for doing that:

   • Set up a folder of local programs and change the search path. You need to do this for your user account only once. Suppose your user folder is C:\Users\Ziheng (please, replace this path with your own path, which will contain your username and your folders names). On Vista or Windows 7, this tends to be the default user folder. On Windows XP, you may see something like C:\Documents and Settings\Ziheng (again, this is an example, you may see your username instead).
   • Use Windows Explorer to create a folder called bin inside your user folder. In this example, C:\Users\Ziheng\bin. If you are the superuser/administrator of your PC, you may prefer the folder C:\bin. Whatever you choose, remember that this will be the folder for holding executable programs.

4. Next, we will add this folder onto the search path, which the OS uses to search for executable programs. The following is for Windows Vista (the menu may be slightly different on Windows 2000/XP, but similar). Open Control Panel and choose Classic View. Now, double-click on System and choose Advanced System Settings. Then, click on the tab Advanced and then on the button Environment Variables. Under User variables, now double-click on the variable Path to edit, then on the variable value field, and then move the cursor to the beginning. Now, insert the name of our program folder (e.g., in our example, C:\Users\Ziheng\Bin or C:\Bin, but please modify according to the folder you have created). Note that you will see a semicolon, which is used to separate the folder names. Be careful not to introduce any errors and keep using the semicolon if you need to include more folders. To save the new settings, please click OK.

5. Now, you can copy the PAML executables. Copy or move the pre-compiled executables (baseml.exe, codeml.exe, evolver.exe, chi2.exe, etc.) from the paml4.9j\bin\ folder to the local programs folder you will have created (e.g., C:\Users\Ziheng\Bin\ in this example). After this, you can execute any of these programs from a command prompt wherever you are. If you like, you can include the version number by renaming the executable files (e.g., baseml.exe and codeml.exe to baseml4.exe and codeml4.exe, respectively). In that way, you will then run the program from the command line by typing codeml4 instead of codeml, which is useful if you have several versions installed on your PC

6. Last, you can run a PAML program. Avoid double-clicking the program names from Windows Explorer or will not see any error messages on the screen when the program crashes. Instead, please start a command prompt box where you want to start the PAML program you want to run. For example, Start > Programs > Accessories > Command Prompt, or Start > Run and then type cmd and OK. You can right-click on the title bar and choose Properties to change the size, font, or colour of the window. Now, cd to the folder which contains your input files to tun the PAML program you want and type the name of its executable file (e.g., codeml, mcmctree, etc.). Here, we show how you can cd to the PAML folder (suppose you have extracted the archive into C:\Programs\paml4.9j\) and run the codeml program using the default files.

   C:
   cd \Programs\paml4.9j\
   codeml

Because there is no executable file called codeml.exe (or codeml.bat, etc.) in your current folder, the OS will look for it in the folders listed in the environment variable path that you will have already defined. Therefore, the OS will find and execute the file codeml.exe in the C:\Users\Ziheng\Bin folder, which is the path that we exported in the environment variable in the example above (you will have a different path according to your username and the folder you chose). If you want, you could also use the absolute path to run the PAML programs, although you will need to remember this path! You could type something like the following:

C:\Programs\paml4.9j\bin\codeml 

Some codeml analyses use amino acid distance (e.g., grantham.dat file in the dat directory of the PAML software) or substitution rate matrices (e.g., wag.dat file in the dat directory of the PAML software). You will then need to copy the necessary file to your current folder or specify its correct path in the control file to run the program. If the path is not correct or not found, the program will ask you to input the full path to that file until found.

Graphical user interface: PAML-X

A graphical user interface called PAML-X was written by Bo Xu of Institute of Zoology, Chinese Academy of Sciences in Beijing. This GUI was written in Qt and should run on Windows, Mac OS X, and Linux, although the versions for Mac OS X and Linux may not be well tested.

Warning

Please note that PAML-X is no longer maintained, so please use it at your own risk!

If, despite the warning above, you still want to try PAML-X, please download and install PAML (see above) and also PAML-X (links below). When using pamlX1.3.1 (GUI), you will need to use PAML V4.9 or later. When you run PAML-X for the first time, you need to specify the PAML folder name.

• Source code for PAML-X.
• Windows executable for PAML-X.
• Mac OS X / Linux executable for PAML-X.

Note

While the Windows executable seems to work fine for Windows users, some Linux/UNIX users may experience issues when compiling the GUI due to incompatibilities with the Qt package. If you are one of these users, you may want to try the following:

• In the latest Linux versions, you should be able to have different versions of Qt packages. PAML-X requires Qt4, and so please install this version either via Synaptic or by typing the following command:

  sudo apt-get install qt4-default

• After that, you may want to move to the PAML-X folder with the source code and type:

  qmake pamlX.pro
  make

If there are no issues, the software should start compiling and, at the end, you should see an executable file called pamlX appear.