Port the magnetic exchange workflow from atomate1 (Heisenberg fit + Vampire Tc) by Luguza · Pull Request #1528 · materialsproject/atomate2

Luguza · 2026-08-18T08:55:11Z

Summary

Port of atomate1's ExchangeWF. Closes #1404.
However, this PR is part of a large refactor I did for the underlying HeisenbergMapper from pymatgen.
The following PRs are connected and potentially still ongoing:

Add ferri_by_motif_{wyckoff_symbol}_flip strategy; fix dedup never-pruning bug pymatgen#4699
[breaking] Support mixed-supercell orderings in HeisenbergMapper via a shared parent-cell sublattice definition pymatgen#4700

Introduces

New ExchangeMaker flow (atomate2/common/flows/exchange.py): port of atomate1's
ExchangeWF. Given magnetic structures with different spin configurations and
their energies it fits a classical Heisenberg Hamiltonian with pymatgen's
HeisenbergMapper and, optionally, runs Vampire Monte-Carlo for the critical temperature.
New jobs (atomate2/common/jobs/exchange.py): heisenberg_mapping and
build_exchange_doc, replacing the atomate1 HeisenbergModelMapping,
HeisenbergModelToDb and VampireToDb firetasks.
ExchangeMaker.make_from_ordering_doc convenience constructor for chaining onto the
magnetic-orderings workflow: it pulls structures, per-atom energies and the parent
structure out of a computed MagneticOrderingsDocument and re-attaches the magmom site
property that HeisenbergMapper requires.
Input validation in make: structure/energy counts must match, every structure must
carry a magmom site property, and orderings are sorted so the ground state is index 0.
New ExchangeDocument schema (atomate2/common/schemas/exchange.py) with formula,
parent structure, the {cutoff, tol} Heisenberg settings, the Vampire settings actually
used, the fit residual (RMS, meV per magnetic ion - intensive in cell size and number of
orderings, so comparable between materials), ex_params, ex_mat, the serialized
HeisenbergModel, and critical_temp / full VampireOutput when Vampire was run.
New atomate2.vampire subpackage vendoring pymatgen's VampireCaller /
VampireOutput, which were removed from pymatgen in 2026.3.23 (Major reorganization of pymatgen repo pymatgen#4595).
Provenance and every local change are documented in the module docstring.
atomate2/vampire/jobs/run_vampire.py wraps it as a jobflow job.
Vendored caller adapted to the reworked HeisenbergModel API: per-ordering
sublattice_ids and the igraph interaction graph replace the old unique_site_ids dict
and _get_j_exc lookup, and the ground-state cell is read from magnetic_structures[0]
rather than structures[0], which now retains the non-magnetic ions. The avg option is
gone along with the <J> estimate (HeisenbergModel.javg) it read - the model now fits
shell-resolved J_ij over every ordering and igraph carries them per bond in VAMPIRE's
normalized-spin meV convention.
Fixes in the vendored caller:
- The .ucf no longer contains non-magnetic ions, which previously entered the file as
  atoms and de-synchronised the interaction block's node indices.
- Materials are now grouped per (sublattice, spin direction) and each is bound to its own
  unit-cell-category. Without that binding every material kept Vampire's default category
  0, all atoms collapsed into material 1, the magnetic sublattices vanished and the system
  never ordered.
- An explicit alignment check rejects a model whose igraph, magnetic structure and
  sublattice_ids disagree in length, instead of silently writing a broken .ucf.
- A non-zero return code from vampire-serial now raises instead of being ignored.
Tests (tests/vampire/test_vampire_caller.py): four tests over the .mat/.ucf
writers, guarding the HeisenbergModel contract the caller relies on (magnetic-only cell,
in-range interaction indices, .mat/.ucf material agreement, rejection of a misaligned
model). They monkeypatch the vampire-serial subprocess, so no external binary is needed.
pyproject.toml: exclude the vendored vampire_caller.py from ruff so it stays a
faithful copy of the upstream source, and declare the mutually incompatible
strict-forcefields-* extras as [tool.uv] conflicts so uv sync can resolve the
lockfile. The uv change is unrelated to the exchange workflow and can be split out if
preferred.

Additional dependencies introduced (if any)

No new declared dependencies. The vendored vampire_caller.py imports pandas (used
only to parse Vampire's stdout), which already arrives transitively via pymatgen; it is
not added to dependencies here. Say the word if it should be declared explicitly.
External runtime requirement (optional): the Vampire step shells out to a compiled
vampire-serial binary on PATH (https://vampire.york.ac.uk/download/). It is guarded by
monty.dev.requires, and the rest of the flow runs without it via run_vampire=False.

TODO

This is a work-in-progress; the main blocker is upstream.

Requires an unreleased pymatgen. The flow and the vendored caller depend on the
reworked HeisenbergMapper / HeisenbergModel API (magnetic_structures,
per-ordering sublattice_ids, igraph, residual). The pymatgen change has to land and be
released first, and the pymatgen>= pin here bumped accordingly, before this can merge.
Test coverage is partial: only the vendored input-file writers are tested. There are no
tests yet for ExchangeMaker, the two jobs, make_from_ordering_doc, or
ExchangeDocument.from_model.
No documentation page for the workflow yet.
VampireCaller writes its input files into the current working directory - upstream's
ScratchDir block is still commented out, as it was in pymatgen.
make_from_ordering_doc needs a resolved MagneticOrderingsDocument (it inspects the
structures while building the flow), so it cannot yet be chained dynamically onto a running
magnetic-orderings flow via an output reference.

Checklist

Code is in the standard Python style
Doc strings have been added in the Numpy docstring format
for the flow, jobs and schema - two small vendored-adjacent modules are still missing
module-level docstrings.
Type annotations are used throughout the new atomate2 code (the vendored file keeps
upstream's annotations as-is). mypy has not been run yet.
Tests have been added for the vendored input-file writers; the flow, jobs and schema
are not yet covered.
All tests pass (the new tests pass only against the unreleased pymatgen
branch above).

…m atomate1

added a ex_mat field to the ExchangeDocument

The pymatgen fork's HeisenbergModel replaced the ground-state unique_site_ids dict with per-ordering site_labels and dropped _get_j_exc, which crashed run_vampire (TypeError in _create_mat). _create_mat now groups sites into materials by (sublattice, spin sign) straight from site_labels[0], and _create_ucf reads the per-bond J_ij from the igraph edge weights. Also fixes the material-element lookup (it indexed the structure with a sublattice id instead of a site index) and drops the unused HeisenbergMapper construction path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…atgen and update ExchangeDocument to include vampire_settings; add tests for VampireCaller input-file writers.

…ler; update ExchangeDocument schema to include residuals and remove avg option.

JaGeo · 2026-08-18T12:08:32Z

@Luguza thanks! That's great! I am on vacation at the moment and back at the beginning of September. In case I don't react then, could you please ping me again?

esoteric-ephemera · 2026-08-20T09:04:11Z

Thanks @Luguza I'll also try to take a look soon. Is this dependent on the pymatgen PR? I would be curious to know if the maintainers want to add vampire support back

esoteric-ephemera · 2026-08-20T09:05:19Z

+# The strict forcefield groups have mutually incompatible pins (e.g. numpy>=2
+# via mattersim vs numpy==1.26.4). They are meant to be installed one at a time.
+# uv builds a single universal lockfile, so these must be declared as conflicting
+# extras or `uv sync` fails to resolve them together.
+[tool.uv]
+conflicts = [
+    [
+        { extra = "strict-forcefields-generic" },
+        { extra = "strict-forcefields-torch-limited" },
+        { extra = "strict-forcefields-e3nn-limited" },
+        { extra = "strict-forcefields-numpy-limited" },
+    ],
+]
+


I'm not sure this is necessary since these are all optional dependencies, can you remove this?

esoteric-ephemera · 2026-08-20T09:09:56Z

+class VampireOutput(MSONable):
+    """Process results from a Vampire Monte Carlo simulation.


Can you make this a pydantic BaseModel in keeping with our other schema definitions? Also, since this is such a lightweight schema, could this be folded into the exchange schemas?

esoteric-ephemera · 2026-08-20T09:11:22Z

+        for idx, structure in enumerate(structures):
+            if not structure.site_properties.get("magmom"):


Condense:

if any(not structure.site_properties.get("magmom") for structure in structures): ...

esoteric-ephemera · 2026-08-20T09:15:02Z

+@job(name="build exchange doc")
+def build_exchange_doc(
+    heisenberg_model: HeisenbergModel,
+    parent_structure: Structure | None = None,
+    vampire_output: VampireOutput | None = None,
+    vampire_settings: dict | None = None,
+) -> ExchangeDocument:


I understand why a separate job is necessary, but maybe to reduce boilerplate, can you take a look at how the MPMorph workflow has an optional return_as_job kwarg? This could be added to ExchangeDocument.from_model, or you could directly wrap jobflow.Job(ExchangeDocument.from_model(...)) in the workflow (I think)

esoteric-ephemera · 2026-08-20T09:17:34Z

+# vampire_caller.py is vendored verbatim from pymatgen (removed there in 2026.3.23);
+# exclude it from lint/format so it stays a faithful copy of the upstream source.


If the vampire caller remains in atomate2 (depends on pmg maintainer decision), remove these comments since we would have to maintain the interface to vampire moving forward

Luguza · 2026-08-20T09:28:10Z

Thanks @Luguza I'll also try to take a look soon. Is this dependent on the pymatgen PR? I would be curious to know if the maintainers want to add vampire support back

This is dependent on the pymatgen PR since I refactored the underlying HeisenbergMapper. It was silently producing wrong results for mixed supercell systems, which are the default inputs from the magnet orderings workflow. But I have not been implementing a vampire caller into the pymatgen side and instead vendored the vampire caller into atomate2 and then molded it to the new workflow.

esoteric-ephemera · 2026-08-21T07:05:18Z

OK can you ask the PMG devs if they want to restore the vampire caller? The removal was (I think) unintentional

…llow customization via ATOMATE2_VAMPIRE_CMD and improve error messaging.

Luca Frey and others added 10 commits June 1, 2026 17:06

preliminary trial implementation of porting the exchange workflow fro…

8142c33

…m atomate1

refactored vampire specific code to fit into the atomate2 folder scheme

c731bc7

added a ex_mat field to the ExchangeDocument

ammend

df449fe

Wire parent through

ed51af1

Add each materials unit cell category to .mat file

dad3e2c

Update the Exchange Flow and VampireCaller due to the refactor in pym…

0a97928

…atgen and update ExchangeDocument to include vampire_settings; add tests for VampireCaller input-file writers.

Refactor exchange parameters handling in ExchangeMaker and VampireCal…

bffa138

…ler; update ExchangeDocument schema to include residuals and remove avg option.

Update residual meaning

cd9a24a

Apply ruff format and check

8458981

Luguza mentioned this pull request Aug 18, 2026

atomate1 parity: exchange workflow #1404

Open

Merge branch 'main' into exchange-workflow-port-from-atomate1

18e1b66

esoteric-ephemera reviewed Aug 20, 2026

View reviewed changes

Luguza mentioned this pull request Aug 21, 2026

[breaking] Support mixed-supercell orderings in HeisenbergMapper via a shared parent-cell sublattice definition materialsproject/pymatgen#4700

Open

Update VAMPIRE command handling in ExchangeMaker and VampireCaller; a…

4f255d0

…llow customization via ATOMATE2_VAMPIRE_CMD and improve error messaging.

Navigation Menu

Uh oh!

Port the magnetic exchange workflow from atomate1 (Heisenberg fit + Vampire Tc) - #1528

Port the magnetic exchange workflow from atomate1 (Heisenberg fit + Vampire Tc)#1528
Luguza wants to merge 12 commits into
materialsproject:mainfrom
Luguza:exchange-workflow-port-from-atomate1

Luguza commented Aug 18, 2026 •

edited

Loading

Uh oh!

JaGeo commented Aug 18, 2026

Uh oh!

esoteric-ephemera commented Aug 20, 2026

Uh oh!

esoteric-ephemera Aug 20, 2026

Uh oh!

esoteric-ephemera Aug 20, 2026

Uh oh!

esoteric-ephemera Aug 20, 2026

Uh oh!

esoteric-ephemera Aug 20, 2026

Uh oh!

esoteric-ephemera Aug 20, 2026

Uh oh!

Luguza commented Aug 20, 2026

Uh oh!

esoteric-ephemera commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		class VampireOutput(MSONable):
		"""Process results from a Vampire Monte Carlo simulation.

		for idx, structure in enumerate(structures):
		if not structure.site_properties.get("magmom"):

		# vampire_caller.py is vendored verbatim from pymatgen (removed there in 2026.3.23);
		# exclude it from lint/format so it stays a faithful copy of the upstream source.

Uh oh!

Conversation

Luguza commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Introduces

Additional dependencies introduced (if any)

TODO

Checklist

Uh oh!

JaGeo commented Aug 18, 2026

Uh oh!

esoteric-ephemera commented Aug 20, 2026

Uh oh!

esoteric-ephemera Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

esoteric-ephemera Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

esoteric-ephemera Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

esoteric-ephemera Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

esoteric-ephemera Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Luguza commented Aug 20, 2026

Uh oh!

esoteric-ephemera commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Luguza commented Aug 18, 2026 •

edited

Loading