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

Currently, only process_hkl and render_hkl understand symmetry (and render_hkl
only understands it when plotting a zone axis pattern).  get_hkl does NOT
currently understand symmetry, which means you'll have to expand any molecular
model (the PDB) out to P1 to get the correct results.  You can achieve that, for
example, by loading it into Mercury, turning on "Packing", and re-saving.
Alternatively, using CCP4:

$ echo symgen P63 | pdbset xyzin model.pdb xyzout model-P1.pdb

[ While on this subject, you'll probably also want to include hydrogens in the
model using something like:
$ echo HYDROGENS APPEND | hgen xyzin model.pdb xyzout model-with-H.pdb     ]

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 process_hkl 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.

Space groups would only be needed to make get_hkl handle symmetry properly, but
that hasn't been done yet, so symmetry.c just handles point groups for now.  The
method used in symmetry.c is general to both point groups and space groups, even
though the code currently is not.

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:

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 your symmetry
breaks in weird ways.

Now, 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 given 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.