From b730350f342972083bc28195d0042b2485135ee9 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Sat, 26 Mar 2011 22:42:49 +0100 Subject: More documentation stuff --- doc/indexamajig.txt | 70 +++++++++++++++++++++++++++---------- doc/reference/CrystFEL-docs.sgml | 7 +++- doc/reference/CrystFEL-sections.txt | 6 ++++ 3 files changed, 63 insertions(+), 20 deletions(-) (limited to 'doc') 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=". You also need to specify the overall number of CPUs, so that +the program knows when to 'wrap around'. Using "--cpuoffset=", 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 ". 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 @@ For CrystFEL 0.2.0. + 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. + @@ -22,6 +26,7 @@ Handling reflection data + There are three main reflection list thingies. 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
quaternion quaternion + +quaternion_modulus +normalise_quaternion +random_quaternion +quaternion_valid +quat_rot
-- cgit v1.2.3