.. PyMatterSim documentation master file, created by
   sphinx-quickstart on Sat Apr  5 18:04:13 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Python for Matters Simulations documentation!
==================================================

.. Add your content using ``reStructuredText`` syntax. See the
.. `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
.. documentation for details.

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   Getting started <self>
   reader
   writer
   neighbors
   gr
   sq
   boo_2d
   boo_3d
   orderings
   dynamics
   hessian
   vectors
   topodefect
   utils

Getting started
----------------

This toolkit is a Physics-driven data analyis of computer simulations 
for materials science, chemistry, physics, and beyond. Currently, the
library is mainly designed for computer simulations of amorphous materials
and supercooled liquids from the open source simulator LAMMPS. But the
analyis is in principle useful for any simulations, and it is straightforward
to make extensions.


Installation [recommend in a virtual environment]
----------------

Step 1: 

   You need a C++compiler that supports at least the `C++11` standard and cmake.

   Recommend using `conda` or `mamba` for installation.
   
   Linux: `conda install gxx cmake` or `mamba install gxx cmake`

   Mac OS.`conda install clang cmake` or `mamba install clang cmake`

   Windows: `conda install gxx cmake` or `mamba install gxx cmake` or Download visual studio installer from [here](https://visualstudio.microsoft.com/vs/older-downloads/) and install the C++ compiler.

   A package manager is also a good choice, for example:

   ubuntu: `sudo apt-get install g++ cmake`

   centos: `sudo yum install gcc-c++ cmake3`

   macos: `brew install gcc cmake`

   Now that you have all the build tools, pip will help you complete everything for compilation.

Step 2: 

.. code:: bash

   python3.10 -m venv .venv
   source .venv/bin/activate
   pip install PyMatterSim

   or 
   
   git clone https://gitee.com/yuanchaohu/pymattersim  --recursive
   cd  pymattersim
   pip install .

Note that this may require updated version of `setuptools`, which can be upgraded by pip or conda. 
At the same time, this may require version check of the pip certificates doing 
`open /Applications/Python\ 3.10/Install\ Certificates.command` (for MAC)
`pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org --upgrade pip`


The source code is available from this `gitee project <https://gitee.com/yuanchaohu/pymattersim>`_,
and the package is deployed at `this PYPI page <https://pypi.org/project/PyMatterSim/>`_.

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

The documentation for **PyMatterSim** is `hosted online <https://doc-pymattersim.readthedocs.io/en/latest/>`_

Citation
----------------

.. code:: bash

   @article{hu2024pymattersimpythondataanalysis,
         title={PyMatterSim: a Python Data Analysis Library for Computer Simulations of Materials Science, Physics, Chemistry, and Beyond}, 
         author={Y. -C. Hu and J. Tian},
         year={2024},
         eprint={2411.17970},
         archivePrefix={arXiv},
         primaryClass={cond-mat.mtrl-sci},
         url={https://arxiv.org/abs/2411.17970}, 
   }


Working in progress.

References
----------------

- Y.-C. Hu et al. `Origin of the boson peak in amorphous solids <https://doi.org/10.1038/s41567-022-01628-6>`_. **Nature Physics**, 18(6), 669-677 (2022) 
- Y.-C. Hu et al. `Revealing the role of liquid preordering in crystallisation of supercooled liquids <https://doi.org/10.1038/s41467-022-32241-z>`_. **Nature Communications**, 13(1), 4519 (2022)
- Y.-C. Hu et al. `Physical origin of glass formation from multicomponent system <https://www.science.org/doi/10.1126/sciadv.abd2928>`_. **Science Advances** 6 (50), eabd2928 (2020)
- Y.-C. Hu et al. `Configuration correlation governs slow dynamics of supercooled metallic liquids <https://doi.org/10.1073/pnas.1802300115>`_. **Proceedings of the National Academy of Sciences U.S.A.**, 115(25), 6375-6380 (2018)
- Y.-C. Hu et al. `Five-fold symmetry as indicator of dynamic arrest in metallic glass-forming liquids <https://doi.org/10.1038/ncomms9310>`_. **Nature Communications**, 6(1), 8310 (2015) 


Unit Tests
----------------
The unit tests for **PyMatterSim** are included in the github repository
and are configured to be run using the python :mod:`UnitTest` library:

.. code-block:: bash

   # auto-run tests with shell scripts
   cd shell
   bash *sh

   # run individual tests
   cd tests/yourdir/
   python *py


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`