How CrystFEL handles symmetry
-----------------------------

Most programs in CrystFEL understand point group symmetry.  The exception is
"get_hkl", which you can read about below.  You give the point group following
the "-y" option to the programs.

Please read doc/process_hkl for important information on how symmetry is used
during the indexing and merging procedures.  It's important to understand how
this works before, for example, trying to merge a dataset.

Symmetry definitions are included in src/symmetry.c.  Point group definitions
are required for merging and the display of merged results, but space groups are
not taken into account since merging does not care about systematic absences -
as far as CrystFEL is concerned, systematic absences are just measurements
which happen to have values of zero.  Each space group belongs to exactly one
point group, which you can look up in the International Tables for X-Ray
Crystallography.  Alternatively, "twin-calculator.pdf" in the same directory as
this file lists all the space groups according to point group, Laue class and
holohedry.


Adding a new point group
------------------------

Point groups are being added here as they are required, so it's likely that the
exact one you want hasn't been added yet.  Here's how to add a new one by
editing src/symmetry.c.

First, expand the check_cond() function to include a description of the
asymmetric reciprocal unit cell for the point group.  Every reflection in the
whole of reciprocal space must map onto exactly one reflection in the asymmetric
unit cell so defined.  The asymmetric cell is usually defined with positive h, k
and l, but it doesn't really matter.  Working out the required condition means
visualising the cell and taking care to properly handle situations such as the
(000) reflection.  Get this right, otherwise you'll go crazy when it breaks in
weird ways.

Next, expand the num_general_equivs() function.  Given a point group, this
function must return the number of equivalent reflections for a general
reflection, including the input reflection.  High-symmetry reflections (usually
ones with zeroes in their indices) have fewer equivalents, but the num_equivs()
function will work this out for you.

Finally, add the new point group to the get_general_equiv() function.  This
function takes a set of Miller indices, a point group and an index "n", and
returns (by reference) the indices of the "n"th equivalent reflection. You just
have to worry about the general position, because get_equiv() will work out the
special positions for you.  get_general_equiv() must return the original indices
when idx=0.

If you want the new point group to be used for simulation on the GPU, you will
also need to modify src/diffraction-gpu.c and data/diffraction.cl.  Choose a
simple capitalised name for the point group and add it to the list of OpenCL
preprocessor definitions in setup_gpu().  Then add a corresponding list of
equivalents following the established pattern in molecule_factor().  That's it.