Merge pull request #37 from SMTG-Bham/pr-commensurability-handling

Update commensurability warning

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)
@@ -80,18 +84,38 @@ def generate(pc_file, code, sc_file, matrix, kpoints, time_reversal, out_file, n
 
     primitive = read(pc_file)
     supercell = read(sc_file)
+    _quantitative_inaccuracy_warning = (
+        'Warning: There is a lattice parameter mismatch in the range 2-5% between the primitive (multiplied by the '
+        'transformation matrix) and the supercell. This will lead to some quantitative inaccuracies in the Brillouin '
+        'Zone spacing (and thus effective masses) of the unfolded band structures.')
+    _incommensurate_warning = (
+        'Warning: the super cell and the primitive cell are not commensurate (lattice parameter difference >5%). This '
+        'will likely lead to severe inaccuracies in the results! You should double check the correct transformation '
+        'matrix, primitive and super cells have been provided.')
+
     if matrix:
         transform_matrix = matrix_from_string(matrix)
-        if not np.allclose(primitive.cell @ transform_matrix, supercell.cell):
-            click.echo('Warning: the super cell and the the primitive cell are not commensure.')
-            click.echo('Proceed with the assumed tranform matrix')
+        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):
-            click.echo('The super cell and the the primitive cell are not commensure.')
-            raise click.Abort()
+        if not np.allclose(tmp, transform_matrix, 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'(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()}')
 

tests/conftest.py

@@ -40,6 +40,17 @@ def _inner(tag=''):
     return _inner
 
 
+@pytest.fixture
+def agsbte2_project_dir(datapath, tmp_path):
+    """Create a temporary directory containing AgSbTe2 inputs for testing"""
+
+    def _inner(tag=''):
+        shutil.copytree(datapath('AgSbTe2'), tmp_path / 'AgSbTe2')
+        return tmp_path / 'AgSbTe2'
+
+    return _inner
+
+
 @pytest.fixture
 def mgo_project_dir(datapath, tmp_path):
     shutil.copy2(datapath('mgo.json'), tmp_path / 'mgo.json')

tests/test_cli.py

@@ -49,6 +49,66 @@ def test_generate(si_project_dir):
     assert len(kpts) == 96 + kpts_expected
 
 
+def test_generate_agsbte2(agsbte2_project_dir):
+    """
+    Test the generate function
+    """
+    runner = CliRunner()
+
+    tmp_dir = agsbte2_project_dir(None)
+    os.chdir(tmp_dir)
+
+    output = runner.invoke(
+        easyunfold,  # ~2.5% lattice mismatch in this case, print warning but continue fine
+        ['generate', 'POSCAR_prim', 'SQS_POSCAR', 'KPOINTS_band', '--out-file', 'test'])
+    assert output.exit_code == 0
+
+    assert ('Warning: There is a lattice parameter mismatch in the range 2-5% between the primitive (multiplied by the '
+            'transformation matrix) and the supercell. This will lead to some quantitative inaccuracies in the '
+            'Brillouin Zone spacing (and thus effective masses) of the unfolded band structures.' in output.output)
+    assert '(Guessed) Transform matrix:\n[[1.0, -0.0, 0.0], [1.0, -3.0, 1.0], [1.0, 1.0, -3.0]]' in output.output
+    assert '194 kpoints specified along the path' in output.output
+    for i in [
+            'Supercell cell information:', 'Space group number: 6', 'International symbol: Pm', 'Point group: m',
+            'Primitive cell information:', 'Space group number: 225', 'International symbol: Fm-3m', 'Point group: m-3m'
+    ]:
+        assert i in output.output
+    assert 'Supercell kpoints written to KPOINTS_test' in output.output
+    assert 'Unfolding settings written to test' in output.output
+
+    kpts = read_kpoints('KPOINTS_test')[0]
+    kpts_expected = 1023
+    assert len(kpts) == kpts_expected
+
+    # test with also specifying transformation matrix:
+    os.remove('KPOINTS_test')
+    os.remove('test')
+    output = runner.invoke(
+        easyunfold,  # ~2.5% lattice mismatch in this case, print warning but continue fine
+        ['generate', 'POSCAR_prim', 'SQS_POSCAR', 'KPOINTS_band', '--out-file', 'test', '-m', '1 0 0 1 -3 1 1 1 -3'])
+    print(output.output)
+    print(output.stdout)
+    assert output.exit_code == 0
+
+    assert ('Warning: There is a lattice parameter mismatch in the range 2-5% between the primitive (multiplied by the '
+            'transformation matrix) and the supercell. This will lead to some quantitative inaccuracies in the '
+            'Brillouin Zone spacing (and thus effective masses) of the unfolded band structures.' in output.output)
+    assert 'Proceeding with the assumed transformation matrix.' in output.output
+    assert 'Transform matrix:\n[[1.0, 0.0, 0.0], [1.0, -3.0, 1.0], [1.0, 1.0, -3.0]]' in output.output
+    assert '194 kpoints specified along the path' in output.output
+    for i in [
+            'Supercell cell information:', 'Space group number: 6', 'International symbol: Pm', 'Point group: m',
+            'Primitive cell information:', 'Space group number: 225', 'International symbol: Fm-3m', 'Point group: m-3m'
+    ]:
+        assert i in output.output
+    assert 'Supercell kpoints written to KPOINTS_test' in output.output
+    assert 'Unfolding settings written to test' in output.output
+
+    kpts = read_kpoints('KPOINTS_test')[0]
+    kpts_expected = 1023
+    assert len(kpts) == kpts_expected
+
+
 @pytest.mark.parametrize('tag', ['', '_spin', '_soc'])
 def test_unfold(si_project_dir, tag):
     """

tests/test_data/AgSbTe2/KPOINTS_band

@@ -0,0 +1,197 @@
+\Gamma -> L -> W -> X -> \Gamma
+194
+Reciprocal
+0.0 0.0 0.0 1 \Gamma
+0.009259259259259257 0.009259259259259259 0.009259259259259259 1
+0.018518518518518514 0.018518518518518517 0.018518518518518517 1
+0.027777777777777773 0.027777777777777773 0.027777777777777773 1
+0.03703703703703703 0.037037037037037035 0.037037037037037035 1
+0.04629629629629629 0.04629629629629629 0.04629629629629629 1
+0.055555555555555546 0.055555555555555546 0.055555555555555546 1
+0.0648148148148148 0.06481481481481481 0.06481481481481481 1
+0.07407407407407406 0.07407407407407407 0.07407407407407407 1
+0.08333333333333331 0.08333333333333331 0.08333333333333331 1
+0.09259259259259257 0.09259259259259257 0.09259259259259257 1
+0.10185185185185183 0.10185185185185183 0.10185185185185183 1
+0.11111111111111109 0.11111111111111109 0.11111111111111109 1
+0.12037037037037035 0.12037037037037035 0.12037037037037035 1
+0.1296296296296296 0.12962962962962962 0.12962962962962962 1
+0.1388888888888889 0.1388888888888889 0.1388888888888889 1
+0.1481481481481481 0.14814814814814814 0.14814814814814814 1
+0.1574074074074074 0.1574074074074074 0.1574074074074074 1
+0.16666666666666663 0.16666666666666663 0.16666666666666663 1
+0.17592592592592593 0.17592592592592593 0.17592592592592593 1
+0.18518518518518515 0.18518518518518515 0.18518518518518515 1
+0.19444444444444445 0.19444444444444445 0.19444444444444445 1
+0.20370370370370366 0.20370370370370366 0.20370370370370366 1
+0.21296296296296297 0.21296296296296297 0.21296296296296297 1
+0.22222222222222218 0.22222222222222218 0.22222222222222218 1
+0.23148148148148145 0.23148148148148148 0.23148148148148148 1
+0.2407407407407407 0.2407407407407407 0.2407407407407407 1
+0.24999999999999997 0.25 0.25 1
+0.2592592592592592 0.25925925925925924 0.25925925925925924 1
+0.26851851851851855 0.26851851851851855 0.26851851851851855 1
+0.2777777777777778 0.2777777777777778 0.2777777777777778 1
+0.28703703703703703 0.28703703703703703 0.28703703703703703 1
+0.2962962962962962 0.2962962962962963 0.2962962962962963 1
+0.3055555555555556 0.3055555555555556 0.3055555555555556 1
+0.3148148148148148 0.3148148148148148 0.3148148148148148 1
+0.32407407407407407 0.32407407407407407 0.32407407407407407 1
+0.33333333333333326 0.33333333333333326 0.33333333333333326 1
+0.3425925925925926 0.3425925925925926 0.3425925925925926 1
+0.35185185185185186 0.35185185185185186 0.35185185185185186 1
+0.36111111111111105 0.3611111111111111 0.3611111111111111 1
+0.3703703703703703 0.3703703703703703 0.3703703703703703 1
+0.37962962962962965 0.37962962962962965 0.37962962962962965 1
+0.3888888888888889 0.3888888888888889 0.3888888888888889 1
+0.3981481481481481 0.39814814814814814 0.39814814814814814 1
+0.40740740740740733 0.40740740740740733 0.40740740740740733 1
+0.4166666666666667 0.4166666666666667 0.4166666666666667 1
+0.42592592592592593 0.42592592592592593 0.42592592592592593 1
+0.4351851851851851 0.4351851851851852 0.4351851851851852 1
+0.44444444444444436 0.44444444444444436 0.44444444444444436 1
+0.4537037037037037 0.4537037037037037 0.4537037037037037 1
+0.4629629629629629 0.46296296296296297 0.46296296296296297 1
+0.47222222222222215 0.47222222222222215 0.47222222222222215 1
+0.4814814814814814 0.4814814814814814 0.4814814814814814 1
+0.49074074074074076 0.49074074074074076 0.49074074074074076 1
+0.49999999999999994 0.5 0.5 1 L
+0.5 0.4943181818181818 0.5056818181818181 1
+0.5 0.48863636363636365 0.5113636363636364 1
+0.49999999999999994 0.4829545454545454 0.5170454545454546 1
+0.49999999999999994 0.47727272727272724 0.5227272727272727 1
+0.49999999999999994 0.47159090909090906 0.5284090909090909 1
+0.5 0.46590909090909094 0.5340909090909091 1
+0.5 0.4602272727272727 0.5397727272727273 1
+0.5 0.45454545454545453 0.5454545454545454 1
+0.5 0.44886363636363635 0.5511363636363636 1
+0.5 0.4431818181818182 0.5568181818181819 1
+0.5 0.4375 0.5625 1
+0.49999999999999994 0.4318181818181818 0.5681818181818181 1
+0.5 0.42613636363636365 0.5738636363636364 1
+0.5 0.42045454545454547 0.5795454545454545 1
+0.5 0.4147727272727273 0.5852272727272727 1
+0.5 0.4090909090909091 0.5909090909090908 1
+0.5 0.40340909090909094 0.5965909090909091 1
+0.49999999999999994 0.3977272727272727 0.6022727272727273 1
+0.49999999999999994 0.39204545454545453 0.6079545454545454 1
+0.49999999999999994 0.38636363636363635 0.6136363636363636 1
+0.49999999999999994 0.3806818181818182 0.6193181818181818 1
+0.5 0.375 0.625 1
+0.5 0.3693181818181818 0.6306818181818181 1
+0.49999999999999994 0.36363636363636365 0.6363636363636364 1
+0.5 0.35795454545454547 0.6420454545454546 1
+0.49999999999999994 0.35227272727272724 0.6477272727272727 1
+0.49999999999999994 0.34659090909090906 0.6534090909090909 1
+0.49999999999999994 0.34090909090909094 0.6590909090909091 1
+0.49999999999999994 0.3352272727272727 0.6647727272727272 1
+0.49999999999999994 0.32954545454545453 0.6704545454545454 1
+0.5 0.32386363636363635 0.6761363636363636 1
+0.49999999999999994 0.3181818181818182 0.6818181818181818 1
+0.49999999999999994 0.3125 0.6875 1
+0.49999999999999994 0.3068181818181818 0.6931818181818181 1
+0.49999999999999994 0.30113636363636365 0.6988636363636364 1
+0.49999999999999994 0.29545454545454547 0.7045454545454545 1
+0.49999999999999994 0.28977272727272724 0.7102272727272727 1
+0.49999999999999994 0.28409090909090906 0.7159090909090908 1
+0.5 0.27840909090909094 0.7215909090909091 1
+0.5 0.27272727272727276 0.7272727272727273 1
+0.49999999999999994 0.26704545454545453 0.7329545454545454 1
+0.49999999999999994 0.26136363636363635 0.7386363636363636 1
+0.49999999999999994 0.2556818181818182 0.7443181818181818 1
+0.5 0.25 0.75 1 W
+0.5 0.24218749999999997 0.7421875 1
+0.5 0.23437499999999997 0.734375 1
+0.5 0.2265625 0.7265625 1
+0.5 0.21874999999999997 0.71875 1
+0.5 0.2109375 0.7109375 1
+0.5 0.203125 0.703125 1
+0.5 0.19531249999999997 0.6953125 1
+0.5 0.1875 0.6875 1
+0.5 0.1796875 0.6796875 1
+0.5 0.171875 0.671875 1
+0.5 0.1640625 0.6640625 1
+0.5 0.15625 0.65625 1
+0.5 0.1484375 0.6484375 1
+0.5 0.140625 0.640625 1
+0.5 0.1328125 0.6328125 1
+0.5 0.125 0.625 1
+0.5 0.1171875 0.6171875 1
+0.5 0.10937499999999999 0.609375 1
+0.5 0.1015625 0.6015625 1
+0.5 0.09374999999999999 0.59375 1
+0.5 0.0859375 0.5859375 1
+0.5 0.078125 0.578125 1
+0.5 0.07031249999999999 0.5703125 1
+0.5 0.0625 0.5625 1
+0.5 0.05468750000000001 0.5546875 1
+0.5 0.04687499999999999 0.546875 1
+0.5 0.0390625 0.5390625 1
+0.5 0.031250000000000014 0.53125 1
+0.5 0.023437499999999997 0.5234375 1
+0.5 0.015625000000000007 0.515625 1
+0.5 0.007812500000000017 0.5078125 1
+0.5 0.0 0.5 1 X
+0.49206349206349204 0.0 0.49206349206349204 1
+0.4841269841269841 0.0 0.4841269841269841 1
+0.47619047619047616 0.0 0.47619047619047616 1
+0.4682539682539682 0.0 0.4682539682539682 1
+0.46031746031746035 0.0 0.46031746031746035 1
+0.4523809523809524 0.0 0.4523809523809524 1
+0.4444444444444444 0.0 0.4444444444444444 1
+0.4365079365079365 0.0 0.4365079365079365 1
+0.42857142857142855 0.0 0.42857142857142855 1
+0.4206349206349206 0.0 0.4206349206349206 1
+0.41269841269841273 0.0 0.41269841269841273 1
+0.40476190476190477 0.0 0.40476190476190477 1
+0.3968253968253968 0.0 0.3968253968253968 1
+0.3888888888888889 0.0 0.3888888888888889 1
+0.38095238095238093 0.0 0.38095238095238093 1
+0.373015873015873 0.0 0.373015873015873 1
+0.36507936507936506 0.0 0.36507936507936506 1
+0.3571428571428571 0.0 0.3571428571428571 1
+0.3492063492063492 0.0 0.3492063492063492 1
+0.3412698412698412 0.0 0.3412698412698412 1
+0.3333333333333333 0.0 0.3333333333333333 1
+0.3253968253968254 0.0 0.3253968253968254 1
+0.31746031746031744 0.0 0.31746031746031744 1
+0.30952380952380953 0.0 0.30952380952380953 1
+0.3015873015873016 0.0 0.3015873015873016 1
+0.29365079365079366 0.0 0.29365079365079366 1
+0.28571428571428575 0.0 0.28571428571428575 1
+0.2777777777777778 0.0 0.2777777777777778 1
+0.2698412698412698 0.0 0.2698412698412698 1
+0.2619047619047619 0.0 0.2619047619047619 1
+0.25396825396825395 0.0 0.25396825396825395 1
+0.24603174603174602 0.0 0.24603174603174602 1
+0.23809523809523808 0.0 0.23809523809523808 1
+0.23015873015873017 0.0 0.23015873015873017 1
+0.22222222222222218 0.0 0.22222222222222218 1
+0.2142857142857143 0.0 0.2142857142857143 1
+0.2063492063492063 0.0 0.2063492063492063 1
+0.1984126984126984 0.0 0.1984126984126984 1
+0.19047619047619047 0.0 0.19047619047619047 1
+0.18253968253968253 0.0 0.18253968253968253 1
+0.1746031746031746 0.0 0.1746031746031746 1
+0.16666666666666669 0.0 0.16666666666666669 1
+0.1587301587301587 0.0 0.1587301587301587 1
+0.1507936507936508 0.0 0.1507936507936508 1
+0.14285714285714288 0.0 0.14285714285714288 1
+0.1349206349206349 0.0 0.1349206349206349 1
+0.12698412698412698 0.0 0.12698412698412698 1
+0.11904761904761904 0.0 0.11904761904761904 1
+0.11111111111111109 0.0 0.11111111111111109 1
+0.10317460317460321 0.0 0.10317460317460321 1
+0.0952380952380952 0.0 0.0952380952380952 1
+0.08730158730158732 0.0 0.08730158730158732 1
+0.07936507936507937 0.0 0.07936507936507937 1
+0.07142857142857144 0.0 0.07142857142857144 1
+0.06349206349206349 0.0 0.06349206349206349 1
+0.0555555555555556 0.0 0.0555555555555556 1
+0.0476190476190476 0.0 0.0476190476190476 1
+0.039682539682539715 0.0 0.039682539682539715 1
+0.031746031746031717 0.0 0.031746031746031717 1
+0.02380952380952383 0.0 0.02380952380952383 1
+0.015873015873015886 0.0 0.015873015873015886 1
+0.007936507936507943 0.0 0.007936507936507943 1
+0.0 0.0 0.0 1 \Gamma

tests/test_data/AgSbTe2/POSCAR_prim

@@ -0,0 +1,10 @@
+Ag1 Te1
+1.0
+   0.0000000000000000    3.0399999999999991    3.0399999999999991
+   3.0399999999999991    0.0000000000000000    3.0399999999999991
+   3.0399999999999991    3.0399999999999991    0.0000000000000000
+Ag Te
+1 1
+direct
+   0.0000000000000000    0.0000000000000000    0.0000000000000000 Ag
+  -0.5000000000000000    0.5000000000000000    0.5000000000000000 Te

tests/test_data/AgSbTe2/SQS_POSCAR

@@ -0,0 +1,41 @@
+Ag4 Sb4 Te8
+   1.0000000000000000
+     0.0000000000000000    3.0153641666817892    3.0153641666817892
+    -6.3146236125343318    5.8489685063819117   -5.8489685063819117
+    -6.3469556992336607   -5.8654942008784907    5.8654942008784907
+   Ag   Sb   Te
+     4     4     8
+Direct
+  0.0000000000000000  0.7527020370361285  0.2759265817118562
+ -0.0000000000000000  0.4935370195973322  0.5138950873723097
+ -0.0000000000000000  0.2587596038798642  0.7615285940182124
+  0.5000000000000000  0.8768400938939700  0.6165996651820500
+ -0.0000000000000000  0.9953006355473802  0.0085537967871281
+  0.5000000000000000  0.3842174318681571  0.1227410907740850
+  0.5000000000000000  0.1219783801937458  0.3760017615926263
+  0.5000000000000000  0.6300065004980725  0.8574337035506276
+  0.0000000000000000  0.7715898516865103  0.7457215845430222
+ -0.0000000000000000  0.5064226597851310  0.9851925528078957
+  0.0000000000000000  0.2494475112407989  0.2374070649248258
+  0.5000000000000000  0.1226897397507456  0.8663781307658880
+  0.0000000000000000  0.0119377410978760  0.5023102979327116
+  0.5000000000000000  0.8567663249734002  0.1320448189015473
+  0.5000000000000000  0.6033195325030615  0.3724492380933057
+  0.5000000000000000  0.3644849364479630  0.6258160310418472
+
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00
+  0.00000000E+00  0.00000000E+00  0.00000000E+00