More documentation

4 files changed, 106 insertions, 0 deletions

diff --git a/README b/README
index 86b5ce10..79d16288 100644
--- a/README
+++ b/README
@@ -88,3 +88,26 @@ coordinate system is formed using these definitions, CrystFEL will consider the
 positive z direction to point towards the source of the incident beam.
 
 The detector surface is assumed to be perpendicular to the incident beam.
+
+
+Program name
+------------
+
+There seems to be a tendency to capitalise the names of programs in
+publications.  It's not 1970 any more, and programs can have capitalisation
+any way we choose, not just all capitals.  I hope you can forgive me for being
+fussy about how my work is referred to in publications and talks.
+
+The name for the overall software suite is "CrystFEL", with this being the only
+acceptable capitalisation.  The individual programs should always be referred to
+with all letters in lower case, exactly as written earlier in this file.
+
+In most cases, it will be more appropriate to refer to the overall suite than to
+one of its constituent programs.
+
+The following are NOT acceptable forms: "CRYSTFEL", "crystFEL", "Crystfel",
+"Indexamajig", "INDEXAMAJIG", "PATTERN_SIM", "Pattern_Sim", "Pattern_sim".
+
+In addition, CrystFEL is made up of "programs", not "routines" nor "procedures".
+(The "programs" in turn are made up from "routines" and "procedures", but unless
+you are exploring the source code, there's no need for you to know about that).
diff --git a/doc/indexamajig b/doc/indexamajig
new file mode 100644
index 00000000..7d6e0d16
--- /dev/null
+++ b/doc/indexamajig
@@ -0,0 +1,83 @@
+indexmajig - bulk indexing and data reduction program
+-----------------------------------------------------
+
+The indexamajig program takes as input a list of diffraction image files,
+currently in HDF5 format.  For each image, it attempts to find peaks and then
+index the pattern.  If successful, it will measure the intensities of the peaks
+at Bragg locations and produce a list in the form "h k l I", with some extra
+information about the locations of the peaks.
+
+For minimal basic use, you need to provide the list of diffraction patterns,
+the method which will be used to index (currently there is only one available
+method), a file describing the geometry of the detector, and a PDB file which
+contains the unit cell which will be used for the indexing.
+
+Syntax: src/indexamajig [options]
+
+Process and index FEL diffraction images.
+
+  -h, --help              Display this help message.
+
+  -i, --input=<filename>  Specify file containing list of images to process.
+                           '-' means stdin, which is the default.
+
+      --indexing=<method> Use 'method' for indexing.  Choose from:
+                           none     : no indexing
+                           dirax    : invoke DirAx
+  -g. --geometry=<file>   Get detector geometry from file.
+
+
+With just the above options, this program does not do much of practical use.
+You should also enable some of the following:
+
+      --near-bragg        Output a list of reflection intensities to stdout.
+                           When pixels with fractional indices within 0.1 of
+                           integer values (the Bragg condition) are found,
+                           the integral of pixels within a ten pixel radius
+                           of the nearest-to-Bragg pixel will be reported as
+                           the intensity.  The centroid of the pixels will
+                           be given as the coordinates, as well as the h,k,l
+                           (integer) indices of the reflection.  If a peak
+                           was located by the initial peak search close to
+                           the "near Bragg" location, its coordinates will
+                           be taken as the centre instead.
+      --simulate          Simulate the diffraction pattern using the indexed
+                           unit cell.  The simulated pattern will be saved
+                           as "simulated.h5".  You can TRY to combine this
+                           with "-j <n>" with n greater than 1, but it's
+                           not a good idea.
+      --filter-cm         Perform common-mode noise subtraction on images
+                           before proceeding.  Intensities will be extracted
+                           from the image as it is after this processing.
+      --filter-noise      Apply an aggressive noise filter which sets all
+                           pixels in each 3x3 region to zero if any of them
+                           have negative values.  Intensity measurement will
+                           be performed on the image as it was before this.
+      --write-drx         Write 'xfel.drx' for visualisation of reciprocal
+                           space.  Implied by any indexing method other than
+                           'none'.  Beware: the units in this file are
+                           reciprocal Angstroms.
+      --dump-peaks        Write the results of the peak search to stdout.
+                           The intensities in this list are from the
+                           centroid/integration procedure.
+      --no-match          Don't attempt to match the indexed cell to the
+                           model, just proceed with the one generated by the
+                           auto-indexing procedure.
+      --unpolarized       Don't correct for the polarisation of the X-rays.
+      --check-sanity      Check that indexed locations approximately correspond
+                           with detected peaks.
+
+
+Options for greater performance or verbosity:
+
+      --verbose           Be verbose about indexing.
+      --gpu               Use the GPU to speed up the simulation.
+  -j <n>                  Run <n> analyses in parallel.  Default 1.
+
+
+Control of model and data input:
+
+     --intensities=<file> Specify file containing reflection intensities
+                           to use when simulating.
+ -p, --pdb=<file>         PDB file from which to get the unit cell to match.
+ -x, --prefix=<p>         Prefix filenames from input file with 'p'.
diff --git a/doc/pattern_sim b/doc/pattern_sim
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/doc/pattern_sim
diff --git a/doc/process_hkl b/doc/process_hkl
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/doc/process_hkl