Cleanup 2026

.github/workflows/ci.yaml

@@ -1,63 +1,58 @@
-name: MacroDensity CI
+name: CI
 
 on:
-  pull_request:
-    branches:
-      - master
-      - development(calysta)
   push:
-    branches:
-      - master
-      - development(calysta)
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
 
 jobs:
-
-#   qa:
-#     runs-on: ubuntu-latest
-#     steps:
-#       - uses: actions/checkout@v2
-#       - uses: pre-commit/action@v2.0.0
-
   test:
-    #needs: qa
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
-        os: [ubuntu-latest,]
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
-    runs-on: ${{matrix.os}}
     steps:
-    - uses: actions/checkout@v3
-
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools setuptools_scm wheel
-        pip install -r requirements.txt
-        pip install pytest
-        pip install pytest-cov
-        pip install pytest-mpl
-        pip install -e .
-
-    - name: Check package versions
-      run: |
-        pip show -V pytest
-        pip show -V ase
-        pip show -V matplotlib
-
-    - name: Run tests
-      run: pytest --cov=macrodensity --mpl tests/unit_tests.py --cov-report=xml -v
-
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-        fail_ci_if_error: true
-        verbose: true
-        files: ./coverage.xml
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-cov
+
+      - name: Run tests
+        run: pytest tests/unit_tests.py -v --cov=macrodensity --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install linters
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Check code style with ruff
+        run: ruff check macrodensity/ --select=E,F,W --ignore=E501,E741,F401,F841,F821,F823,W605

CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "MacroDensity"
+abstract: "A Python package for analysis of electrostatic potential and electron density from electronic structure calculations."
+type: software
+authors:
+  - family-names: "Butler"
+    given-names: "Keith T."
+    orcid: "https://orcid.org/0000-0001-5432-5597"
+  - family-names: "Walsh"
+    given-names: "Aron"
+    orcid: "https://orcid.org/0000-0001-5460-7033"
+  - family-names: "Harnett-Caulfield"
+    given-names: "Liam"
+  - family-names: "Tesiman"
+    given-names: "Calysta A."
+    orcid: "https://orcid.org/0009-0008-7784-4320"
+  - family-names: "Mosquera-Lois"
+    given-names: "Irea"
+repository-code: "https://github.com/WMD-group/MacroDensity"
+url: "https://macrodensity.readthedocs.io/"
+license: MIT
+keywords:
+  - density functional theory
+  - electrostatic potential
+  - electron density
+  - VASP
+  - materials science

README.md

@@ -1,4 +1,9 @@
-# Welcome to MacroDensity
+# MacroDensity
+
+[![Build Status](https://github.com/WMD-group/MacroDensity/actions/workflows/ci.yaml/badge.svg)](https://github.com/WMD-group/MacroDensity/actions)
+[![PyPI version](https://badge.fury.io/py/macrodensity.svg)](https://pypi.org/project/macrodensity/)
+[![Documentation](https://readthedocs.org/projects/macrodensity/badge/?version=latest)](https://macrodensity.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ``MacroDensity`` is a Python package to post-process electrostatic potential and
 electron density files from electronic structure calculations and plot in a number of ways, including:
@@ -40,6 +45,36 @@ pip install -e .
 ```
 
 
+# Quick Example
+
+Calculate and plot the planar average of an electrostatic potential from a VASP LOCPOT file:
+
+```python
+import macrodensity as md
+
+# Plot planar average along the z-axis
+df, fig = md.plot_planar_average(
+    lattice_vector=20.0,  # Length of cell in z-direction (Angstrom)
+    input_file='LOCPOT',
+    axis='z'
+)
+```
+
+Calculate the on-site potential for a specific atomic species:
+
+```python
+# Get potential at oxygen sites
+potentials, fig = md.plot_on_site_potential(
+    species='O',
+    sample_cube=[2, 2, 2],
+    potential_file='LOCPOT',
+    coordinate_file='POSCAR'
+)
+```
+
+See the [tutorials](https://macrodensity.readthedocs.io/en/latest/tutorials.html) for more detailed examples.
+
+
 # Literature
 
 For more information on the theory behind the package, please see the following references:

macrodensity/__init__.py

@@ -2,14 +2,59 @@
 MacroDensity is a package to read, process and plot electrostatic potential and electron density
 files from electronic structure calculations.
 """
-import math
 
-import numpy as np
-from scipy import interpolate
-
-from macrodensity.averages import *
-from macrodensity.density import *
-from macrodensity.io import *
-from macrodensity.plotting import *
-from macrodensity.tools import *
-from macrodensity.utils import *
+from macrodensity.averages import (
+    macroscopic_average,
+    planar_average,
+    spherical_average,
+    travelling_volume_average,
+    volume_average,
+)
+from macrodensity.density import element_vol, gradient_magnitude
+from macrodensity.io import (
+    get_band_extrema,
+    read_gulp_potential,
+    read_vasp_density,
+    read_vasp_density_classic,
+    read_vasp_parchg,
+)
+from macrodensity.plotting import (
+    energy_band_alignment_diagram,
+    plot_active_plane,
+    plot_active_space,
+    plot_field_at_point,
+    plot_on_site_potential,
+    plot_planar_average,
+    plot_plane_field,
+    plot_variation_along_vector,
+)
+from macrodensity.tools import (
+    bulk_interstitial_alignment,
+    bulk_vac,
+    create_plotting_mesh,
+    diff_potentials,
+    dipole_correction,
+    extend_potential,
+    get_layer_sites,
+    match_resolution,
+    matched_spline_generate,
+    scissors_shift,
+    sort_potential,
+    spline_generate,
+    subs_potentials,
+    translate_grid,
+)
+from macrodensity.utils import (
+    GCD,
+    GCD_List,
+    density_2_grid,
+    get_third_coordinate,
+    get_volume,
+    inverse_participation_ratio,
+    matrix_2_abc,
+    number_in_field,
+    numbers_2_grid,
+    one_2_2d,
+    points_2_plane,
+    vector_2_abscissa,
+)

macrodensity/averages.py

@@ -60,9 +60,7 @@ def macroscopic_average(
             )
             macro_average[i] = macro_average[i] / period_points
         else:
-            macro_average[i] = (
-                macro_average[i] + sum(potential[start:end]) / period_points
-            )
+            macro_average[i] = sum(potential[start:end]) / period_points
 
     print("Average of the average = ", np.average(macro_average))
 
@@ -124,10 +122,10 @@ def volume_average(
                 xv = int(n_origin[0] + travelled[0] + x)
                 yv = int(n_origin[1] + travelled[1] + y)
                 zv = int(n_origin[2] + travelled[2] + z)
-                # Minimum image convention
-                zv = int(zv - nz * round(zv / nz))
-                yv = int(yv - ny * round(yv / ny))
-                xv = int(xv - nx * round(xv / nx))
+                # Periodic boundary wrapping
+                xv = xv % nx
+                yv = yv % ny
+                zv = zv % nz
                 potential_cube[x, y, z] = grid[int(xv), int(yv), int(zv)]
 
     return potential_cube.mean(), np.var(potential_cube)
@@ -221,7 +219,7 @@ def spherical_average(
     )
 
     ## PRINTING
-    if print_output == True:
+    if print_output:
         print("Potential            Variance")
         print("--------------------------------")
         print(cube_pot, "   ", cube_var)

macrodensity/density.py

@@ -37,15 +37,7 @@ def gradient_magnitude(
         >>> print(grad_magnitude)
 
     """
-    grad_mag = gx
-    for i in range(gx.shape[0]):
-        for j in range(gy.shape[1]):
-            for k in range(gz.shape[2]):
-                grad_mag[i, j, k] = np.sqrt(
-                    gx[i, j, k] ** 2 + gy[i, j, k] ** 2 + gz[i, j, k] ** 2
-                )
-
-    return grad_mag
+    return np.sqrt(gx**2 + gy**2 + gz**2)
 
 
 def element_vol(vol: float, nx: int, ny: int, nz: int) -> float:

macrodensity/io.py

@@ -57,7 +57,7 @@ def read_gulp_potential(gulpfile: str = "gulp.out") -> tuple:
 
     for n, line in enumerate(lines):
         if line.rfind("Electrostatic potential on a grid") > -1:
-            for k in reversed(range(9, NGX * NGY * NGZ + 9)):
+            for k in range(9, NGX * NGY * NGZ + 9):
                 potential.append(float(lines[n + k].split()[3]))
 
     return np.asarray(potential), NGX, NGY, NGZ, lattice