More documentation stuff

7 files changed, 124 insertions, 47 deletions

diff --git a/.gitignore b/.gitignore
index b5243bc9..106acb13 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,26 +24,4 @@ src/sum_stack
 src/geomatic
 src/.dirstamp
 *~
-doc/reference/.args
-doc/reference/.hierarchy
-doc/reference/.interfaces
-doc/reference/.prerequisites
-doc/reference/.signals
-doc/reference/CrystFEL-decl-list.txt
-doc/reference/CrystFEL-decl.txt
-doc/reference/CrystFEL-overrides.txt
-doc/reference/CrystFEL-undeclared.txt
-doc/reference/CrystFEL-undocumented.txt
-doc/reference/CrystFEL-unused.txt
-doc/reference/CrystFEL.args
-doc/reference/CrystFEL.hierarchy
-doc/reference/CrystFEL.interfaces
-doc/reference/CrystFEL.prerequisites
-doc/reference/CrystFEL.signals
-doc/reference/html-build.stamp
-doc/reference/html.stamp
-doc/reference/html/
-doc/reference/scan-build.stamp
-doc/reference/sgml-build.stamp
-doc/reference/sgml.stamp
-doc/reference/xml/
+doc/reference/*
diff --git a/configure b/configure
index b6ae88a3..3aa76df7 100755
--- a/configure
+++ b/configure
@@ -1489,7 +1489,7 @@ Optional Features:
   --disable-tiff          Disable the use of libTIFF
   --disable-cairo         Disable the use of Cairo
   --disable-gdk-pixbuf    Disable the use of gtk-pixbuf
-  --enable-gtk-doc        use gtk-doc to build documentation [[default=no]]
+  --enable-gtk-doc        use gtk-doc to build documentation [[default=yes]]
   --enable-gtk-doc-html   build documentation in html format [[default=yes]]
   --enable-gtk-doc-pdf    build documentation in pdf format [[default=no]]
 
@@ -7723,7 +7723,7 @@ fi
 if test "${enable_gtk_doc+set}" = set; then :
   enableval=$enable_gtk_doc;
 else
-  enable_gtk_doc=no
+  enable_gtk_doc=yes
 fi
 
 
diff --git a/doc/indexamajig.txt b/doc/indexamajig.txt
index a7cac95f..c7097851 100644
--- a/doc/indexamajig.txt
+++ b/doc/indexamajig.txt
@@ -59,7 +59,11 @@ You can control what information is included in the output stream using
 
 So, if you just want the integrated intensities of indexed peaks, use
 "--record=integrated".  If you just want to check that the peak detection is
-working, used "--record=peaks".
+working, used "--record=peaks".  If you want the integrated peaks for the
+indexable patterns, but also want to check the peak detection for the patterns
+which could not be indexed, you might use
+"--record=integrated,peaksifnotindexed" and then use "check-peak-detection" from
+the "scripts" folder to visualise the results of the peak detection.
 
 
 Peak Detection
@@ -154,28 +158,57 @@ F), you should be careful when using "compare" for the cell reduction, since
 be converted to the non-primitive conventional cell from the PDB.
 
 
-A Note about Unit Cell Settings
--------------------------------
+Tuning CPU affinities for NUMA hardware
+---------------------------------------
 
-CrystFEL's core symmetry module only knows about one setting for each unit cell.
-You must use the same setting.  That means that the unique axis (for cells which
-have one) must be "c".
+If you are running indexamajig on a NUMA (non-uniform memory architecture)
+machine, a performance gain can sometimes be made by preventing the kernel from
+allowing a process or thread to run on a CPU which is distant from the one on
+which it started.  Distance, in this context, might mean that the CPU is able to
+access all the memory visible to the original CPU, but perhaps only relatively
+slowly via a cable link.  In many cases a group of CPUs will have direct access
+to a certain region of memory, and so the process may be scheduled on any CPU in
+that group without any penalty.  However, scheduling the process to any CPU
+outside the group may be slow.  When running under Linux, indexamajig is able to
+avoid such sub-optimal process scheduling by setting CPU affinities for its
+threads.  The CPU affinities are also inherited by subprocesses (e.g. MOSFLM or
+DirAx).
+
+To do this usefully, you need to give indexamajig some information about your
+hardware's architecture.  Specify the size of the CPU groups using
+"--cpugroup=<n>".  You also need to specify the overall number of CPUs, so that
+the program knows when to 'wrap around'.  Using "--cpuoffset=<n>", where "n" is
+a group number (not a CPU number), allows you to manually skip a few CPUs, which
+may be useful if you do not want to use all the available CPUs but want to avoid
+running all your jobs on the same ones.
+
+Note that specifying the above options is NOT the same thing as giving the
+number of analyses to run in parallel (the 'number of threads'), which is done
+with "-j <n>".  The CPU tuning options provide information to indexamajig about
+how to set the CPU affinities for its threads, but it does not specify how many
+threads to use.
 
+Example: 72-core Altix UV 100 machine at the author's institution
 
-Unconventional Use
-------------------
+This machine consists of six blades, each containing two 6-core CPUs and some
+local memory.  Any CPU on any blade can access the memory on any other blade,
+but the access will be slow compared to accessing memory on the same blade.
+When running two instances of indexamajig, a sensible choice of parameters might
+be:
 
-There are some less often used options, for example "--dump-peaks" to dump the
-peak locations found by the peak search (in turn presented to the indexer).
-This might be useful if you want to check the performance of the peak finder.
-If you run a large dataset with bot --dump-peaks and --near-bragg enabled,
-you'll generate a large amount of data.  To separate the peaks from the
-indexed peaks, use scripts/stream-split as follows:
+1: --cpus=72 --cpugroup=12 --cpuoffset=0 -j 36
+2: --cpus=72 --cpugroup=12 --cpuoffset=36 -j 36
 
-scripts/stream-split myoutputfile.txt indexed.txt peaks.txt
+This would dedicate half of the CPUs to one instance, and the other half to the
+other.
 
-.. to generate both indexed.txt and peaks.txt.  One of the last two arguments
-can be "/dev/null" if you're only interested in the other.
+
+A Note about Unit Cell Settings
+-------------------------------
+
+CrystFEL's core symmetry module only knows about one setting for each unit cell.
+You must use the same setting.  That means that the unique axis (for cells which
+have one) must be "c".
 
 
 "Gotchas"
@@ -183,5 +216,4 @@ can be "/dev/null" if you're only interested in the other.
 
 Don't run more than one indexamajig jobs simultaneously in the same working
 directory - they'll overwrite each other's DirAx or MOSFLM files, causing subtle
-problems
-which can't easily be detected.
+problems which can't easily be detected.
diff --git a/doc/reference/CrystFEL-docs.sgml b/doc/reference/CrystFEL-docs.sgml
index 08f97f3d..ba20fbea 100644
--- a/doc/reference/CrystFEL-docs.sgml
+++ b/doc/reference/CrystFEL-docs.sgml
@@ -10,9 +10,13 @@
     <releaseinfo>
       For CrystFEL 0.2.0.
     </releaseinfo>
+    <abstract>
     This is the internal documentation for CrystFEL.  Unless you are looking at
     the code, writing new programs or fixing bugs, you should not need to read
-    this.
+    this.  You might use the information here when reading the code or to better
+    understand how the software works, or refer to it when creating a new
+    program within the suite.
+    </abstract>
   </bookinfo>
 
   <chapter>
@@ -22,6 +26,7 @@
 
   <chapter>
     <title>Handling reflection data</title>
+        <abstract>There are three main reflection list thingies.</abstract>
         <xi:include href="xml/reflist.xml"/>
         <xi:include href="xml/reflitemlist.xml"/>
   </chapter>
diff --git a/doc/reference/CrystFEL-sections.txt b/doc/reference/CrystFEL-sections.txt
index 1adda7b5..b6021270 100644
--- a/doc/reference/CrystFEL-sections.txt
+++ b/doc/reference/CrystFEL-sections.txt
@@ -33,6 +33,12 @@ show_matrix_eqn
 <SECTION>
 <FILE>quaternion</FILE>
 quaternion
+<SUBSECTION>
+quaternion_modulus
+normalise_quaternion
+random_quaternion
+quaternion_valid
+quat_rot
 </SECTION>
 
 <SECTION>
diff --git a/m4/gtk-doc.m4 b/m4/gtk-doc.m4
index 8b55c2c0..9033c7d2 100644
--- a/m4/gtk-doc.m4
+++ b/m4/gtk-doc.m4
@@ -25,8 +25,8 @@ AC_DEFUN([GTK_DOC_CHECK],
   dnl enable/disable documentation building
   AC_ARG_ENABLE([gtk-doc],
     AS_HELP_STRING([--enable-gtk-doc],
-                   [use gtk-doc to build documentation [[default=no]]]),,
-    [enable_gtk_doc=no])
+                   [use gtk-doc to build documentation [[default=yes]]]),,
+    [enable_gtk_doc=yes])
 
   if test x$enable_gtk_doc = xyes; then
     ifelse([$1],[],
diff --git a/src/utils.c b/src/utils.c
index 7a27e057..02de3e14 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -166,12 +166,42 @@ int poisson_noise(double expected)
 }
 
 
+/**
+ * SECTION:quaternion
+ * @short_description: Simple quaternion handling
+ * @title: Quaternion
+ * @section_id:
+ * @see_also:
+ * @include: "utils.h"
+ * @Image:
+ *
+ * There is a simple quaternion structure in CrystFEL.  At the moment, it is
+ * only used when simulating patterns, as an argument to %cell_rotate to
+ * orient the unit cell.
+ */
+
+/**
+ * quaternion_modulus:
+ * @q: A %quaternion
+ *
+ * If a quaternion represents a pure rotation, its modulus should be unity.
+ *
+ * Returns: the modulus of the given quaternion.
+ **/
 double quaternion_modulus(struct quaternion q)
 {
 	return sqrt(q.w*q.w + q.x*q.x + q.y*q.y + q.z*q.z);
 }
 
 
+/**
+ * normalise_quaternion:
+ * @q: A %quaternion
+ *
+ * Rescales the quaternion such that its modulus is unity.
+ *
+ * Returns: the normalised version of @q
+ **/
 struct quaternion normalise_quaternion(struct quaternion q)
 {
 	double mod;
@@ -188,6 +218,11 @@ struct quaternion normalise_quaternion(struct quaternion q)
 }
 
 
+/**
+ * random_quaternion:
+ *
+ * Returns: a randomly generated, normalised, quaternion.
+ **/
 struct quaternion random_quaternion()
 {
 	struct quaternion q;
@@ -202,6 +237,18 @@ struct quaternion random_quaternion()
 }
 
 
+/**
+ * quaternion_valid:
+ * @q: A %quaternion
+ *
+ * Checks if the given quaternion is normalised.
+ *
+ * This function performs a nasty floating point comparison of the form
+ * <code>(modulus > 0.999) && (modulus < 1.001)</code>, and so should not be
+ * relied upon to spot anything other than the most obvious input error.
+ *
+ * Returns: 1 if the quaternion is normalised, 0 if not.
+ **/
 int quaternion_valid(struct quaternion q)
 {
 	double qmod;
@@ -216,6 +263,15 @@ int quaternion_valid(struct quaternion q)
 }
 
 
+/**
+ * quat_rot
+ * @q: A vector (in the form of an %rvec)
+ * @z: A %quaternion
+ *
+ * Rotates a vector according to a quaternion.
+ *
+ * Returns: A rotated version of @p.
+ **/
 struct rvec quat_rot(struct rvec q, struct quaternion z)
 {
 	struct rvec res;