From 3761e1f1e07b14c3d2b105ceccb231e053d025ad Mon Sep 17 00:00:00 2001 From: Thomas White Date: Fri, 5 Mar 2021 11:10:02 +0100 Subject: Switch to markdown for README --- AUTHORS | 20 ------ README | 208 -------------------------------------------------------------- README.md | 134 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 134 insertions(+), 228 deletions(-) delete mode 100644 README create mode 100644 README.md 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 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 - Richard Kirian - Kenneth Beyerlein - Andrew Aquila - Andrew Martin - Lorenzo Galli - Chun Hong Yoon - Kenneth Beyerlein - Karol Nass - Nadia Zatsepin - Anton Barty - Cornelius Gati - Fedor Chervinskii - Alexandra Tolstikova - Wolfgang Brehm - Valerio Mariani - Parker de Waal - Takanori Nakane - Keitaro Yamashita - Mamoru Suzuki - Thomas Grant - Steve Aplin - Oleksandr Yefanov - Helen Ginn - Nicolas Riebesel - Yaroslav Gevorkov - Omri Mor - --------------------------------------------------------------------------------- - -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 . - --------------------------------------------------------------------------------- - -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 . + + +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). + -- cgit v1.2.3