charmm 1 NIH versions of CHARMM on HP-UX Mar 1997
NAME
charmm - running CHARMM and browsing the help files
COMMANDS:
Commands:
charmm master script for running most CHARMM versions
charmmdoc master script for text browsing docs of most versions
charmm_help full HTML-based CHARMM documentation browser [Jan'96]
Obsolete but still available:
charmm23.old frozen version of CHARMM23; no X graphics
charmm22 frozen version of CHARMM22; no parallel support
SYNTAX:
charmm [ version ] [ keywords ] [ CHARMM args ] [ I/O redirection ]
charmm23.old [ keywords ] [ CHARMM args ] [ I/O redirection ]
charmm22 [ CHARMM args ] [ I/O redirection ]
CHARMM args :: args to CHARMM in the form 1:arg (reference as @1)
I/O redirection :: standard Unix file redirection; < > >&
version :: default c24n6; oneof[ c25n3 c25a3 c25n2 c25a2 c24n6
c24n5 c24n4 c24b1 c23f4 c23f3 c23f2c ]
keywords :: size_key feature_key mode_key
size_key :: one of ( small medium large ); the default is small
feature_key :: one of ( full lite test ); the default is lite
mode_key :: single; forces single processor mode (non-parallel)
Version Information
charmm == charmm c26n1; NIH version of CHARMM 26, c26a1 superset
charmm c26n2 == NIH mods (bug fixes, etc.) to c26a2 ('test' only)
charmm c26n1 == NIH mods (bug fixes, etc.) to c26a1
charmm c25n3 == NIH mods (bug fixes, etc.) to c25a3
charmm c25a3 == Harvard c25, 2nd "alpha" release
charmm c25n2 == NIH mods (bug fixes, etc.) to c25a2
charmm c25a2 == Harvard c25, 2nd "alpha" release
charmm c24n6 == parallel Particle-Mesh Ewald (PME) supported
charmm c24n5 == NIH mods (bugfix, extensions) to c24b2
charmm c24b1 == Harvard additions to c24n4 ('test' only)
charmm c24n4 == earlier default version, early GAMESS, parallel MM
charmm c23f4 == NIH development version, no Harvard c24 code (charmm24f4)
charmm c23f3 == NIH extensions to Harvard c23f3 version (charmm24)
charmm c23f2c == NIH extensions to Harvard c23f2 version (charmm23)
SYNOPSIS:
The commands listed above are scripts in /usr/local/bin which invoke
the appropriate CHARMM executable, passing any arguments and redirected
I/O to the CHARMM command line. These are the actively supported means
for running both single processor and parallel host calculations with
CHARMM, for both foreground usage and batch jobs. The scripts also
reduce the priority of foreground CHARMM jobs.
The size keywords refer to the array dimensions based on the maximum
number of atoms; "small" is ca. 6000 atoms, "medium" is ca. 25000 atoms,
and "large" is ca. 60000 atoms. Depending on the nature of the system
and other factors, some dimensioned limits may be exceeded even though
the number of atoms may be less than these values.
The feature keywords, "full" and "lite", refer to the inclusion of the
many added options in the "full" version, such as GAMESS, RISM, MTS, TSM,
MOLVIB, RXNCOR; memory usage is approximately doubled when the "full"
feature version is used. The default is now the "lite" version, which
does include the parallel code and the X11 graphics display. With c24n4,
the AM1 semi-empirical code (QUANTUM feature) is included in the "lite"
version.
The "test" feature keyword applies ONLY to c23f3 and later versions, and
runs the most recently compiled experimental version of CHARMM
(caveat emptor); any size keyword is ignored, as there is only one test
version (usually medium or large). The "single" keyword is generally only
necessary for foreground usage on a host with a parallel queue; by default,
the scripts assume parallel mode is desired when CHARMM is started on one
of these machines (e.g. par11).
Startup Size (MB) Table for c24n5
| Feature Set
Size | Lite Full
=========|===============================
small | 17.6 30.7
medium | 40.7 60.0
large | 105.0 135.7
DOCUMENTATION BROWSERS:
charmmdoc [ topic [ topic [ ... ] ] ] [ version ]
topic :: the name of a CHARMM documentation file w/o the .doc extension
(Available topics are listed if one is not supplied as an argument.)
version :: as above for the 'charmm' command; defaults to c24n5
The documentation browser uses the Unix 'pg' utility; commands require
a [RETURN]. The 'h' command provides a brief command summary for 'pg';
keying [RETURN] alone displays the next page. Unlike 'more', you can
move or search backwards in the file being browsed; numbers are interpreted
as page numbers, so the command '1' will go back to the beginning of the file.
This is the preferred browser for slower links, especially dialup slower
than 14.4 Kbps, or remote networks which can't support the bandwidth for
the 'charmm_help' HTML browser.
If the DISPLAY environment variable is set, these "charmmdoc" browsers will
attempt to use the Motif based text browser 'xcat'.
HTML BASED BROWSER:
charmm_help
This command now does the equivalent of either
mosaic -home http://www.mgsl.dcrt.nih.gov/Charmm OR
netscape http://www.mgsl.dcrt.nih.gov/Charmm
The latter is done if the directory ~/.netscape exists (in the user's
home directory), but the HTML pages remain 100% percent Mosaic compatible;
an argument of m or M will force the use of Mosaic.
Documentation for c24n5, c25a2, and now c25n3 is available;
an added feature is a case insensitive full text search of all the CHARMM
documentation files. The Local Stuff page now includes a 'man' page search
and browse system for all the HP-UX online documentation, and a good deal of
locally contributed commands in the /usr/local/bin directory.
------------------------------------------------------------------------
EXAMPLES: (% = the prompt from csh or tcsh)
[1] set "parameter" 1 to 20, read input from anal.inp, write to anal.out,
and put the process in the background
% charmm 1:20 < anal.inp >& anal.out &
[2] run charmm in foreground, sending output to both a file and stdout,
reading input from anal.inp
% charmm < anal.inp | tee anal.out
[3] run the large version (60000 atoms) of CHARMM
% charmm c24n4 large
[4] run the full feature version (GAMESS, etc.) of CHARMM
% charmm full
[5] run the test version of CHARMM
% charmm c24b1 test
[6] browse documentation for COoRdinate MANipulation, SCALAR commands
% charmmdoc corman scalar
SEE ALSO:
CHARMM documentation
'man' pages for: batchq, submit, qb, pg, number
------------------------------------------------------------------------
APPENDIX A: Example script to run extensive dynamics calculations
Once a model system has fully constructed (all coordinates assigned in
the desired conformation and spatial arrangement) and energy minimized at
least briefly, it is ready for a dynamics simulation. In almost every
case, that will require an extensive series of calculations; it is useful
to have a means of naming the output files to indicate the sequence in
which the calculations were performed. The following
csh
script, usually named
dyn.csh
, illustrates the use of the local
number
command (a script), after checking for a successful completion:
#! /bin/csh -f
# ASSUMPTION (1): input files are named dynXX.inp where XX is optional
# useful for startup phase; for example, to start using dynstrt.inp,
# dyn.csh strt
# would be used; for production dynamics runs, simply dyn.csh
# ASSUMPTION (2): output files are named dyn.res dyn.trj dyn.out
# ASSUMPTION (3): previous restart file read as dyn.rea
# ASSUMPTION (4): /usr/local/bin/number is available
#
# the env var PWD should be set for parallel queues
#
setenv PWD /v/deimos/users/rvenable/data/dppc/geldyn
#
# note the command is enclosed in curly braces, NOT parentheses
#
if { charmm medium lite < dyn$1.inp >& dyn.out } then
# SUCCESSFUL RUN; COPY RESTART FILE
cp dyn.res dyn.rea
# NUMBER THE OUTPUT FILES; CHANGE EXTENSIONS TO SUIT APPLICATION
foreach fil ( trj out res )
/usr/local/bin/number dyn.$fil
end
else
# CHARMM RUN FAILED; CREATE .ERR FILE WITH TIMESTAMP
set ts = `date +%m%d.%H%M`
mv dyn.out dyn.err.$ts
exit(201)
endif
An advantage of the above script is that once any heating and/or
equilibration are completed, it is relatively simple to repeatedly
submit more calculations. The
ex post facto
numbering of generic file names depends only on the timestamps of the
first and last file in a sequential series. (See the man page for the
number
command.) The restart file (renamed to the generic
dyn.rea
after each successful run) is all that CHARMM needs (besides
a PSF and parameters) to continue a dynamics calculation. Output files
have sequence numbers appended to the generic names, e.g. dyn.out.1,
dyn.out.2, etc.; this simplifies analysis of the resulting files,
especially coordinate or velocity trajectories.
In case the "number" script isn't available, here it is:
#! /bin/csh -f
if ( $2 == '' ) then
@ i0 = 1
else
@ i0 = $2
endif
if -e $1.$i0 then
set f = ` /bin/ls -1tr $1.* | tail -1 `
set n = {$f:e}
@ n = $n + 1
mv $1 $1.$n
else
mv $1 $1.$i0
endif
------------------------------------------------------------------------
APPENDIX B: Memory Considerations for Larger Systems
For larger systems, of more than 7000 or 8000 atoms, CHARMM has to obtain
additional memory from the OS in order to accomodate the nonbond pair list
and possibly the image atom list. If the memory estimate provided by CHARMM
is too small, CHARMM increases the estimate and tries again. The first memory
block, now potentially unused, remains tied to the program until it completes,
wasting machine resources. If the output file contains more than one or two
lines with the VEHEAP> tag, there is a strong possibility that machine memory
is being wasted. For systems over 10,000 atoms or so, the wasted memory used
may prevent a job from running, will certainly slow down the calculation, and
could severely hinder other users of the same machine.
There are two simple ways to minimize the amount of memory wasted:
(1) Use the nonbond option NBSCale real to increase the size of the
initial guess for the first memory allocation; valid wherever nonbond
options may appear, e.g. ENERgy, DYNAmics, MINImiz, and UPDAte. Note that
NBSCale must be used in the first statement which generates a nonbond list;
an UPDAte without NBSCale followed by DYNAmics with NBSCale is ineffective.
For a system of just under 17,000 atoms, a value of 1.5 was effective in
providing about 25 MB of memory reduction compared to the the default NBSCale
value (1.0); while for a system of about 10,000 atoms, the optimum of 1.4 gave
a reduction of about 12 MB. For example:
mini abnr nstep 500 nprint 10 tolenr 1.e-6 cutnb 14. ctofnb 12. ctonnb 10. -
fshift cdie eps 1.0 vshift inbfrq 20 imgfrq 20 cutim 14. nbscale 1.5
Likewise for DNYAmics, ENERgy, or the UPDAte commands; the latter is useful in
doing some trial and error probes to determine the optimum NBSCale value,
with fixed sizes for CUTNB and CUTIM:
update cutnb 14. ctofnb 12. ctonnb 10. fshift cdie eps 1.0 vshift -
inbfrq 20 imgfrq 20 cutim 14. nbscale @1 -
where the csh or tcsh command line might be something like:
% charmm medium 1:1.5 < tst_nbscal.inp >& nbscal_1.5 &
The above is based on single processor calculations; the same general idea
applies to parallel calculations, but the optimum value for NBSCale will
be less than 1.0, perhaps 0.7 to 0.8 for systems in the 10K to 17K atom
range. With versions c24n4 and c24b1, memory usage can be further reduced
using the IMSCale keyword; optimal values seem to be around 0.6 to 0.7,
but some experimentation will be required depending on the number of atoms
and the cutoffs being used.
(2) Pre-allocate some memory using GETHeap (See test.doc) prior to any
commands which generate nonbond or image lists (UPDAte, ENER, MINI, DYNA).
The job summary data at the end of a sucessful CHARMM run shows the memory
used, in 'words' (usually 4 bytes), as the LENGTH: field of the lines starting
with the PRINHP> tag. An increasing series of LENGTH: values indicates
possible failed memory allocations; for example:
FREE LIST
PRINHP> ADDRESS: 1 LENGTH: 2048000 NEXT: 6154983
PRINHP> ADDRESS: 6154983 LENGTH: 5210112 NEXT: 11365097
PRINHP> ADDRESS: 11365097 LENGTH: 7634944 NEXT: 19000043
PRINHP> ADDRESS: 19000043 LENGTH: 9551872 NEXT: 0
The first LENGTH: value is the initial HEAP size, the second is a failed
allocation; the third is the nonbond list, and the last is the image list.
Note that 5210112 words is about 20 MB of memory (divide by 262144 to get
MB from words). The total memory used for the HEAP is the sum of the LENGTH:
values, so the goal is to reduce the total by reducing the number of additional
allocations to one (no images) or two (with images). This applies to both
single and parallel host calculations; the best value to use for GETHeap will
change if either CUTNB or CUTIM are changed.
For the above 17,000 atom system, pre-allocating the largest block resulted
in a similar memory reduction to using NBSCale 1.5; the statement
getheap 9551872
would set aside the largest memory block, and as a consequence, the allocation
of the first additional block of 5210112 words never occurs. For the 10,000
atom system, GETHeap was not effective at reducing the amount of memory used.
------------------------------------------------------------------------
APPENDIX C: Adding USER* routines to CHARMM
The following dummy routines can be replaced by user-written ones to
supply additional energy terms, time series definitions, atom selections,
and other extensions to CHARMM.
SUBROUTINE USERSB
SUBROUTINE USERE(EU,X,Y,Z,DX,DY,DZ,QECONT,ECONT,NATOMX)
SUBROUTINE USRACM(NATOMX,X,Y,Z,DX,DY,DZ,QECONT,ECONT,ICALL)
SUBROUTINE USERNM(IUSER,X,Y,Z,XNORMA,YNORMA,ZNORMA,NATOMX)
SUBROUTINE USRSEL(NTAGS,FLAGS,X,Y,Z,QCOOR)
SUBROUTINE USRTIM(SERVAL,QAT,NQ,ITIME,
1 NATOMX,X,Y,Z,XREF,YREF,ZREF,NSKIP,DELTA,TVAL)
SUBROUTINE USRINI
SUBROUTINE USPAFL(I,XX,YY,ZZ,XY,XZ,YZ,
1 XNORM,YNORM,ZNORM,NATOM,ISLCT)
An automated means of obtaining usersb.src and required files has been
set up for both c24n4 and c24n5:
(1) create a directory for the code and the eventual private CHARMM version
(2) copy the file ~charmm/c24n5/build/hpux/usersb.mk (or c24n4 version)
to the new directory (optionally rename usersb.mk to Makefile; see below)
(3) edit usersb.mk if you wish to change the defaults of "medium" and "lite"
(4) type make -f usersb.mk setup (files copied, link created)
(5) edit usersb.src to replace one or more dummy routines, add called routines
(6) type make -f usersb.mk charmm (program created)
If you change the name of usersb.mk to Makefile, you may omit the -f usersb.mk
argument; also, charmm is the default "target", and it's use is optional.
Read the header of usersb.mk for additional details.
Note that the cover script charmm in /usr/local/bin sets
the following environment variables for parallel usage:
HOST the hostname, e.g. par0, par11
PWD the working directory (usually CHARMM input and output are here)
NODE0 the master parallel host ( par0f or par11f )
NODE1 a slave parallel host ( par1f or par12f )
NODE2 a slave parallel host ( par2f or par13f )
NODE3 a slave parallel host ( par3f or par14f )
You must write a cover script which sets these environment variables and then
calls your private version of CHARMM in order to run parallel calculations, or
else set the variables explicitly.
Information and HTML Formatting Courtesy of:
NHLBI/LBC Computational Biophtsics Section
FDA/CBER/OVRR Biophysics Laboratory