Instructions for the use of GNOM

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

At the ILL, use the command gnom.

Back to the D22 documentation

Back to the LSS home page

The worldwide version on the ILL web is here.

                    *  PROGRAM PACKAGE GNOM *

             Small-Angle Scattering Data Processing
             by Means of the Regularization Technique

      -----        Version E4.3     21/08/99 16:50          -----
      -----              for IBM-PC and UNIX                -----

  GNOM is written by  D.Svergun & A.Semenyuk
                      EMBL c/o DESY  Notkestrasse 85
                      D-22603 Hamburg, GERMANY
                      Institute of Crystallography
                      Academy of Sciences of Russia
                      117333 Leninsky pr.,59 Mocsow, RUSSIA

  Version 4.3 released by D.Svergun
          Tel.       (+49) (0)40 89902 125
          Fax.       (+49) (0)40 89902 149
          E-mail     Svergun@EMBL-Hamburg.DE



              What is new in version 4.3
              Structure of input data file
              Output file
              Standard deviations
              Integral kernel and job type
              Experimental conditions
              Regularization parameter
              Perceptual criteria
              Error estimates
              Next job
              On-line help
              Configuration file
              Practical advises
              Hardware and software requirements



GNOM is an indirect transform program for small-angle  scattering
data processing.  It reads  in one-dimensional  scattering curves
(possibly smeared  with instrumental  distortions) and  evaluates
the   particle   distance  distribution   function   p(r)    (for
monodisperse systems) or the size distribution function D(R) (for
polydisperse systems). The main equations relating the scattering
intensity to  the  distribution  functions  and  describing   the
smearing effects one can find in the text-books (e.g. [0]).

GNOM  is  similar   to  the  known   programs  of  Glatter   [1],
Moore  [2]  and  Provencher  [3].  There  are,  however, some
points, which   make  GNOM   more  convenient   in   application.
GNOM   is a  dialogue    program;    the    user     instructions
presented  here explain how to answer the questions properly. The
versions E4.0 and  higher make use  of the "configuration  file",
where some or all the parameters can be pre-defined; this  allows
to  work  with  GNOM  in  different  modes,  ranging  from  fully
interactive to   batch mode.  The names  of the parameters in the
following description refer to the configuration file names.

The algorithms used in the program are described elsewhere [4-6].
They are  based on  the Tikhonov's  regularization technique [7];
several subroutines  published in  [8] are  modified and  used in
GNOM.   The   value   of   the   regularization   parameter    is
estimated    by    the    program    automatically    using   the
perceptual criteria [9].

                        What is new in version 4.3

1. Version 4.3 WILL NOT run under DOS or Win3.x on IBM PC,
   it requires Win95/98 or WinNT.

2. Version 4.3 is a double precision version.

3. Maximum numbers of experimental points in the input data file,
   of the data points after joining and of the points
   in the characteristic function are increased to 2048, 512 and
   101, respectively.

4. Version 4.3 searches for the input of the data stream in a
   smarter way. When reading in the input data, GNOM searches
   for THREE valid lines containing increasing s and positive I(s).
   Due to this, GNOM is able to read e.g. files in sasCIF format
   or those in the ILL or LOQ format without editing.

5. A possibility is added to omit data points in the beginning
   and at the end of the input file(s).

6. The angular scale can optionally be reduced to the units of
   4*pi*sin(theta)/lambda [Angstrom].

7. An option AH (or LH ) < 0 is added to emulate the case of
   infinite slit coliimation (e.g. Kratky camera geometry)

8. Both IBM-PC and UNIX versions of GNOM4.3 use now the GNUPLOT
   graphics and support several printer formats for hardcopy output.

                        Structure of input data file

Input  file  (parameter  INPUT1)  is   a  sequential   ASCII file
containing the experimental data.   First line is always  treated
as a problem title (comment).  Then the program  searches for the
first  data   line.  Valid  data  line  should  contain  momentum
transfer,  non-zero   intensity,   and,   optionally,    standard
deviation  in  a  free  format  (that  is, separated by blanks or
commas).    After this all  valid lines   are treated as    data;
invalid  line or   end-of-file   are considered  as the  end   of
the input stream.  Maximum number of data points is 1024.

This  way  to  read  data  is  rather  flexible, allowing to skip
additional  headers  and  to  use  the  data  with or without the
standard deviations. However, long  files will take some  time to
read (especially on VAX'es).

With modern devices one can measure lots of data points with tiny
angular step. This is not always good, and sometimes might become
harmful when using indirect  methods, because each angular  point
gives rise  to a  separate equation,  which are,  in fact, linear
dependent. Note that the angular step Delta(s) = Dsamp / 6, where
Dsamp=(pi)/Dmax is a sampling distance, is claimed to be optimum.
To optimize the performance, GNOM joins neighbouring data  points
when it finds the number of points to be unreasonably high.

The program can handle simultaneously two data sets corresponding
to the same  sample but recorded  with different conditions  (see
below).  The second input file (parameter INPUT2) should have the
same structure.  Default answer to the question 'Input file name,
second run' is NO second run.

Note, that the momentum transfer is assumed to be

       s = 4 (pi) sin (theta) / (average wavelength),

where theta is a half of the scattering angle.

  Example of the input file :
   PROBLEM #13
This line is skipped because of error, the next because of zero intensity :
  0.0001     0.0         17.1
This is again skipped: the next is the first valid data line:
 0.05564   ,     1.2323e10  111111111.
 0.05574 1.1323e10
 0.05584 18303353, 1e10 , This is the text which does not change anything!
  1.e-1     1.0323e10,   8E8    It is just not read.
  0.07        0.0         17.1
The previous line indicates the end of the data set

			Output file

This is  a sequential  disk file  where all  the information from
GNOM will  be printed  in ASCII  form (parameter  OUTPUT, default
file name is gnom.out)

			Standard deviations

   If  some  standard  deviations  (or  all  of  them)  are   not
specified, negative  or  equal  to   zero,  the   user  will   be
prompted  for   their estimation (parameter  DEVIAT). A  positive
number means constant relative deviation per  point. If the  user
enters zero   (default answer),   the program  will estimate  the
errors  automatically  with  the  help  of a polynomial smoothing

 3  means that for each point with a non-positive standard
    deviation a relative deviation 0.03*A is assumed, where A is
    the intensity in this point

                     Integral kernel and job type

   The program searches for a distribution function in real space
(characteristic  function  for   monodisperse  systems  or   size
distribution function for polydisperse systems). These  functions
are  related  to  the  experimental  intensity  by  corresponding
Fourier  transform  followed  by  some  convolutions representing
smearing effects (if the latter exist).  The integral equation is
represented in a form of a linear system and solved with  respect
to the distribution function.  The matrix of the system is called
"design matrix".  To evaluate  it, the user must specify  several


     0 - calculation of distance distribution function for a
          monodisperse system (default job). The function
	  p(r) = gamma(r)*r**2 is evaluated, where gamma(r) is
	  the characteristic function of the particle.

     1 - calculation of volume distribution function
          D(R)=(4*pi/3)*R**3 N(R) for polydisperse system of
          solid spheres (R is the sphere radius, N(R) relative
          number of particles with this radius in the system)

     2 -  calculation of size distribution function of
          particles with the user-supplied form factor (parameter
          FORFAC). In this case the form factor of particles
          should be supplied in a separate file. The first line
          of this file should contain three values in free format:

             NFORM   - number of points in the formfactor
             NDIM    - number of dimensions (NDIM=1 long particles,
                       NDIM=2 plane particles, NDIM=3 globular particles)
             DELSR   - increment in the s*R units (s scattering vector,
                       R characteristic particle size). The form factor
                       is to be given in the points 0., DELSR, 2DELSR,...

           This should be followed by the form factor values (NFORM values
           in 8E10.3 format, NFORM <2500)

	   The function D(R) = N(R)*R**NDIM is evaluated; R is a
           user-defined characteristic size (e.g. radius of gyration)

      3 - calculation of the distance distribution function of thickness
          assuming monodisperse system of flattened particles. The
          function p(r) = gammat(r) is evaluated, where gammat(r) is
          the characteristic function of thickness. In this case the
	  experimental intensity as well the errors are multiplied by
	  s**2 which corresponds to the thickness scattering factor.

      4 - calculation of the distance distribution function of the
          cross-section assuming monodisperse system of rod-like particles.
          The function p(r) = gammac(r)*r is evaluated, where gammac(r) is
          the characteristic function of thickness. In this case the
          experimental intensity as well as the errors are multiplied by
          s, which corresponds to the cross-section scattering factor.

     5 -  calculation of the length distribution function p(r)
          for a polydisperse system of long cylinders p(r) = H
          N(H), where H is the length of the cylinder, N(H)
          number of rods of the lengths H. Radius of the cylinder
          is assumed to be a constant (see parameter RAD56 below).

     6 -  calculation of the surface distribution function p(r)
          for a polydisperse system of spherical shells
          p(r) = 4*pi*R**2*N(R), where R is the outer radius
          of the shell, N(R) number of the shells of the outer
          radius R. The shells are assumed to have the same
          relative thickness (see parameter RAD56 below).

***  RMIN (for JOB=1,2,5,6), RMAX

Maximum diameter of the particle                  (for JOB=0)
Minimum and maximum radii of spheres              (for JOB=1)
Minimum and maximum characteristic particle sizes (for JOB=2)
Maximum diameter of the particle thickness        (for JOB=3)
Maximum diameter of the particle cross-section    (for JOB=4)
Minimum and maximum heights of cylinders          (for JOB=5)
Minimum and maximum outer radii of shells         (for JOB=6)

          - define the interval in real space, where the distribution
            function is assumed to be non-zero

*** For JOB=5 or 6, the parameter RAD56 is to be specified:

JOB=5:  RAD56 means the radius of a cylinder (RAD56=0 means
        infinitely thin rods)

JOB=6:  RAD56 means the relative thickness of a shell (its inner
        radius is RAD56*(outer radius). RAD56=0 means
        infinitely thin shells.

*** Number of real space points (parameter NREAL)
          - number of points, in which the disiribution function will
            be specified (less than 72). Default number of NR is
            evaluated by GNOM in order to have reasonable ratio

*** Boundary conditions (parameters LZRMIN, LZRMAX)
         - it is possible to fix the values of the distribution
           function to zero at the ends of the interval by answering

*** Kernel-storage file name (parameter KERNEL)
          - name of the file, where the design matrix is saved

                    Experimental conditions

*** Type of experimental set-up (parameter IDET)

The user must  define which type of  experimental set-up is used.
IDET=0 means no smearing, IDET=1 means 1D-detector (slit geometry
with rectangular slits is assumed), IDET=2 means 2D-detector (the
data is obtained by a circular average).

*** Wavelength smearing (parameters FWHM1 and FWHM2, valid for
                            IDET=1 or 2)

are  the  Full-Width-at-Half-Maximum     of     the    wavelength
distribution function  for the  first (second)  data set.  FWHM=0
means  monochromatic  radiation.   If  IDET=2  (2D-detector),   a
possibility  of  submitting  an  arbitrary  wavelength profile is
forseen. To this end, one should specify FWHM=0, and the  program
will try  to read  the wavelength  profile from  the beam profile
file  (SPOT1  and/or  SPOT2),  assuming  that it follows the beam
profile. If the wavelength  profile is not present  monochromatic
radiation is assumed.

***  Beam divergency in 1D-case (parameters AH1, AH2, AW1, AW2,
                    LH1, LH2, LW1, LW2, valid for IDET=2 )

In 1D-case,  a rectangular  slit geometry   is assumed,  with the
slit-height  parameters AH - projection  of the beam  height   in
the  detector  plane,  and   AL  - heigth of the detector   slit,
and  similar  slit-width   parameters AW and LW.  Therefore,  the
beam  profile  is  assumed  to  be a trapezoidal function

         < ----- (A-L) ----- >
         * * * * * * * * * * *
        *                     *
       *                       *
      *                         *
     *                           *
    < ---------- (A+L) ----------->

both in the direction perpendicular and parallel to the alignment
of the detector.  In the former  case (slit-height effect)  A=AH,
L=LH;  in  the  latter  case  (slit-width effect) A=AW, L=LW. The
units of AH, LH,  AW, LW are to  be the same as  for the momentum

*** Beam profile files (parameters SPOT1 and SPOT2, valid for

To describe the beam divergency  in the 2D-case  the  used should
specify  the   file    containing  the   "spot  function",   i.e.
distribution of the  primary beam   intensity in the  2D-detector
plane  (without   sample),  measured    with the given  geometry.
The function   is assumed  to be  a square  matrix, stored  in  a
separate file.

The file structure:

1st line           :NB - number of rows (and columns) in the beam
                    TRANS - the factor relating the resolution of
                    the beam profile (detector step, DetSt)
                    and the angular step in the experimental curve
                    (DeltaS), TRANS=DetSt/DeltaS. By default, TRANS=1,
                    i.e. it is assumed that the angular step is equal
                    to the distance between two channels in the beam
                    NB and TRANS can be written in the free
                    format separated by blanks or commas (NB is
                    compulsory parameter, TRANS - auxiliary). A comment
                    can be added after TRANS (of NBEAM if TRANS is not

2nd-(NB+1)st lines : each containing NB numbers, separated by blanks
                     or commas - beam profile.

The beam  profile is  used to  evaluate the  smearing due to beam
divergency  assuming  that  the  curve  is obtained by a circular
average. Circularly  averaged and  normalized profile  is used to
this end. Additional  smearing due to  the radial average  of the
2D-data  is  assumed  to  be one unit in the detector profile.

If FWHM = 0 (see above), then an arbitrary wavelength profile
could be specified after the beam profile in the following way:

(NB+2)nd line :     :comment
(NB+3)rd line :     :NW   - number of points in the wavelength profile;
                     WL1  - starting wavelength;
                     DLAM - wavelength increment
                     (all the three parameters are compulsory)
(NB+4)th etc        :wavelength profile (NW values in arbitrary

If  FWHM  =  0  and  the  wavelength profile is not submitted (or
improperly specified), no wavelength smearing is included.

  7   1.5   Beam profile: Detector step=1.5*Delta(s) in the input file
      0.     1.     4.     5.     4.     1.     0.
      1.    45.   143.   211.   143.    45.     1.
      4.   143.   460.   678.   460.   143.     4.
      5.   211.   678.  1000.   678.   211.     5.
      4.   143.   460.   678.   460.   143.     4.
      1.    45.   143.   211.   143.    45.     1.
      0.     1.     4.     5.     4.     1.     0.
Wavelength profile (will be read in if FWHM=0 has been specified)
27, 4.59, 0.01106
0.00,  30.36, 68.16, 175.4, 236.1, 240.3, 200.3, 174.7,
139.2, 113.9, 112.4, 115.9, 109.3, 87.42, 65.51, 76.43,
116.7, 125.7, 128.0, 106.9, 80.50, 62.44, 48.11, 49.16,
43.41, 28.76, 0.

If instrumental  distortions (especially  all of  them)  present,
the evaluation of the  design matrix may become  a time-consuming
procedure.   When making  successive computations  with the  same
experimental conditions and real  space limitations, one can  use
the same integral kernel, if it has been already calculated.  For
this, one should answer 'Y' when prompted 'Is the kernel  already
evaluated  [N]?'  (parameter  LKERN),  and  enter  after  it  the
kernel-storage file name.

The  program  can  handle  simultaneously  two  runs  recorded at
different (or the same) experimental conditions. The user  should
then supply two  separate experimental data  files (first -  with
lower  s  range;  however,  the  ranges  may overlap) and specify
explicitly  two  sets  of  experimental  conditions.  The   scale
factor  for  the  second  run (parameter COEF)  is  evaluated  by
the program automatically [6].

			Regularization parameter

The main question,  typical  for  solving ill-posed problems   is
how  to  stabilize  the  solution  properly  (here: how to find a
positive regularization parameter ALPHA, which demands smoothness
of the solution). The larger ALPHA, the more attention is paid to
the  smoothness  of  the  distribution  function  and  the   less
attention - to fitting the experimental data.

This  search  was   done  in  the   earlier GNOM versions by  the
generalized discrepancy method [7] using sucsessive  calculations
with different  ALPHA values.    The  ALPHA was  chosen so  as to
fulfil the well-known Chi-square criterion: the sum of deviations
of the smeared intensity, corresponding to the given ALPHA,  from
the experimantal values,  weighted with the  standard deviations,
should be equal to 1 +  AN1. Here the value of AN1  is calculated
by the program and represents  the degree of unconformity of  the
problem (it equals to zero  if NS=NR and increases with the ratio
NS/NR). If AN1  is too large  (AN1 > 1)  the warning is  printed.
This warning, in princilpe, means that the input  data/parameters
are  to  be  checked;  however,  it  does  not  hinder  followins

The discrepancy   criterion alone,   however, in   many cases can
not ensure the correctness  of the solution. Standart  deviations
may not  be known  or may  be wrong.  Another criterion which can
also be  used is  the stability  of the  solution with respect to
changing ALPHA.  It can  serve for  manual [1],  or automatic [5]
search, but sometimes fails as well.

                        Perceptual criteria

In  the  EN.N   versions the  computer   is  instructed to get  a
plausible  solution  basing  on   several  criteria,  like    its
smoothness,  stability,  absence  of  systematic deviations, etc.
Some of them are to be fulfilled by increasing ALPHA, the  others
- by its decreasing. A compromise  is to be found. It is  done as

Each  criterion   is  expressed   mathematically.  For   a  given
solution one calculates the  value of the criterion  and compares
with its "ideal" value. All estimates of the parameters have  the
form of Gaussians

           P(i) = EXP ( - [(A(i) - B(i))/SIGMA(i)]**2 )

     where  A(i) - expected ("ideal") value of the criterion
            B(i) - its actual value,
        SIGMA(i) - width of the distribution (FWHM/1.665)

(values A(i) and SIGMA(i) are specified a priori). Then the total
estimate is calculated as

       TOTAL =  P = SUM ( P(i) * W(i) ) / SUM (W(i))

where   W(i)  -  weight  of  the  given  criterion  (also fixed).
Therefore,  all  P(i)  and  P  are  between  0 and 1. The program
searches for a maximum of the total estimate P.

The following criteria are used for estimates:

DISCRP --- CHI-square test in reciprocal space (using the
           specified standard deviations. If they are correct,
	   should be slightly less than 1 (ideal value is taken as
	   0.7). Increases with ALPHA.

OSCILL --- shows the smoothness of the solution.
           Evaluated as the ratio ||dp/dr|| / ||p|| related to this
           ratio for a monomodal sine function. Decreases with ALPHA.
	   Ideal value 1.1 (for a characteristic function of a uniform
	   sphere). Here || || denotes the function norm.

STABIL --- shows stability of the solution with respect
           to the change of ALPHA. Calculated as d(ln||p||)/d(ln(ALPHA))
	   Ideal value 0.

SYSDEV --- indicates the presence of systematic deviations
           of the restored (smeared) curve Ires(s) from the experimetnal
	   data Iexp(s). Calculated as N1 / (N/2), where  N is the number
	   of experimental points, N1 - number of changing sign of the
	   difference (Iexp - Ires). Ideal value 1. Important parameter
	   (unless you suspect your data contain systematic deviations).
	   Increases with ALPHA.

POSITV --- relative norm of positive part of p(r).
           Ideal value, of course, 1.

VALCEN --- indicates validity of the chosen interval in
           real space (relative norm of the central part of p(r) ).
           Ideal value tends to 1 (0.95 for a sphere).
	   Much less than 1 if your interval is too wide.

The user  is asked  to enter  the ALPHA  value. If  this value is
already known to the user (e.g., from previous calculations  with
similar data), he can type the negative ALPHA, then the  solution
with  -(ALPHA)  will  be   evaluated.  A  positive  ALPHA   means
automatic search  of ALPHA  by maximizing  the total  estimate as
described below; no further  manual refinement is possible  (this
is convenient for  using GNOM in  the batch mode).   Default case
(ALPHA=0) means   automatic search  accompanied   by   a  graphic
representation  (plot  lg(ALPHA)  vs TOTAL). This plot would help
the  user  to  correct  ALPHA     manually  in the cases when the
automatic search breaks down (see Practical advises).

The search of  ALPHA works as   follows. First the  program finds
the  theoretical  maximum  (Highest)  ALPHA  value  for the given
problem  [7]  (in  graphic  representation  the  Y-axis  is drawn
through  this  value).  Then   it  tries  to  maximze  the  total
estimate with  the given  set   of A(i),  SIGMA(i) and  W(i). The
default set is

 Weight        1.000     3.000     3.000     3.000     1.000     1.000
 Sigma          .300      .600      .120      .120      .120      .120
 Ideal          .700     1.100      .000     1.000     1.000      .950

(here parameters OSCILL, STABIL and SYSDEV are considered to be
most important).

The program  evaluates first  the grid  of the  TOTAL values  for
ALPHA  <  1000*Highest  ALPHA  (indicated  as open circles in the
plot). Then the  golden section search  is performed to  maximize
the estimate (characters '+' on the plot).

NOTE: when OSCILL  is  too large while SYSDEV already  reasonable
(here: OSCILL>13,  SYSDEV>0.5), the   value of  TOTAL is  put  to
zero.   If  zero  value   is  encountered,   the  program   stops
evaluating  the  grid.  This  is  made  in order to avoid useless
computations for too small ALPHA values.

After the solution  is found, the  user may either  accept it, or
change the weight/width of distribution for any criterion, or try
to get a new maximum estimate, or change the ALPHA manually. When
you increase the distribution width for a given parameter, larger
deviations  from  the  expected  values  are  allowed  for   this
parameter. When you increase the weight of a parameter, it  plays
a  more  significaht   role  in   the  estimate,   therefore  the
solution maximizing   the    estimate  will    be   shifted    to
fulfil     the  corresponding  criterion.  The  changed  set   of
parameters can be  stored onto an  ASCII disk file  and then used
again for  a similar  object by  entering its  name when prompted
'File containing expert  parameters' (parameter EXPERT).  In this
file  user  may   also  edit  all  the  values (including "ideal"

The solution can  also be plotted  on the screen.   The intensity
plot  presents  together  the  experimental data (astericks), the
desmeared (solid)  curve and  the corresponding  smeared (dotted)
curve.  Note that for the cases JOB = 3, 4 and 5 the experimental
curves are modified.   Namely, for JOB=3,  I(s) is multiplied  by
s**2,    for    JOB=4    by    s,    for    JOB=5    divided   by
(2*J1(s*RAD56)/s*RAD56)**2  (the  latter  is  the   cross-section
factor  of  a  cylinder,   J1(x)  Bessel  function   of  the 1-st
order).  These modified curves are  are plotted and  printed onto
the output file.

The  distribution  plot  shows  the  obtained correlation or size
distribution  function.  Radius  of   gyration  and  zero   angle
intensity  are  also  evaluated  in  real  space  using  the p(r)
function. Note  that for  the case  JOB=2 the  values in real and
reciprocal space may not coincide, because I(0) will be evaluated
as  the  NDIM-th  moment  of  D(R),  and  Rg  as  sqrt((NDIM+2)th

			Error estimates

After   the   soluton   is   accepted by  the user,   the  errors
propagation   can  be  estimated.  This  is  made via a series of
Monte-Carlo  simulations.  The  standard deviations  in the  p(r)
function as  well   as in  the radius  of gyration and zero-angle
intensity are evaluated. The random sequence is initiated by  the
four-digit  value  of  current  time  (min:sec), so that slightly
different values of error  estimates are obtained on  exactly the
same data set (the number of Monte-Carlo generations is 100).

Note: the Monte-Carlo routines were rewritten for the versions
      E3.3 and then 4.1 therefore some differences may also
      exist between the results of different versions.


Graphic routines in the program use GKS or GHOST-80 (VMS or UNIX
versions), MS-Fortran 5.1 graphic package (MS-DOS version). The
possibility to use the public domain Gnuplot package also exists
for UNIX version.

  ---  GKS graphics ---

If you use  DEC GKS assign  your used workstation  to the logical
GKS$CONID and the workstation type to GKS$WSTYPE. (See HELP GKS)

If you want to use GNOM  with  other than DEC GKS  implementation
you  have  to  specify  some  or  all  of  the  elements  of   an
configuration matrix stored in a configuration file.   The  users
of  a  GKS  implementation  are  free  to chose LUNs, CONIDs, and
WSTYPEs. Some implementations make  a difference between the  LUN
of  a  FORTRAN  open  statement  and  the  CONID  of  a  GKS open
workstation statement.

Empty matrix elements are not used.

LUN    - logical unit number
CONID  - connection identifier
WSTYPE - workstation type

                          | LUN      | CONID    | WSTYPE
  Error log file          | cfg(1,1) |          |
  Workstation independent |          |          |
    segment storage       |          | cfg(2,2) | cfg(3,2)
  Used workstation        |          | cfg(2,3) | cfg(3,3)
  GKS metafile output     |          |          |
    workstation           | cfg(1,4) | cfg(2,4) | cfg(3,4)
  TEKTRONIX 4010/4014     |          |          |
    workstation           |          |          | cfg(3,5)


                          | LUN      | CONID    | WSTYPE
  Error log file          | 6 *)     | 0        | 0
  Workstation independend |          |          |
    segment storage       | 0        | 0        | 3
  Used workstation        | 0        | 6 *)     | -101 **)
  GKS metafile output     |          |          |
    workstation           | 100      | 100      | 4
  TEKTRONIX 4010/4014     |          |          |
    workstation           | 0        | 0        | 101

    *) standard FORTRAN output unit

   **) or assign -101 to logical GKS$WSTYPE.
       If you use a TEKTRONIX terminal with VT220 compatible mode or
       vice versa the program switches automatically between both modes by
       specifying the minus sign.

Assign  the  configuration  file  specification  to  the  logical

Separate the fifteen integers in this file at least by one blank.
For example, the GTS-GRAL GO_CONFIGURATION file is:

6 0 0 0 0  3 0 6 -101 100 100 4 0 0 101

Optionally,  the  plots  can  be  saved in the device-independent
form and then  reproduced on  other terminal  or device.  To this
end, user  should enter  a   non-blank file  name when   prompted
"Metafile name [none]:". This metafile has the default  extension
.GKSM  and can  afterwards  be  processed  by  the dialogue  GKSM
interpreter (file    GMI.EXE), which either   shows the  metafile
on  the  screen,  or   prepares   device-dependent   file    with
extension .LIS to  be printed   on   an   output   device   (line
printer, laser  printer, plotter).

If  you  use  the  GKS  metafile  interpreter  with  a  DEC   GKS
implementation assign  .FALSE. to  the logical  GMI_CONFIGURATION
otherwise .TRUE.

The low-level graphic calls  to GKS and the  GKSM-interpreter are
written  by  O.Kuehnholz   (GKSS  Research  Center,   Geesthacht,

  ---  GHOST-80 graphics  ---

It  uses  the  pure  Tektronix  emulation  (linked with T4010 and
GRIDPLUS). The output  to the grid  file is similar  the metafile
output for  GKS.   The default  extenstion for  the grid  file is

  ---  MS-Fortran graphics  ---

CGA, EGA, VGA, Olivetti and Hercules adapters are suppotred  (for
the latter case, one should first run the file MSHERC.COM ).  The
font file COURB.FON  from the MS-Fortran distribution package  is
assumed to  be either in the working directory, or in the c:\, or
in c:\fortran\lib\  directory.  If the file is not found, no text
will appear in graphic mode.

The build-in PrintScreen facility  does  NOT  require preliminary
loading  of  the   DOS  GRAPHICS.  It  supports 9-pin and  24-pin
Epson-compatible   dot   matrix   printers,   as   well   as  any
HP-compatible  printer  recognizing  HP  PCL  commands  (HP Laser
Jet,   Desk Jet,  etc ). The use  of the dump  screen routines is
regulated by the parameter  PRINTER (valid printers are  EPSON09,
EPSON24  and  HPPCL).   If  your  printer  is NOT compatible with
either Epson or HP,  use standard DOS PrintScreen  (then GRAPHICS
is necessary).

Note: after PrintScreen, no command "Eject" is send. The page  is
to be  ejected manually.  This allows  in some  cases, e.g.  when
printing with HP printers on DIN  A4 paper, to have two plots  on
one page.

---   Gnuplot graphics (UNIX version)  ---

On UNIX machines, a possibility  exists to use the public  domain
Gnuplot graphic package. It is used not as a separate interactive
program, but  as a  graphic library.  GNOM creates  a sequence of
data/command files in the /tmp directory which are then  executed
by Gnuplot.  To use  Gnuplot version  of GNOM,  the following  is

i)  Gnuplot  version  3.0  and  higher  must be installed and the
gnuplot executables should be in the PATH variable.

ii) Environment vagiable GNUTERM  has to be defined  according to
the Gnuplot conventions.  If GNUTERM is  not defined, no  graphic
output is produced.

iii)  If  the  environment  variable    GNUPRINT is defined, GNOM
captures each  plot in  the format  of this  printer onto a fixed
disk file named /tmp/gnu-capture. This is made after the plot  is
viewed and CR is pressed. Note that this file will be OVERWRITTEN
by the next screen capture, therefore, if the user wishes to have
a hardcopy, the  file has to  be sent to  the printer or  renamed
BEFORE  pressing  CR  after  viewing  the  NEXT  plot. After GNOM
finishes, the file /tmp/gnu-capture contains the LAST plot.  Note
also that  the GNOM  variable PRINTER  is yet  dummy in  the UNIX
version. If   GNUPRINT  is not defined,  GNOM produces no  screen



%setenv GNUTERM x11
%setenv GNUPRINT postscript

if you run GNOM in a X-window environment and want an
output for the postscript printer.


%setenv GNUTERM vttek
%setenv GNUPRINT hpljii

if you run GNOM on a VT-Tektronix emulation and want
an output for the HP-Laserjet series II.

For a detailed description of the supported terminals and
printers, type 'set term' inside Gnuplot.

                      Next job

After the job is finished, the  user is asked whether to run  the
program  again  (parameter  NEXTJOB).  Answering  "No"  stops the
program. "Yes" means new job. "Same" means that the new data  set
will be calculated under the same conditions as the previous  one
(with the same integral kernel).

                      On-line help

Answering  a  question  mark  '?'  followed  by  'Enter'  to each
question allows to get a short help on the parameter.

                       Configuration file

Some  or  all  of  the  parameters  used  by  the  program can be
specified in the configuration  file named 'gnom.cfg'. The  first
line of the file is always treated as a comment. The structure of
a valid information line is shown below:

  1-7   9    Between brackets               Comment
 NAME  Type     Value
PRINTER C [      HPPCL       ]  Printer type

Here NAME is the name of the parameter (all names are fixed),
the letter in the 9-th column shows the type of the parameter:
(C - character, I - integer, R - real). The value of the
parameter is to be put between the square brackets (not more than
35 characters). If the line is not valid (e.g., ] is missing, or
the parameter name is wrong), it is skipped and the warning is printed.

When  GNOM  is  started,  it  first  tries  to  find and read the
configuration file in  the current directory.  If the local  file
named 'gnom.cfg'  does not  exist, it  tries to  read the  global
configuration file :

   On  IBM-PC, it is always the file 'c:\gnom\gnom.cfg'

   On VAX, it is  'GNOCFG:gnom.cfg', where the logical GNOCFG
   defines the directory. Example: if the command


   is issued, the global file will be searched in the user's
   login directory.

   On UNIX machines, it is 'GNOCFGgnom.cfg', where GNOCFG is an
   environment variable. Example: if the command

   %setenv GNOCFG /usr/local/include/

   is given , the global configuration file is

If GNOM finds a non-blank value between the square brackets for a
parameter in the configuration file, this parameter is assumed to
be  already  defined,   therefore,  it  will   NOT  be   prompted
interactively (the other parameters will be asked as usual).  The
read-in configuration table is printed on the screen ( ...  means
that the variable is not defined). The user can either accept the
values  or  switch  to  the  interactive  mode.  GNOM assumes the
interactive mode also when neither local nor global configuration
file has been found.

Specific values for some parameters :

   Zero values of the parameters NREAL and COEF mean
   that the values evaluated by the program will be accepted.

   For the EXPERT and INPUT2, 'none' means NO file.

   As UNIX is case-sensitive, be careful with the file names in
   the configuration file for the UNIX version.

   For IDET=2, if FWHM1/FWHM2 are equal to zero, GNOM will try to
   find the wavelength distribution function after the beam
   profile in the corresponding SPOT1/SPOT2 file.

The  example  of  the  global  configuration file is shown below.
In this  file only  a few  variables are  fixed, and  the program
will not ask for them.  More specific configuration files can  be
put in the local working  directories. They can be configured  in
such a way,  that the program  will ask only  a few questions  or
even run in the batch  mode. Examples of the local  configuration
files can be found in the distribution package.

General configuration file
PRINTER C [      HPPCL       ]  Printer type
FORFAC  C [                  ]  Form factor file (valid for JOB=2)
EXPERT  C [     none         ]  File containing expert parameters
INPUT1  C [                  ]  Input file name (first file)
INPUT2  C [                  ]  Input file name (second file)
OUTPUT  C [                  ]  Output file
PLOINP  C [       y          ]  Plotting flag: input data (Y/N)
PLORES  C [       y          ]  Plotting flag: results    (Y/N)
EVAERR  C [                  ]  Error flags: calculate errors   (Y/N)
PLOERR  C [       y          ]  Plotting flag: p(r) with errors (Y/N)
LKERN   C [                  ]  Kernel file status (Y/N)
JOBTYP  I [                  ]  Type of system (0/1/2/3/4/5/6)
RMIN    R [                  ]  Rmin for evaluating p(r)
RMAX    R [                  ]  Rmax for evaluating p(r)
LZRMIN  C [                  ]  Zero condition at r=rmin (Y/N)
LZRMAX  C [                  ]  Zero condition at r=rmax (Y/N)
KERNEL  C [                  ]  Kernel-storage file
DEVIAT  R [      0.0         ]  Default input errors level
IDET    I [                  ]  Experimental set up (0/1/2)
FWHM1   R [                  ]  FWHM for 1st run
FWHM2   R [                  ]  FWHM for 2nd run
AH1     R [                  ]  Slit-height parameter AH (first  run)
LH1     R [                  ]  Slit-height parameter LH (first  run)
AW1     R [                  ]  Slit-width  parameter AW (first  run)
LW1     R [                  ]  Slit-width  parameter LW (first  run)
AH2     R [                  ]  Slit-height parameter AH (second run)
LH2     R [                  ]  Slit-height parameter LH (second run)
AW2     R [                  ]  Slit-width  parameter AW (second run)
LW2     R [                  ]  Slit-width  parameter LW (second run)
SPOT1   C [                  ]  Beam profile file (first run)
SPOT2   C [                  ]  Beam profile file (second run)
ALPHA   R [      0.0         ]  Initial ALPHA
NREAL   R [       0          ]  Number of points in real space
COEF    R [                  ]
RAD56   R [                  ]  Radius/thickness (valid for JOB=5,6)
NEXTJOB C [                  ]

The  configuration   file  may   contain  arbitrary   number   of
parameters.  Not  all  of  them  have  to appear in the file: the
missing  parameters  will  be  treated  as  non-defined.  It   is
advisable,  however,  to  end  the  configuration  file  with the
NEXTJOB parameter. If NEXTJOB is 'Y' or 'S', the next lines  will
describe the parameters for the new job, and so on. The last line
in this case should be:

NEXTJOB C [ N ]   Ends the program

If you run the NEXTJOB, GNOM keeps the values which were used in
the previous job as program defaults (for character variables it
is true if the number of characters does not exceed 12).

Example: using the general configuration file shown above, the
default output file will be 'gnom.out' (program default); if you
enter another name, say,'mygnom.out' and then answer "Y" to the
NEXTJOB question, default output file will be 'mygnom.out'.

                         Practical advises

This chapter has arisen as a result of practical applications  of
GNOM and is based mainly on the typical user questions.

GNOM is intended to be as user-friendly as possible, that is,  it
normally  runs  OK  using  the  default  answers.  In particular,
default  value  of  the  number  of  real  space points is highly
recommended to use.

The units in real and reciprocal space must be reciprocal to each
other.  Thus,  if  the  momentum  transfer is given in reciprocal
angstroms (lambda in angstroms), the particle sizes in real space
are to be specified also in angstroms. If you want particle sizes
in miles,  the input  file has  to contain  momentum transfer  in
reciprocal miles.  The units  of the  parameters describing  beam
divergency should be the same as for the momentum transfer.

All the weighting functions are normalized so that the  desmeared
curve is on the same scale as the smeared one. In parcitular,  as
the  wavelength  effects  are  always  relative,  the  wavelength
distribution gets reduced to Lambda=1.  This does not mean   that
the  program  works  only   for  this  wavelength,  because   the
wavelength information is already contained in the s-units.

One more thing about the wavelength effects: in X-ray experiments
with the  conventional sources  (X-ray tubes)  they are  normally

The rectangular  slit geometry  assumed for  the 1D-detectors  is
normally a good approximation  for practical applications. It  is
valid, of  course, both  for linear  multi-channel detectors  and
single  channel  moving  detectors.  Note  that  the  slit-height
function, if non-symmetric, can  be symmetriezed, because of  the
properties  of  the  slit-smearing  integral.  Asymmetries in the
slit-width  function,  if  exist,   can  be  neglected,  as   the
slit-width effects  are normally  small. The  case of "infinitely
long slit" can be covered, e.g., by putting AH=Smax, LH=0,  where
Smax is the momentum transfer of the last data point. For a  more
detailed description  of the  smearing effects  see, e.g. Ref[0],

If  you  specify  the  maximum  size  so that Dmax*Smin (Smin the
momentum  transfer  of  the  first  data  point)  is greater than
Pi=3.1416926,  a   warning  is   printed.  This  means  that  the
first data  point is  beyond the  first sampling  point and   the
information content may  be not sufficient  to obtain a  reliable
solution.  However,  the  warning  does  not  hinder  the progran

Default settings of the Expert parameters are also valid for  the
most of "normal" systems. However, in some cases it is  advisable
to change the default set  in order to ensure reliable  automatic
search of ALPHA. Typical examples are:

--  If you do not know standard deviations in the experimental
    data, put the weight of DISCRP to zero.

--  If you suspect that your distribution function is
    non-monomodal, put the ideal value of OSCILL to M, where M is
    the number of modes. For example, if you expect to have a
    bimodal size distribution function (JOB=1), put OSCILL=2.

--  If the distribution function can show negative peaks
    (say, X-ray scattering from lipoproteins in water, JOB=0),
    put the weight of POSITV to zero (and OSCILL is better to put
    to 2 or 3, as in previous example).

The program may fail to  evaluate the constant for the second run
in   the   trivial   case   with   no   smearing  because of poor
stability of the design matrix in this case. The users are kindly
asked to correct the value manually.

The program explores the range

   (10**3 * Hightest ALPHA) > ALPHA > (10**(-18) * Highest ALPHA)

to maximize the estimate. If the total estimate is monotonous  in
this range, the  warning is printed.  In such cases  the user can
perform  manual  search,  or  restart  the  maximization from the
current  point.  Important:  normally,  the   plausible  range of
ALPHAs is approximately 10E-6 * (Hihgest ALPHA).

If the solution  found by the  program is by  far not acceptable,
this just means that  the maximization procedure (golden  section
search in logarithmic ALPHA scale) is trapped by a local minimum.
One   can    restart   the    maximization   from  an  ALPHA in a
"plausible" range.

Another reason of  getting a non-acceptable  solution could be  a
non-consistency of the data and the assumptions. In this case the
user will  get the  warning about  AN1 and,  normally, rather low
value   of  the  maximum  estimate.

By   default,   the      program   puts p(rmin)=0, p(rmax)=0.  If
these conditions are not applied,  non-zero  p(r)'s can exist  at
the ends of the real space interval. Sometimes by p(0)   one  can
take a  constant background into account (note   that   for JOB=3
p(0)    is   normally non-zero). If you do not know Dmax,   it is
better first not to fix p(rmax), because this value will help  to
judge whether the chosen interval is correct  (if,  for  example,
rmax is too small, p(r) is systematically higher than zero in the
vicinity of rmax).

Model  calculations  show  that   the  evaluation  of  the   size
distribution function  of cylinders  (JOB=5) is  a very ill-posed
problem, because  the scattering  curves from  long cylinders are
rather flat and it is not so easy to distinguish between them  in
the scattering curve, as e.g. for polydisperse system of spheres.
Therefore  for  JOB=5   it  is  very   important  to  have   good
measurements  in  the  beginning  of  the  scattering curve where
scattering   from   cylinders   of   different   length   differs
significantly from each other.

                Hardware and software requirements

 ---   IBM-PC   ---

 MS-DOS version 2.1 and higher (DOS 5.0 is recommended).
 Minimum 468Kbytes RAM and 512KBytes free disk space.
 CGA, EGA, VGA, GVGA, ATT or Hercules graphic board.
 A 8087/287/387/487 mathematical co-processor.

---   VAX-VMS   ---

GKS implemebtation level not less than 2b, or
GHOST graphics with Tektronix emulation

---   UNIX      ---

GKS implemebtation level not less than 2b, or
GHOST graphics with Tektronix emulation,   or
Gnuplot public domain graphic package version
3.0 and higher.


     0. Feigin L.A. & Svergun D.I. (1987). Structure Analysis by
        Small-Angle X-Ray and Neutron Scattering. NY: Plenum

     1. Glatter O. (1977). J.Appl.Cryst., 10, 415-421

     2. Moore P.B. (1980). J.Appl.Cryst., 13, 168-175

     3. Provencher S.W. (1982). Computer Phys.Commun., 27,
        213-227, 229-242

     4. Svergun D.I., Semenyuk A.V. (1987). Doklady AN SSSR, 297,
        1373-1377 (in Russian)

     5. Svergun D.I., Semenyuk A.V., Feigin L.A. (1988). Acta Cryst.,
        A44, 244-250

     6. Svergun D.I. (1991). J.Appl.Cryst., 24, 485-492

     7. Tikhonov A.N., Arsenin V.Ya. (1977). Solution of Ill-Posed
        Problems. NY: Wiley

     8. Tikhonov A.N., Goncharsky A.V., Stepanov V.V., Yagola A.G.
        (1983). Regularizing Algorithms and a priory Information.
        Moscow: Nauka, (in Russian)

     9. Svergun D.I. (1992). J. Appl. Cryst., 25, 495-503.

Web document produced by Roland May, ILL Grenoble (last update: 26-Jan-2000)