|                                                                    |
|                      NAMD 2.2 Release Notes                        |
|                                                                    |

This file includes directions for running and compiling NAMD,
an explanation of the automated usage reporting mechanism,
advice for dealing with endian issues when switching platforms,
a list of know deficiencies, and advice for reporting bugs.


New Features

--- First Port to Windows ---

NAMD now runs on Windows.  NAMD is built and tested on Windows NT,
but should work on Windows 98 and 2000 as well.  You can now run
NAMD on all those desktop machines that sit idle at night.

--- Parallel PME Reciprocal Sum ---

Formerly a serial bottleneck, the particle mesh Ewald FFT and
reciprocal space sum have been distributed.  Early results have
demonstrated speedups on 128 processors of a Cray T3E.  The number
of processors used may be limited with the "PMEProcessors" parameter.

--- FFTW in Shipping Binaries ---

Under a new license with MIT, FFTW (www.fftw.org) is now included in 
all release binaries.  Users no longer need recompile NAMD themselves
to obtain this performance boost.  (FFTW is also available under GPL.)

--- Conjugate Gradient Minimizer ---

The default minimizer is now based on conjugate gradients and line
searches.  It is orders of magnitude faster than the old method, which
is still available via the "velocityQuenching" option.  If you have
any problems with the new minimizer, please contact us immediately.

--- Improved Load Balancer ---

With a new load balancing framework and careful removal of serial
bottlenecks, we have demonstrated scaling to 1024 or even 2048
processors on the ASCI Red machine.  This work will be presented at
SC2000 and is a finalist for the Gordon Bell award.


Running NAMD

-- Workstation Networks --

Workstation networks require two files, the namd2 executable and the
conv-host program.  The conv-host program starts namd2 on the desired
hosts, and handles console I/O for the node programs.

To specify what machines namd2 will run on, the user creates a file
called "nodelist".  Below is an example nodelist file:

group main
 host brutus
 host romeo

The "group main" line defines the default machine list.  Hosts brutus
and romeo are the two machines on which to run the simulation.  Note
that conv-host may run on one of those machines, or conv-host may run
on a third machine.

The "rsh" command ("remsh" on HPUX) is used to start namd2 on each node
specified in the nodelist file.  If NAMD fails without printing any
output, check to make sure that "rsh" works on your machine, by seeing
if "rsh hostname ls" works for each host in the nodelist.  If you want
or need to use "ssh" instead, then add "setenv CONV_RSH ssh" to your
login or batch script and try "ssh hostname ls" to each host first to
ensure that the machine is in your .ssh/known_hosts file.

Some automounters use a temporary mount directory which is prepended
to the path returned by the pwd command.  To run on multiple machines
you must place a "pathfix" line in your nodelist file before any
"host" lines.  For example:

group main
 pathfix /tmp_mnt
 host alpha1
 host alpha2

A number of parameters may be passed to conv-host.  The most important
is the "+pX" option, where X specifies the number of processors.  If X
is less than the number of hosts in the nodelist, machines are
selected from top to bottom.  If X is greater than the number of
hosts, conv-host will start multiple processes on the machines,
starting from the top.  To run multiple processes on members of a SMP
workstation cluster, you may either just use the +p option to go
through the list the right number of times, or list each machine
several times, once for each processor.  The default is +p1.

You may specify the nodelist file with the "++nodelist" option and the
group (which defaults to "main") with the "++nodegroup" option.  If
you do not use "++nodelist" conv-host will first look for "nodelist"
in your current directory and then ".nodelist" in your home directory.

If you always want to run on the machine you are logged in to you may
use "localhost" in place of the hostname in your nodelist file, but
only if there are no other machines.  You will not need "pathfix".
For example, ".nodelist" in your home directory could read:

group main
 host localhost

Once the nodelist file is set up, and you have your configuration file
prepared (alanin.conf, in this example), run NAMD as follows:

conv-host +pX namd2 alanin.conf

Intel and Alpha processors produce binary files (restart and DCD
files) which must be "byte-swapped" to be read on other platforms.
The flipbinpdb and flipdcd programs will perform this conversion.
NAMD and VMD now handle this conversion automatically for most files.
See the section "Endian Issues" below.

-- Windows Workstation Networks ---

Windows is the same as other workstation networks described above,
except that rsh is not available on this platform.  Instead, you must
run the provided daemon (daemon.exe) on every node listed in the
nodelist file, even if you are only running on one machine.  Using
daemon_background rather than daemon will eliminate consoles for the
daemon and node processes.

-- IBM RS/6000 SP --

Run NAMD as you would any POE program.  The options and environment
variables for poe are various and arcane, so you should consult your
local documentation for recommended settings.  As an example, to run
interactively on Blue Horizon one would specify:

poe namd2 alanin.conf -nodes n -tasks_per_node m -rmpool 1

-- Cray T3E --

The T3E version has been tested on the Pittsburgh Supercomputer Center
T3E.  To run on X processors, use the mpprun command:

mpprun -n X namd2 alanin.conf

-- Origin 2000 --

For small numbers of processors (1-8) use the non-MPI version of namd2.
If your stack size limit is unlimited, which DQS may do, you will need
to set it with "limit stacksize 64M" to run on multiple processors.
To run on X processors call the binary directly with the +p option:

namd2 +pX alanin.conf

For better performance on larger numbers of processors we recommend
that you use the MPI version of NAMD.  To run this version, you must
have MPI installed.  Furthermore, you must set two environment
variables to tell MPI how to allocate certain internal buffers.  Put
the following commands in your .cshrc or .profile file, or in your
job file if you are running under a queuing system:

setenv MPI_REQUEST_MAX 10240
setenv MPI_TYPE_MAX 10240

Then run NAMD with the following command:

mpirun -np X namd2 alanin.conf


Automated Usage Reporting

NAMD may print information similar to the following at startup:

 Info: Sending usage information to NAMD developers via UDP.
 Info: Sent data is: 1 NAMD  2.2  Solaris-Sparc  1    verdun  jim

The information you see listed is sent via a single UDP packet and
logged for future analysis.  The UDP protocol does not retransmit
lost packets and does not attempt to establish a connection.  We will
use this information only for statistical analysis to determine how
frequently NAMD is actually being used.  Your user and machine name
are only used for counting unique users, they will not be correlated
with your download registration data.

We collect this information in order to better justify continued
development of NAMD to the NIH, our primary source of funding.  We
also use collected information to direct NAMD development efforts.
If you are opposed to this reporting, you are welcome to recompile
NAMD and disable it.  Usage reporting is disabled in the release
Windows binaries for version 2.2, but will be added in version 2.3.


Endian Issues

Some architectures write binary data (integer or floating point) with
the most significant byte first; others put the most significant byte
last.  This doesn't effect text files but it does matter when a binary
data file that was written on a "big-endian" machine (Sun, HP, SGI) is
read on a "small-endian" machine (Intel, Alpha) or vice versa.

NAMD generates DCD trajectory files and binary coordinate and velocity
files which are "endian-sensitive".  While VMD can now read DCD files
from any machine and NAMD reads most other-endian binary restart files,
most analysis programs (like CHARMM or X-PLOR) require same-endian DCD
files.  We provide the programs flipdcd and flipbinpdb for switching the
endianness of DCD and binary restart files, respectively.  These programs
use mmap to alter the file in-place and may therefore appear to consume
an amount of memory equal to the size of the file.


Known Deficiencies

- NAMD requires X-PLOR or CHARMM to produce the .psf structure input
  files.  If you don't have one of these, you probably can't use NAMD.
  We are planning on adding these features to VMD or a new program.

- The DPMTA fast multipole electrostatics method is not available on
  the Windows port.  PME with a periodic system is recommended instead.


Problems?  Found a bug?

For problems or questions, send email to namd@ks.uiuc.edu.  If you
think you have found a bug, please follow the steps outlined below.
Your feedback will help us improve NAMD.

 1. Download and test the latest version of NAMD. 
 2. Please check the FAQ, known bugs and problem reports. 
 3. Gather, in a single directory, all input and config files needed
    to reproduce your problem. 
 4. Run once, redirecting output to a file. 
 5. Tar everything up (but not the namd2 or conv-host binaries) and
    compress it. 
 6. Email namd@ks.uiuc.edu with: 
    - A synopsis of the problem as the subject. 
    - The NAMD version number the problem occurs with. 
    - The platform and number of CPU's the problem occurs with. 
    - A description of the problematic behavior and any error messages. 
    - If the problem is consistent or random. 
    - The compressed tar file as an attachment (or a URL if it is too big). 
 7. We'll get back to you by the next business day. 


Compiling NAMD

You must first download and install NAMD's communications library,
Charm++/Converse, from http://charm.cs.uiuc.edu/.  You will have
to obtain the Aug 1, 2000 beta version via public CVS.  The following
table shows the version needed for each NAMD architecture.  It is
important that the same compiler is used for both Charm++ and NAMD.

    NAMD Arch Name     Description                   Charm Version
   ----------------   ---------------------------   ---------------
    Linux-i686-KCC     Linux with KCC 3.3 compiler   net-linux-kcc
    Linux-i686-g++     Linux with GNU compiler       net-linux
  * Linux-Alpha-cxx    Alpha Linux w/ DEC compiler   net-linux-axp-cxx
  * Linux-Alpha-g++    Alpha Linux w/ GNU compiler   net-linux-axp
    Origin2000-MPI-CC  SGI Origin 2000 with MPI      mpi-origin
    Origin2000-CC      SGI Origin 2000 w/o MPI       origin2000
    Tru64-Alpha-CC     Tru64 Unix w/ DEC compiler    net-axp-cc
  * Tru64-Alpha-g++    Tru64 Unix w/ GNU compiler    net-axp
    T3E-CC             SGI/Cray T3E                  t3e
    Solaris-Sparc-CC   Solaris 2.6 or later          net-sol-cc
    Solaris-Sparc-g++  Solaris 2.6 or later          net-sol
    Solaris-i686-g++   Solaris 2.6 or later          net-sol-x86
  * HPUX-CC            HP-UX 10.0 or later with CC   net-hp-cc
    HPUX-aCC           HP-UX 10.0 or later with aCC  net-hp-acc
    HPUX-g++           HP-UX 10.0 or later with GNU  net-hp
    AIX-RS6000-xlC     IBM AIX with xlC              net-rs6k
    IBM-SP             IBM SP Series                 sp3
    ASCI-Red           ASCI Red                      paragon-red
  * Win32-i686-MSVC    Windows with MS Visual C++    net-win32

  * These architectures may fail to build or be unstable.  Building
    on Win32 is not fully automated yet.  Don't try it at home.

Once you have obtained the Charm++/Converse source code, you can
build the libraries needed by NAMD for each architecture with the
SUPER_INSTALL command in the charm directory:


where CHARMVERSION is the appropriate version listed above.  You only
actually need the bin, include, and lib subdirectories, you can remove
pgms and tmp from each build directory.  You only need pvm if you have
not disabled DPMTA in the Makefile (see below).

Edit Make.charm to point to the directory where Charm++ is installed.

Now you can type "./config ARCH" where ARCH is a ARCH architecture
name listed above (or as a file suffix in the arch directory).  This
will create a build directory for that architecture.  If you wish to
create this directory elsewhere use "./config DIR/ARCH", replacing
DIR with the location the build directory should be created.

Now "cd" to your build directory and type make.  The namd2 binary as
well as the flipdcd and flipbinpdb utilities will be created.  A link
to conv-host (see below) will be created as appropriate.

If you have trouble building NAMD your compiler may be different from
ours.  The architecture-specific makefiles in the arch directory use
several options to elicit similar behavior on all platforms.  Your
compiler may conform to an earlier C++ specification than NAMD uses.
You compiler may also enforce a later C++ rule than NAMD follows.
You may ignore repeated warnings about new and delete matching.

You may edit Makefile to enable or disable DPMTA and DPME.  DPMTA is
required if you want to use the fast multipole algorithm for full
electrostatics.  DPME is only useful for comparison with the new
particle mesh Ewald code.  You must specify "useDPME on" in the
simulation config file to switch to the old DPME code.  DPMTA and
DPME are included in the release binaries.

You may enable linking with Tcl by editing arch/BASEARCH.tcl (where
BASEARCH is ARCH without the -CC, -g++, or -KCC compiler extension)
and adding "tcl" to the config command line: "./config tcl ARCH"
Tcl is required for Tcl global forces (tclForces) and for Tcl
scripting.  Tcl is available from www.scriptics.com.  Tcl is included
in the release binaries.

You may enable linking with FFTW by editing arch/BASEARCH.fftw (where
BASEARCH is ARCH without the -CC, -g++, or -KCC compiler extension)
and adding "fftw" to the config command line: "./config tcl fftw ARCH"
FFTW is required in order to use the newer particle mesh Ewald.  FFTW
is available from www.fftw.org.  If you download the RPM or configure
FFTW with --enable-type-prefix you will need to make symbolic links to
the double precision versions of the libraries and header files.  FFTW
is now included in the release binaries under a special license.