Merge branch 'main' into paper

.github/workflows/ci.yaml

@@ -60,7 +60,7 @@ jobs:
   publish-pypi:
 
     needs: [build]
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') && (github.repository == 'SMTG-UCL/easyunfold')
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') && (github.repository == 'SMTG-Bham/easyunfold')
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
     runs-on: ubuntu-latest
     steps:

.github/workflows/docs-deploy.yaml

@@ -48,7 +48,7 @@ jobs:
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         # Deply the documentation built only on the push even
-        if: ${{ (github.event_name != 'pull_request') && (github.repository == 'SMTG-UCL/easyunfold') }}
+        if: ${{ (github.event_name != 'pull_request') && (github.repository == 'SMTG-Bham/easyunfold') }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/_build/html

README.md

@@ -1,12 +1,12 @@
-![build](https://github.com/SMTG-UCL/easyunfold/actions/workflows/ci.yaml/badge.svg)
-[![docs](https://github.com/SMTG-UCL/easyunfold/actions/workflows/docs.yaml/badge.svg)](https://smtg-ucl.github.io/easyunfold/)
-[![codecov](https://codecov.io/gh/SMTG-UCL/easyunfold/branch/main/graph/badge.svg?token=XLLWWU5UM2)](https://codecov.io/gh/SMTG-UCL/easyunfold)
+![build](https://github.com/SMTG-Bham/easyunfold/actions/workflows/ci.yaml/badge.svg)
+[![docs](https://github.com/SMTG-Bham/easyunfold/actions/workflows/docs.yaml/badge.svg)](https://smtg-Bham.github.io/easyunfold/)
+[![codecov](https://codecov.io/gh/SMTG-Bham/easyunfold/branch/main/graph/badge.svg?token=XLLWWU5UM2)](https://codecov.io/gh/SMTG-Bham/easyunfold)
 [![PyPI](https://img.shields.io/pypi/v/easyunfold)](https://pypi.org/project/easyunfold)
-[![Downloads](https://img.shields.io/pypi/dm/easyunfold)](https://smtg-ucl.github.io/easyunfold/)
+[![Downloads](https://img.shields.io/pypi/dm/easyunfold)](https://smtg-Bham.github.io/easyunfold/)
 <!--- When JOSS submitted, add this: [![JOSS](https://joss.theoj.org/papers/10.21105/joss.04817/status.
 svg)](https://doi.org/10.21105/joss.)--->
 
-[![easyunfold](docs/img/logo.svg)](https://smtg-ucl.github.io/easyunfold/)
+[![easyunfold](docs/img/logo.svg)](https://smtg-Bham.github.io/easyunfold/)
 
 `easyunfold` is intended for obtaining the effective band structure of a supercell for a certain _k_-point
 path of the primitive cell. It was originally based on

docs/conf.py

@@ -71,14 +71,14 @@
 html_theme = 'sphinx_book_theme'
 html_theme_options = {
   'navigation_depth': 2,
-  'repository_url': 'https://github.com/SMTG-UCL/easyunfold',
+  'repository_url': 'https://github.com/SMTG-Bham/easyunfold',
   'use_repository_button': True,
   "show_navbar_depth": 2,
   'home_page_in_toc': True,
   "icon_links": [
         {
             "name": "GitHub",
-            "url": "https://github.com/SMTG-UCL/easyunfold",  # required
+            "url": "https://github.com/SMTG-Bham/easyunfold",  # required
             "icon": "fa-brands fa-github",
         },
         {

docs/examples.md

@@ -2,7 +2,7 @@
 
 Worked examples showcasing the capability of the `easyunfold`.
 Input files for these examples can be found 
-[here](https://github.com/SMTG-UCL/easyunfold/tree/main/examples).
+[here](https://github.com/SMTG-Bham/easyunfold/tree/main/examples).
 
 ```{toctree}
 :maxdepth: 1

docs/examples/example_mgo.md

@@ -2,15 +2,15 @@
 
 :::{note}
 The files needed for this example are provided in the 
-[examples/MgO](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/MgO) folder.
+[examples/MgO](https://github.com/SMTG-Bham/easyunfold/tree/main/examples/MgO) folder.
 :::
 
 Often it is useful to know the various contributions of atoms in the structure to the electronic bands 
 in the band structure, to analyse the chemistry and orbital interactions at play in the system. This 
 can be computed for unfolded bands as well.
 
 For a normal band structure calculation, the contributions can be inferred by colouring the band 
-according to the elemental contributions, which can be done using [sumo](https://github.com/SMTG-UCL/sumo).
+according to the elemental contributions, which can be done using [sumo](https://github.com/SMTG-Bham/sumo).
 
 ```{figure} ../../examples/MgO/MgO/band.png
 :width: 400px
@@ -25,7 +25,7 @@ dimension of information (atomic projection) can be tricky to visualise.
 
 In this example, we unfold the bands from a MgO 2x1x2 supercell with a Mg atom displaced to break 
 symmetry. The procedure is essentially the same as described in the 
-[Si supercell example](https://smtg-ucl.github.io/easyunfold/examples/example_si222.html).
+[Si supercell example](https://smtg-Bham.github.io/easyunfold/examples/example_si222.html).
 
 The only difference here is that we turn on the calculation of orbital projections in `VASP` with 
 `LORBIT = 11` (`12`, `13` and `14` will also work) in the `INCAR` file, and then use the `plot-projections` subcommand 

docs/examples/example_nabis2.md

@@ -2,7 +2,7 @@
 
 :::{note}
 The files needed for reproducing this example are provided in the 
-[examples/NaBiS2](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/NaBiS2) folder. 
+[examples/NaBiS2](https://github.com/SMTG-Bham/easyunfold/tree/main/examples/NaBiS2) folder. 
 Note that the `PROCAR.gz` file will need to be decompressed with `gzip -d PROCAR.gz` if recalculating 
 and reproducing these example plots.
 :::
@@ -161,7 +161,7 @@ Atom-projected unfolded band structure of NaBiS<sub>2</sub> alongside the electr
 ```
 The orbital contributions of elements in the DOS plot are automatically coloured to match that of the atomic 
 projections in the unfolded band structure plot, and these colours can be changed with the `--colours` option (as shown 
-in the [MgO example](https://smtg-ucl.github.io/easyunfold/examples/example_mgo.html)). 
+in the [MgO example](https://smtg-Bham.github.io/easyunfold/examples/example_mgo.html)). 
 
 ## Unfolded Band Structure with Specific Atom Selection
 In certain cases, we may want to project the contributions of specific atoms to the unfolded band structure, rather

docs/examples/example_si211_castep.md

@@ -7,7 +7,7 @@ path using CASTEP.
 
 :::{note} 
 The files needed for this example are provided in the 
-[examples/Si-castep](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/Si-castep) folder. 
+[examples/Si-castep](https://github.com/SMTG-Bham/easyunfold/tree/main/examples/Si-castep) folder. 
 This guide assumes the current working directory is located at the root of that folder.
 :::
 
@@ -19,7 +19,7 @@ easyunfold generate Si_prim.cell Si_211_band/Si_211_band.cell band.cell --code c
 
 :::{tip}
 Here, `band.cell` contains the band structure path and labels of the high symmetry _k_-points for the 
-primitive cell. The [sumo](https://github.com/SMTG-UCL/sumo) package can be used to generate it with ease.
+primitive cell. The [sumo](https://github.com/SMTG-Bham/sumo) package can be used to generate it with ease.
 :::
 
 The `easyunfold generate` command above also generates an `easyunfold.json` file in the current directory, 
@@ -112,7 +112,7 @@ Spectral function of the unfolded bands.
 ```
 
 :::{tip} 
-See the [NaBiS<sub>2</sub> example](https://smtg-ucl.github.io/easyunfold/examples/example_nabis2.html) for tips on 
+See the [NaBiS<sub>2</sub> example](https://smtg-Bham.github.io/easyunfold/examples/example_nabis2.html) for tips on 
 customising and prettifying the unfolded band structure plot.
 :::
 

docs/examples/example_si222.md

@@ -7,7 +7,7 @@ crystalline silicon (Si) which contains a displaced atom, breaking symmetry.
 
 :::{note} 
 The files needed for this example are provided in the 
-[examples/Si222](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/Si222) folder. This 
+[examples/Si222](https://github.com/SMTG-Bham/easyunfold/tree/main/examples/Si222) folder. This 
 guide assumes the current working directory is located at the root of that folder.
 :::
 
@@ -19,7 +19,7 @@ easyunfold generate Si/POSCAR Si_super_deformed/POSCAR Si/KPOINTS_band
 
 Here, `KPOINTS_band` is the `KPOINTS` file corresponding to the band structure path for the primitive 
 unit cell, which in this case was generated using `sumo-kgen` (see [Step 1](
-https://smtg-ucl.github.io/easyunfold/guide.html#step-1-generate-the-kpoints-path-of-the-primitive-cell) 
+https://smtg-Bham.github.io/easyunfold/guide.html#step-1-generate-the-kpoints-path-of-the-primitive-cell) 
 of the tutorial docs page).
 
 This generates an  `easyunfold.json` file in the current direction containing information about the 
@@ -88,7 +88,7 @@ mpirun -np 4 vasp_std  # run the calculation
 ```
 
 Alternatively, there is a `run.sh` script in the 
-[examples/Si222/Si_super_deformed](https://github.com/SMTG-UCL/easyunfold/tree/main/examples/Si222/Si_super_deformed) 
+[examples/Si222/Si_super_deformed](https://github.com/SMTG-Bham/easyunfold/tree/main/examples/Si222/Si_super_deformed) 
 folder that can be used to perform these two steps above.
 
 ## Perform band unfolding
@@ -126,7 +126,7 @@ Spectral function of the unfolded bands.
 ```
 
 :::{tip} 
-See the [NaBiS<sub>2</sub> example](https://smtg-ucl.github.io/easyunfold/examples/example_nabis2.html) for tips on 
+See the [NaBiS<sub>2</sub> example](https://smtg-Bham.github.io/easyunfold/examples/example_nabis2.html) for tips on 
 customising and prettifying the unfolded band structure plot. Here we have also actually used the `--intensity 3.5` 
 option to increase the spectral function intensity.
 :::

docs/index.md

@@ -1,10 +1,10 @@
 # `easyunfold` Documentation
 
-![build](https://github.com/SMTG-UCL/easyunfold/actions/workflows/ci.yaml/badge.svg)
-[![docs](https://github.com/SMTG-UCL/easyunfold/actions/workflows/docs.yaml/badge.svg)](https://smtg-ucl.github.io/easyunfold/)
-[![codecov](https://codecov.io/gh/SMTG-UCL/easyunfold/branch/main/graph/badge.svg?token=XLLWWU5UM2)](https://codecov.io/gh/SMTG-UCL/easyunfold)
+![build](https://github.com/SMTG-Bham/easyunfold/actions/workflows/ci.yaml/badge.svg)
+[![docs](https://github.com/SMTG-Bham/easyunfold/actions/workflows/docs.yaml/badge.svg)](https://smtg-Bham.github.io/easyunfold/)
+[![codecov](https://codecov.io/gh/SMTG-Bham/easyunfold/branch/main/graph/badge.svg?token=XLLWWU5UM2)](https://codecov.io/gh/SMTG-Bham/easyunfold)
 [![PyPI](https://img.shields.io/pypi/v/easyunfold)](https://pypi.org/project/easyunfold)
-[![Downloads](https://img.shields.io/pypi/dm/easyunfold)](https://smtg-ucl.github.io/easyunfold/)
+[![Downloads](https://img.shields.io/pypi/dm/easyunfold)](https://smtg-Bham.github.io/easyunfold/)
 <!--- When JOSS submitted, add this: [![JOSS](https://joss.theoj.org/papers/10.21105/joss.04817/status.
 svg)](https://doi.org/10.21105/joss.)--->
 
@@ -13,7 +13,7 @@ path of the primitive cell. It was originally based on
 [PyVaspwfc](https://github.com/QijingZheng/VaspBandUnfolding) for reading VASP wavefunction outputs, 
 with a notable improvement being that symmetry-breaking is properly accounted for by sampling necessary 
 additional _k_-points and averaging accordingly.
-Typical applications of band structure unfolding are the electronic structure analysis of defects, disorder, alloys, surfaces (and more), as illustrated in the example outputs below and [docs examples](https://smtg-ucl.github.io/easyunfold/examples.html).
+Typical applications of band structure unfolding are the electronic structure analysis of defects, disorder, alloys, surfaces (and more), as illustrated in the example outputs below and [docs examples](https://smtg-Bham.github.io/easyunfold/examples.html).
 
 Our goal is to implement the band structure unfolding workflow in a robust and user-friendly software 
 package.
@@ -49,7 +49,7 @@ In all cases, the supercell symmetry is lowered compared to the pristine primiti
 Hence, for a given _k_-point path in the primitive cell Brillouin Zone, additional _k_-points are 
 required to be sampled for the supercell, and the extracted spectral weights need to be appropriately 
 averaged to obtain the correct effective band structure (EBS). See the docs 
-[Theory](https://smtg-ucl.github.io/easyunfold/theory.html) page for more details.
+[Theory](https://smtg-Bham.github.io/easyunfold/theory.html) page for more details.
 <!-- when JOSS submitted, add link to paper (discussion of theory) here! -->
 <!--- When JOSS submitted, add 'Citation' section here, and CITATION.cff --->
 
@@ -96,7 +96,7 @@ And those who helped in the development:
 ## Bugs reports and feature requests
 Bug reports and feature requests are well come.
 If you found any bug or missing features please report it on the 
-[Issue Tracker](https://github.com/SMTG-UCL/easyunfold/issues).
+[Issue Tracker](https://github.com/SMTG-Bham/easyunfold/issues).
 
 ## Seeking support 
 
@@ -111,7 +111,7 @@ for external contributions, we prefer the
 [fork and pull](https://guides.github.com/activities/forking/)
 workflow while core developers use branches in the main repository:
 
-1. First open an [Issue](https://github.com/SMTG-UCL/easyunfold/issues) to discuss the proposed 
+1. First open an [Issue](https://github.com/SMTG-Bham/easyunfold/issues) to discuss the proposed 
    contribution. This discussion might include how the changes fit `easyunfold`'s scope and a
   general technical approach.
 2. Make your own project fork and implement the changes

docs/tutorial.md

@@ -23,7 +23,7 @@ In all cases, the supercell symmetry is lowered compared to the pristine primiti
 Hence, for a given _k_-point path in the primitive cell Brillouin Zone, additional _k_-points are 
 required to be sampled for the supercell, and the extracted spectral weights need to be appropriately 
 averaged to obtain the correct effective band structure (EBS). See the docs 
-[Theory](https://smtg-ucl.github.io/easyunfold/theory.html) page for more details.
+[Theory](https://smtg-Bham.github.io/easyunfold/theory.html) page for more details.
 
 At the moment, two plane-wave DFT codes, VASP[^vasp] and CASTEP[^castep], are supported. In principle, 
 support can be easily added for other plane-wave codes if the wavefunction can be read in.
@@ -40,10 +40,10 @@ For disordered materials, this primitive cell should be the idealised primitive
 
 This can be done by well-established packages such as 
 [seekpath](https://www.materialscloud.org/work/tools/seekpath) or 
-[sumo](https://github.com/SMTG-UCL/sumo).
+[sumo](https://github.com/SMTG-Bham/sumo).
 Note that the "standardised" primitive cell may be different from your input structure,
 and the generated path is correct for the standard primitive cell only.
-We recommend using [sumo](https://github.com/SMTG-UCL/sumo) for generating the _k_-points, which provides 
+We recommend using [sumo](https://github.com/SMTG-Bham/sumo) for generating the _k_-points, which provides 
 a nice command line interface, and automatically informs you if your input structure is not the required 
 'standardised' primitive cell:
 

easyunfold/__init__.py

@@ -2,4 +2,4 @@
 Collection of code for band unfolding
 """
 
-__version__ = '0.3.0'
+__version__ = '0.3.2'

easyunfold/cli.py

@@ -48,7 +48,11 @@ def easyunfold():
     type=click.Choice(SUPPORTED_DFT_CODES),
     show_default=True,
 )
-@click.option('--matrix', '-m', help='Transformation matrix')
+@click.option('--matrix',
+              '-m',
+              help='Transformation matrix, in the form "x y z" for a diagonal matrix, '
+              'or "x1 y1 z1, x2 y2 z2, x3 y3 z3" for a 3x3 matrix. Automatically guessed if not '
+              'provided.')
 @click.option('--symprec', help='Tolerance for determining the symmetry', type=float, default=1e-5, show_default=True)
 @click.option('--out-file', '-o', default='easyunfold.json', help='Name of the output file')
 @click.option('--no-expand', help='Do not expand the kpoints by symmetry', default=False, is_flag=True)
@@ -91,21 +95,26 @@ def generate(pc_file, code, sc_file, matrix, kpoints, time_reversal, out_file, n
 
     if matrix:
         transform_matrix = matrix_from_string(matrix)
-        if not np.allclose(primitive.cell @ transform_matrix, supercell.cell, rtol=2e-2):  # 2% mismatch tolerance
-            if np.allclose(primitive.cell @ transform_matrix, supercell.cell, rtol=5e-2):  # 2-5% mismatch
+        if not np.allclose(transform_matrix @ primitive.cell, supercell.cell, rtol=2e-2):  # 2% mismatch tolerance
+            if np.allclose(transform_matrix @ primitive.cell, supercell.cell, rtol=5e-2):  # 2-5% mismatch
                 click.echo(_quantitative_inaccuracy_warning)
             else:
                 click.echo(_incommensurate_warning)
+                click.echo(f'Transform matrix x primitive cell:\n{transform_matrix @ primitive.cell}')
+                click.echo(f'Supercell cell:\n{supercell.cell}')
             click.echo('Proceeding with the assumed transformation matrix.')
         click.echo(f'Transform matrix:\n{transform_matrix.tolist()}')
     else:
         tmp = supercell.cell @ np.linalg.inv(primitive.cell)
         transform_matrix = np.rint(tmp)
         if not np.allclose(tmp, transform_matrix, rtol=2e-2):  # 2% mismatch tolerance
-            if np.allclose(primitive.cell @ transform_matrix, supercell.cell, rtol=5e-2):  # 2-5% mismatch
+            if np.allclose(transform_matrix @ primitive.cell, supercell.cell, rtol=5e-2):  # 2-5% mismatch
                 click.echo(_quantitative_inaccuracy_warning)
             else:
                 click.echo(_incommensurate_warning)
+                click.echo(f'(Guessed) Transform matrix:\n{transform_matrix.tolist()}')
+                click.echo(f'Transform matrix x primitive cell:\n{transform_matrix @ primitive.cell}')
+                click.echo(f'Supercell cell:\n{supercell.cell}')
                 raise click.Abort()
 
         click.echo(f'(Guessed) Transform matrix:\n{transform_matrix.tolist()}')

easyunfold/plotting.py

@@ -332,7 +332,7 @@ def _plot_spectral_function_rgba(
             else:
                 fig, axes = plt.subplots(1, 2, figsize=figsize, dpi=dpi)
         else:
-            axes = [ax] if not isinstance(ax, list) else ax
+            axes = ax if isinstance(ax, (list, np.ndarray)) else [ax]
             fig = axes[0].figure
 
         mask = (engs < (ylim[1] + eref)) & (engs > (ylim[0] + eref))

easyunfold/utils.py

@@ -209,13 +209,15 @@ def wrap_kpoints(kpoints: Union[list, np.ndarray]):
     kpoints = np.array(kpoints) + 0.5
     kpoints -= np.floor(kpoints)
     kpoints -= 0.5
+    # Giving some numerical tolerance when enforcing the range [-0.5, 0.5)
+    kpoints[np.abs(kpoints - 0.5) < 1e-7] = -0.5
     return kpoints
 
 
 def find_unique(seq: np.ndarray, func=None):
     """
     Find unique slices along the first dimension of an np.array.
-    This is function is not optimised for high performance and has a O(N^2) scaling.
+    This function is not optimised for high performance and has a O(N^2) scaling.
 
     :return: A tuple of (unique, unique_idx, inv_mapping)
     """

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "easyunfold"
-authors = [{name = "Bonan Zhu", email = "[email protected]"}]
+authors = [{name = "Bonan Zhu", email = "[email protected]"}, {name = "Seán Kavanagh", email = "[email protected]"}]
 readme = "README.md"
 license = {file = "LICENSE"}
 classifiers = [
@@ -19,16 +19,17 @@ dependencies = ["scipy~=1.0", "numpy~=1.0", "matplotlib~=3.0", "ase~=3.14", "spg
                 "castepxbin~=0.3.0", "castepinput~=0.1"]
 
 [project.urls]
-"Homepage" = "https://github.com/SMTG-UCL/easyunfold"
-"Documentation" = "https://smtg-ucl.github.io/easyunfold/"
+"Homepage" = "https://github.com/SMTG-Bham/easyunfold"
+"Documentation" = "https://smtg-Bham.github.io/easyunfold/"
 
 [project.scripts]
 easyunfold = "easyunfold.cli:easyunfold"
 
 [project.optional-dependencies]
 doc = [
     "sphinx-click>=4,<5", "sphinx-autodoc2>=0.4,<0.5", "sphinx-book-theme>=1,<2",
-    "sphinx-copybutton>=0.3,<0.4", "myst-parser[linkify]", "sphinx>=6,<7"
+    "sphinx-copybutton>=0.3,<0.4", "myst-parser[linkify]", "sphinx>=6,<7", "astroid<3"
+    # astroid needs to be <3 due to: https://github.com/sphinx-extensions2/sphinx-autodoc2/issues/31
 ]
 test = ["pytest", "pytest-cov", "coverage", "sumo"]
 dos = ["sumo"]