aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas White <taw@physics.org>2021-03-05 11:10:02 +0100
committerThomas White <taw@physics.org>2021-03-05 11:10:45 +0100
commit3761e1f1e07b14c3d2b105ceccb231e053d025ad (patch)
tree6790b60718ace5fb344cf88eef8e7417351980ce
parent8155e281cac386c0ea58f1a0f61f72be863f0f58 (diff)
Switch to markdown for README
-rw-r--r--AUTHORS20
-rw-r--r--README208
-rw-r--r--README.md134
3 files changed, 134 insertions, 228 deletions
diff --git a/AUTHORS b/AUTHORS
index b00a2a08..8b49d146 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,23 +1,3 @@
-Funding acknowledgements
-------------------------
-
-Development of CrystFEL is primarily funded by the Helmholtz Association via
-programme-oriented funds.
-
-Additional funding for CrystFEL is provided by "X-Probe", a project of the
-European Union's 2020 Research and Innovation Program Under the Marie
-Skłodowska-Curie grant agreement 637295 (2015-2018).
-
-Additional funding for CrystFEL is provided by the BMBF German-Russian
-Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
-
-Past funding for CrystFEL has been received from BioStruct-X, a project funded
-by the Seventh Framework Programme (FP7) of the European Commission.
-
-
-Contributors
-------------
-
* Thomas White <taw@physics.org>
Lead author, architecture, "vision" and so on.
diff --git a/README b/README
deleted file mode 100644
index d74ea8c6..00000000
--- a/README
+++ /dev/null
@@ -1,208 +0,0 @@
-CrystFEL - Data processing for serial crystallography
------------------------------------------------------
-
-Copyright © 2012-2020 Deutsches Elektronen-Synchrotron DESY,
- a research centre of the Helmholtz Association.
-
-Authors:
- Thomas White <taw@physics.org>
- Richard Kirian <rkirian@asu.edu>
- Kenneth Beyerlein <kenneth.beyerlein@desy.de>
- Andrew Aquila <andrew.aquila@cfel.de>
- Andrew Martin <andrew.martin@desy.de>
- Lorenzo Galli <lorenzo.galli@desy.de>
- Chun Hong Yoon <chun.hong.yoon@desy.de>
- Kenneth Beyerlein <kenneth.beyerlein@desy.de>
- Karol Nass <karol.nass@desy.de>
- Nadia Zatsepin <nadia.zatsepin@asu.edu>
- Anton Barty <anton.barty@desy.de>
- Cornelius Gati <cornelius.gati@desy.de>
- Fedor Chervinskii <fedor.chervinskii@gmail.com>
- Alexandra Tolstikova <alexandra.tolstikova@desy.de>
- Wolfgang Brehm <wolfgang.brehm@gmail.com>
- Valerio Mariani <valerio.mariani@desy.de>
- Parker de Waal <Parker.deWaal@vai.org>
- Takanori Nakane <nakane.t@gmail.com>
- Keitaro Yamashita <k.yamashita@spring8.or.jp>
- Mamoru Suzuki <mamoru.suzuki@protein.osaka-u.ac.jp>
- Thomas Grant <tgrant@hwi.buffalo.edu>
- Steve Aplin <steve.aplin@desy.de>
- Oleksandr Yefanov <oleksandr.yefanov@desy.de>
- Helen Ginn <helen@strubi.ox.ac.uk>
- Nicolas Riebesel <nicolas.riebesel@tuhh.de>
- Yaroslav Gevorkov <yaroslav.gevorkov@desy.de>
- Omri Mor <omor1@asu.edu>
-
---------------------------------------------------------------------------------
-
-CrystFEL is free software: you can redistribute it and/or modify it under the
-terms of the GNU General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with
-CrystFEL. If not, see <http://www.gnu.org/licenses/>.
-
---------------------------------------------------------------------------------
-
-CrystFEL is a suite of programs for processing (and simulating) Bragg
-diffraction data from "serial crystallography" experiments, often (but not
-always) performed using an X-ray Free-Electron Laser. Some of the particular
-characteristics of such data which call for a specialised software suite are:
-
-- The sliced, rather than integrated, measurement of intensity data. Many, if
- not all reflections are partially integrated.
-
-- Many patterns (thousands) are required - high throughput is needed.
-
-- The crystal orientations in each pattern are random and uncorrelated, meaning
- that:
-
-- Merging into lower symmetry point groups may require the resolution of
- indexing ambiguities.
-
-
-CrystFEL includes programs for simulating and processing patterns subject to the
-above characteristics. The main data processing pipeline is defined by four
-programs:
-
- - indexamajig, for bulk indexing and integration of diffraction patterns
-
- - process_hkl, for quickly merging per-pattern lists of intensities into
- a single reflection list
-
- - partialator, for merging patterns more accurately (and much more
- slowly) using scaling, partiality modelling and
- post refinement
-
- - ambigator, for resolving indexing ambiguities
-
-There are two tools for calculating figures of merit for reflection data:
-
- - compare_hkl, for figures of merit that involve comparing two sets of
- data, like CC* and R_split
-
- - check_hkl, for figures of merit based on only one set of data, like
- completeness, redundancy and twinning tests
-
-Three tools are provided for visualising data:
-
- - cell_explorer, for examining distributions of lattice parameters
-
- - hdfsee, an image viewer
-
- - render_hkl, for turning reflection lists into pretty graphics
-
-CrystFEL can also simulate data, e.g. for methods development:
-
- - pattern_sim, which performs a Fourier image calculation
-
- - partial_sim, which calculates reflection intensities based on a
- partiality calculation and optionally plots the peaks
- in an image
-
-There are also five utility programs:
-
- - get_hkl, for doing various simple operations on reflection lists such
- as expanding by symmetry or adding noise
-
- - cell_tool, for doing operations on unit cells such as applying
- transformations or looking for indexing ambiguities
-
- - geoptimiser, for refining detector geometry.
-
- - list_events, for creating event lists from multi-event files.
-
- - make_pixelmap, for creating HDF5 pixel map files for other programs
- like Cheetah and OnDA
-
- - whirligig, for finding multiple shots from single crystals.
-
-
-There is also a folder full of scripts for achieving many related tasks, such as
-file format conversion.
-
-Standard "man" pages are provided for documentation, or you can invoke any
-program with the argument "--help" to get a summary of options. There are some
-example geometry and beam description files in doc/examples, and API
-documentation created using Doxygen.
-
-
-Installation
-------------
-
-The terse installation instructions below should be enough if you're experienced
-with installing software from source. More detailed installation information is
-available on the website:
-https://www.desy.de/~twhite/crystfel/install.html
-
-Mandatory dependencies:
- - CMake 3.12 or later
- - HDF5 1.8.0 or later (1.10.0 or later preferred)
- - GNU Scientific Library (GSL)
- - Bison 2.6 or later
- - Flex
- - Zlib (1.2.3.5 or later preferred)
-
-"Optional" dependencies:
- - GTK2 or later (GTK3 preferred)
- - Cairo
- - Pango
- - gdk-pixbuf
- - NCurses
- - libPNG
- - libTIFF
- - FFTW3
- - XGandalf (https://stash.desy.de/users/gevorkov/repos/xgandalf)
-
-"Optional" run-time dependencies:
- - Mosflm (https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/)
- - DirAx (http://www.crystal.chem.uu.nl/distr/dirax/)
- - XDS (http://xds.mpimf-heidelberg.mpg.de/)
-
-Note that "optional" means that you *can* install CrystFEL without them, however
-your installation will lack important components such as the visualisation
-tools and certain indexing algorithms.
-
-For processing electron diffraction or wide-bandwidth X-ray data, you should
-also install PinkIndexer from:
-https://stash.desy.de/users/gevorkov/repos/pinkindexer
-
-Installation follows the normal CMake procedure:
-
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
-$ sudo make install
-
-If external libraries have been installed in non-standard locations, you can set
-the path like this, for example for Xgandalf:
- cmake -DXGANDALF_INCLUDES=/path/to/xgandalf/include \
- -DXGANDALF_LIBRARIES=/path/to/xgandalf/lib/libxgandalf.so
-
-The path to HDF5 can be set similarly:
- cmake -DHDF5_ROOT=/path/to/hdf5 (... /include, /lib etc)
-
-To install CrystFEL in a custom location, use:
- cmake -DCMAKE_INSTALL_PREFIX=/path/for/crystfel/installation
-
-
-Funding acknowledgements
-------------------------
-
-Development of CrystFEL is primarily funded by the Helmholtz Association.
-
-Partial funding for CrystFEL has previously been provided by:
-
-- "X-Probe", a project of the European Union's 2020 Research and Innovation
- Program Under the Marie Skłodowska-Curie grant agreement 637295 (2015-2018).
-
-- The BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
-
-- BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the
- European Commission (2011-2016).
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..8306c030
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+CrystFEL - Data processing for serial crystallography
+=====================================================
+
+Copyright © 2012-2021 Deutsches Elektronen-Synchrotron DESY,
+ a research centre of the Helmholtz Association.
+
+See AUTHORS for full details of contributors.
+
+Introduction
+------------
+
+CrystFEL is a suite of programs for processing (and simulating) Bragg
+diffraction data from "serial crystallography" experiments, often (but not
+always) performed using an X-ray Free-Electron Laser. Compared to rotation data,
+some of the particular characteristics of such data which call for a
+specialised software suite are:
+
+* The sliced, rather than integrated, measurement of intensity data. Many, if
+ not all reflections are partially integrated.
+
+* Many patterns (thousands) are required - high throughput is needed.
+
+* The crystal orientations in each pattern are random and uncorrelated.
+
+* Merging into lower symmetry point groups may require the resolution of
+ indexing ambiguities.
+
+
+Getting started
+---------------
+
+The best way to get started, after installation, is to run command ```crystfel```
+to start the graphical user interface.
+
+
+Installation
+------------
+
+CrystFEL installation is supported on GNU/Linux and Mac OS X. The terse
+installation instructions below should be enough if you're experienced with
+installing software from source. More detailed installation information is
+available [on the website](https://www.desy.de/~twhite/crystfel/install.html).
+
+Here are the mandatory dependencies - you cannot install CrystFEL without these:
+
+* Either [CMake](https://cmake.org/) 3.12 or later or [Meson](https://mesonbuild.com/) (Meson is preferred)
+* [HDF5](https://www.hdfgroup.org/downloads/hdf5/) 1.8.0 or later (1.10.0 or later is required for many recent data formats)
+* [GNU Scientific Library (GSL)](https://www.gnu.org/software/gsl/)
+* [Bison](https://www.gnu.org/software/bison/) 2.6 or later
+* [Flex](https://www.gnu.org/software/flex/)
+* [Zlib](https://www.zlib.net/) (1.2.3.5 or later preferred for better decompression speed)
+
+The following dependencies are "optional", in the sense that you can install
+CrystFEL without them. However, a CrystFEL installation without these will lack
+important features such as the graphical user interface:
+
+* GTK3 or later
+* Cairo
+* Pango
+* gdk-pixbuf
+* NCurses
+* libPNG
+* [libccp4](ftp://ftp.ccp4.ac.uk/opensource/)
+
+Note that all of the dependencies mentioned above (including libccp4) should be
+available from your Linux distribution's package manager, or from
+[Homebrew](https://brew.sh/) on Mac OS. You should not need to download and
+install any of them separately from source, and we emphatically recommend
+against trying to do so!
+
+Note that using the libraries from the full CCP4 suite is not recommended. CCP4
+includes so many other libraries that it becomes very difficult to link using
+the correct versions of everything.
+
+Processing data relies on indexing algorithms. The more of the following are
+installed, the better your experience will be:
+
+* [FFTW3](http://fftw.org/)
+* [XGandalf](https://stash.desy.de/users/gevorkov/repos/xgandalf)
+* [PinkIndexer](https://stash.desy.de/users/gevorkov/repos/pinkindexer)
+* [Mosflm](https://www.mrc-lmb.cam.ac.uk/mosflm/mosflm/)
+* [DirAx](http://www.crystal.chem.uu.nl/distr/dirax/)
+* [XDS](http://xds.mpimf-heidelberg.mpg.de/)
+
+Installation follows the normal CMake procedure:
+
+```
+$ mkdir build
+$ cd build
+$ cmake ..
+$ make
+$ sudo make install
+```
+
+Or, with Meson:
+
+```
+$ meson . build
+$ ninja -C build
+$ sudo ninja -C build install
+```
+
+
+Licence
+-------
+
+CrystFEL is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+CrystFEL. If not, see <http://www.gnu.org/licenses/>.
+
+
+Funding acknowledgements
+------------------------
+
+Development of CrystFEL is primarily funded by the Helmholtz Association.
+
+Partial funding for CrystFEL has previously been provided by:
+
+- "X-Probe", a project of the European Union's 2020 Research and Innovation
+ Program Under the Marie Skłodowska-Curie grant agreement 637295 (2015-2018).
+
+- The BMBF German-Russian Cooperation "SyncFELMed", grant 05K14CHA (2014-2017).
+
+- BioStruct-X, a project funded by the Seventh Framework Programme (FP7) of the
+ European Commission (2011-2016).
+