Skip to content

Write formatted Wannier90 spin matrices for spinor LCAO calculations - #8331

Open
Stardust0831 wants to merge 6 commits into
deepmodeling:developfrom
Stardust0831:feat/lcao-wannier-spn
Open

Stardust0831 wants to merge 6 commits into
deepmodeling:developfrom
Stardust0831:feat/lcao-wannier-spn

Conversation

@Stardust0831

@Stardust0831 Stardust0831 commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Add out_wannier_spn to the direct LCAO Wannier90 interface. ABACUS writes a formatted <seedname>.spn by default when towannier90=1, calculation=nscf, basis_type=lcao, wannier_method=2 and nspin=4. Set out_wannier_spn=0 to skip it. In other configurations the default is off, and an explicit 1 triggers the standard INPUT requirement error. In the Wannier90 input, set spinors = true and spn_formatted = true.

For each k point, the writer folds the existing orbital overlap into S(k) and evaluates the three Pauli matrices between the retained Bloch spinors. It writes the upper triangle in the same band order and gauge as the other Wannier90 files, respecting exclude_bands. The writer shares its stream status with all MPI ranks after opening and closing the file.

When the Python interface requests spin output, it sets the text format and checks that out_wannier_mmn, out_wannier_amn and out_wannier_eig are enabled before launching NSCF. This prevents a companion file from an earlier calculation in OUT.ABACUS from being paired with new spin matrices. Native ABACUS can also export .spn independently.

Addresses #6968 for the direct LCAO interface.

Tests

The regression runs a fully relativistic, noncollinear oxygen system at two k points with different complex overlap matrices and excludes the third band. The SCF run succeeds with the flag omitted and rejects an explicit spin-output request. The direct Wannier NSCF writes the file by default and skips it with an explicit 0. The regression compares every exported complex element against an independent NumPy calculation using the binary wavefunctions and orbital overlaps from the same run. Wannier90 builds the checkpoint and postw90.x reads the formatted file and computes the spin magnetic moment.

The following passed on SAI with Wannier90 3.1.0:

ctest --test-dir build --no-tests=error -V -R '^03_NAO_wannier_spn$'
python3 interfaces/Wannier90_interface/tests/check_wannier_spn.py wannier90.x postw90.x mpirun -np 1 /path/to/abacus_basic_para
PYTHONPATH=interfaces/Wannier90_interface python3 -m unittest discover -s interfaces/Wannier90_interface/tests -v

For 546 complex elements per run, the maximum absolute error was 4.121e-16 with four MPI ranks (CTest) and 3.357e-16 with one rank, against a tolerance of 1e-10. Both runs produced the same spin magnetic moment to the printed precision. The optional CTest invokes the external Wannier90 and postw90 executables to verify compatibility with the consumer.

For both MPI configurations, the test verifies that the absolute .spn path in the NSCF log points to the generated file. Both configurations also wrote .spn with all three companion outputs disabled. A directory at the output path forced an open failure, and a symlink to /dev/full forced a write failure. Each invocation exited with a nonzero status, and every rank's NSCF log contained the corresponding diagnostic.

The Python regression prepopulates OUT.ABACUS with old files and disables each companion in turn. Each case reports the disabled parameter before launching NSCF or copying files. The full Python workflow passed SCF, NSCF, Wannierisation and postw90, including a rerun with stale files in the working directory.

abacus_basic_para -h out_wannier_spn displayed the input metadata. abacus_basic_para --check-input gave the expected result for 27 combinations covering an omitted flag, an explicit 0 and an explicit 1. With the flag omitted, the non-spin-polarized diamond example wrote MMN, AMN and EIG and skipped SPN. The spinor Bi2Se3 example produced a formatted SPN with 969,600 complex elements, which postw90.x read successfully.

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Python SPN workflow can mix files from different NSCF runs when a companion output is disabled. This was a static source review; no builds or runtime tests were run.

@AsTonyshment AsTonyshment left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, no other comments from my side.

Use the existing five export prerequisites to choose the default when out_wannier_spn is omitted. Keep explicit flags under the existing INPUT requirement. Match the default when preparing the Python workflow and cover both the SCF and NSCF paths.
@Stardust0831

This comment was marked as off-topic.

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One test-coverage suggestion below. This was a static source review; no builds, CLI checks or runtime tests were run.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants