ConvergenceTracker -Kevin Chu

.github/workflows/workflow.yml

@@ -0,0 +1,49 @@
+name: CodeCov
+on: [push, pull_request]
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    env:
+      OS: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r kvnchv/requirements.txt
+        pip install -e kvnchv/
+        pip install pytest pytest-cov pytest-assume
+    - name: Build qe from source
+      run: |
+        sudo apt-get install -y --no-install-recommends \
+          autoconf \
+          build-essential \
+          ca-certificates \
+          gfortran \
+          libblas3 \
+          libc6 \
+          libfftw3-dev \
+          libgcc-s1 \
+          liblapack-dev \
+          wget
+        cd $HOME
+        wget https://gitlab.com/QEF/q-e/-/archive/qe-7.1/q-e-qe-7.1.tar.gz
+        tar -xzf q-e-qe-7.1.tar.gz
+        cd q-e-qe-7.1
+        ./configure
+        make pw
+        echo 'export PATH="$HOME/q-e-qe-7.1/bin:$PATH"' >> ~/.bashrc
+        source ~/.bashrc
+    - name: Run pytest
+      run: |
+        pytest --rootdir=/home/runner/work/rewotes/rewotes/kvnchv/ --cov=kvnchv/converger --cov-report=xml --verbose kvnchv/tests
+    - name: Build coverage report
+      run: coverage lcov
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        files: ./coverage.lcov

kvnchv/.gitignore

@@ -0,0 +1,13 @@
+# environment
+venv
+.vscode/
+
+# packaging
+*.egg-info/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+
+# testing files
+tests/.pytest_cache
+tests/resources/*/outdir/

kvnchv/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/pycqa/flake8
+    rev: 5.0.4
+    hooks:
+      - id: flake8
+        additional_dependencies:
+          - flake8-import-order
+        args: ['--config=kvnchv/setup.cfg']
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 4.0.0  # pick a git hash / tag to point to
+    hooks:
+      - id: pydocstyle
+        args: ['--config=kvnchv/setup.cfg']

kvnchv/README.md

@@ -0,0 +1,62 @@
+# K-point convergence tracker (Materials)
+
+> Ideal candidate: scientists skilled in Density Functional Theory and proficient in python.
+
+# Overview
+
+The aim of this task is to create a python package that implements automatic convergence tracking mechanism for a materials simulations engine. The convergence is tracked with respect to the k-point sampling inside a reciprocal cell of a crystalline compound.
+
+# Requirements
+
+1. automatically find the dimensions of a k-point mesh that satisfy a certain criteria for total energy (eg. total energy is converged within dE = 0.01meV)
+1. the code shall be written in a way that can facilitate easy addition of convergence wrt other characteristics extracted from simulations (forces, pressures, phonon frequencies etc)
+1. the code shall support VASP or Quantum ESPRESSO
+
+# Expectations
+
+- correctly find k-point mesh that satisfies total energy convergence parameters for a set of 10 materials, starting from Si2, as simplest, to a 10-20-atom supercell of your choice
+- modular and object-oriented implementation
+- commit early and often - at least once per 24 hours
+
+# Timeline
+
+We leave exact timing to the candidate. Must fit Within 5 days total.
+
+# User story
+
+As a user of this software I can start it passing:
+
+- path to input data (eg. pw.in / POSCAR, INCAR, KPOINTS) and
+- kinetic energy cutoff
+
+as parameters and get the k-point dimensions (eg. 5 5 5).
+
+# Operating assumptions
+
+The assumed directory structure is:
+```
+rundir/
+    pw.in
+    pseudo/
+        potentialfile.UPF
+```
+
+The input file should be named `pw.in` and is assumed to have the following:
+
+&CONTROL section contains the following fixed parameters
+- outdir = 'outdir'
+- pseudo_dir = 'pseudo'
+- prefix='__prefix__',
+- tstress = .true.
+- tprnfor = .true.
+
+Automatically generated uniform of k-points, i.e. `K_POINTS automatic`
+- K_POINTS is the last "card" in the input
+
+
+# Notes
+
+- *create an account at exabyte.io and use it for the calculation purposes*
+    - Could authenticate API but not submit jobs succesfully.
+    - Package tests are with a local quantum ESPRESSO install. 
+- suggested modeling engine: Quantum ESPRESSO

kvnchv/converger/__init__.py

@@ -0,0 +1,3 @@
+from .manager import Manager
+from .solvers import EspressoSolver
+from .version import __version__

kvnchv/converger/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions."""
+
+
+class InputFilesNotFoundError(Exception):
+    """Error when the provided input path string is not a valid Path."""
+
+
+class TargetOutputNotFoundError(Exception):
+    """Error when requested target variable was not found in solver results."""
+
+
+class SolverSubprocessFailedError(Exception):
+    """Return processed subprocess error."""
+
+
+class SolverNotImplementedError(Exception):
+    """Error when the requested solver is not implemented."""
+
+
+class SolverNotInstalledError(Exception):
+    """Error when the requested solver is not installed."""
+
+
+class UnsupportedParameterError(Exception):
+    """Error when provided parameters are unsupported."""
+
+
+class EspressoOutputNotFoundError(Exception):
+    """Error when expected espresso output XML file was not found."""

kvnchv/converger/manager.py

@@ -0,0 +1,130 @@
+"""Convergence workflow manager."""
+import itertools
+from copy import deepcopy
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from jsonschema import ValidationError, validate
+
+from .exceptions import (InputFilesNotFoundError,
+                         SolverNotImplementedError,
+                         TargetOutputNotFoundError
+                         )
+from .schema import input_schema
+from .solvers import EspressoSolver
+
+solvers = {"espresso": EspressoSolver}
+
+
+class Manager():
+    """Main class for convergence workflow run."""
+
+    def __init__(self, input_dict: dict):
+        self.input_dict: dict = deepcopy(input_dict)
+        self.schema: dict = input_schema  # schema to validate against
+
+        self.solver_input: dict  # solver-configuration
+        self.input_path: Path
+        self.target: str  # convergence target value name
+        self.tol: float  # tolerance (absolute) to satisfy
+        self.parameter_space: list  # list of input parameter specifications
+
+        self.data: pd.DataFrame  # DataFrame for parameter sets and outputs
+
+        self.validate_schema()
+        self._parse_input()
+
+    def _parse_input(self):
+        """Convert input dict to class attrs."""
+        for param, val in self.input_dict.items():
+            # special handling for input path
+            if param == "input_path":
+                if not Path(val).exists():
+                    raise InputFilesNotFoundError
+                self.input_path = Path(val)
+            else:
+                setattr(self, param, val)
+
+    def validate_schema(self):
+        """Validate against schema."""
+        try:
+            validate(self.input_dict, self.schema)
+        except ValidationError as err:
+            raise err
+        return True
+
+    def _get_solver(self, run_params: dict):
+        """Initialize solver object."""
+        if self.solver_input["name"] not in solvers:
+            raise SolverNotImplementedError
+
+        return solvers[self.solver_input["name"]](
+                    self.solver_input,
+                    self.input_path,
+                    run_params
+                )
+
+    def run(self):
+        """Run convergence workflow."""
+        self.process_parameters()
+        return_target = np.zeros(len(self.data))
+        return_target.fill((np.nan))
+        return_reldelta = np.zeros(len(self.data))
+        return_reldelta.fill((np.nan))
+
+        # run first iteration
+        target_prev = 0.0
+        target_eval = self.run_solver(0)
+        return_target[0] = target_eval
+
+        rel_tol = (target_eval - target_prev) / target_eval
+        return_reldelta[0] = rel_tol
+        target_prev = target_eval
+
+        converged = False
+        for run_idx in range(1, len(self.data)):
+            if abs(rel_tol) < self.tol:
+                # assemble results dataframe
+                converged = True
+                break
+            target_eval = self.run_solver(run_idx)
+            return_target[run_idx] = target_eval
+
+            rel_tol = (target_eval - target_prev) / target_prev
+            return_reldelta[run_idx] = rel_tol
+            target_prev = target_eval
+
+        # update job results data
+        self.data[self.target] = return_target
+        self.data["relative_tol"] = return_reldelta
+        self.data = self.data.dropna()
+
+        if converged:
+            return 0
+        return 1
+
+    def run_solver(self, idx: int) -> float:
+        """Run solver for parameter set 'idx' and extract target converence value."""
+        run_params = dict(self.data.iloc[idx])
+        solver = self._get_solver(run_params)
+        solver.run()
+        if self.target not in solver.results.keys():
+            err_string = (f"{self.target} not found in results."
+                          f"Possible values are {list(solver.results.keys())}")
+            raise TargetOutputNotFoundError(err_string)
+        return solver.results[self.target]
+
+    def process_parameters(self):
+        """Process parameter_space input values define simulation set."""
+        param_arrays = []
+        param_names = []
+        for param_d in deepcopy(self.parameter_space):
+            # if delta is not provided, assume unit step
+            del_p = 1.0 if "delta" not in param_d else param_d["delta"]
+            param_names.append(param_d["name"])
+            param_arrays.append(np.arange(param_d["start"], param_d["max"]+del_p, del_p))
+
+        self.data = pd.DataFrame(
+            list(itertools.product(*param_arrays)),
+            columns=param_names)

kvnchv/converger/schema.py

@@ -0,0 +1,62 @@
+"""Input schema for Manager convergence workflow."""
+
+solver_schema = {
+    "description": "Solver parameters",
+    "type": "object",
+    "properties": {
+        "name": {
+            "description": "Name of solver type.",
+            "type": "string"
+        },
+        "solver_path": {
+            "description": "Explicit path to solver.",
+            "type": "string"
+        },
+    },
+    "required": ["name"]
+}
+
+input_schema = {
+    "type": "object",
+    "properties": {
+        "solver_input": solver_schema,
+        "input_path": {
+            "description": "Path containing required files for solver.",
+            "type": "string"
+        },
+        "tol": {
+            "description": "Minimum relative tolerance for target quantity.",
+            "type": "number"
+        },
+        "target": {
+            "description": "Output quantity to converge.",
+            "type": "string",
+        },
+        "parameter_space": {
+            "description": "Parametric space to evaluate convergence on.",
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "description": "Parameter name",
+                        "type": "string"
+                    },
+                    "start": {
+                        "description": "Initial parameter value.",
+                        "type": "number"
+                    },
+                    "max": {
+                        "description": "Final parameter value.",
+                        "type": "number"
+                    },
+                    "delta": {
+                        "description": "Step size between parameters"
+                    }
+                },
+                "required": ["name", "start", "max"]
+            }
+        }
+    },
+    "required": ["solver_input", "input_path", "tol", "target", "parameter_space"]
+}

kvnchv/converger/solvers/__init__.py

@@ -0,0 +1 @@
+from .espresso_solver import EspressoSolver