decryst: decrypt your crystal structure
=======================================

About
-----

This is decryst [1], a software suite designed for crystal structure
determination from X-ray powder diffraction data using the direct-space method.
decryst can apply anti-bump constraints automatically during the procedure of
structure optimisation, reducing the probability of solutions becoming
chemically unreasonable.  decryst is designed with parallel and distributed
computing in mind, and aims to be simple, efficient and flexible.

[1] <https://gitea.com/CasperVector/decryst>.


Installation
------------

Dependencies:
* To build decryst, you need:
  - A POSIX compliant building environment.
  - The ZeroMQ library (3.x or newer) for `decr_sas' and `decr_sac'.
* To run decryst, you need:
  - Python (whether 2.x or 3.x) for `decr_utils'.
  - POSIX compliant Unix utilities and ssh(1) for the examples.

Building:
$ cd src && make

Installation:
# cd src && cp decr_mcs decr_lsa decr_sas decr_sac /usr/bin && cd -
# mkdir /usr/share/decryst && cp python/*.json /usr/share/decryst
# cp python/decr_utils /usr/bin

(Optional) building the benchmark programs:
$ mkdir test && cd test
$ cp -s ../src/* ../bench/* . && mv benchmark.mk Makefile
$ make


Documentation
-------------

See subdirectories of the `doc' directory:
* `usage': documentation on usage of the programs shipped with decryst.
* `scripts': helpful scripts for use with decryst.
* `examples': example data files.
* `thesis': the author's dissertation on decryst.
* `wyck': files used to compute asymmetric units for special Wyckoff positions.
Do note that, in order to perform those tasks that require more sophisticated
automation, the user is expected to understand (or to be willing to learn) some
basics of Unix shell scripting.  Luckily, this is not too difficult, and will be
very rewarding (in a sense that is not specific to decryst).

To compile the source code for the dissertation, a recent TeXLive system is
required; additionally, certain Chinese fonts (cf. the casthss package below)
need to be installed and properly configured for use with XeLaTeX.  After these
are done, the user needs to execute the following commands:
$ cd doc && git clone https://gitea.com/CasperVector/casthss
$ cp -a thesis/* casthss && rm -rf thesis casthss/.git && mv casthss thesis
$ ln -s $TEXMFDIST/fonts/opentype/public/gfsdidot ~/.local/share/fonts
$ cd thesis && latexmk

The dissertation was based on the following papers by the author of decryst:
* Y. Liu (2017). "Real-time detection and resolution of atom bumping in
  crystallographic models". Acta Cryst. A73(5): 414-422. arXiv: 1708.03180.
* Y. Liu (2018). "decryst: an efficient software suite for structure
  determination from powder diffraction". J. Appl. Cryst. 51(4): 1237-1243.
  arXiv: 1801.08372.
Readers who are already familiar with the contents of these papers are advised
to additionally read sections 2.1.1, 2.3.1, 3.1.3, 3.2.1, 3.3.1-3.3.3 and
chapter 4 in the thesis.


Compatibility
-------------

decryst has undergone some backward-incompatible changes, and those who intend
to reproduce previous results are advised to check out appropriate commits:
* Results from the (Liu 2017) paper can be verified with commit 0bcee817.
* Results from the (Liu 2018) paper and the thesis can be verified with commit
  ceb7ff2c; the changes (mostly in commits dfca78e1 and ea48f1e6) were necessary
  to address some fairly important defects in the original design.

The author would like to note that decryst is not intended to be a rapidly
moving software project; actually, due to multiple reasons, the project has
entered "bugfix mode" (i.e. no new functionalities) after recent fixes for the
above-mentioned design flaws.  However, as noted in (Liu 2018), the author
explicitly wishes the techniques in decryst to be adopted in widely used
crystallographic software packages, and the decryst codebase has always strived
to be (reasonably) easily hackable.


Copying
-------

Copyright (c) 2016-2021 Casper Ti. Vector <CasperVector@gmail.com>

Unless explicitly indicated otherwise, all files included in this software are
covered by the CC0 licence [2].

[2] <https://creativecommons.org/publicdomain/zero/1.0/>.