Merge pull request #19 from PhasesResearchLab/docs

Update docs

Author: nhew1994

README.md

@@ -1,26 +1,36 @@
-## pyzentropy
+# pyzentropy
 [![Testing](https://github.com/nhew1994/pyzentropy/actions/workflows/test.yml/badge.svg)](https://github.com/nhew1994/pyzentropy/actions/workflows/test.yml)
 
-## Installation
-It is recommended to first set up a virtual environment using Conda:
+# Installation
+## Recommended: Create a Virtual Environment
 
-    conda create -n pyzentropy python=3.12      
+Using Conda:
+
+    conda create -n pyzentropy python=3.12
     conda activate pyzentropy
 
-Clone the main branch of the repository:
-    
+## Install pyzentropy
+### From PyPI (coming soon)
+
+    python -m pip install pyzentropy
+
+<sub>PyPI installation will be available in a future release. For now, please install from source as described below.</sub>
+
+### From Source 
+
+Clone the repository:
+
     git clone https://github.com/nhew1994/pyzentropy.git
+    cd pyzentropy
+    python -m pip install -e .
 
 Or clone a specific branch:
-    
-    git clone -b <branch_name> https://github.com/nhew1994/pyzentropy.git
-
-  Then move to `pyzentropy` directory and install in editable (`-e`) mode.
 
+    git clone -b <branch_name> https://github.com/nhew1994/pyzentropy.git
     cd pyzentropy
     python -m pip install -e .
 
-## Example notebooks
+# Example notebooks
 Click the badge below to open the project in GitHub Codespaces.  
 Then, browse the `examples/codespace` folder to explore and run the example notebooks:
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

docs/_source/installation.md

@@ -0,0 +1,34 @@
+
+# Installation
+
+
+<span style="font-size:1.3em; font-weight:bold">Recommended: Create a Virtual Environment</span>
+
+Using Conda:
+
+    conda create -n pyzentropy python=3.12
+    conda activate pyzentropy
+
+
+<span style="font-size:1.3em; font-weight:bold">Install pyzentropy</span>
+
+<span style="font-size:1.1em; font-weight:bold">From PyPI (coming soon)</span>
+
+    python -m pip install pyzentropy
+
+**Note:** PyPI installation will be available in a future release. For now, please install from source as described below.
+
+
+<span style="font-size:1.1em; font-weight:bold">From Source</span>
+
+Clone the repository:
+
+    git clone https://github.com/nhew1994/pyzentropy.git
+    cd pyzentropy
+    python -m pip install -e .
+
+Or clone a specific branch:
+
+    git clone -b <branch_name> https://github.com/nhew1994/pyzentropy.git
+    cd pyzentropy
+    python -m pip install -e .

docs/_source/overview.rst

@@ -0,0 +1,50 @@
+==========    
+pyzentropy
+==========
+
+**pyzentropy** is an open-source Python package for first-principles thermodynamic calculations 
+based on the recursion property of entropy. For a system consisting of multiple configurations, 
+each with its own intrinsic entropy, the total entropy can be written as
+
+.. math::
+
+   S = -k_B \sum_{k=1}^{N} p_k \ln p_k + \sum_{k=1}^{N} p_k S_k
+
+where :math:`k` indexes the :math:`N` configurations and :math:`p_k` is the probability 
+of configuration :math:`k`. The first term corresponds to the *configurational entropy*, 
+while the second term is the probability-weighted sum of the *intra-configurational entropies*.
+
+This expression is based on the recursion property of entropy, well known in information 
+theory, which allows the system’s microstates to be coarse-grained into partitions indexed 
+by :math:`k`. We also refer to this as the *zentropy* method, which combines *Zustandssumme* 
+("sum over states") with *entropy*, emphasizing that the total entropy is constructed by 
+summing over configurations that themselves possess intrinsic entropy.
+
+The zentropy method allows microstates sharing similar physical characteristics to be 
+grouped into configurations, making the total entropy easier to compute by first calculating
+the entropies of individual configurations. In practice, the intra-configurational entropies 
+:math:`S_k` can be obtained using established open-source tools such as Phonopy and DFTTK.
+
+Key Features
+------------  
+
+Input Data
+^^^^^^^^^^
+
+For each configuration :math:`k`:
+
+- Helmholtz free energy :math:`F_k(T,V)` and its first and second derivatives with respect to :math:`V`
+- Entropy :math:`S_k(T,V)` and heat capacity at constant volume :math:`C_{V,k}(T,V)`
+
+Capabilities
+^^^^^^^^^^^^
+
+**pyzentropy** enables the following analyses and visualizations:
+
+- Generate 2D plots of configuration-dependent properties as functions of :math:`T` or :math:`V`.
+- Compute system-level properties as a function of temperature :math:`T` and volume :math:`V`.
+- Calculate thermodynamic properties at fixed pressure :math:`P`.
+- Construct :math:`T\!-\!V` and :math:`P\!-\!T` phase diagrams *(currently limited to a single common tangent construction)*.
+- Generate 2D plots of system properties as a function of :math:`T` or :math:`V`.
+- Generate 2D plots of system properties at fixed :math:`P` as a function of :math:`T`.
+- Generate 3D thermodynamic landscapes (in development).

docs/_source/tutorials.md

@@ -0,0 +1,10 @@
+
+# Tutorials
+
+Below are the currently available examples:
+
+**Examples:**
+
+- **Fe<sub>3</sub>Pt**: Example of applying zentropy to the 3 lowest energy configurations in Fe<sub>3</sub>Pt 12-atom supercell. The Helmholtz energies were calculated using the energy–volume curves and the Debye–Grüneisen model.
+
+The Jupyter notebooks are located in `examples/codespace` and can be run using **GitHub Codespaces** or locally in your preferred IDE (e.g., VS Code).

docs/api.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+   pyzentropy.configuration
+   pyzentropy.system
+   pyzentropy.utilities
+   :maxdepth: 6