Skip to content

fix(unfold): refuse an atom with no translated image, and take the nearest image - #93

Merged
lllangWV merged 9 commits into
mainfrom
fix/unfold-translation-map
Oct 28, 2026
Merged

lllangWV merged 9 commits into
mainfrom
fix/unfold-translation-map

Conversation

@lllangWV

Copy link
Copy Markdown
Owner
film.mp4

Why

Band unfolding pairs each atom with its image under every primitive-cell translation. When no atom matched, the map kept index 0. When two atoms matched, the last one won. A vacancy, an interstitial, or a transformation_matrix that does not make the supercell gave unfolding weights with no error. This was item "Unfolding silently falls back to basis 0" in #57.

What changed

  • New translation_images in pyprocar/utils/unfolder.py builds the map. It picks the nearest same-label site within tol_radius. It raises a ValueError that names the atom and the translation when the map is not one to one.
  • Unfolder (behind ebs.unfold and pyprocar.unfold) and the legacy procarunfold.Unfolder both call it.
  • The legacy unfolder tests used a "2x2x2 supercell" with 2 atoms, so they pinned the fallback. They now use the 8 sites of a real 2x2x2 supercell.

Scope

  • A supercell with a vacancy or an interstitial is refused, not unfolded. A ghost-atom scheme would be a new feature.
  • A substituted atom still maps onto its host site, so alloy supercells still unfold. A guard test holds this.
  • The NaN weight for a band whose phases are all zero (Plotting and QE-phase defects (tracker) #57) is a separate item. This PR does not touch it.

Blast Radius

Every pyprocar.unfold and ebs.unfold call goes through the new map. For a valid supercell the map is the same, so the weights are the same. A call that used to return wrong weights now raises.

Verification

  • Wrong matrix on the MgB2 fixture (data/examples/bands/unfolding/supercell, diag(4, 2, 1) instead of diag(2, 2, 2)). On main the weights differ from the correct ones by up to 0.74, with no error. On the PR it raises, naming atom 0 (Mg) and the translation (0.25, 0, 0). Head dfd4777f.

    main (before) plots wrong weights with no error; PR (after) raises a ValueError that names the atom and translation

  • Correct matrix on the same fixture. The diag(2, 2, 2) weights are bitwise identical on main and the PR (max difference 0.0, 150 x 80 weights).

  • Independent reference. $H run ref-unfold data/examples/bands/unfolding .../ref_unfold.py matches ebs.unfold to 8.9e-16. Its analytic check passes at 1.1e-16.

  • Red, then green. python .github/scripts/red_green.py origin/main passes. The vacancy, wrong-matrix and interstitial cases did not raise on main. The 1.6 Angstrom dimer's bonding band got weight 0.0 on main, and gets 1.0 (the Popescu-Zunger value) here.

  • CI commands. The non-data suite passes (3580 tests). The 95 data-marked unfolding tests pass. ruff check and format gates pass. The ty baseline gate shows no new diagnostic from this change, and 4 stale entries are pruned in their own commit.

Not verified

  • No real DFT supercell with a vacancy was run. The vacancy path is the same branch as the wrong-matrix path, which ran on the real fixture.
  • Locally, ty reports 3 unresolved-import diagnostics in tests/scripts/. main shows the same 3 in this worktree, so CI is the final check.

Created with Claude Opus 5.5 in T3 Code.

…t image wins

Red on main: a vacancy and a transformation_matrix that does not make the
cell return weights with no error, and a 1.6 Angstrom dimer's bonding band
gets weight 0 instead of 1.
… are supercells

The 2x2x2 fixture held atoms at the origin and the body centre only, so six
of its eight translations had no image and the tests pinned the silent
fallback to basis 0. It now holds the eight sites of the supercell.
Two atoms landing on one image leave another atom with no preimage, so the
translation map is not one to one.
…arest image

Unfolder._make_translate_maps left index 0 for an atom with no image under
a primitive-cell translation, and let the last atom within tol_radius win.
A vacancy, an interstitial or a transformation_matrix that does not make
the supercell gave weights with no error, and a short bond inside the
tolerance mapped an atom onto its neighbour.

translation_images now picks the nearest same-label site within the
tolerance and raises a ValueError naming the atom and the translation when
the map is not one to one. Both unfolders call it.
@lllangWV
lllangWV merged commit 26ecebc into main Oct 28, 2026
5 checks passed
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.

1 participant