Update docstrings

.github/workflows/gh-pages.yaml

@@ -0,0 +1,38 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - main  # Set a branch name to trigger deployment
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.110.0'
+
+      - name: Build
+        run: hugo --minify
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        # If you're changing the branch from main,
+        # also change the `main` in `refs/heads/main`
+        # below accordingly.
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

.github/workflows/static.yml

@@ -37,7 +37,7 @@ jobs:
         uses: actions/upload-pages-artifact@v2
         with:
           # Upload entire repository
-          path: 'build'
+          path: 'docs/'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2

Building_docs.md

@@ -3,6 +3,7 @@ To build the documentation you will need the following packages:
 - sphinx
 - sphinx-apidoc
 - autodoc
+- intersphinx
 
 ### Steps
 1. First, generate the autdoc sources for the API reference from the root using
@@ -15,4 +16,6 @@ To build the documentation you will need the following packages:
 
 This will generate the docs in the `_build` directory
 
+3. For deploying, we follow the guide here: https://medium.com/flycode/how-to-deploy-a-static-website-for-free-using-github-pages-8eddc194853b
+
 

README.md

@@ -1,3 +1,5 @@
+<img src="../figures/logo.png" alt="drawing" width="150"/>
+
 <!-- [![code coverage](https://img.shields.io/codecov/c/gh/materialsproject/jobflow/main)](https://codecov.io/gh/materialsproject/jobflow/) -->
 <!-- [![pypi version](https://img.shields.io/pypi/v/jobflow?color=blue)](https://pypi.org/project/jobflow/) -->
 <!-- ![supported python versions](https://img.shields.io/pypi/pyversions/jobflow) -->

asimtools/asimmodules/benchmarking/parity.py

@@ -31,8 +31,8 @@ def calc_parity_data(
 
     :param subset: List of atoms instances
     :type subset: List
-    :param calc: ASE Cailculator instance
-    :type calc: Calculator
+    :param calc_id: calc_id specification
+    :type calc_id: str
     :param properties: Properties to evaluate, choose from "energy", \
         "forces" and "stress", defaults to ('energy', 'forces', 'stress')
     :type properties: List, optional

asimtools/asimmodules/elastic_constants/cubic_energy_expansion.py

@@ -85,11 +85,20 @@ def cubic_energy_expansion(
     deltas: Sequence[float] = (-0.01,-0.0075,-0.005,0.00,0.005,0.0075,0.01),
     ase_cubic_eos_args: Optional[Dict] = None,
 ) -> Dict:
-    '''
-    Calculates B, C11, C12 and C44 elastic constants of a structure with cubic
-    symmetry
-    '''
-
+    """Calculates B (Bulk modulus), C11, C12 and C44 elastic constants of 
+    a structure with cubic symmetry
+
+    :param calc_id: calc_id specification
+    :type calc_id: str
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
+    :type image: Dict
+    :param deltas: strains to apply in each direction, defaults to (-0.01,-0.0075,-0.005,0.00,0.005,0.0075,0.01)
+    :type deltas: Sequence[float], optional
+    :param ase_cubic_eos_args: Argumenents to pass to :func:`asimtools.asimmodules.geometry_optimization.ase_cubic_eos_optimization`, defaults to None
+    :type ase_cubic_eos_args: Optional[Dict], optional
+    :return: Elastic constant results
+    :rtype: Dict
+    """
     calc = load_calc(calc_id)
     atoms = get_atoms(**image)
     atoms.set_calculator(calc)

asimtools/asimmodules/geometry_optimization/ase_cubic_eos_optimization.py

@@ -16,19 +16,19 @@
 from asimtools.utils import get_atoms
 
 def ase_cubic_eos_optimization(
-    image: Dict,
     calc_id: str,
+    image: Dict,
     npoints: Optional[int] = 5,
     eos_string: Optional[str] = 'sj',
     eps: Optional[float] = 0.04,
     plot: Optional[bool] = True,
 ) -> Dict:
     """Generate the energy-volume equation of state (energy calculations not parallelized)
 
-    :param image: Image input
-    :type image: Dict
-    :param calc_id: calc_id
+    :param calc_id: calc_id specification
     :type calc_id: str
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
+    :type image: Dict
     :param npoints: Number of energy points to calculate, must be >5, defaults to 5
     :type npoints: Optional[int], optional
     :param eos_string: eos_string as specified for :func:`ase.eos.calculate_eos`, defaults to 'sj'

asimtools/asimmodules/geometry_optimization/atom_relax.py

@@ -14,17 +14,17 @@
 def atom_relax(
     calc_id: str,
     image: Dict,
-    optimizer: str = 'GPMin', #GPMin is fastest according to ASE docs
+    optimizer: str = 'GPMin', #GPMin is fast in many cases according to ASE docs
     properties: Tuple[str] = ('energy', 'forces'),
     fmax: float = 0.02,
     prefix: Optional[str] = None,
 ) -> Dict:
     """Relaxes the given tomic structure using ASE's built-in structure
     optimizers
 
-    :param calc_id: Calculator ID
+    :param calc_id: calc_id specification
     :type calc_id: str
-    :param image: image configuration
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
     :type image: Dict
     :param prefix: Prefix of output files, defaults to ''
     :type prefix: str, optional

asimtools/asimmodules/geometry_optimization/cell_relax.py

@@ -26,9 +26,9 @@ def cell_relax(
 ) -> Dict:
     """Relax cell using ASE Optimizer
 
-    :param calc_id: Key for calculator provided in calc_input
+    :param calc_id: calc_id specification
     :type calc_id: str
-    :param image: Image parameters, see :func: asimtools.utils.get_atoms
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
     :type image: Dict
     :param prefix: Prefix to output files, defaults to ''
     :type prefix: str, optional

asimtools/asimmodules/geometry_optimization/optimize.py

@@ -1,13 +1,12 @@
 #!/usr/bin/env python
 '''
-Relaxes structure using ASE while retaining symmetry. Requires ASE>=3.23
+Relaxes both atoms and cell coordinates simultaneously.
 
 Author: [email protected]
 '''
 from typing import Dict, Optional
 import ase.optimize
 from ase.constraints import ExpCellFilter
-from ase.spacegroup.symmetrize import FixSymmetry
 from ase.io.trajectory import Trajectory
 from asimtools.calculators import load_calc
 from asimtools.utils import get_atoms
@@ -22,9 +21,9 @@ def optimize(
 ) -> Dict:
     """Relaxes cell (and atoms) using ase.constraints.ExpCellFilter while retaining symmetry
 
-    :param calc_id: calc_id in calc_input.yaml
+    :param calc_id: calc_id specification
     :type calc_id: str
-    :param image: image specification
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
     :type image: Dict
     :param optimizer: Any optimizer from ase.optimize, defaults to 'BFGS'
     :type optimizer: str, optional

asimtools/asimmodules/geometry_optimization/symmetric_cell_relax.py

@@ -23,9 +23,9 @@ def symmetric_cell_relax(
 ) -> Dict:
     """Relaxes cell (and atoms) using ase.constraints.ExpCellFilter while retaining symmetry
 
-    :param calc_id: calc_id in calc_input.yaml
+    :param calc_id: calc_id specification
     :type calc_id: str
-    :param image: image specification
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
     :type image: Dict
     :param optimizer: Any optimizer from ase.optimize, defaults to 'BFGS'
     :type optimizer: str, optional

asimtools/asimmodules/lammps/lammps.py

@@ -4,7 +4,7 @@
 
 Author: [email protected]
 '''
-from typing import Dict
+from typing import Dict, Optional
 from pathlib import Path
 import subprocess
 import logging
@@ -15,14 +15,34 @@
 
 def lammps(
     template: str,
-    image: Dict = None,
+    image: Optional[Dict] = None,
     prefix: str = '',
     atom_style: str = 'atomic',
-    variables: Dict = None,
+    variables: Optional[Dict] = None,
     lmp_cmd: str = 'lmp',
     masses: bool = True,
 ) -> Dict:
-    ''' 
+    """Runs a lammps script based on a specified template, variables can be 
+    specified as arguments to be defined in the final LAMMPS input file if 
+    placeholders are put in the template
+
+    :param template: path to lammps input template file
+    :type template: str
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`, defaults to None
+    :type image: Dict, optional
+    :param prefix: Prefix to be added to input file, defaults to ''
+    :type prefix: str, optional
+    :param atom_style: LAMMPS style in which to write image to Lammps data input e.g. full, atomic etc., defaults to 'atomic'
+    :type atom_style: str, optional
+    :param variables: Dictionary of variables to be defined into the lammps input, defaults to None
+    :type variables: Dict, optional
+    :param lmp_cmd: Command with which to run LAMMPS, defaults to 'lmp'
+    :type lmp_cmd: str, optional
+    :param masses: Whether to specify atomic masses in LAMMPS data input, requires ASE>3.23.0, defaults to True
+    :type masses: bool, optional
+    :return: LAMMPS out file names
+    :rtype: Dict
+    """    ''' 
     Runs a lammps simulation based on a template lammps input script
     '''
     if variables is None:

asimtools/asimmodules/phonons/ase_phonons.py

@@ -21,6 +21,23 @@ def ase_phonons(
     kpts: Sequence[int] = (20, 20, 20),
     supercell: Sequence[int] = (5,5,5),
 ) -> Dict:
+    """Calculates phonon spectrum and DOS using ASE
+
+    :param calc_id: calc_id specification
+    :type calc_id: str
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
+    :type image: Dict
+    :param path: Path in BZ for plot
+    :type path: str
+    :param delta: delta in ASE phonons, defaults to 0.01
+    :type delta: float, optional
+    :param kpts: kpts in ASE phonons, defaults to (20, 20, 20)
+    :type kpts: Sequence[int], optional
+    :param supercell: repeat of image to use as supercell, defaults to (5,5,5)
+    :type supercell: Sequence[int], optional
+    :return: Empty dictionary
+    :rtype: Dict
+    """
 
     atoms = get_atoms(**image)
     calc = load_calc(calc_id)

asimtools/asimmodules/singlepoint.py

@@ -21,9 +21,9 @@ def singlepoint(
     """Evaluates the properties of a single image, currently implemented
     properties are energy, forces and stress
 
-    :param calc_id: ID of calculator provided in calc_input or global file
+    :param calc_id: calc_id specification
     :type calc_id: str
-    :param image: Image config, see :func:`asimtools.utils.get_atoms`
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
     :type image: Dict
     :param properties: properties to evaluate, defaults to ('energy', 'forces')
     :type properties: Tuple[str], optional

asimtools/asimmodules/surface_energies/surface_energies.py

@@ -1,9 +1,7 @@
 #!/usr/bin/env python
 '''
-Describe the asimmodule briefly here. If this is a asimmodule that runs multiple steps,
-describe it here using reStructuredText to generate autodocs
-
-Cite the papers where the method/asimmodule was first introduced here as well
+Calculates surface energies of slabs defined by args specified for
+pymatgen.core.surface.generate_all_slabs()
 
 Author: [email protected]
 '''
@@ -38,16 +36,32 @@ def get_surface_energy(slab, calc, bulk_e_per_atom):
     return converged, surf_en, slab_en, area
 
 def surface_energies(
-    image: Dict,
     calc_id: str,
+    image: Dict,
     millers: Union[str,Sequence] = 'all',
     atom_relax_args: Optional[Dict] = None,
     generate_all_slabs_args: Optional[Dict] = None,
 ) -> Dict:
-    '''
-    Calculates surface energies of slabs defined by args specified for
+    """Calculates surface energies of slabs defined by args specified for
     pymatgen.core.surface.generate_all_slabs()
-    '''
+
+    :param calc_id: calc_id specification
+    :type calc_id: str
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
+    :type image: Dict
+    :param millers: List of miller indices to consider in the form 'xyz',
+        defaults to 'all'
+    :type millers: Union[str,Sequence], optional
+    :param atom_relax_args: Args to pass to
+        :func:`asimtools.asimmodules.geometry_optimization.atom_relax.atom_relax`,
+        defaults to None
+    :type atom_relax_args: Optional[Dict], optional
+    :param generate_all_slabs_args: Args to pass to
+        :func:`pymatgen.core.surface.generate_all_slabs`, defaults to None
+    :type generate_all_slabs_args: Optional[Dict], optional
+    :return: _description_
+    :rtype: Dict
+    """
 
     calc = load_calc(calc_id)
     bulk = get_atoms(**image)

asimtools/asimmodules/transformations/scale_unit_cells.py

@@ -28,17 +28,21 @@ def scale_unit_cells(
 ) -> Dict:
     """Produce a set of images with unit cells scaled compared to the input
 
-    :param image: Image parameters
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
     :type image: Dict
     :param scales: Scaling values by which to scale cell, defaults to None
     :type scales: Optional[Sequence], optional
-    :param logspace: Parameters to pass to np.logspace for scaling values, defaults to None
+    :param logspace: Parameters to pass to np.logspace for scaling values,
+        defaults to None
     :type logspace: Optional[Sequence], optional
-    :param linspace: Parameters to pass to np.linspace for scaling values, defaults to None
+    :param linspace: Parameters to pass to np.linspace for scaling values,
+        defaults to None
     :type linspace: Optional[Sequence], optional
-    :param scale_by: Scale either "volume" or "a" which is lattice parameter, defaults to 'a'
+    :param scale_by: Scale either "volume" or "a" which is lattice parameter,
+        defaults to 'a'
     :type scale_by: str, optional
-    :raises ValueError: If more than one of scales, linspace, logspace are provided
+    :raises ValueError: If more than one of scales, linspace, logspace are
+        provided
     :return: Path to xyz file
     :rtype: Dict
     """

asimtools/asimmodules/vacancy_formation_energy/vacancy_formation_energy.py

@@ -1,9 +1,6 @@
 #!/usr/bin/env python
 '''
-Describe the asimmodule briefly here. If this is a asimmodule that runs multiple steps,
-describe it here using reStructuredText to generate autodocs
-
-Cite the papers where the method/asimmodule was first introduced here as well
+Calculates the monovacancy formation energy from a bulk structure
 
 Author: [email protected]
 '''
@@ -23,6 +20,24 @@ def vacancy_formation_energy(
     atom_relax_args: Optional[Dict] = None,
     repeat: Optional[Sequence] = None
 ) -> Dict:
+    """Calculates the monovacancy formation energy from a bulk structure
+
+    :param calc_id: calc_id specification
+    :type calc_id: str
+    :param image: Image specification, see :func:`asimtools.utils.get_atoms`
+    :type image: Dict
+    :param vacancy_index: Index of atom to remove, defaults to 0
+    :type vacancy_index: int, optional
+    :param atom_relax_args: Args to pass to
+        :func:`asimtools.asimmodules.geometry_optimization.atom_relax.atom_relax`,
+        defaults to None
+    :type atom_relax_args: Optional[Dict], optional
+    :param repeat: Repeat to apply to image to create supercell, defaults to
+        None
+    :type repeat: Optional[Sequence], optional
+    :return: Empty dictionary
+    :rtype: Dict
+    """    
 
     calc = load_calc(calc_id)
     bulk = get_atoms(**image).repeat(repeat)