MolSSI-Education · yuanzhou0827 · Jul 30, 2019 · Jul 30, 2019 · Jul 30, 2019 · Jul 30, 2019
diff --git a/docs/.Contributors.rst.swp b/docs/.Contributors.rst.swp
diff --git a/docs/API.rst b/docs/API.rst
@@ -0,0 +1,90 @@
+.. _API:
+
+=================
+API Documentation
+=================
+
+Initialize the system
++++++++++++++++++++++
+
+For initialize the sysetm, the ``generate_initial_state()`` will generate an initial state either in a random way or import from a *.xyz* file.
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.generate_initial_state
+
+.. tip::
+
+    The *.xyz* file will give the coordinates of all the particles. If the method is *random*, num_particles and box_length are required arguments.
+
+Class Box
++++++++++
+
+This is the class to generate a box, with the particles parameters.
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.Box
+
+In the class, we have functions as follows:
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.Box.wrap
+    mc_lj_potential.Box.minimum_image_distance
+
+And we set the volume and num_particles as properties, can be called as:
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.Box.volume
+    mc_lj_potential.Box.num_particles    
+
+
+Class MCState
++++++++++++++
+
+In the class ``MCState``, we will have functions for the energies in the defined system:
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.MCState
+
+In the class, we can calculate total pair energy, tail correction, unit energy and particle energy by functions as follows:
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.MCState.calculate_total_pair_energy
+    mc_lj_potential.MCState.calculate_tail_correction
+    mc_lj_potential.MCState.calculate_unit_energy
+    mc_lj_potential.MCState.get_particle_energy
+
+
+Monte Carlo Steps
++++++++++++++++++
+
+After that the Monte Carlo will determine the acceptance of each movement with ``accept_or_reject()``:
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.accept_or_reject
+
+
+Optimization
+++++++++++++
+
+Optimization of the scale of displacement can be done by ``adjust_displacement()``:
+
+.. autosummary::
+    :toctree: autosummary
+
+    mc_lj_potential.adjust_displacement
+
+
diff --git a/docs/Acknowledgement.rst b/docs/Acknowledgement.rst
@@ -0,0 +1,10 @@
+.. _Acknowledgement:
+
+===============
+Acknowledgement
+===============
+
+MolSSI Software Summer School
+-----------------------------
+
+Detailed information is at  `MolSSI <https://molssi.org>`_.
diff --git a/docs/Contributors.rst b/docs/Contributors.rst
@@ -0,0 +1,33 @@
+.. _Contributors:
+
+============
+Contributors
+============
+
+
+Arpit Bansal
+  | [email protected]
+  | University at Buffalo (SUNY)
+
+
+
+Govinda KC
+  | [email protected]
+  | University of Texas at El Paso
+
+
+
+Madison Berger
+  | [email protected]
+  | University: University of North Texas
+
+
+Rishabh D Guha
+  | [email protected]
+  | UnivNorth Carolina State University
+
+
+Yuan Zhou
+  | [email protected]
+  | University of Michigan, Ann Arbor
+
diff --git a/docs/Makefile b/docs/Makefile
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
@@ -15,4 +15,4 @@ make html
 ```
 
 The compiled docs will be in the `_build` directory and can be viewed by opening `index.html` (which may itself 
-be inside a directory called `html/` depending on what version of Sphinx is installed).
+be inside a directory called `html/` depending on what version of Sphinx is installed).
diff --git a/docs/Tutorial.rst b/docs/Tutorial.rst
@@ -0,0 +1,139 @@
+.. _Tutorial:
+
+========
+Tutorial
+========
+
+**mc_lj_potential** is a python package to carry out Monte Carlo simulation of Lennard Jones particles. By calling different functions in the package, users can get the total pair energy, tail correction, particle energy and unit energy of a defined system with specific cubic box size, number of particles and their coordinates.
+
+generate_initial_state
+++++++++++++++++++++++
+
+.. code-block:: python
+
+    #mc_lj.py
+    import mc_lj_potential as mc
+    import numpy as np
+    np.random.seed(123)
+    num_particles = 100
+    box_length = 10.0
+    coordinates =  mc.generate_initial_state(method = 'random', num_particles = num_particles, box_length = box_length)
+    print(coordinates)
+
+.. note::
+
+    Attention: The ``np.random.seed(123)`` here is used to make sure users can get the same results by following  the tutorials below. There is no need to generate the random seed forcely in users' simulation.
+
+save the script as mc_lj.py, run it, then the output is 100 random coordinates:
+
+.. code-block:: bash
+
+    ~/my_project$ python mc_lj.py
+    [[-6.46469186e+00 -2.36139335e+00 -1.76851454e+00]
+     [-5.01314769e+00 -6.69468970e+00 -3.73106460e+00]
+     [-9.30764198e+00 -6.34829739e+00 -4.30931901e+00]
+     [-3.42117518e+00 -2.93178016e+00 -6.79049707e+00]
+     [-3.88572245e+00 -9.67789661e-02 -3.48044255e+00]
+     [-6.87995406e+00 -1.32491730e+00 -1.25451756e+00]
+     [-4.81551374e+00 -4.81827587e+00 -5.84400959e+00]
+     ...
+
+.. note::
+
+    User are allow to import coordinates from a file as well. Instead of ``mc.generate_initial_state(method = 'random', 
+    num_particles = num_particles, box_length = box_length)``, use 
+    ``mc.generate_initial_state(method = 'file', box_length = box_length)``.
+
+calculate energy in the system
+++++++++++++++++++++++++++++++
+
+In order to calculate the energy in the system, we need to initialize our box into unit box with ``wrap()`` and ``minimum_image_distance()``.
+
+.. code-block:: python
+
+    box = mc.Box(coordinates = coordinates, box_length = box_length)
+    print(box.coordinates)
+
+add this into mc_lj.py, run it:
+
+.. code-block:: bash
+
+    ~/my_project$ python mc_lj.py
+    [[-6.46469186e+00 -2.36139335e+00 -1.76851454e+00]
+     [-5.01314769e+00 -6.69468970e+00 -3.73106460e+00]
+     [-9.30764198e+00 -6.34829739e+00 -4.30931901e+00]
+     [-3.42117518e+00 -2.93178016e+00 -6.79049707e+00]
+     [-3.88572245e+00 -9.67789661e-02 -3.48044255e+00]
+     [-6.87995406e+00 -1.32491730e+00 -1.25451756e+00]
+     [-4.81551374e+00 -4.81827587e+00 -5.84400959e+00]
+     ...
+
+it will update our coordinates into the box.
+
+calculate total pair energy
+---------------------------
+
+.. code-block:: python
+
+    mcs = mc.MCState(box1 = box, cutoff = 3.0)
+    total_pair_energy = mcs.calculate_total_energy()
+    print("total pair energy of the system is",total_pair_energy)
+
+The output is:
+
+.. code-block:: bash
+
+    ~/my_project$ python mc_lj.py
+    total pair energy of the system is 18677707323853.145
+
+
+calculate tail correction
+-------------------------
+
+.. code-block:: python
+
+    tail_correction = mcs.calculate_tail_correction()
+    print("tail correction of the system is", tail_correction)
+
+The output is:
+
+.. code-block:: bash
+
+     ~/my_project$ python mc_lj.py
+     tail correction of the system is -3.101388808502446
+
+
+calculate unit energy
+---------------------
+
+.. code-block:: python
+
+    unit_energy = mcs.calculate_unit_energy()
+    print("unit energy of the system is",unit_energy)
+
+The output is:
+
+.. code-block:: bash
+
+    ~/my_project$ python mc_lj.py
+    unit energy of the system is 186777073238.50043
+
+
+get particle energy
+-------------------
+
+For example, the particle energy of the first particle can be obtained by ``mcs.get_particle_energy(0)`` where the **index 0** means the first particle in the system. 
+
+.. code-block:: python
+
+    particle_energy = mcs.get_particle_energy(0)
+    print("particle energy of the first particle is",particle_energy)
+
+The output is:
+
+.. code-block:: bash
+
+    ~/my_project$ python mc_lj.py
+    particle energy of the first particle is 12.663401162199152
+
+
diff --git a/docs/autosummary/mc_lj_potential.Box.minimum_image_distance.rst b/docs/autosummary/mc_lj_potential.Box.minimum_image_distance.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.Box.minimum\_image\_distance
+==============================================
+
+.. currentmodule:: mc_lj_potential
+
+.. automethod:: Box.minimum_image_distance
diff --git a/docs/autosummary/mc_lj_potential.Box.num_particles.rst b/docs/autosummary/mc_lj_potential.Box.num_particles.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.Box.num\_particles
+====================================
+
+.. currentmodule:: mc_lj_potential
+
+.. autoproperty:: Box.num_particles
diff --git a/docs/autosummary/mc_lj_potential.Box.rst b/docs/autosummary/mc_lj_potential.Box.rst
@@ -0,0 +1,31 @@
+mc\_lj\_potential.Box
+=====================
+
+.. currentmodule:: mc_lj_potential
+
+.. autoclass:: Box
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~Box.__init__
+      ~Box.minimum_image_distance
+      ~Box.wrap
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~Box.num_particles
+      ~Box.volume
+
+
diff --git a/docs/autosummary/mc_lj_potential.Box.volume.rst b/docs/autosummary/mc_lj_potential.Box.volume.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.Box.volume
+============================
+
+.. currentmodule:: mc_lj_potential
+
+.. autoproperty:: Box.volume
diff --git a/docs/autosummary/mc_lj_potential.Box.wrap.rst b/docs/autosummary/mc_lj_potential.Box.wrap.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.Box.wrap
+==========================
+
+.. currentmodule:: mc_lj_potential
+
+.. automethod:: Box.wrap
diff --git a/docs/autosummary/mc_lj_potential.MCState.calculate_tail_correction.rst b/docs/autosummary/mc_lj_potential.MCState.calculate_tail_correction.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.MCState.calculate\_tail\_correction
+=====================================================
+
+.. currentmodule:: mc_lj_potential
+
+.. automethod:: MCState.calculate_tail_correction
diff --git a/docs/autosummary/mc_lj_potential.MCState.calculate_total_pair_energy.rst b/docs/autosummary/mc_lj_potential.MCState.calculate_total_pair_energy.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.MCState.calculate\_total\_pair\_energy
+========================================================
+
+.. currentmodule:: mc_lj_potential
+
+.. automethod:: MCState.calculate_total_pair_energy
diff --git a/docs/autosummary/mc_lj_potential.MCState.calculate_unit_energy.rst b/docs/autosummary/mc_lj_potential.MCState.calculate_unit_energy.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.MCState.calculate\_unit\_energy
+=================================================
+
+.. currentmodule:: mc_lj_potential
+
+.. automethod:: MCState.calculate_unit_energy
diff --git a/docs/autosummary/mc_lj_potential.MCState.get_particle_energy.rst b/docs/autosummary/mc_lj_potential.MCState.get_particle_energy.rst
@@ -0,0 +1,6 @@
+mc\_lj\_potential.MCState.get\_particle\_energy
+===============================================
+
+.. currentmodule:: mc_lj_potential
+
+.. automethod:: MCState.get_particle_energy