readme.rst 6.44 KB
Newer Older
srmnitc's avatar
srmnitc committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14
..  In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
    document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
    template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
    and followed by white space (if you see warnings when this file is built they this is a common origin for problems).

..  We allow the template to be standalone, so that the library maintainers add it in the right place


..  Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
    progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.

..  sidebar:: Software Technical Information

  Name
srmnitc's avatar
srmnitc committed
15
    pybop
srmnitc's avatar
srmnitc committed
16 17

  Language
srmnitc's avatar
srmnitc committed
18
    Python (2.7, 3.4, 3.5, 3.6)
srmnitc's avatar
srmnitc committed
19 20

  Licence
srmnitc's avatar
srmnitc committed
21
    `GNU General Public License v3.0 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_
srmnitc's avatar
srmnitc committed
22 23

  Documentation Tool
srmnitc's avatar
srmnitc committed
24
    Sphinx/RST
srmnitc's avatar
srmnitc committed
25 26

  Application Documentation
srmnitc's avatar
srmnitc committed
27
    https://srmnitc.github.io/pybop/html/index.html
srmnitc's avatar
srmnitc committed
28 29

  Relevant Training Material
srmnitc's avatar
srmnitc committed
30
    https://mybinder.org/v2/gh/srmnitc/pybop/master?filepath=examples%2F
srmnitc's avatar
srmnitc committed
31 32

  Software Module Developed by
srmnitc's avatar
srmnitc committed
33
    Sarath Menon
srmnitc's avatar
srmnitc committed
34 35 36 37 38 39 40 41


..  In the next line you have the name of how this module will be referenced in the main documentation (which you  can
    reference, in this case, as ":ref:`example`"). You *MUST* change the reference below from "example" to something
    unique otherwise you will cause cross-referencing errors. The reference must come right before the heading for the
    reference to work (so don't insert a comment between).


srmnitc's avatar
srmnitc committed
42 43 44
#####
pybop
#####
srmnitc's avatar
srmnitc committed
45 46 47 48 49 50 51 52 53 54

..  Let's add a local table of contents to help people navigate the page

..  contents:: :local:

..  Add an abstract for a *general* audience here. Write a few lines that explains the "helicopter view" of why you are
    creating this module. For example, you might say that "This module is a stepping stone to incorporating XXXX effects
    into YYYY process, which in turn should allow ZZZZ to be simulated. If successful, this could make it possible to
    produce compound AAAA while avoiding expensive process BBBB and CCCC."

srmnitc's avatar
srmnitc committed
55
``pybop`` is a python module for calculation of bond orientational order parameters [#]_. The core functionality of ``pybop`` is written in C++ with python wrappers using `pybind11 <https://pybind11.readthedocs.io/en/stable/intro.html>`_ . This allows for fast calculations with possibilities for seamless expansion in python. 
srmnitc's avatar
srmnitc committed
56 57 58 59 60 61

Purpose of Module
_________________

.. Keep the helper text below around in your module by just adding "..  " in front of it, which turns it into a comment

srmnitc's avatar
srmnitc committed
62 63 64 65 66 67 68 69 70 71 72 73 74
Bond orientational order parameters have been widely used in distinction of crystal structures in computational studies [#]_. Additionally, these parameters have also been used to distinguish between solid and liquid particles in studies of crystallisation during solidification [#]_.

``pybop`` provides a flexible post-processing python environment for these calculations, at the same time ensuring speed and efficiency as the core code is written in C++ with `pybind11 bindings <https://pybind11.readthedocs.io/en/stable/intro.html>`_. ``pybop`` also links with `Voro++ <http://math.lbl.gov/voro++/>`_ code to carry out calculations of voronoi volumes, indices and face areas.

Some of the major uses of ``pybop`` are listed below-    

- calculations including the bond order parameters :math:`q_{i}` where :math:`i = \{2,3 \to 12\}`.  
- averaged versions which has been to improve the resolution in identification of crystal structures [#]_.
- weighted :math:`q_{i}` where the contributions are weighted by the voronoi face area shared with adjacent atoms [#]_.
- distinction of liquid and solid atoms based on :math:`q_{6}` parameter.
- calculation of the parameters in non-orthogonal simulation boxes.
- other quantities like radial distribution function, coordination number and voronoi volume of individual particles.

srmnitc's avatar
srmnitc committed
75
``pybop`` can read in output data from LAMMPS [#]_ `dump format <https://lammps.sandia.gov/doc/dump.html>`_ and POSCAR files from VASP. The module also provides an easy interface for extension of the available data formats or linking with other codes to read in input data.
srmnitc's avatar
srmnitc committed
76 77 78

.. I will add information about the paper and results using pybop.

srmnitc's avatar
srmnitc committed
79 80 81 82 83 84 85


Background Information
______________________

.. Keep the helper text below around in your module by just adding "..  " in front of it, which turns it into a comment

86
See the `application documentation <https://srmnitc.github.io/pybop/html/index.html>`_ for full details.
srmnitc's avatar
srmnitc committed
87

Alan O'Cais's avatar
Alan O'Cais committed
88 89
The utilisation of Dask within the project came about as a result of the `E-CAM High Throughput Computing ESDW <https://www.e-cam2020.eu/event/4424/?instance_id=71>`_ held in Turin in 2018 and 2019.

srmnitc's avatar
srmnitc committed
90 91 92 93 94
Building and Testing
____________________

.. Keep the helper text below around in your module by just adding "..  " in front of it, which turns it into a comment

srmnitc's avatar
srmnitc committed
95 96 97 98 99 100 101 102 103 104 105
**Installation**  

First, clone the ``pybop`` repository by ``git clone https://github.com/srmnitc/pybop.git``.
After cloning the repository, ``pybop`` can be installed by running ``python setup.py install`` from main code directory. It can be uninstalled by ``pip uninstall pybop``. All the dependencies of ``pybop`` are installed automatically.

**Testing**  

``pybop`` also contains automated tests which use the `pytest <https://docs.pytest.org/en/latest/>`_ python library, which can be installed by ``pip install pytest``. The tests can be run by executing the command ``pytest tests/`` from the main code directory.


**Examples**  
srmnitc's avatar
srmnitc committed
106

srmnitc's avatar
srmnitc committed
107
Examples uses of ``pybop`` can be found `here <https://srmnitc.github.io/pybop/html/examples.html>`_. An `interactive notebook <https://mybinder.org/v2/gh/srmnitc/pybop/master?filepath=examples%2F>`_ using binder is also available.
srmnitc's avatar
srmnitc committed
108 109 110 111 112 113

Source Code
___________

.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!

Alan O'Cais's avatar
Alan O'Cais committed
114
The `source code <https://github.com/srmnitc/pybop>`_.  of the module can be found on GitHub. 
srmnitc's avatar
srmnitc committed
115 116


srmnitc's avatar
srmnitc committed
117 118 119 120 121 122
.. [#]  Steinhardt, PJ, Nelson, DR, Ronchetti, M. Phys. Rev. B 28, 1983.
.. [#]  Lechner, W, Dellago, C, Bolhuis, P.G. J. Chem. Phys. 125, 2011., Diaz Leines, G, Drautz, R, Rogal, J. J. Chem. Phys. 146, 2017.
.. [#]  Diaz Leines, G, Drautz, R, Rogal, J. J. Chem. Phys. 146, 2017.
.. [#]  Lechner, W, Dellago, C. J. Chem. Phys. 129, 2008.
.. [#]  Mickel, W, Kapfer, S.C, Schroder-Turk, G.E, Mecke, K. J. Chem. Phys. 138, 2013.
.. [#]  Plimpton, S. J Comp. Phys. 117, 1995.