Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
126 commits
Select commit Hold shift + click to select a range
f9b5a27
update INPUT file
Nov 5, 2026
2535321
fix(bands): add BANDS/ subdirectory and per-step filename suffix for …
Nov 5, 2026
17a6862
Unify ionic step label to "Ionic_Step" across all output files.
Nov 5, 2026
d4c3c69
Unify IONIC STEP to Ionic_Step in WFC and band output headers.
Nov 5, 2026
4038796
unify ionic step header keyword to Ionic_Step in DOS/eig_occ/HS outputs
Nov 5, 2026
f2f3394
Fix hs_dense_io test assertions for Ionic_Step keyword sync.
Nov 5, 2026
411b16e
unify CSR sparse-matrix step header from "STEP: N" to "Ionic_Step N"
Nov 5, 2026
cd6a9c3
Unify "# istep:" to "# Ionic_Step" in PDOS text output.
Nov 5, 2026
91465ba
sync test reference headers with Ionic_Step keyword in HS matrix outputs
Nov 5, 2026
ffbb420
Correct out_mat_r output filename documentation
Nov 5, 2026
1cdac73
refactor(io): disambiguate cube channel suffixes from real spin indices
Nov 5, 2026
6343111
Rename Vxc(R) sparse output to vxcrs{spin}_nao.csr
Nov 5, 2026
6703379
sync remaining .ref fixtures with Ionic_Step keyword
Nov 6, 2026
8ba451b
fix(ASE): accept Ionic_Step header when counting eig_occ frames
Nov 6, 2026
1021fac
fix(io): pass band output directory explicitly to write_bands
Nov 6, 2026
d04111e
fix(test): make hsr_writer tests MPI-safe for multi-rank launches
Nov 7, 2026
3b770f5
fix(io): rename MO-basis Vxc matrix to vxcmo to avoid vxck collision
Nov 7, 2026
574e84f
fix(io): make out_mat_xc2 a final-step snapshot without g suffix
Nov 7, 2026
384e1cd
fix(io): write spin-independent H terms once with correct spin labels
Nov 7, 2026
cde869f
fix(io): add one-based Ionic_Step marker to Lx/Ly/Lz matrix output
Nov 7, 2026
97dd337
fix(io): honor out_app_flag for mulliken.txt output
Nov 7, 2026
568b530
fix(io): honor out_app_flag and out_freq_ion for eig_occ.txt
Nov 7, 2026
8b1a7b0
fix(io): write band outputs on the out_freq_ion rhythm
Nov 7, 2026
43d2d80
fix(io): write eband outputs on the out_freq_ion rhythm
Nov 7, 2026
73700fb
fix(io): number projected-band XML files per step and annotate the frame
Nov 7, 2026
81e8740
fix(io): route xc(r) cubes through CHG/ and out_app_flag
Nov 7, 2026
3a5ee91
fix(io): unify scalar-text ionic-step markers as "# Ionic_Step N"
Nov 7, 2026
ef9764d
fix(io): use the bare "Ionic_Step N" marker for CSR and real-space ma…
Nov 7, 2026
d3d466f
docs(example): align relax/output INPUT comments with actual products
Nov 7, 2026
5f47ede
fix(io): add spin and step suffixes to the k-space dH matrix names
Nov 7, 2026
af89f99
fix(io): report the real ionic step in the LDOS cube header
Nov 7, 2026
6d491af
fix(io): write a valid cube header for the out_xc_r files
Nov 7, 2026
0b26605
docs(input): describe the final-snapshot and cube-header behaviour
Nov 7, 2026
274a4dd
fix(io): report the real ionic step in the partial-charge cube header
Nov 7, 2026
d11ec9b
fix(io): report the real ionic step in the PW LDOS / STM cube headers
Nov 7, 2026
0e8c42d
fix(test): align MO-basis Vxc references with 1-based ionic step
Nov 7, 2026
af5a0e6
docs(example): document output layout convention for out_app_flag modes
Nov 7, 2026
2504a57
Merge remote-tracking branch 'upstream/develop' into pr-8293
Nov 8, 2026
32d97c3
fix(io): match Libxc mixed-derivative labels to packing order
Nov 8, 2026
004ce71
test(io): pin sparse writer truncation for final-snapshot outputs
Nov 8, 2026
c72ee57
fix(ase): discover eig_occ files for all out_app_flag modes
Nov 8, 2026
e041630
refactor(io): pass out_app_flag to nscf_bands explicitly
Nov 8, 2026
58874b0
fix(io): correct v4rho3sigma channel labels
Nov 9, 2026
7eb3518
fix(io): append MO Vxc matrices in mode 1
Nov 9, 2026
1e33947
test(io): capture process rank once in hsr writer tests
Nov 9, 2026
48a6638
test(io): cover mode-2 band snapshots in BANDS/
Nov 9, 2026
6b2df07
test(io): write eig_occ test files to testing::TempDir()
Nov 9, 2026
a02332e
test(io): write sparse H/S test file to testing::TempDir()
Nov 9, 2026
f7cf5ff
docs(input): document band, Vxc and xc_r output naming
Nov 9, 2026
b7b69aa
fix(io): make dS/dR sparse output spin-independent
Nov 9, 2026
068fa11
refactor(io): drop spin suffix from dS/dR sparse output names
Nov 9, 2026
b9b0d63
refactor(io): write dH/dR and dS/dR in the H(R)/S(R) CSR layout
Nov 9, 2026
42b8493
refactor(io): split r(R) sparse output into per-axis CSR files
Nov 9, 2026
c1ff9a6
feat(io): align tr_nao.csr with the self-describing CSR layout
Nov 9, 2026
bfbe07d
feat(io): write angular-momentum matrices in the self-describing CSR …
Nov 9, 2026
a0286ce
feat(io): add per-frame provenance headers to ionic-step outputs
Nov 9, 2026
156abc0
Align H(k)/S(k) text output format with write_dmk
Nov 9, 2026
1f93a72
Fix text hk filename k-index and prefix
Nov 9, 2026
dac4928
Update integration-test refs for new H(k)/S(k) text format
Nov 9, 2026
c0c8b83
S(k) filename: drop redundant spin suffix
Nov 9, 2026
38ff398
Fix ibz_ik formula for symmetry-reduced k-point lists
Nov 9, 2026
fac73df
Align T(k) text output format with write_dmk / write_hsk
Nov 9, 2026
b4c7c5c
Align Hamiltonian-term H(k) text output with write_dmk / write_hsk
Nov 9, 2026
1500cec
Align Vxc(R) CSR output with the H(R) CSR layout
Nov 9, 2026
bab7046
Unify running-log file-written notices
Nov 9, 2026
e03e819
Announce remaining LCAO output files in running log
Nov 9, 2026
3c48904
Announce structural and run-metadata files in running log
Nov 9, 2026
5eefe27
Fix running-log banners, units and cube descriptors
Nov 9, 2026
9405813
Write the NAO orbital table once per run
Nov 9, 2026
5d82d7d
Drop the duplicated H(k)/S(k) banner
Nov 9, 2026
7a482d0
Wrap the skipped-autoset warning across several log lines
Nov 9, 2026
7f144c8
fix(ase): align eig_occ frames by Ionic_Step ID
Nov 9, 2026
a523997
docs(example): refresh output comments in 04_relax_with_output_lcao I…
Nov 9, 2026
2c0c585
fix(io): align H(k)/T(k) naming and dense text output contract
Nov 9, 2026
059e7a4
chore(io): clean reference whitespace and lock T(k) naming
Nov 9, 2026
ec61879
test(io): cover dense H(k) text output and isolate dS/dR artifacts
Nov 9, 2026
5593726
CI: add paths-ignore to non-required-check workflows
Nov 12, 2026
8ae5f75
test(io): parse DOS grid size past the provenance header
Nov 13, 2026
05c92b8
fix(io): report H(R) term output only after a successful write
Nov 13, 2026
fd0172d
fix(io): write H(k)/S(k) text bodies in row-major order
Nov 13, 2026
a71f4dd
fix(io): truncate H(k) term files at the first ionic step
Nov 13, 2026
3fb10d7
refactor(io): pass rank and log handles explicitly to cut global use
Nov 13, 2026
181541f
fix(ase): never fall back to a stale eig_occ.txt for announced runs
Nov 13, 2026
e904c7e
chore(io): trim header includes and align output docs with tests
Nov 13, 2026
87fb942
test(io): cover the Vxc(MO) text append contract
Nov 13, 2026
92fa197
test(io): smoke-test the Angmom_op CSR assembly path
Nov 13, 2026
340c1b5
test(io): assert Angmom_op CSR values against the L kernels
Nov 13, 2026
b66485a
docs(io): document vxc matrix naming and gate README-only PRs
Nov 13, 2026
c122448
Merge remote-tracking branch 'upstream/develop' into 2026-11-05-a
Nov 13, 2026
930cecf
fix(io): adapt local writers to the Parallel_Blkcyclic rename
Nov 13, 2026
f81a490
test(io): decouple band dir from the global one and assert shifted sp…
Nov 13, 2026
a20dd89
test(ase): cover the legacy ionic step marker in eig_occ parsing
Nov 13, 2026
9ba3cba
refactor(io): extract libxc cube channel suffixes and test them
Nov 13, 2026
1d075de
refactor(io): centralize the per-step frame append decision
Nov 13, 2026
60e23fe
fix(io): stop emitting transposed T(k) and DM(k) text bodies
Nov 16, 2026
d46e01e
fix(io): make DM(k) reading match the written format
Nov 16, 2026
f13a927
feat(io): restart LCAO from DM(k) with streaming reads
Nov 17, 2026
4ea3390
fix(io): always persist the final ionic step output
Nov 17, 2026
af5783b
refactor(io): unify CSR text headers and skip empty R blocks
Nov 18, 2026
12436a8
refactor(io): use the shared CSR header for S(R) output
Nov 18, 2026
44a063a
refactor(io): centralize sparse R-space file naming
Nov 18, 2026
d5a01e9
docs(input): state that CSR outputs omit empty R blocks
Nov 18, 2026
8f8ed40
fix(pw): resolve EXX source files in the mode-2 output layout
Nov 18, 2026
1253c5a
docs(pw): describe EXX source file discovery for hybrid NSCF
Nov 18, 2026
51bf49c
refactor(io): use out_freq_ion as the only output cadence
Nov 18, 2026
d0de95b
fix(io): reject out_mat_l with nspin=4 during input parsing
Nov 18, 2026
69ba37a
refactor(io): share the CSR banner between sparse writers and HContainer
Nov 18, 2026
74696ac
perf(io): skip row-wise reductions for empty CSR blocks
Nov 18, 2026
7f0241e
fix(io): pass real istep to write_Vxc_LIP so # Ionic_Step is 1-based
Nov 18, 2026
cdf5bcb
fix(io): reject non-positive text precision for out_hsk/out_dmk/out_m…
Nov 18, 2026
ab851cf
Merge branch 'develop' of github.com:deepmodeling/abacus-develop into…
Nov 19, 2026
315ac2a
docs(input): correct out_mat_xc description for lcao_in_pw output dir…
Nov 19, 2026
2024e74
test(io): cover stale-frame truncation and payload in Vxc(MO) append …
Nov 19, 2026
8497763
fix(esolver): create MAT/ before output_SR in get_s mode-2 runs
Nov 19, 2026
3f19a7b
fix(io): validate stored k coordinates in read_dmk
Nov 19, 2026
db517ba
fix(lcao): broadcast DMR presence decision in init_chg_dm
Nov 19, 2026
0f805b6
test(io): use TempDir and assert stream opens in empty-CSR test
Nov 19, 2026
f70f501
test(io): replace default basis argument with PW convenience overload
Nov 19, 2026
8ee1ccc
test(io): rename dH/dk outputs to dhkK<dir>_iaN and update refs
Nov 19, 2026
cc268b1
fix(io): reject non-finite DM(k) restart values
Nov 19, 2026
2987444
docs(io): document DM(k) conj-first element convention
Nov 19, 2026
d07665a
test(ref): sync CSR refs with case-input R counts after hs_sparse_io …
Nov 19, 2026
eaa182d
fix(dmk): propagate UnitCell parse failures instead of misreading coo…
Nov 19, 2026
f5772dc
Merge branch 'develop' of github.com:deepmodeling/abacus-develop into…
Nov 19, 2026
62dc5d0
fix(dmk): broadcast read status on descriptor communicator
Nov 19, 2026
1155916
docs(input): clarify out_xc_r cube file naming channels
Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/ase_plugin_test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@ name: Atomic Simulation Environment (ASE) Plugin Test

on:
pull_request:
paths-ignore:
- 'docs/**'
- '**/*.md'
- '.coderabbit.yaml'

defaults:
run:
Expand Down
4 changes: 4 additions & 0 deletions .github/workflows/cuda.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ name: CUDA Test
on:
workflow_dispatch:
pull_request:
paths-ignore:
- 'docs/**'
- '**/*.md'
- '.coderabbit.yaml'
push:
branches:
- develop
Expand Down
4 changes: 4 additions & 0 deletions .github/workflows/pytest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@ name: Pyabacus Build and Test

on:
pull_request:
paths-ignore:
- 'docs/**'
- '**/*.md'
Comment thread
mohanchen marked this conversation as resolved.
Resolved
- '.coderabbit.yaml'

defaults:
run:
Expand Down
52 changes: 52 additions & 0 deletions .github/workflows/readme-metadata.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: README metadata

# pytest.yml ignores docs and markdown-only changes, which also skips
# README edits even though the Python packages declare those files as
# their package readme. Keep a lightweight check on that path.

on:
pull_request:
paths:
- '**/README.md'
- '**/pyproject.toml'

defaults:
run:
shell: bash

jobs:
metadata:
name: Package readme metadata
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7.0.1
- name: Set up Python
uses: actions/setup-python@v7
with:
python-version: 3.8
- name: Validate readme declarations
run: |
python - <<'EOF'
import pathlib
import re
import sys

failures = []
for pyproject in sorted(pathlib.Path(".").rglob("pyproject.toml")):
text = pyproject.read_text(encoding="utf-8")
match = re.search(r'^\s*readme\s*=\s*["\']([^"\']+)["\']', text, re.M)
if match is None:
continue
readme = pyproject.parent / match.group(1)
if not readme.is_file():
failures.append(f"{pyproject}: declared readme {match.group(1)} does not exist")
elif readme.stat().st_size == 0:
failures.append(f"{pyproject}: declared readme {match.group(1)} is empty")
else:
print(f"ok: {pyproject} -> {match.group(1)}")

for failure in failures:
print(f"error: {failure}")
sys.exit(1 if failures else 0)
EOF
4 changes: 2 additions & 2 deletions docs/advanced/elec_properties/dos.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,13 +87,13 @@ Along with the DOS files, we also produce the projected density of states (PDOS)
The PDOS file uses a plain-text format. Each row corresponds to one energy point and one atom. Columns: energy(eV), atom (1-based), species, then pdos values ordered as s(1), p(3), d(5), f(7), etc. Zeta components are summed, and values below 1e-6 are zeroed out.

```
# istep: 1
# Ionic_Step 1
# npoints: 2736
# energy(eV) atom species pdos(1/eV), columns: s(m=0) p(m=0,+1,-1) d(m=0,+1,-1,+2,-2) f(m=0,+1,-1,+2,-2,+3,-3)
-55.607730 1 Fe 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000
...
```

The `# istep:` line is only present for geometry-optimization (istep) output. Within each angular momentum `l`, the `2l+1` columns follow the magnetic-quantum-number order `m = 0, +1, -1, +2, -2, ...`.
The `# Ionic_Step` line is only present for geometry-optimization (istep) output. Within each angular momentum `l`, the `2l+1` columns follow the magnetic-quantum-number order `m = 0, +1, -1, +2, -2, ...`.

For nspin=2, two files are written (pdoss1* and pdoss2*), one per spin channel. For nspin=4, the two spinor components are summed into a single file. The unit of PDOS is also `(number of states)/(eV * unitcell)`.
26 changes: 13 additions & 13 deletions docs/advanced/elec_properties/hs_matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ and

## out_hsk

Use [out_hsk](../input_files/input-main.md#out_hsk) to print the upper triangular part of the Hamiltonian and overlap matrices for each k point into `OUT.${suffix}`. It is available for both gamma-only and multi-k calculations. The format value is:
Use [out_hsk](../input_files/input-main.md#out_hsk) to print the Hamiltonian and overlap matrices for each k point into `OUT.${suffix}`. It is available for both gamma-only and multi-k calculations. The format value is:

| Value | Format |
| --- | --- |
Expand All @@ -27,29 +27,29 @@ The $H(k)$ and $S(k)$ matrices are stored with numerical atomic orbitals as basi

As for information on the k points, one may look for the `SETUP K-POINTS` section in the running log.

The output filenames depend on the k-point algorithm and `nspin`:
The output filenames depend on the k-point algorithm and `nspin`. Text output (`out_hsk 1`) and native binary output (`out_hsk 2`) use different gamma-only names, because only the text writer omits the `k` marker when there is no k-point index to report:

| Calculation mode | `nspin` | Hamiltonian files | Overlap files |
| --- | --- | --- | --- |
| `gamma_only = 1` | 1 | `hk_nao.txt` | `sk_nao.txt` |
| `gamma_only = 1` | 2 | `hks1_nao.txt`, `hks2_nao.txt` | `sk_nao.txt` |
| `gamma_only = 0` | 1 | `hk${k}_nao.txt` | `sk${k}_nao.txt` |
| `gamma_only = 0` | 2 | `hk${k}s1_nao.txt`, `hk${k}s2_nao.txt` | `sk${k}_nao.txt` |
| `gamma_only = 0` | 4 | `hk${k}s4_nao.txt` | `sk${k}_nao.txt` |
| Calculation mode | `nspin` | Text H(k) | Text S(k) | Binary H(k) | Binary S(k) |
| --- | --- | --- | --- | --- | --- |
| `gamma_only = 1` | 1 | `h_nao.txt` | `s_nao.txt` | `hk_nao.dat` | `sk_nao.dat` |
| `gamma_only = 1` | 2 | `hs1_nao.txt`, `hs2_nao.txt` | `s_nao.txt` | `hks1_nao.dat`, `hks2_nao.dat` | `sk_nao.dat` |
| `gamma_only = 0` | 1 | `hk${k}_nao.txt` | `sk${k}_nao.txt` | `hk${k}_nao.dat` | `sk${k}_nao.dat` |
| `gamma_only = 0` | 2 | `hk${k}s1_nao.txt`, `hk${k}s2_nao.txt` | `sk${k}_nao.txt` | `hk${k}s1_nao.dat`, `hk${k}s2_nao.dat` | `sk${k}_nao.dat` |
| `gamma_only = 0` | 4 | `hk${k}_nao.txt` | `sk${k}_nao.txt` | `hk${k}s4_nao.dat` | `sk${k}_nao.dat` |

Here `${k}` is the one-based k-point index. For `nspin = 2`, the overlap matrix is spin-independent, so only one overlap file is written for each physical k point. The gamma-only algorithm does not support `nspin = 4`; use the multi-k algorithm with an explicit Gamma-only `KPT` file for a noncollinear calculation at Gamma.
Here `${k}` is the one-based k-point index. For `nspin = 2`, the overlap matrix is spin-independent, so only one overlap file is written for each physical k point. The gamma-only algorithm does not support `nspin = 4`; use the multi-k algorithm with an explicit Gamma-only `KPT` file for a noncollinear calculation at Gamma. In text output the spinor Hamiltonian is stored as one complex matrix, so no spin suffix is added; the binary format keeps the historical `s4` marker.

Only when `out_app_flag` is 2 is `g${step}` inserted before `_nao`, where `${step}` is the one-based ionic-step index. For example, the first spin channel at the first k point and first ionic step is written to `hk1s1g1_nao.txt`. With `out_app_flag = 0` the fixed file is truncated and overwritten at every write, and with `out_app_flag = 1` it accumulates one record per written step.

Each output block starts with a comment header containing the one-based ionic-step index, filename, `gamma only` flag, and matrix dimensions. It is followed by `Row 1`, `Row 2`, and so on. Each row contains the matrix elements from the diagonal through the upper triangle.
With `out_hsk 1`, each ionic-step record is a self-describing text block. It starts with `Ionic_Step ${step}`, followed by the number of spin directions, the one-based spin index, the total number of k points, the one-based k-point index, the Cartesian and direct coordinates, the k-point weight, the Fermi energy in Ry, the number of localized basis functions, and the matrix dimension. A `user_defined_lattice` block with the lattice vectors and atomic positions follows. The matrix body then stores every element of the dense $N \times N$ matrix in row-major order: row by row from $i = 0$ to $N-1$, and within each row from $j = 0$ to $N-1$. Both triangles and the diagonal are written; the body is not restricted to the upper triangle. Four complex values or eight real values are written per line, and values with magnitude below $10^{-10}$ are flushed to zero.

For multi-k calculations, the matrices are Hermitian and each matrix element is written as `(real,imag)`. For gamma-only calculations, the matrices are symmetric and the matrix elements are written as real numbers.

> **Note (3.10-LTS):** In the 3.10-LTS version, the corresponding keyword is `out_mat_hs`, and the output file names are `data-0-H` and `data-0-S`, etc.

### Native Binary Format

For `out_hsk 2`, the filenames in the table above use `.dat` instead of `.txt`. Each matrix record is written without padding or a self-describing header:
For `out_hsk 2`, the binary filenames listed in the table above are used. Each matrix record is written without padding or a self-describing header:

1. the matrix dimension as a native C++ `int`;
2. the upper-triangular elements in row-major order, from `(0,0)` through `(0,N-1)`, then `(1,1)` through `(1,N-1)`, and so on;
Expand Down Expand Up @@ -105,7 +105,7 @@ Each ionic step is a complete record with no padding; its header is self-identif
4. `nnz` native `int` column indices.
5. `dimension + 1` native `long long` row pointers.

All R blocks stored by the internal HContainer are present, including blocks with zero nonzero values. The sparse threshold is `1e-10`, matching text CSR output. The format uses the host integer representation and byte order and therefore requires a compatible ABI. It does not contain unit-cell, spin, or matrix-label metadata; those are determined by the calculation input and filename.
All R blocks stored by the internal HContainer are present, including blocks with zero nonzero values. The binary sparse threshold is `1e-10`; the text CSR files instead drop complex components below `1e-16` and keep real values unfiltered, so the two formats may differ on near-zero elements. The format uses the host integer representation and byte order and therefore requires a compatible ABI. It does not contain unit-cell, spin, or matrix-label metadata; those are determined by the calculation input and filename.

When `out_app_flag` is 1, the first ionic step truncates the shared file and later ionic steps append complete records. When `out_app_flag` is 0, the fixed file is truncated and overwritten at every write. Only when `out_app_flag` is 2 is every ionic step written to its own file.

Expand Down
18 changes: 18 additions & 0 deletions docs/advanced/elec_properties/hybrid_nscf.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,24 @@ out_wfc_pw 0
out_chg 0
```

### Source file discovery

`read_file_dir` may point to an output directory produced with any
`out_app_flag`; the source files do not have to be renamed. Fixed names take
precedence:

| Source directory content | File used |
|---|---|
| `eig_occ.txt`, `wfk*_pw.dat` | The fixed names (modes 0 and 1) |
| Only numbered names | The latest written ionic step `g{step}`, and within it the latest electronic iteration `e{iter}`, for wavefunctions |

When fixed names are absent, occupations are searched in `read_file_dir` and
wavefunctions in `read_file_dir` followed by its `PSI/` subdirectory, which is
where `out_app_flag 2` stores them. For a multi-step source the last written
step is selected automatically; use a single-step SCF source when a specific
snapshot is required. A fixed-name file produced with `out_app_flag 1` must
contain a single SCF snapshot, since appended multi-frame files are rejected.

Supports CPU/CUDA and `nspin 1/2`; use one MPI rank for CUDA. ACE, SOC,
unscreened exchange, forces and stress are unsupported in this workflow.
Set `symmetry -1`: input `0` is accepted but PW EXX resets it to `-1` at runtime.
Expand Down
39 changes: 30 additions & 9 deletions docs/advanced/elec_properties/position_matrix.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,45 @@
# Extracting Position Matrices

In ABACUS, we provide the INPUT keyword [out_mat_r](../input_files/input-main.md#out_mat_r) to write the position matrices into a file named `data-rR-tr` in the directory `OUT.${suffix}`. The position matrices is defined as:
In ABACUS, we provide the INPUT keyword [out_mat_r](../input_files/input-main.md#out_mat_r) to write the position matrices into three files, one per Cartesian component: `rrx_nao.csr`, `rry_nao.csr` and `rrz_nao.csr`. They are stored in the matrix output directory, which is `OUT.${suffix}` when [out_app_flag](../input_files/input-main.md#out_app_flag) is 0 or 1 and its `MAT/` subdirectory when out_app_flag is 2; in the latter case a `g${step}` index is inserted before `_nao.csr`, where `${step}` is the one-based ionic-step index. The position matrices are defined as:

$$\langle \chi_\mu|\hat{r}|\chi_\nu\rangle$$

This functionality is not available for gamma_only calculations. If you want to use it in gamma_only calculations, you should turn off [gamma_only](../input_files/input-main.md#gamma_only), and explicitly specifies that gamma point is the only k point in the KPT file.

Each file or each section of the appended file starts with "STEP: " followed by the current ion/md step, then the second line starts with "Matrix Dimension of $r(R)$: " followed by the dimension of the matrix, and the third line starts with "Matrix number of $r(R)$: " followed by the matrix number. The rest of the format is arranged into blocks, such as:
Each file or each section of the appended file starts with an informative header:

```
-5 -5 -5 //R (lattice vector)
...
-5 -5 -4 //R (lattice vector)
...
-5 -5 -3 //R (lattice vector)
Ionic_Step 1
# print r matrix in real space r(R) x-component
1 # number of spin directions
1 # spin index
6 # number of localized basis
9 # number of Bravais lattice vector R

user_defined_lattice
...

#----------------------------------------------------------------------#
# CSR Format #
...
#----------------------------------------------------------------------#
```

Each block here contains the matrix for the corresponding cell. There are three columns in each block, giving the matrix elements in x, y, z directions, respectively. There are altogether nbasis * nbasis lines in each block, which emulates the matrix elements.
The header records the ionic step, the matrix label and Cartesian component, the spin metadata, the number of localized basis functions and the number of non-empty Bravais lattice vectors actually written, followed by the `user_defined_lattice` cell block and the CSR format description. The rest of the file consists of one sparse block per non-empty Bravais lattice vector (an R vector is kept when at least one of the three Cartesian components has an element above the sparse threshold), such as:

In molecular dynamics (MD) calculations, the output frequency is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion). With out_app_flag = 2, each written ionic step has its own file named `rrg${step}_nao.txt`, where `${step}` is the one-based ionic-step index; with out_app_flag = 0 or 1 the fixed name `rr_nao.txt` is reused (mode 0 truncates and overwrites it at every write, mode 1 appends one record per written step). The single-shot output of `calculation = get_s` is always named `rr_nao.txt`. The files are stored in `OUT.${suffix}` when [out_app_flag](../input_files/input-main.md#out_app_flag) is 0 or 1, and in its `MAT/` subdirectory when out_app_flag is 2. For example, if we are running a 10-step MD with out_freq_ion = 3 and out_app_flag = 2, the files are `MAT/rrg1_nao.txt`, `MAT/rrg4_nao.txt`, `MAT/rrg7_nao.txt`, and `MAT/rrg10_nao.txt`.
```
-5 -5 -5 12 // R (lattice vector) and number of non-zero elements
# CSR values
...
# CSR column indices
...
# CSR row pointers
...
```

Values wrap every six entries and column indices every sixteen entries. Only Bravais lattice vectors for which at least one of the three components has a non-zero element are written; a component that is empty for a given `R` is still recorded as a valid zero block, so the three files share the same sequence of `R` blocks.

In molecular dynamics (MD) calculations, the output frequency is controlled by [out_freq_ion](../input_files/input-main.md#out_freq_ion). With out_app_flag = 2, each written ionic step has its own files named `rrxg${step}_nao.csr`, `rryg${step}_nao.csr` and `rrzg${step}_nao.csr`, where `${step}` is the one-based ionic-step index; with out_app_flag = 0 or 1 the fixed names `rrx_nao.csr`, `rry_nao.csr` and `rrz_nao.csr` are reused (mode 0 truncates and overwrites them at every write, mode 1 appends one record per written step). The single-shot output of `calculation = get_s` is always written to the fixed names. For example, if we are running a 10-step MD with out_freq_ion = 3 and out_app_flag = 2, the x-component files are `MAT/rrxg1_nao.csr`, `MAT/rrxg4_nao.csr`, `MAT/rrxg7_nao.csr`, and `MAT/rrxg10_nao.csr`, and the y/z components follow the same pattern.

## get_s
We also offer the option of only calculating the position matrix without running SCF. For that purpose, in `INPUT` file we need to set the keyword [calculation](../input_files/input-main.md#calculation) to `get_s`, and [out_mat_r](../input_files/input-main.md#out_mat_r) to `true`.
Loading
Loading