How to set up and use PHENIX

Contents

Installation

Platform support

PHENIX is supported on most common Linux platforms (kernel 2.6 or newer), Mac OS X version 10.4 or newer, and Windows XP or newer. Binary installers are built on the following systems:

  • Fedora Core 8 (64-bit)
  • Fedora Core 12 (64-bit)
  • CentOS 4 (32-bit)
  • CentOS 5 (both)
  • Ubuntu 10.04 (both)
  • Windows XP (32-bit)
  • Windows 7 (64-bit)
  • Mac OS 10.4 (32-bit)
  • Mac OS 10.6 (64-bit)

Most of these installers should also run on newer systems and/or different Linux distributions such as Linux Mint or SuSE, as long as the architecture is the same. Linux kernels prior to 2.6 are not supported, but kernel versions 3.x should be compatible with the installers built on 2.6.

If you are running Mac OS 10.6 (Snow Leopard) or newer, you will almost certainly want to use the 64-bit Mac installer. On Linux, you can find out what platform you are running with the command 'uname -p'; for machines reporting "i686", use the intel-linux-2.6 installer. On Windows, the 64-bit Windows 7 installer only supports machines which actually run the 64-bit version of the OS; if you are using 32-bit Windows 7 (or previous) you will need to use the 32-bit installer built on Windows XP.

Space requirements

For the complete PHENIX installation you will need approximately 2.5GB of disk space.

Graphical installer - Mac

Installation by this method uses familiar interfaces provided by the operating systems. Destination directory is fixed to the folder /Applications. You will need administrative privileges to run the installer.

Graphical installer - Windows

Installation:
  • Download and run PHENIX from the download page

Destination directory is fixed, to the top level of the C: drive. You will need administrative privileges to run the installer.

Upgrade to newer version:

Currently upgrade to new version is done manually

  • Uninstall Phenix by going to the Windows Programs and Features in the control panel, choose the existing PHENIX installation and click Uninstall
  • Then install the new version

Working from command line in Windows: If for some reason you would like to work using the PHENIX command line commands in Windows, follow those steps

  • Create a command prompt shortcut on your desktop
  • Right click on the shortcut, go to properties, and change the target and the Start in, according to your PHENIX installation.
    • target to "%SystemRoot%\system32\WindowsPowerShell\v1 .0\powershell.exe " -NoExit -Command & {C:\WINDOWS\system32\cmd .exe /k C:\PHENIX-1.8.4-1493\Phenix-1.8.4-1493_build\setpaths_all .bat }
    • Start in to the folder you want the command prompt to start in, something like C:Usersuser_nameworkjunk

Now when you double-click on the shortcut, you will open a command prompt with your PHENIX environment.

Command-line installer (Mac and Linux)

You should obtain the latest distribution of PHENIX including the binary bundles for your machine architectures. Unpack the tar file:

% tar xvf phenix-installer-<version>-<platform>.tar

Change to the installer directory:

% cd phenix-installer-<version>

To install:

% ./install       [will install in /usr/local/phenix-<version> by default,
                   requires root permissions]

% ./install --prefix=<directory>  [will make <directory>/phenix-<version> and install there]

Note: <directory> must be a absolute path (i.e. starts with a /). A relative path starting with ../ will not work correctly.

Installation of the binary version of PHENIX requires no compilation, only the generation of some data files, so you will probably have to wait about 5-10 minutes for the installation to complete (depending on the performance of your installation platform).

For license information please see LICENSE file. For source of components see SOURCES.

Running Phenix

If you intend to use the graphical interface and installed Phenix using the Mac or Windows graphical installers, no further configuration is necessary - just double-click the icon for the main Phenix GUI. Instructions below are for users of the command-line installer and/or programs.

Setting up the command-line environment

Once you have successfully installed PHENIX, to set up your environment please source the phenix_env file in the phenix installation directory (for example - replace "<version>" with the actual installed version, such as "1.8.4-1496"):

% source /usr/local/phenix-<version>/phenix_env [sh/tcsh users]

or

% . /usr/local/phenix-<version>/phenix_env.sh [sh/bash users]

To run jobs remotely, you need to source the phenix_env in your .cshrc (or equivalent) file.

If you used the graphical Mac installer, you can find the files here:

/Applications/PHENIX-<version>/Contents/phenix-<version>/phenix_env*

The following environmental variables should now be defined (here with example values):

PHENIX=/usr/local/phenix
PHENIX_INSTALLER_DATE=080920070957
PHENIX_VERSION=1.3
PHENIX_RELEASE_TAG=final
PHENIX_ENVIRONMENT=1
PHENIX_MTYPE=intel-linux-2.6-x86_64
PHENIX_MVERSION=linux
PHENIX_USE_MTYPE=intel-linux-2.6-x86_64

It is not necessary (or useful) to define environmental variables for SOLVE/RESOLVE for PHENIX. If you have them set in your environment they are ignored by PHENIX.

Documentation

You can find documentation in the PHENIX GUI (under the Help menu). Alternatively, you can use a web browser to view the documentation supplied with PHENIX, by typing:

% phenix.doc

If this doesn't work because of browser installation issues then you can point a web browser to the correct location in your PHENIX installation (for example):

% firefox /usr/local/phenix-<version>/doc/index.html

or:

% mozilla $PHENIX/doc/index.html

For license information please see the LICENSE file.

For the source of the components see SOURCES.

Help

You can join the PHENIX bulletin board and/or view the archives:

http://www.phenix-online.org/mailman/listinfo/phenixbb

Alternatively you can send email to:

bugs@phenix-online.org  (if you think you've found a bug)
help@phenix-online.org  (if you'd like to ask us questions)

User interfaces

Different user interfaces are required depending on the needs of a diverse user community. Most modules in Phenix can be run either through a graphical user interface (GUI) or as command-line programs. For new users (and those without experience with Unix/Linux systems), we recommend using the graphical interface.

The PHENIX GUI

For new users and anyone unfamiliar with Unix command lines, we recommend using the graphical interface. To run, simply type this command:

% phenix &

Please see the other documentation files to get more details about the PHENIX GUI.

Command Line Interface

Advanced users (or anyone developing automated pipelines) may prefer to use the command-line interface. This is particularly the case when rapid results are required, such as data quality assessment and twinning analysis, or substructure solution at the synchrotron beam line. Tools that facilitate the ease of use at the early stages of structure solution, such as data analyses (phenix.xtriage), substructure solution (phenix.hyss) and reflection file manipulations such as the generation of a test set, reindexing and merging of data (phenix.reflection_file_converter) are available via simple command line interfaces. Most of the larger programs such as phenix.refine and the AutoSol, AutoBuild, and LigandFit wizards are also available as command-line tools.

To illustrate the command line interface, the command used to run the program that carries out a data quality and twinning analyses is:

phenix.xtriage my_data.sca [options]

Further options can be given on the command line, or can be specified via a parameter file:

phenix.xtriage my_parameters.def

A similar interface is used for macromolecular refinement:

phenix.refine my_model.pdb my_data.mtz

Although SCALEPACK and MTZ formats are indicated in the above example, reflection file formats such as D*TREK, CNS/XPLOR or SHELX can be used, as the format is detected automatically.

Help for all command line applications can be obtained by use of the flag --help :

phenix.refine --help

There are also many other command line tools (described in detail elsewhere in this documentation). You can list them all with

phenix.list

or alternatively:

::
phenix.list ave

to list all methods that contain the characters ave in their names or descriptions.

Note: all commands have their regular name and name qualified with the version. You can always use the version-qualified name to ensure which version of a command you are using (in case you have multiple versions of PHENIX or related applications installed).

The runtime options for most PHENIX tools are controlled using a lightweight syntax called PHIL (Python Hierarchial Interface Language), which is designed to work both as command-line arguments or as more verbose parameter files. A basic overview of PHIL is available in the overview of file formats.

Troubleshooting

Problems starting the GUI

Ubuntu tends to be installed without an important library that is linked to by the GUI code. If you encounter an error message about a missing library upon starting the GUI, you can add it to your system with this command:

sudo apt-get install libjpeg62