DAMMIN
Manual

 

 

General Information

For general information see

D.Svergun (1999). Restoring low resolution structure of biological macromolecules from solution scattering using simulated annealing. Biophys. J., 76, 2879-2886.

The users are referred to this paper for details.

For those who do not wish to read instructions

DAMMIN reads in output files of GNOM (the latter is an indirect transformation program available from this server). After starting DAMMIN in the default USER mode you will need to specify

	Log-file name <name>,
	Project description
	name of the GNOM output file,
	if known, point symmetry of the particle : Default group is P1(no symmetry) Point groups P2, P22, P3, P32, P4, P42, P5, P6, P62 are supported (note: groups P5, P6, P62 not fully tested)
	if known, expected particle anisometry: Unknown (default), Prolate, Oblate

and default answers to all other questions.

After the program is finished, you will get the files

<name>.log :	log file
<name>.fit :	fit to the desmeared and smoothed data from GNOM.
<name>.fir :	fit to the raw experimental data
<name>-1.pdb :	resulting model in PDB-like format that can be viewed e.g. with RasMol in 'spacefill' mode or with MASSHA (see Atsas package)

 

To have a more reliable solution one may run DAMMIN several times and average the results (e.g. using the DAMAVER package, which can be downloaded from this site).

For more detailed information, see Sample run below.

What is new in version 5.3

 Version 5.3 Release 13/08/07 Hollow sphere search volume in the case of icosahedral symmetry is enabled.

 Version 5.1 Release 19/08/05 

- can be run in a command-line mode (most important parameters specified in the UNIX style 
when starting the program)
- KEEP mode introduced (program keeps the list of best solutions and produces
up to 15 different models fitting the data for subsequent analysis by DAMAVER)
- symmetry groups P1-P19, P222-P122, icosahedral symmetry as well as cubic
types P23 and P432 are supported.

 Version 4.6 Release 10/03/03 Start from ellipsoid/cylinder/parallelepiped/sphere is enabled.

 Version 4.5 Release 13/08/02 If smearing is present, the *.fir file gives an estimate of the fit to smeared experimental data (the *.fit curve is approximately smeared as in a single iteration of Lake's method). Some defaults are changed, in particular, default nAtoms (P1): 2000 (Fast), 5500 (Slow), 9500 (Expert).

 Version 4.4d Release 05/02/02 Variable default weight of looseness penalty (decreases with nAtoms -- important if more than 5000 atoms) Defaults for expert mode are as for very slow annealing.

 Version 4.4c Release 17/12/01 Default #atoms for fast mode increased (for P1, from 1500 to 2000). The maximum allowed #atoms increased from 5000 to 100000. Fixing thresholds are decreased (somewhat slower but more reliable for anisometric particles).

 Version 4.4a,b Release 24/11/01 Reads Gnomoko files. Constant subtraction procedure corrected.

 Version 4.3b Release 07/07/01 Contact radius in looseness computation increased to r_c=2.5r₀ to properly evaluate looseness for P5 and P6 (affected versions: 4.3, 4.3a)  

 Version 4.3a Release 20/06/01 A bug in reading data from the Gnom file has been corrected: If the Gnom file contained several runs, the FIRST Gnom run was read, and not the LAST run as should be (affected versions: 3.7 to 4.3)  

A Win9x/NT/2000 version is available compiled using the QuickWin graphics of Compaq Fortran (dammin43qw.exe). It can run from the desktop (we suggest to copy this file together with other QuickWin applications into c:/Atsas and create a shortcut). The program stores the last working directory in a file c:\Atsas\dammin.ini and would start from this directory next time. During the minimization, the QuickWin program displays current fit to the experimental data in a separate window.

A console-style version without graphics for PC is also available. The UNIX version does not have graphics as before.

There are now four operating modes:

   - the default FAST mode (equivalent to the USER mode in v. 3.1),

   - a SLOW mode (slow annealing, larger number of dummy atoms and more spherical harmonics taken into account)

   - an experimental JAGGED mode, also uses more dummy atoms and more spherical harmonics. The difference from SLOW mode is that the temparature is decreased faster but than increased again in repeating cycles (reannealing).

   - an EXPERT mode (permits to tune ALL parameters, equivalent to that in v. 3.1).

NOTES

     SLOW mode may be useful for very anisometric particles, although it takes significantly longer CPU times.

     JAGGED mode may be used as a faster alternative to the SLOW  mode (still under testing)

     In most 'normal' cases, FAST mode is OK. The other modes may be required for extremely anisometric shapes (flat, starting from 5:5:1, or elongated, starting from 1:1:10). However, if you have enough patience to run SLOW or JAGGED mode, it may be useful to compare results from different modes

     If FAST mode does not provide a good fit, you MUST run SLOW or JAGGED!

  A peripheral penalty (PenPer) is added to prevent the algorithm from 'feeling' the border of the search volume. The program usually works fine with the default value of this penalty weight (0.2 in FAST/SLOW/JAGGED modes). The weight may be changed in the EXPERT mode..

Symmetry can also be used when loading initial approximation from a file. Symmetries P32, P42, P5, P6 and P62 are added (note: groups P5, P6, P62 not fully tested as yet). For P2 symmetry, it is possible to choose whether the particle is elongated along or across the twofold axis.

 In Expert mode, the choice of the weighting function is introduced:

   0 -   W(s) = s^2  (Porod weighting)

   1 -   Porod weighting with emphasis of initial points (default)

   2 -   logarithmic scale weighting

   In the earlier default weighting function (s^2) the very low angle points (to the left from the Porod's plot  maximum) vere somewhat underestimated. This sometimes lead to poor fits in this range for very anisometric (1:10) particles. We  introduced an option to give to the starting points an average weight between the s^2 and the value corresponding to the maximum of the Porod plot. A logarithmic weighting (fitting the data on a logarithmic scale) is also introduced. Both options 1 and 2 may give better results over option 0 for very anisometric objects. The default option is 1 and can only be changed in the Expert mode.

Hardware Platforms

 

DAMMIN v.4.5 runs on :	IBM-PC (Win95, Win98, WinNT, Win2000)
	SGI (IRIX 6.3)
	DEC Alpha (Compaq Tru64 UNIX V5.1)

Average CPU time on an IBM-PC Pentium-III 500 MHz machine in FAST mode is about 2 h without symmetry restrictions and about 1 h with symmetry restrictions. SLOW mode may be up to 20 times longer.

Sample Run (version 3.1)

Below, instructions are presented on how to use DAMMIN The questions to be answered by the user are marked in bold. The rest will be printed by DAMMIN for information only.

Shape restoration of hen egg white lysozyme is taken as an example.

Raw data file	:	lyzexp.dat
Data processed by GNOM	:	file gnomly.out
Output files	:	ly04*.*

All these files are included in the distribution package.

=== DAMMIN31 started on 07-Dec-1999 17:45:38

---------------------------------------------------
Computation mode (User or Expert) ...... < User >: <return>
---------------------------------------------------

The first question of DAMMIN refers to the computation mode. It is assumed that the users select the User mode (default answer). The Expert mode permits to modify the parameters controlling the minimization process and is reserved for future use.

---------------------------------------------------
Log file name .......................... < .log >: ly02
---------------------------------------------------

The LOG-file will contain information about the minimization (it will be written there simultaneously with the screen output). First letters of the Log-file name (not more than six) will be taken as

Project identificator .................................. : ly02
and used to create the output file names (see below).

---------------------------------------------------
Enter project description ................... : Lysozyme default
---------------------------------------------------

Project description that will be printed to the output files.
Random sequence initialized from ....................... : 174548

The program initializes the random number generator from current time (hh:mm:ss) so that successive runs of DAMMIN (except those performed exactly at the same time of the day) will use different random sequences. It is recommended to make several runs to check the stability of the solution.

---------------------------------------------------
Input data, GNOM output file name ...... < .out >: gnomly
---------------------------------------------------

DAMMIN takes input information from a GNOM output file. This means that the experimental data should be first processed by GNOM and then read in DAMMIN. There are several reasons for doing this, the most important one being to speed up the computations. Versions of GNOM for different platforms are freely available and can be retrieved from the same FTP site (see README )

DAMMIN reads the raw data file name, maximum particle size Dmax, the raw curve with the errors and processed curve. If there are several GNOM solutions in a single file (e.g. after computations with several Dmax), DAMMIN reads THE LAST ONE (assuming that the last is the correct one).

Please note, that GNOM FILE SHOULD NOT BE EDITED! If an error occurs while reading the GNOM file, the file name is prompted again.

---------------------------------------------------
Angular units in the input file :
4*pi*sin(theta)/lambda [1/angstrom] (1)
4*pi*sin(theta)/lambda [1/nm ] (2) < 2 >: 1
---------------------------------------------------

The working units for DAMMIN are angstroms, and the scattering vector is in 4*pi*sin(theta)/lambda [1/angstrom]. If GNOM file contains data in nm, they will be appropriately scaled. For convenience, default values are 1 if Dmax read from GNOM file is less than 30 and 2 if Dmax>30.

Number of GNOM data points ............................. : 214
Maximum s value [1/angstrom] ........................... : .4984
Number of Shannon channels ............................. : 7.932
---------------------------------------------------
Portion of the curve to be fitted ...... < 1.000 >: 1
---------------------------------------------------

For information, DAMMIN prints the smax value and the number of Shannon channels in the curve nShan=Dmax*smax/pi. As outer parts of the scattering curves may contain significant contributions from the internal structure, DAMMIN gives an opportunity to fit only a portion of the curve, in the example above from 0 to 0.5*smax.

IN MANY CASES (ESPECIALLY, FOR SMALL PROTEINS) IT IS BETTER NOT TO FIT the OUTER PARTS OF THE SCATTERING CURVES.

Number of knots in the curve to fit .................... : 40

DAMMIN interpolates the portion of the PROCESSED GNOM curve (backtranformed from the p(r) function, i.e. desmeared curve without noise) in order to have appr. 5*nShan knots in the curve to fit. This number of knots is sufficient to represent a smooth curve and allows to speed up the calculations (in this case by a factor of appr. 7 [280(total # of points read)/41=6.8])

A constant was subtracted .............................. : 4.307e-2

DAMMIN tries to subtract a constant from the data to force the s^-4 decay of the intensity at higher angles. If this is not successful, a message

** Constant subtraction procedure skipped **

is printed.

Maximum order of harmonics ............................. : 10

The default value for the maximum order of spherical harmonics taken in the computation of scattering intensity L=10 is usually sufficient in most practical applications. If you wish to fit a scattering curve over a very broad range (e.g. more than 15 Shannon channels) or if the particle is expected to be very anisometric, it might be useful to compute with larger L (maximum L=20 is supported).
Notes : The computation time is proportional to L², i.e. a run with L=20 takes 4 times more CPU than the default run

---------------------------------------------------
Initial DAM (CR for a sphere) .......... < .pdb >:<return>
---------------------------------------------------

By default, DAMMIN uses a spherical search volume. The use of other volumes requires specially prepared initial approximation files and is currently not supported in the USER mode.

---------------------------------------------------
Particle symmetry (P1/P2/P3/P4/P222) ... < P1 >: p1
---------------------------------------------------

If the information about the point symmetry of the particle is available, the symmetry can be imposed on possible solutions. Currently, the four point symmetries can be used: P2, P3, P4, P222. P1 (default) means no symmetry restrictions.

---------------------------------------------------
Maximum diameter [Angstrom] ............ < 50.0 >:<return>
---------------------------------------------------

By default, the diameter of the spherical search volume is equal to that of the particle read from the GNOM file.

Packing radius of dummy atoms .......................... : 2.000
Radius of the sphere generated ......................... : 25.00
Number of dummy atoms .................................. : 1481
Excluded volume per atom ............................... : 45.28

The sphere is filled by densely packed dummy atoms. The radius of the atoms is selected to have approximately nAtom=1500 atoms in the search volume.

Radius of 1st coordination sphere ...................... : 4.020
Minimum number of contacts ............................. : 6
Maximum number of contacts ............................. : 12
Looseness penalty weight ............................... : 1.000e-2
No of non-solvent atoms ................................ : 1481
Initial DAM looseness .................................. : 7.487e-3
Disconnectivity penalty weight ......................... : 1.000e-2
Initial DAM # of graphs ................................ : 1
Discontiguity value .................................. : 0.0
Looseness fixing threshold ............................. : 8.000e-2
R-factor fixing threshold ............................. : 3.000e-2
*** The structure was randomized ***
No of non-solvent atoms ................................ : 734
Randomized DAM looseness ............................... : .1035
Randomized DAM # of graphs ............................. : 1
Discontiguity value .................................. : 0.0
Expected particle anisometry ........................... : Unknown
Initial scale factor ................................... : 1.027e-8
Scale factor fixed (Y=Yes, N=No) ....................... : N
Initial R^2 factor ..................................... : .2911
Initial R factor ..................................... : .5396
Initial penalty ........................................ : 1.035e-3
Initial fVal ........................................... : .2922

The initial structure is randomized (i.e. the spheres in the search volume are assigned numbers 0 (=solvent) and 1 (=particle) and the simulated annealing procedure begins to minimize the function

fVal = Rfac + Penalty
Here

Rfac2 =	SUM [ (Scale*Imod(i) - Iexp(i)) s(i)2 ]2 i
	--------------------------------------------------
	SUM [ Iexp(i) s(i)2 ]2 i

where Scale is a scale factor providing the best least squares fit, and

Penalty = WeiLos*Los + WeiDis*Dis

is a sum of penatlies for looseness (Los) and disconnectivity (Dis) of the current DAM.

Initial annealing temperature .......................... : 1.000e-3
Annealing schedule factor .............................. : 0.9000
# of independent atoms to modify ....................... : 1
Max # of iterations at each T .......................... : 103670
Max # of successes at each T ........................... : 10367
Min # of successes to continue ......................... : 103
Max # of annealing steps ............................... : 100

The number of iterations per temperature is nIter = 70*nAtoms/nSym, where nSym is a reduction factor due to symmetry restrictions (nSym=2 for P2, nSym=3 for P3, nSym=4 for P4 and P222). The number of successes nSucc is 0.1*nIter.

jAnn: 1 T: 0.100E-02 iSuc: 10367 nEva: 13636 CPU: 0.2313E+02
SqfVal: 0.4058 Rf: 0.40387 Los:0.1296 DisCog:0.0268 Sca: 0.119E-07

First line:	Step #,	Temperature,	# of successes,	total # of function evaluations,	CPU time used.
Second line:	Sqrt(fVal),	Rfactor,	PenLos,	PenDis,	Scale

The current solution is saved after each temperature in the PDB-like format onto the files <Project identificator>-{0,1}.pdb, i.e. in the above case, to run01-0.pdb (solvent atoms) and run01-1.pdb (particle atoms). The *-01.pdb file also contains the integral parameters of the current model.

Of course, only run01-1.pdb is of interest, the other file is written just for information. The dummy atoms in both files are saved as C-alpha atoms. The *.pdb files can be visualized with any crystallographic program, e.g. with RasMol (spacefill mode)

The current fit to the GNOM curve is saved onto run01.fit in the form s (regridded knots), IGnom (backtransformed), Ifit.

If you wish to view the current fit or current structure while the program is running, it is STRONGLY recommended to copy these files to temporary files under other names and work with the latter. Otherwise, depending on the operating system, the output file might be locked at the next temperature output and the program will crash.

jAnn: 40 T: 0.164E-04 iSuc: 10367 nEva: 1214322 CPU: 0.1598E+04
SqfVal: 0.0300 Rf: 0.01303 Los:0.0729 DisCog:0.0000 Sca: 0.213E-07

Number of atoms fixed .................................. : 568
Reduced # iterations per T ............................. : 63910
Reduced # successes per T ............................. : 6391

When the shape is already well defined, some of the dummy atoms are fixed (to be particle or to be solvent atoms) to prevent unnecessary rotations and movements of the entire DAM and thus to impove the convergence. The temperature for doing this is selected using the "Looseness fixing" and "R-factor fixing" thresholds and cannot be modified in the USER mode.

jAnn: 41 T: 0.148E-04 iSuc: 6391 nEva: 1231488 CPU: 0.1620E+04
SqfVal: 0.0300 Rf: 0.01303 Los:0.0729 DisCog:0.0000 Sca: 0.213E-07
...........................................
jAnn: 82 T: 0.197E-06 iSuc: 66 nEva: 3134980 CPU: 0.4191E+04
SqfVal: 0.0130 Rf: 0.00481 Los:0.0147 DisCog:0.0000 Sca: 0.133E-07

The annealing is finished when the number of successes iSuc is less than 0.05*nAtom/nSym. At the end, Rf should be less that 1 percent, Los a few percent, DisCog should be zero.

This task ran on a SGI Workstation and took about 1h10' of CPU time. On a 400 MHz Pentium-II IBM-PC machine under NT, simular run takes about 2.5h CPU. Note that DOS/Win3.1 version would return real elapsed time instead of CPU used.

When the program is finished, the files *.pdb and *.fit provide the final solution. Moreover, the root-mean square deviation to the raw experimental data is computed

Final Chi against raw data ............................. : 1.593
Final Chi against raw data-Const ....................... : .4584

(the first number refers to the data as they are, the second to the data after the constant subtraction). The fit to the raw data is saved onto the file run01.fir in the form

sExp (actual), Iraw, Error, Iraw-Constant, Ifit.

===== DAMMIN31 finished at 07-Dec-1999 18:56:38