Below you will find short instructions how to use DAMMIN by Dmitri Svergun.
The information below corresponds to the file /hosts/lass2/d1/lss/svergun/Dammin/dammin.ins.

At the ILL, use the command dammin.

                            D A M M I N  Beta release version 2.7b

Ab inito shape determination by simulated
annealing using a single phase dummy atoms model

User instructions

Last modified --- 30/08/99 15:19

Hardware platforms: IBM-PC (WinNT, Win95, Win98) UNIX (SUN, SGI)

DAMMIN implements an ab initio shape determination algorithm described by

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.
Contact E-mail address: svergun@embl-hamburg.de

Contributors: M.Kozin, M.Petoukhov, V.Volkov.

===========================================================

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

(i) Log-file name <name>, (ii) project description,
(iii) name of the GNOM output file,
(iv) if known, point symmetry of the particle:
                                P1(no symmetry, default), P2, P3, P4 or P222

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 by GNOM data
<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 the 'spacefill' mode

For more detailed information, see Sample run below.

===========================================================

GNOM runs on IBM-PC (Win95, Win98, WinNT)
                            Sun SPARC (Solaris 2.5)
                            SGI (IRIX 6.3)

Average CPU time on an IBM-PC Pentium-II 400 MHz machine
is about 2-3 h without symmetry restrictions and about 1h
with symmetry restrictions.

===========================================================

                            SAMPLE RUN

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

Shape restoration of hen egg white lysozyme is taken as an example.
Raw data file :                       lyzexp.dat (collected at the EMBL, Hamburg)
Data processed by GNOM: file gnomly.out
Outpit files :                            ly04*.*.

All these files are included in the distribution package.

Note that the test run was performed with DAMMIN ver. 2.6.
Later versions may give other values (in particular, computation
of the final Chi is corrected in v 2.7)

=== DAMMIN26 started on 17-Aug-1999 15:00:53

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

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 >: ly04 =QUE=
---------------------------------------------------

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 .................................. : ly04
and used to create the output file names (see below).

---------------------------------------------------
Enter project description ................... : Lysozyme test run =QUE=
---------------------------------------------------

Project description that will be printed to the output files.

Random sequence initialized from ....................... : 141510

The program initializes the random number generator from current
time (hhmmss) so that succesive runs of DAMMIN (except those
performed exactly 24 hours one after the other) will
use different random sequences. It is recommended to make several runs
in order to check the stability of the solution.

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

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, most important of them being speeding up the computations.
Versions of GNOM for different platforms are freely available
and can be retrieved from the same FTP site (see README in the
/sax directory of ftp.embl-hamburg.de)

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.

** Information read from the GNOM file **
Raw data file name ........................................................ : lyzexp.dat
Maximum diameter of the particle ............................. : 50.00
Solution at Alpha = .320E+00 Rg : .154E+02 I(0)..... : .656E+01
Number of GNOM data points ..................................... : 214

---------------------------------------------------

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

---------------------------------------------------

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 =QUE=
---------------------------------------------------

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
not the entire curve, but rather a portion of it, in the example
above from 0 to 0.5*smax.

IN MANY CASES (ESPECIALLY, FOR SMALL PROTEINS) IT IS BETTER
NOT TO FIT 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

Maximum order of spherical harmonics taken in the computation
of scattering intensity.

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

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 =QUE=
---------------------------------------------------

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 uesd: P2, P3, P4, P222.
P1 (default) means no symmetry restrictions.

---------------------------------------------------
Maximum diameter [Angstrom] ............ < 50.0 >: =QUE=
---------------------------------------------------

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 ........................................... : 753
Randomized DAM looseness ..................................... : .1068
Randomized DAM # of graphs .................................. : 6
Discontiguity value ...................................................... : 6.662e-3
Initial scale factor ......................................................... : 9.868e-9
Scale factor fixed (Y=Yes, N=No) ............................... : N
Initial R^2 factor ............................................................ : .2953
Initial R factor ................................................................ : .5435
Initial penalty ................................................................. : 1.134e-3
Initial fVal ........................................................................ : .2965

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

fVal = Rfac + Penalty

Here

                    SUM [ (Scale*Imod(i) - Iexp(i)) s(i)^2 ]^2
i Rfac^2 = ----------------------------------------
                    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 ......................................... : .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 ................................ : 74
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: 13533 CPU: 0.4757E+02
SqfVal: 0.4212 Rf: 0.41941 Los:0.1253 DisCog:0.0286 Sca: 0.112E-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>-{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 Xtal 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 operation system, output the file might be locked at the next
temperature output and the program will crash.
......................................

jAnn: 39 T: 0.182E-04 iSuc: 10367 nEva: 1167193 CPU: 0.3190E+04
SqfVal: 0.0315 Rf: 0.01517 Los:0.0765 DisCog:0.0000 Sca: 0.224E-07

Number of atoms fixed ........................................... : 553
Reduced # iterations per T .................................... : 64960
Reduced # successes per T .................................. : 6496

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: 40 T: 0.164E-04 iSuc: 6496 nEva: 1184542 CPU: 0.3238E+04
SqfVal: 0.0305 Rf: 0.00986 Los:0.0830 DisCog:0.0000 Sca: 0.252E-07
......................................

jAnn: 83 T: 0.177E-06 iSuc: 57 nEva: 3193947 CPU: 0.8776E+04
SqfVal: 0.0129 Rf: 0.00457 Los:0.0146 DisCog:0.0000 Sca: 0.129E-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 about a few percent, DisCog should be zero.

The CPU time used by the program in the above run is appr. 2.5 h
on a 400 MHz Pentium-II IBM-PC machine under NT. Note that
DOS/Win3.1 version would return real elapsed time instead of CPU used.

===== DAMMIN26 finished on 18-Aug-1999 01:40:45

Note that this task ran in underground and the real
time elapsed is greater than the 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 .................................... : .5112
Final Chi against raw data-Const ....................... : .3055

(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.

Note: a bug in the computation of the final Chi is corrected in v 2.7
</project></name></name></name></name></name>