# Downloading and installing PAML ## `PAML` for Linux 1. Clone the [`PAML` GitHub repository here](https://github.com/abacus-gene/paml) to download the latest version. 2. Now, follow the commands below: ```sh # 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: ```sh emacs .cshrc ``` * Now, insert the following line: ```sh # Please change with the path on your system. set path = ($path . /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: ```bash # Please change with the path on your sysyem. export PATH=/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](https://github.com/abacus-gene/paml/releases/tag/4.10.7). 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](https://github.com/abacus-gene/paml/tree/dev). 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: ```sh # 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](https://github.com/abacus-gene/paml/releases/tag/4.10.7). 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](Installation.md#exporting-paths-linux)). 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 : ```sh # Please change with the path on your sysyem. export PATH=/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: ```sh [[ -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`](https://github.com/abacus-gene/paml/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](https://github.com/abacus-gene/paml). You can download a [zip compressed file](https://github.com/abacus-gene/paml/archive/refs/heads/master.zip) to automatically start the download, and then decompress it on your local disk. Alternatively, you can use the command line: ```sh # 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](https://learn.microsoft.com/en-us/windows/wsl/install), the [Git Bash](https://gitforwindows.org/), or other alternatives to start a command-line shell that you may have installed on your PC to compile the `PAML` programs: ```sh # 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](Installation.md#exporting-paths-linux). ## 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](https://github.com/abacus-gene/paml). ### Old `PAML` versions for Mac OS X > [!IMPORTANT] > Please note that you should always download the latest `PAML` version from the [`PAML` GitHub repository](https://github.com/abacus-gene/paml). 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](http://abacus.gene.ucl.ac.uk/software/paml4.8a.macosx.tgz). 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](http://abacus.gene.ucl.ac.uk/software/paml4.9j.tgz). 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: ```text 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: ```text CFLAGS = -mcpu=G5 -O4 -funroll-loops -fomit-frame-pointer -finline-functions ``` * For Mac OS X intel uncomment the following line: ```text 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: ```sh 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](https://github.com/abacus-gene/paml). 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](https://github.com/abacus-gene/paml). 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](http://abacus.gene.ucl.ac.uk/software/paml4.9j.tgz). 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. ```sh 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: ```sh 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`](http://abacus.gene.ucl.ac.uk/software/pamlX1.3.1-src.tgz). * [Windows executable for `PAML-X`](http://abacus.gene.ucl.ac.uk/software/pamlX1.3.1-win32.tgz). * [Mac OS X / Linux executable for `PAML-X`](http://abacus.gene.ucl.ac.uk/software/pamlX1.3.1-osx-x86_64.dmg). > [!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: ```sh sudo apt-get install qt4-default ``` * After that, you may want to move to the `PAML-X` folder with the source code and type: ```sh 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.