fix(vasp): warn when POTCAR and POSCAR species order disagree by njzjz · Pull Request #1046 · deepmodeling/dpdata

njzjz · 2026-07-27T05:49:47Z

Fixes #778.

What is actually happening

I reproduced the report with the OUTCAR attached to the issue:

dpdata atom_names: ['Li', 'O',  'F', 'Na', 'Mg', 'Al',  'K', 'Ca']
dpdata atom_numbs: [  3,   39,    3,    3,    3,    3,   10,    6]
POSCAR title     :  Li3  F39   K3   Mg3   Ca3   Na3  Al10   O6

dpdata is not reordering anything. The OUTCAR lists its POTCAR blocks in the order Li O F Na Mg Al K Ca, while the POSCAR title says Li3 F39 K3 Mg3 Ca3 Na3 Al10 O6. VASP takes ions per type from the POSCAR and the species identities from the POTCAR, in POTCAR order, and pairs them positionally without checking that the two agree.

The per-type mass array VASP itself printed settles which pairing it used:

POMASS =   7.01 16.00 19.00 22.99 24.30 26.98 39.10 40.08
           Li     O     F    Na    Mg    Al     K    Ca
ions per type =    3   39    3     3     3     3    10     6

Type 2 has mass 16.00 and 39 ions, so VASP computed Li3 O39 F3 Na3 Mg3 Al3 K10 Ca6 — exactly what dpdata reports. type.raw and type_map.raw are consistent with the calculation that was run. The real problem is upstream: that POTCAR was concatenated in a different order than the POSCAR lists its species, so the calculation used the wrong potential for seven of the eight species, and nothing told the user.

Change

Since dpdata cannot fix the data, it can at least stop the silence. system_info now compares the POTCAR-derived names against the POSCAR title and warns when they disagree:

UserWarning: the POTCAR species order in this OUTCAR (Li O F Na Mg Al K Ca) does not
match the POSCAR title (Li F K Mg Ca Na Al O). VASP assigns the 'ions per type' counts
by POTCAR order, so the atom names reported here are what VASP actually computed; if
that is not what you intended, the POTCAR was concatenated in a different order than
the POSCAR lists its species and the calculation itself used the wrong potentials.

The parsed data is unchanged — the warning is purely diagnostic.

Avoiding false positives

The POSCAR title is arbitrary user text, so it is only read as a formula when every token matches ^[A-Z][a-z]?\d*$ and the symbol is in dpdata.periodic_table.ELEMENTS. VASP pads the title into a 40-character field, so a full-width title is treated as truncated and its final token is dropped — Cr3 Mn5 ... Nb5 M compares the first ten species and ignores the cut one. A single-token title is rejected, since one species cannot disagree on ordering and a one-word title is far more likely to be prose.

Checked against every OUTCAR fixture in the repo; all stay silent:

fixture	title	parsed	warns
`OUTCAR.ch4.1step`	`H C`	`[H, C]`	no
`OUTCAR.ch4.unconverged`	`H C`	`[H, C]`	no
`OUTCAR.Ge.vdw`	`File generated by python recompute scrip`	—	no
`OUTCAR.h2o.md`	`POSCAR file written by OVITO`	—	no
`OUTCAR.h2o.md.10`	`POSCAR file written by OVITO`	—	no
`6362_OUTCAR`	`B8 O6`	`[B, O]`	no
`outcar.longit/OUTCAR`	`Cr3 Mn5 ... Nb5 M`	first 10	no
issue #778 OUTCAR	`Li3 F39 K3 ...`	all 8	yes

Validation

tests/test_vasp_outcar_species_order.py, 13 new cases covering formula parsing, prose rejection, unknown symbols, truncation, and an end-to-end OUTCAR whose two TITEL records are swapped so the POTCAR order contradicts the title.
python -m unittest discover — 2249 passed, 28 skipped.
ruff format / ruff check clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

Bug Fixes
- Added validation for mismatches between species ordering in VASP POSCAR and POTCAR data.
- Displays a warning when inconsistent ordering may affect the interpretation of ion counts.
- Handles formula titles with element counts, missing titles, prose, and truncated entries.
Tests
- Added coverage for matching, conflicting, and truncated species-order scenarios when loading OUTCAR data.

VASP takes the `ions per type` counts from the POSCAR but the species identities from the POTCAR, in POTCAR order, and pairs them positionally without checking. When the two files list species in different orders VASP neither reorders nor complains, so every count lands on the wrong element and dpdata faithfully reports the mislabeled system. The OUTCAR in deepmodeling#778 shows exactly this: POTCAR order is Li O F Na Mg Al K Ca while the POSCAR title reads Li3 F39 K3 Mg3 Ca3 Na3 Al10 O6. The per-type mass array VASP printed, POMASS = 7.01 16.00 19.00 22.99 24.30 26.98 39.10 40.08 confirms VASP used the POTCAR order, so dpdata's output matches what was computed -- but the reporter had no way to see that their potentials did not match their structure. Compare the POTCAR-derived names against the POSCAR title when that title reads as a chemical formula, and warn on a mismatch. The title is free-form text, so it is only parsed when every token is an element symbol with an optional count; VASP pads it to 40 characters, so a full-width title has its final, possibly cut, token dropped. All seven OUTCAR fixtures in the test suite stay silent. Fixes deepmodeling#778. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

codspeed-hq · 2026-07-27T05:51:09Z

Merging this PR will not alter performance

⚠️

Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

✅ 2 untouched benchmarks

_{Comparing njzjz:fix/issue-778 (b864f7c) with master (c77e038)}

codecov · 2026-07-27T05:51:15Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.67%. Comparing base (c77e038) to head (b864f7c).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1046      +/-   ##
==========================================
+ Coverage   87.63%   87.67%   +0.04%     
==========================================
  Files          90       90              
  Lines        9209     9242      +33     
==========================================
+ Hits         8070     8103      +33     
  Misses       1139     1139

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

coderabbitai · 2026-07-27T05:51:34Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 47317fa4-e226-4fc5-b975-4e2a6980aa52

📥 Commits

Reviewing files that changed from the base of the PR and between c77e038 and b864f7c.

📒 Files selected for processing (2)

dpdata/formats/vasp/outcar.py
tests/test_vasp_outcar_species_order.py

📝 Walkthrough

Walkthrough

outcar.py parses the echoed POSCAR title, compares its species order with POTCAR-derived atom names, and warns on mismatches. New tests cover formula parsing, warning behavior, truncated titles, and end-to-end OUTCAR loading.

Changes

VASP species order validation

Layer / File(s)	Summary
POSCAR formula parsing and order checking `dpdata/formats/vasp/outcar.py`	Adds POSCAR title parsing and warnings for disagreements between POSCAR species order and POTCAR-derived atom order.
OUTCAR integration and regression coverage `dpdata/formats/vasp/outcar.py`, `tests/test_vasp_outcar_species_order.py`	Captures the echoed POSCAR title during `system_info`, validates finalized atom names, and tests parsing, warnings, truncation, and complete OUTCAR loading.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: bug

Suggested reviewers: copilot, njzjz-bot

Sequence Diagram(s)

sequenceDiagram
  participant OUTCAR
  participant system_info
  participant order_validation
  OUTCAR->>system_info: provide POSCAR title and POTCAR records
  system_info->>order_validation: compare POSCAR species with atom_names
  order_validation-->>system_info: return silently or emit order warning

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 19.05% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: warning when POTCAR and POSCAR species orders disagree.
Linked Issues check	✅ Passed	The PR addresses `#778` by detecting POTCAR/POSCAR order mismatches, warning users, and preserving the calculation's actual atom order.
Out of Scope Changes check	✅ Passed	The added parser, warning helper, and tests all support the species-order mismatch warning and stay within scope.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Copilot

Pull request overview

This PR adds a diagnostic warning to the VASP OUTCAR parser to help users detect a common upstream input mistake: when POTCAR species order disagrees with the species order implied by the POSCAR title, causing VASP (and therefore dpdata) to label species/counts positionally in POTCAR order without error.

Changes:

Add formula_from_poscar_title() and check_potcar_poscar_order() to compare POTCAR-derived atom names against a formula-like POSCAR title and emit a warning on mismatch.
Extend system_info() to capture the POSCAR = ... title from OUTCAR and invoke the new mismatch check.
Add a new test module covering formula parsing edge cases and an end-to-end mismatch warning scenario.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
`dpdata/formats/vasp/outcar.py`	Parses `POSCAR = ...` title and warns when POTCAR order conflicts with formula-like POSCAR title.
`tests/test_vasp_outcar_species_order.py`	Adds unit and integration tests for title parsing and POTCAR/POSCAR order mismatch warnings.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+            # the POSCAR title echoed among the start parameters, e.g.
+            # POSCAR =  Li3 F39 K3 Mg3 Ca3 Na3 Al10 O6
+            m = re.match(r"\s*POSCAR\s*=\s?(.*)$", ii)
+            if m:
+                poscar_title = m.group(1)


Copilot AI review requested due to automatic review settings July 27, 2026 05:49

dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. dpdata vasp labels Jul 27, 2026

Copilot started reviewing on behalf of njzjz July 27, 2026 05:50 View session

Copilot AI reviewed Jul 27, 2026

View reviewed changes

Comment thread dpdata/formats/vasp/outcar.py

Comment on lines +155 to +159

# the POSCAR title echoed among the start parameters, e.g.

# POSCAR = Li3 F39 K3 Mg3 Ca3 Na3 Al10 O6

m = re.match(r"\s*POSCAR\s*=\s?(.*)$", ii)

if m:

poscar_title = m.group(1)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(vasp): warn when POTCAR and POSCAR species order disagree - #1046

fix(vasp): warn when POTCAR and POSCAR species order disagree#1046
njzjz wants to merge 1 commit into
deepmodeling:masterfrom
njzjz:fix/issue-778

njzjz commented Jul 27, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

codspeed-hq Bot commented Jul 27, 2026

Uh oh!

codecov Bot commented Jul 27, 2026

Uh oh!

coderabbitai Bot commented Jul 27, 2026

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

njzjz commented Jul 27, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is actually happening

Change

Avoiding false positives

Validation

Summary by CodeRabbit

Uh oh!

codspeed-hq Bot commented Jul 27, 2026

Merging this PR will not alter performance

Uh oh!

codecov Bot commented Jul 27, 2026

Codecov Report

Uh oh!

coderabbitai Bot commented Jul 27, 2026

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

njzjz commented Jul 27, 2026 •

edited by coderabbitai Bot

Loading