aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore24
-rwxr-xr-xconfigure4
-rw-r--r--doc/indexamajig.txt70
-rw-r--r--doc/reference/CrystFEL-docs.sgml7
-rw-r--r--doc/reference/CrystFEL-sections.txt6
-rw-r--r--m4/gtk-doc.m44
-rw-r--r--src/utils.c56
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;