From dc6297bd7f6afb752d252d0bc4cd73e6d087391d Mon Sep 17 00:00:00 2001 From: mahe Date: Tue, 18 Feb 2020 17:41:35 -0600 Subject: [PATCH] update doc, add readthedocs.yml --- .readthedocs.yml | 8 ++++++++ doc/conf.py | 11 +++++++---- doc/documentation.rst | 2 +- doc/index.rst | 12 ++++++------ doc/installation.rst | 19 ++++++++++++++++--- doc/requirements.txt | 6 ++++++ doc/tutorial.rst | 8 ++++---- 7 files changed, 48 insertions(+), 18 deletions(-) create mode 100644 .readthedocs.yml create mode 100644 doc/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..e178f5e --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,8 @@ +sphinx: + configuration: doc/conf.py + +python: + version: 3.7 + install: + -requirements: doc/requirements.txt + diff --git a/doc/conf.py b/doc/conf.py index 91c3423..0d1ecb2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -10,15 +10,15 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('../')) # -- Project information ----------------------------------------------------- project = 'pyzfs' -copyright = '2020, He Ma, Marco Govoni, Giulia Galli' +copyright = '2020, University of Chicago' author = 'He Ma, Marco Govoni, Giulia Galli' @@ -27,8 +27,11 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. +master_doc = 'index' + extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] +autodoc_mock_imports = ["mpi4py"] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/documentation.rst b/doc/documentation.rst index 5f2a24a..2e2df79 100644 --- a/doc/documentation.rst +++ b/doc/documentation.rst @@ -3,7 +3,7 @@ Code documentation ================== -**pyzfs** detailed documentation. +**PyZFS** code documentation. ZFS ------ diff --git a/doc/index.rst b/doc/index.rst index 5ed3554..eee705c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,12 +3,12 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to pyzfs's documentation! +Welcome to PyZFS's documentation! ================================= -**pyzfs** is an MPI-parallelized Python code for the first-principles calculation of the spin-spin zero-field-splitting (ZFS) tensor based on wavefunctions obtained from density functional theory (DFT) calculations. +**PyZFS** is an MPI-parallelized Python code for the first-principles calculation of the spin-spin zero-field-splitting (ZFS) tensor based on wavefunctions obtained from density functional theory (DFT) calculations. -**pyzfs** can work with wavefunctions generated by various plane-wave pseudopotential DFT codes including [**Quantum Espresso**](https://www.quantum-espresso.org/) and [**Qbox**](http://qboxcode.org/). **pyzfs** also supports the standard cube file format. **pyzfs** computes the spin-spin ZFS tensor from normalized pseudo-wavefunctions without projected-augmented-wave type corrections and is designed to be scalable to large calculations. For instance, **pyzfs** has been applied to study spin-defects in semiconductors using supercells containing thousands of valence electrons. +**PyZFS** can work with wavefunctions generated by various plane-wave pseudopotential DFT codes including [**Quantum Espresso**](https://www.quantum-espresso.org/) and [**Qbox**](http://qboxcode.org/). **PyZFS** also supports the standard cube file format. **PyZFS** computes the spin-spin ZFS tensor from normalized pseudo-wavefunctions without projected-augmented-wave type corrections and is designed to be scalable to large calculations. For instance, **PyZFS** has been applied to study spin-defects in semiconductors using supercells containing thousands of valence electrons. -------- @@ -23,11 +23,11 @@ Welcome to pyzfs's documentation! .. glossary:: :ref:`installation` - Instructions on how to install the **pyzfs** package. + Instructions on how to install the **PyZFS** package. :ref:`tutorial` - Demonstration of usage of **pyzfs** with wavefunctions from various DFT codes. + Demonstration of usage of **PyZFS** with wavefunctions from various DFT codes. :ref:`documentation` - Detailed documentation of the **pyzfs** package. + Detailed documentation of the **PyZFS** package. diff --git a/doc/installation.rst b/doc/installation.rst index 91351e9..8beeb40 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -4,22 +4,35 @@ Installation ============ -**pyzfs** can be installed with **pip** by running following command in the project root folder containing **setup.py** +**PyZFS** uses the **mpi4py** package for parallelization. An existing MPI implementation (e.g. **MPICH** or **OpenMPI**) is required to install **mpi4py** and **PyZFS**. Many supercomputers provide modules for pre-compiled MPI implementations. To install MPI manually (taking **MPICH** as example), execute the following command on Linux + +.. code:: bash + + $ sudo apt-get install mpich libmpich-dev + +or execute the following command on Mac + +.. code:: bash + + $ brew install mpich + +**PyZFS** can be installed with **pip** by executing the following command in the project root folder containing **setup.py** .. code:: bash $ pip install . -To install **pyzfs** in editable mode +To install **PyZFS** in editable mode .. code:: bash $ pip install -e . -**pyzfs** is designed to be compatible with both Python 2 and Python 3, and depends on the following packages: +**PyZFS** is designed to be compatible with both Python 2 and Python 3, and depends on the following packages: - ``numpy`` - ``scipy`` - ``mpi4py`` + - ``h5py`` - ``ase`` - ``lxml`` diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..ed2a46f --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,6 @@ +numpy +scipy +h5py +ase +lxml + diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 75ce99f..1e4c079 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -4,7 +4,7 @@ Tutorial ============ -After installation, **pyzfs** can be executed in two manners: +After installation, **PyZFS** can be executed in two manners: 1. Construct WavefunctionLoader and ZFSCalculation loader from within Python terminal or Jupyter notebook, and call ZFSCalculation.solve to perform the calculation. @@ -24,7 +24,7 @@ For parallel execution, use the following command $ mpiexec [-n num_of_processes] python -m pyzfs.exec.runzfs [--flags] -where `num_of_processes` is the number of processes. **pyzfs** distributes the calculations on a square grid of processes. If `num_of_processes` is not a square number, **pyzfs** will use the largest square number of processes smaller than `num_of_processes` for calculations. +where `num_of_processes` is the number of processes. **PyZFS** distributes the calculations on a square grid of processes. If `num_of_processes` is not a square number, **PyZFS** will use the largest square number of processes smaller than `num_of_processes` for calculations. Acceptable flags [`--flags`] are listed below, for detailed explanation see `pyzfs.exec.runzfs.py`. @@ -48,9 +48,9 @@ Some example execution commands with flags: .. code:: bash -mpiexec python -m pyzfs.exec.runzfs --wfcfmt qeh5 --prefix pwscf + $ mpiexec python -m pyzfs.exec.runzfs --wfcfmt qeh5 --prefix pwscf .. code:: bash -mpiexec python -m pyzfs.exec.runzfs --wfcfmt qbox --filename gs.xml + $ mpiexec python -m pyzfs.exec.runzfs --wfcfmt qbox --filename gs.xml