Merge pull request #1 from Countoscope/added-tutorial

added simple tutorial to doc

Author: simongravelle

README.rst

@@ -1,6 +1,15 @@
 Countoscope documentation
 =========================
 
+This repository is dedicated to the documentation of the Countoscope. The documentation
+is generated by |Sphinx|, a powerful
+documentation generator for Python projects that transforms reStructuredText into
+HTML, LaTeX, and other formats. 
+
+.. |Sphinx| raw:: html
+
+    <a href="https://www.sphinx-doc.org" target="_blank">Sphinx</a>
+
 How to
 ------
 

docs/source/conf.py

@@ -15,6 +15,7 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.mathjax',
 ]
 
 templates_path = ['_templates']

docs/source/index.rst

@@ -8,14 +8,18 @@ Countoscope
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree:: 
+   :caption: Tutorial
+   :maxdepth: 2
+   :hidden:
+   
+   tutorials/tutorial
 
-.. toctree::
+.. toctree:: 
+   :caption: Python modules
    :maxdepth: 2
    :hidden:
 
    modules/trajectorytool
    modules/boxcountingtool
-   modules/countoscope
+   modules/countoscope

docs/source/tutorials/tutorial.rst

@@ -0,0 +1,84 @@
+Tutorial
+========
+
+Installation
+------------
+
+In order to install the Countoscope Python tool, clone the repository using:
+
+..  code:: bash
+
+  git clone https://github.com/Countoscope/countoscope.git
+
+Install all the required Python packages using:
+
+..  code:: bash
+
+    pip install -r requirements.txt
+
+Then, type:
+
+..  code:: bash
+
+    pip install .
+
+Use
+---
+
+In a Python script or a Jupyter Notebook, define the path to the data trajectory
+file. For instance, using the `3D-closed` dataset provided in the `datasets`
+repository:
+
+..  code:: python
+
+  path_to_data = "/mpath/datasets/datasets/3D-closed/trajectory.xyz"
+
+Import the Countoscope as well as NumPy by typing:
+
+..  code:: python
+
+  from countoscope import Countoscope
+  import numpy as np
+
+The trajectory file `trajectory.xyz` corresponds to a system of 190 particles in
+a :math:`(30 Å)^3` box. Let us define the system size as a NumPy array:
+
+..  code:: python
+
+    system_size = np.array([30, 30, 30])
+
+Finally, let us choose a grid size for the Countoscope measurement:
+
+..  code:: python
+
+    box_size=np.array([10, 10, 10])
+
+Then, launch the Countoscope calculation using *trajectory_file*, *system_size*,
+and *box_size* as input parameters:
+
+..  code:: python
+
+    results = Countoscope(trajectory_file = path_to_data,
+                        system_size=system_size,
+                        box_size=box_size)
+    results.run()
+
+After the calculation is done, all the computed data can be obtained from the
+`results`object. For instance, for :math:`<N>`, type:
+
+..  code:: python
+
+    print(np.round(results.mean_of_N,2))
+
+which will return:
+
+..  code:: bash
+
+    0.84
+
+To plot :math:`<\Delta N^2>`, let us import Pyplot first:
+
+..  code:: python
+
+    import matplotlib.pyplot as plt
+    plt.loglog(results.delta_n2)