diff options
| -rw-r--r-- | .gitignore | 24 | ||||
| -rwxr-xr-x | configure | 4 | ||||
| -rw-r--r-- | doc/indexamajig.txt | 70 | ||||
| -rw-r--r-- | doc/reference/CrystFEL-docs.sgml | 7 | ||||
| -rw-r--r-- | doc/reference/CrystFEL-sections.txt | 6 | ||||
| -rw-r--r-- | m4/gtk-doc.m4 | 4 | ||||
| -rw-r--r-- | src/utils.c | 56 |
7 files changed, 124 insertions, 47 deletions
@@ -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/* @@ -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; |