add comments and other minor details

docs/api.rst

@@ -7,3 +7,5 @@ This is the Python API for phonoLAMMPS
 .. automodule:: phonolammps
     :members:
 
+
+end

docs/conf.py

@@ -83,18 +83,8 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+autodoc_mock_imports = ['lammps', 'lammps', 'phonopy']
 
-# autodoc_mock_imports = ['lammps', 'lammps.lammps']
-
-from unittest.mock import MagicMock
-
-class Mock(MagicMock):
-    @classmethod
-    def __getattr__(cls, name):
-        return MagicMock()
-
-MOCK_MODULES = ['lammps']
-sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
 # -- Options for HTML output ----------------------------------------------
 

docs/requirements.rst

@@ -14,6 +14,9 @@ Mandatory requirements
 - phonopy (https://atztogo.github.io/phonopy/)
 - LAMMPS python interface (https://lammps.sandia.gov/doc/Python_library.html)
 
+*Note: LAMMPS python interface may need to be installed manually from LAMMPS source.
+Check LAMMPS manual for further information*
+
 Optional requirements for phonon band structure preview
 -------------------------------------------------------
 - matplotlib

examples/Si/si_api.py

@@ -27,6 +27,7 @@
 
 structure = phlammps.get_unitcell()
 
+
 # define structure for dynaphopy
 dp_structure = Structure(cell=structure.get_cell(),  # cell_matrix, lattice vectors in rows
                          scaled_positions=structure.get_scaled_positions(),

phonolammps/__init__.py

@@ -26,7 +26,6 @@ class PhonoBase:
     * __init__()
     * get_forces()
 
-
     """
 
     def get_path_using_seek_path(self):
@@ -39,12 +38,11 @@ def get_path_using_seek_path(self):
         try:
             import seekpath
 
-            structure = self._structure
-            cell = structure.get_cell()
-            positions = structure.get_scaled_positions()
-            numbers = np.unique(structure.get_chemical_symbols(), return_inverse=True)[1]
-            structure = (cell, positions, numbers)
-            path_data = seekpath.get_path(structure)
+            cell = self._structure.get_cell()
+            positions = self._structure.get_scaled_positions()
+            numbers = np.unique(self._structure.get_chemical_symbols(), return_inverse=True)[1]
+
+            path_data = seekpath.get_path((cell, positions, numbers))
 
             labels = path_data['point_coords']
 
@@ -71,6 +69,7 @@ def get_force_constants(self, include_data_set=False):
             phonon = get_phonon(self._structure,
                                 setup_forces=False,
                                 super_cell_phonon=self._supercell_matrix,
+                                primitive_matrix=self._primitive_matrix,
                                 NAC=self._NAC,
                                 symmetrize=self._symmetrize)
 
@@ -102,6 +101,8 @@ def get_force_constants(self, include_data_set=False):
     def plot_phonon_dispersion_bands(self):
         """
         Plot phonon band structure using seekpath automatic k-path
+        Warning: The labels may be wrong if the structure is not standarized
+
         """
 
         import matplotlib.pyplot as plt
@@ -238,6 +239,8 @@ def __init__(self,
                  use_NAC=False,
                  symmetrize=True):
         """
+        Main PhonoLAMMPS class
+
         :param lammps_input: LAMMPS input file name or list of commands
         :param supercell_matrix:  3x3 matrix supercell
         :param primitive cell:  3x3 matrix primitive cell
@@ -289,6 +292,7 @@ def get_units(self, commands_list):
     def get_forces(self, cell_with_disp):
         """
         Calculate the forces of a supercell using lammps
+
         :param cell_with_disp: supercell from which determine the forces
         :return: numpy array matrix with forces of atoms [Natoms x 3]
         """
@@ -302,7 +306,6 @@ def get_forces(self, cell_with_disp):
             cmd_list += ['-echo', 'none', '-screen', 'none']
 
         lmp = lammps.lammps(cmdargs=cmd_list)
-        # lmp.file(self._lammps_input_file)
         lmp.commands_list(self._lammps_commands_list)
         lmp.command('replicate {} {} {}'.format(*supercell_sizes))
         lmp.command('run 0')
@@ -350,6 +353,9 @@ def __init__(self,
                  use_NAC=False,
                  symmetrize=True):
         """
+        Experimental class to use Tinker to calculate forces, can be used
+        as an example to how to expand phonoLAMMPS to other software
+
         :param txyz_input_file:  TXYZ input file name (see example)
         :param supercell_matrix:  3x3 matrix supercell
         :param primitive cell:  3x3 matrix primitive cell
@@ -444,7 +450,7 @@ def get_forces(self, cell_with_disp):
     phonon = get_phonon(structure,
                         setup_forces=False,
                         super_cell_phonon=[[2, 0, 0], [0, 2, 0], [0, 0, 2]],
-                        #NAC=self._NAC,
+                        NAC=False,
                         symmetrize=True)
 
 

phonolammps/phonopy_link.py

@@ -23,27 +23,57 @@ def get_atom_types(self):
 
 
 class ForceConstants:
+    """
+    Define Force constants object
+    """
     def __init__(self, force_constants, supercell=np.identity(3)):
+        """
+        Initialize force constants
+
+        :param force_constants: array matrix containing the force constants (phonopy format)
+        :param supercell: 3x3 array (or list of lists) containing the supercell definition
+        """
 
         self._force_constants = np.array(force_constants)
         self._supercell = np.array(supercell)
 
     def get_array(self):
+        """
+        get the force constants array in phonopy format
+
+        :return: force constants array
+        """
         return self._force_constants
 
     def get_supercell(self):
+        """
+        get the supercell (respect to the unit cell) in which the force constants are defined
+
+        :return: 3x3 array containing the supercell
+        """
         return self._supercell
 
 
 def get_phonon(structure,
                NAC=False,
                setup_forces=True,
                super_cell_phonon=np.identity(3),
-               primitive_axis=np.identity(3),
+               primitive_matrix=np.identity(3),
                symmetrize=True):
+    """
+    Return a phonopy phonon object (instance of the class Phonon)
+    
+    :param structure: unit cell matrix (lattice vectors in rows)
+    :param NAC: (Bool) activate/deactivate Non-analytic corrections
+    :param setup_forces: (Bool) decide if pre-calculate harmonic forces in phonon object
+    :param super_cell_phonon: 3x3 array containing the supercell to be used to calculate the force constants
+    :param primitive_matrix: 3x3 array containing the primitive axis (in rows) which define the primitive cell
+    :param symmetrize: decide if symmetrize the force constants
+    :return: phonopy phonon object
+    """
 
     phonon = Phonopy(structure, super_cell_phonon,
-                     primitive_matrix=primitive_axis,
+                     primitive_matrix=primitive_matrix,
                      symprec=1e-5, is_symmetry=symmetrize)
 
     # Non Analytical Corrections (NAC) from Phonopy [Frequencies only, eigenvectors no affected by this option]
@@ -76,10 +106,22 @@ def get_phonon(structure,
 def obtain_phonon_dispersion_bands(structure, bands_ranges, force_constants, supercell,
                                    NAC=False, band_resolution=30, band_connection=False,
                                    primitive_matrix=np.identity(3)):
-
+    """
+    Get the phonon dispersion bands in phonopy format
+
+    :param structure: unit cell matrix (lattice vectors in rows)
+    :param bands_ranges: define the path in the reciprocal space (phonopy format)
+    :param force_constants: force constants array ( in phonopy format)
+    :param supercell: 3x3 array containing the supercell to be used to calculate the force constants
+    :param NAC: (Bool) activate/deactivate Non-analytic corrections
+    :param band_resolution: define number of points in path in the reciprocal space
+    :param band_connection: decide if bands will be all connected or in segments
+    :param primitive_matrix: 3x3 array containing the primitive axis (in rows) which define the primitive cell
+    :return:
+    """
     phonon = get_phonon(structure, NAC=NAC, setup_forces=False,
                         super_cell_phonon=supercell,
-                        primitive_axis=primitive_matrix)
+                        primitive_matrix=primitive_matrix)
 
     phonon.set_force_constants(force_constants)
 
@@ -92,3 +134,18 @@ def obtain_phonon_dispersion_bands(structure, bands_ranges, force_constants, sup
     phonon.set_band_structure(bands, is_band_connection=band_connection, is_eigenvectors=True)
 
     return phonon.get_band_structure()
+
+
+def get_primitive_structure(structure, primitive_matrix=np.eye(3)):
+    from phonopy.structure.cells import get_primitive
+    return get_primitive(structure, primitive_matrix)
+
+
+def standarize_structure(structure):
+    from phonopy.structure.spglib import standardize_cell
+
+    lattice, positions, numbers = standardize_cell(structure, to_primitive=False, no_idealize=False, symprec=1e-5)
+
+    return PhonopyAtoms(positions=positions,
+                        numbers=numbers,
+                        cell=lattice)

requirements.txt

@@ -5,7 +5,7 @@
 # mandatory
 numpy>=1.8.2
 phonopy
-# lammps
+# lammps (Need to be installed manually from LAMMPS source)
 
 # (optional) for plotting phonon band structure
 matplotlib