          EDNA MXv1 Characterisation Manual
          =================================

This manual is a short introduction on how to run the EDNA MXv1 characterisation version 1.0.1.
For installation instructions, see the file $EDNA_HOME/mxv1/INSTALL.txt. 

The edna-mxv1-characterisation application accepts two types of input, either an XML file 
or a list of ADSC images:


1. Using XML input with the MXv1 characterisation application
-------------------------------------------------------------

The XML input must be of type XSDataCollection. You can find an example of an XML file in:

$EDNA_HOME/mxv1/plugin/EDPluginControlCharacterisation-v1.0/tests/data/XSDataCollection_reference.xml

Use the "--data" command line argument to start the MXv1 characterisation with XML input:

  edna-mxv1-characterisation --data XSDataCollection.xml

The XML input gives you full freedom for accessing all parameters in the MXv1
data model such as the chemical composition of the crystal content, the diffraction plan etc.


2. Using the MXv1 characterisation application without an XML input file
------------------------------------------------------------------------

In order to facilitate execution of edna-mxv1-characterisation it is possible to instead of defining
an XML file give a list of ADSC images using the "--image" keyword:

  edna-mxv1-characterisation --image test_1_001.img [ test_1_002.img ... ]
  
The images must have an image number in the file name, and the following parameters must 
be constant for all images:

  * Crystal
  * Wavelength
  * Distance
  * Detector type

Optional keywords when using the "--image" options:
  
  --flux     : Beam flux [photon/s]
  
  --beamSize : Beam size [mm] (beam assumed to be square)

  --maxExposureTimePerDataCollection : The maximum time a crystal will be exposed to the X-ray
                                       beam. This value can either be used as the longest time
                                       a crystal can be exposed to the X-ray beam before being 
                                       destroyed by radiation damage, or it can be used to 
                                       optimise data collection in case of lack of time 
                                       (e.g. end of beamtime).

  --minExposureTimePerImage : the shortest exposure time at which the shutter of the beamline can 
                              work reliably.
  
Note that all these options (and many, many more) are available in the XML file
input mentioned above, but these keywords have no effect when using the "--data"
keywor. Thus, if you want to modify these values using XML input, you must modify
the corresponding value in the XML file.

Note also that in order to run RADDOSE both the flux and the beamsize must be
provided.

The "--image" keyword input has been added only for rapdily run the MXv1 characterisation
on a set of images. In order to take advantage of the full potential of the
MXv1 characterisation application please use the XML input described above.


3. Results
----------

If correct input has been provided to edna-mxv1-characterisation, it will generate two kinds
of output - an "executive summary" which is displayed in the terminal from which 
the edna-mxv1-characterisation application was launched, and an XML output file.

The edna-mxv1-characterisation application creates a new directory in the directory from 
where it was launched:

  YYYYMMDD-HHMMSS-EDApplicationMXv1Characterisation-v1.0.1
  
All the input files, output files and the files generated by the third-party
programs (MOSFLM, RADDOSE and BEST) are stored in sub-directories of this directory.

The output XML file from the characterisaton can be found in the "Characterisation"
sub directory:

  YYYYMMDD-HHMMSS-EDApplicationMXv1Characterisation-v1.0.1/Characterisation/EDPluginControlCharacterisationv01_dataOutput.xml
  
