Add PD regression tests, QE 7.4.1 update, and documentation

.gitignore

@@ -0,0 +1 @@
+__pycache__/

README.md

@@ -8,12 +8,43 @@ There is an option to calculate symmetry-adapted Wannier functions.
 
 ## Installation
 
-You can install this package using pip:
+If you are working from a local checkout of this repository, install it with:
 
+```bash
+pip install -e .
 ```
+
+For development, including the test dependencies, use:
+
+```bash
+pip install -e '.[dev]'
+```
+
+This installs the Python package and the `symwannier` CLI from the current source tree.
+
+If you only want the published Python package and do not need this repository checkout,
+you can instead use:
+
+```bash
 pip install symWannier
 ```
 
+The Python install is enough for:
+
+- `symwannier expand prefix`
+- `symwannier wannierize ... prefix`
+
+It is not enough for the full Quantum ESPRESSO workflow starting from NSCF output.
+In particular, `pip install symWannier` does not install or build:
+
+- `wannier90.x`
+- Quantum ESPRESSO
+- the modified `pw2wannier90.x` source bundled in this repository
+
+If you want to generate `prefix.isym`, `prefix.immn`, `prefix.iamn`, and `prefix.ieig`
+yourself, you still need a Quantum ESPRESSO build that includes the modified
+`pw2wannier90.x`.
+
 ## IBZ calculation using wannier90
 
 Run SCF and NSCF calculations to obtain wave functions in the irreducible Brillouin zone (IBZ).
@@ -33,7 +64,14 @@ Prepare prefix.win and generate prefix.nnkp. You can use the same prefix.win tha
 wannier90.x -pp prefix
 ```
 
-Run pw2wannier90.x with ```irr_bz = .true.``` to compute prefix.immn, prefix.iamn, prefix.ieig. Symmetry infomation is stored in prefix.isym.
+Run pw2wannier90.x with `irr_bz = .true.` to compute `prefix.immn`, `prefix.iamn`,
+and `prefix.ieig`. Symmetry infomation is stored in `prefix.isym`.
+
+If you want to use projectability-based disentanglement from atomic projectors,
+`atom_proj = .true.` can be combined with `irr_bz = .true.` in the modified
+`pw2wannier90.x` source bundled in this repository. In that case, the generated
+`prefix.iamn` can still be expanded and used by the Python-side `wannierize`
+workflow.
 
 Note: Quantum ESPRESSO version 7.3 or later is required for this step.
 ```
@@ -55,20 +93,30 @@ There are sample input and script files, in examples/Cu and examples/Fe.
 
 ## Symmetry adapted Wannier functions
 
-Once prefix.immn, prefix.iamn, prefix.ieig, and prefix.isym are obtained, you can construct Wannier functions as follows.
+Once `prefix.immn`, `prefix.iamn`, `prefix.ieig`, and `prefix.isym` are obtained,
+you can construct Wannier functions as follows.
 ```
 symwannier wannierize -s prefix
 ```
-To construct symmetry-adapted Wannier functions, use the "-S" option instead of "-s".
+To construct symmetry-adapted Wannier functions, use the `-S` option instead of `-s`.
 ```
 symwannier wannierize -S prefix
 ```
 
+If you want to define disentanglement windows from AMN projectability rather than
+from the energy window in `prefix.win`, add the `-P` option.
+
+Typical combinations are:
+
+```bash
+symwannier wannierize -P -s prefix
+symwannier wannierize -P -S prefix
+```
+
 
 ## Paper
 
 For more information, please see
 [T. Koretsune, Comp. Phys. Comm. 285 108645 (2023).](https://doi.org/10.1016/j.cpc.2022.108645)
 
 We hope that you cite this reference when you publish the results using this code.
-

pyproject.toml

@@ -27,5 +27,11 @@ package-dir = { "" = "src" }
 where = ["src"]
 include = ["symwannier"]
 
+[tool.pytest.ini_options]
+markers = [
+	"fast: default regression tests excluding long-running workflow cases",
+	"slow: long-running regression tests for large workflow cases",
+]
+
 [project.scripts]
 symwannier = "symwannier.cli:main"