Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
32 changes: 32 additions & 0 deletions .github/workflows/draft-pdf.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Builds the JOSS paper (paper/paper.md) with the Open Journals toolchain, as
# JOSS asks authors to check before submitting. The PDF is a run artifact.
name: Draft PDF

on:
push:
paths:
- paper/**
- .github/workflows/draft-pdf.yml
pull_request:
paths:
- paper/**
- .github/workflows/draft-pdf.yml
workflow_dispatch:

jobs:
paper:
runs-on: ubuntu-latest
name: Paper draft
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build draft PDF
uses: openjournals/openjournals-draft-action@master
with:
journal: joss
paper-path: paper/paper.md
- name: Upload
uses: actions/upload-artifact@v4
with:
name: paper
path: paper/paper.pdf
117 changes: 117 additions & 0 deletions paper/make_figures.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
"""Build the figure of the JOSS paper.

python paper/make_figures.py

Draws order.png: what MaplePy decides before the Ewald sum,
and the order in which Hopper assigns its codes. Every box in a column has
the same width and every label the same offset, so nothing depends on a
layout engine. Needs matplotlib only.
"""
from pathlib import Path

import matplotlib

matplotlib.use('Agg')
import matplotlib.pyplot as plt # noqa: E402
from matplotlib.patches import FancyArrowPatch, FancyBboxPatch # noqa: E402

HERE = Path(__file__).resolve().parent
INK, MUTED = '#17212b', '#4a5866'
STEP = ('#ffffff', '#17212b')
OUT = { # fill, border
'none': ('#eaedf0', '#586776'),
'defect': ('#f9e0de', '#b0271f'),
'additive': ('#dcefe0', '#2c6b3f'),
'caveat': ('#fcebd0', '#9a5800'),
'violation': ('#e3e0f5', '#3b2c8f'),
}

# main column: (title, description lines, outcome key or None, outcome lines)
STEPS = [
('CIF', [], None, None),
('MaplePy', ['Oxidation states: given, then the CIF\'s own, then the',
'bundled tables; if none settles it, stop and name them.',
'Z from the site counts. Mean-field charge on shared sites.',
'Shortest contact measured; nothing edited.'], None, None),
('Ewald sum (pymatgen)', ['MAPLE per site and per formula unit,',
'Madelung factor, d_ref, d_min, flags.'], None, None),
('Hopper: decomposition', ['Binary oxides from the per-site states;',
'oxygen balance; Δ against the table.'],
'none', ['Tier 1: no residual', '1.1 table lacks the binary',
'1.3 no binary oxide exists', '1.4 charge is not a state']),
('Defect?', ['Coordinates no ionic solid could have,',
'whatever the residual.'],
'defect', ['2.7 split site, d_min < 0.5 Å',
'2.5 coordinate error, d_min < 1.6 Å', ' or O-site CV > 0.05']),
('Δ < 1%?', ['Hoppe\'s criterion.'], 'additive', ['Additive']),
('Caveat?', ['Something bears on the residual.'],
'caveat', ['2.1 Δ > 10%, ordered: a state is wrong',
'2.6 anion vacancies', '2.3 cation disorder',
'2.4 oxygen does not balance']),
('Nothing above', [], 'violation', ['3.1 genuine violation']),
]

W_MAIN, X_MAIN = 5.2, 0.4
W_OUT, X_OUT = 3.9, 6.6
LINE_H, PAD, GAP = 0.27, 0.22, 0.32


def box_height(lines, title=True):
return PAD * 2 + LINE_H * (len(lines) + (1 if title else 0))


def draw():
heights = []
for title, desc, key, out in STEPS:
h = box_height(desc)
if out:
h = max(h, box_height(out, title=False))
heights.append(h)
total = sum(heights) + GAP * (len(STEPS) - 1)
fig = plt.figure(figsize=(10.8, total * 0.98 + 0.3))
ax = fig.add_axes([0, 0, 1, 1])
ax.set_xlim(0, 10.8)
ax.set_ylim(-total - 0.15, 0.15)
ax.axis('off')
y = 0
prev_bottom = None
for (title, desc, key, out), h in zip(STEPS, heights):
hm = box_height(desc)
top = y - (h - hm) / 2
ax.add_patch(FancyBboxPatch((X_MAIN, top - hm), W_MAIN, hm,
boxstyle='round,pad=0,rounding_size=0.08',
fc=STEP[0], ec=STEP[1], lw=1.1))
ax.text(X_MAIN + 0.18, top - PAD - LINE_H / 2, title, color=INK,
fontsize=10.5, fontweight='bold', va='center')
for i, line in enumerate(desc):
ax.text(X_MAIN + 0.18, top - PAD - LINE_H * (i + 1.5), line,
color=MUTED, fontsize=9, va='center')
if prev_bottom is not None:
ax.add_patch(FancyArrowPatch((X_MAIN + W_MAIN / 2, prev_bottom),
(X_MAIN + W_MAIN / 2, top),
arrowstyle='-|>', mutation_scale=11,
color=INK, lw=1.0))
prev_bottom = top - hm
if out:
fc, ec = OUT[key]
ho = box_height(out, title=False)
to = y - (h - ho) / 2
ax.add_patch(FancyBboxPatch((X_OUT, to - ho), W_OUT, ho,
boxstyle='round,pad=0,rounding_size=0.08',
fc=fc, ec=ec, lw=1.1))
for i, line in enumerate(out):
ax.text(X_OUT + 0.18, to - PAD - LINE_H * (i + 0.5), line,
color=INK, fontsize=9,
fontweight='bold' if i == 0 and key == 'none' else None,
va='center')
ax.add_patch(FancyArrowPatch((X_MAIN + W_MAIN, top - hm / 2),
(X_OUT, to - ho / 2),
arrowstyle='-|>', mutation_scale=11,
color=ec, lw=1.0))
y -= h + GAP
fig.savefig(HERE / 'order.png', dpi=200)
print('wrote order.png')


if __name__ == '__main__':
draw()
Binary file added paper/order.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
120 changes: 120 additions & 0 deletions paper/paper.bib
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
@article{Hoppe1966,
author = {Hoppe, Rudolf},
title = {Madelung constants},
journal = {Angewandte Chemie International Edition in English},
year = {1966},
volume = {5},
number = {1},
pages = {95--106},
doi = {10.1002/anie.196600951}
}

@article{Hoppe1970,
author = {Hoppe, Rudolf},
title = {The coordination number -- an ``inorganic chameleon''},
journal = {Angewandte Chemie International Edition in English},
year = {1970},
volume = {9},
number = {1},
pages = {25--34},
doi = {10.1002/anie.197000251}
}

% CHECK: title. The manuscript's Zotero record has it as the journal name.
@article{Hoppe1995,
author = {Hoppe, Rudolf},
title = {New pathways to use {IT} as a tool in solid state chemistry, part 1},
journal = {Zeitschrift f{\"u}r Naturforschung A},
year = {1995},
volume = {50},
pages = {555--567}
}

@article{Ewald1921,
author = {Ewald, P. P.},
title = {Die {B}erechnung optischer und elektrostatischer {G}itterpotentiale},
journal = {Annalen der Physik},
year = {1921},
volume = {369},
number = {3},
pages = {253--287},
doi = {10.1002/andp.19213690304}
}

% CHECK: the usual citation of Hoppe's MAPLE program in Giessen papers.
@misc{Hubenthal1993,
author = {H{\"u}benthal, R.},
title = {{MAPLE}: program for the calculation of the {M}adelung part of lattice energy, version 4},
howpublished = {University of Gie{\ss}en, Germany},
year = {1993}
}

@article{Gale1997,
author = {Gale, Julian D.},
title = {{GULP}: a computer program for the symmetry-adapted simulation of solids},
journal = {Journal of the Chemical Society, Faraday Transactions},
year = {1997},
volume = {93},
number = {4},
pages = {629--637},
doi = {10.1039/A606455H}
}

@article{ReevesMcLaren2026Maple,
author = {Reeves-McLaren, Nik and Gross, Peter},
title = {Database-scale validation of {H}oppe's {MAPLE} additivity theorem for perovskite and pyrochlore oxides},
journal = {Journal of Applied Crystallography},
year = {2026},
note = {Under review}
}

@article{ReevesMcLaren2026Dalton,
author = {Reeves-McLaren, Nik},
title = {Automated bond valence sum analysis for crystallographic database quality assessment: a systematic study of rock salt oxides, halides, and chalcogenides},
journal = {Dalton Transactions},
year = {2026},
volume = {55},
pages = {2868--2882},
doi = {10.1039/D5DT03003J}
}

@article{ReevesMcLaren2026Integrity,
author = {Reeves-McLaren, Nik and Moth-Lund Christensen, Sarah},
title = {Data integrity in materials science in the era of {AI}: balancing accelerated discovery with responsible science and innovation},
journal = {Journal of Materials Chemistry A},
year = {2026},
volume = {14},
pages = {276--283},
doi = {10.1039/D5TA05512A}
}

@article{Zagorac2019,
author = {Zagorac, D. and M{\"u}ller, H. and Ruehl, S. and Zagorac, J. and Rehme, S.},
title = {Recent developments in the {Inorganic Crystal Structure Database}: theoretical crystal structure data and related features},
journal = {Journal of Applied Crystallography},
year = {2019},
volume = {52},
number = {5},
pages = {918--925},
doi = {10.1107/S160057671900997X}
}

@article{Brown2009,
author = {Brown, I. David},
title = {Recent developments in the methods and applications of the bond valence model},
journal = {Chemical Reviews},
year = {2009},
volume = {109},
pages = {6858--6919},
doi = {10.1021/cr900053k}
}

@article{Ong2013,
author = {Ong, Shyue Ping and Richards, William Davidson and Jain, Anubhav and Hautier, Geoffroy and Kocher, Michael and Cholia, Shreyas and Gunter, Dan and Chevrier, Vincent L. and Persson, Kristin A. and Ceder, Gerbrand},
title = {Python Materials Genomics ({pymatgen}): a robust, open-source python library for materials analysis},
journal = {Computational Materials Science},
year = {2013},
volume = {68},
pages = {314--319},
doi = {10.1016/j.commatsci.2012.10.028}
}
73 changes: 73 additions & 0 deletions paper/paper.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: 'MaplePy and Hopper: Madelung energies from crystal structures, and Hoppe''s additivity theorem tested at database scale'
tags:
- Python
- crystallography
- Madelung energy
- MAPLE
- crystal structure validation
- ICSD
authors:
- name: Nik Reeves-McLaren
orcid: 0000-0002-1061-1230
corresponding: true
affiliation: 1
# Peter Gross goes here, with his ORCID, if he agrees to be an author;
# his contribution then goes in the AI usage disclosure as well.
affiliations:
- name: School of Chemical, Materials and Biological Engineering, University of Sheffield, United Kingdom
index: 1
ror: 05krs5044
date: (set on submission)
bibliography: paper.bib
---

<!-- Before submission: Peter's answer on authorship (and, if yes, his
ORCID and contribution); the date; the Zenodo DOI of the release in the
Research impact statement; the AI model versions (marked). -->

# Summary

The lattice energy of an ionic crystal is dominated by its electrostatic, or Madelung, part. Hoppe called this the Madelung Part of Lattice Energy (MAPLE), split it into contributions from each crystallographic site, and showed that the MAPLE of a ternary oxide should equal the weighted sum of the MAPLE values of its binary oxides, usually to within 1% [@Hoppe1966; @Hoppe1970; @Hoppe1995]. A residual above 1% says that something about the structure, or its description, departs from the ionic picture.

`MaplePy` computes per-site and total MAPLE from crystallographic information files (CIFs) with the Ewald summation in `pymatgen` [@Ewald1921; @Ong2013]. `Hopper` decomposes each ternary oxide into binary oxides, computes the additivity residual against a 112-entry reference table, and assigns every structure one of twelve codes in three tiers, so that a residual is interpreted rather than merely reported. Both are distributed as the Python package `maplepy`, with two command lines, `maplepy` and `hopper`, and a Python interface; the two notebooks the package is built from also run on their own.

# Statement of need

Crystal structure databases such as the Inorganic Crystal Structure Database (ICSD) [@Zagorac2019] are the starting point for much of materials science, and increasingly the training data for machine learning, which inherits whatever errors they hold [@ReevesMcLaren2026Integrity]. Local checks, such as bond valence sums [@Brown2009], have been automated at database scale [@ReevesMcLaren2026Dalton]. Hoppe's global electrostatic check has remained a manual exercise, applied one structure or one family at a time.

The obstacle is not the arithmetic: an Ewald sum takes a second. It is what must be decided before the sum can be taken. Every ion needs a charge, and CIFs often carry none, or inconsistent ones. Disordered sites need a charge that no single ion has; the number of formula units per cell must be derived, not trusted; and some deposited coordinates cannot carry a Madelung energy at all. A tool that makes these decisions silently reports a plausible number.

`MaplePy` and `Hopper` are for curators and crystallographers checking sets of structures, for those assembling training sets, and for solid-state chemists applying Hoppe's diagnostics to their own refinements.

# State of the field

Hoppe's laboratory computed MAPLE with its own program [@Hubenthal1993]. General Ewald implementations exist, among them `pymatgen`'s `EwaldSummation` [@Ong2013], and lattice-energy codes such as `GULP` [@Gale1997] include the electrostatic term within full force-field models. None that we know of assigns oxidation states with a record of where each came from, derives *Z* from the crystallography, says when a structure cannot carry a Madelung energy, or tests additivity across a database.

We built on `pymatgen` rather than reimplementing the Ewald sum, and added the decision layer and the classification as a separate tool, because the defaults they need are the opposite of a general-purpose library's: `MaplePy` refuses to guess an oxidation state where the chemistry is ambiguous, or to take *Z* from the reduced composition, which gives *Z* = 1 for a non-stoichiometric refinement.

# Software design

`MaplePy` fails loudly. Oxidation states come from a fixed chain (the user's, the CIF's per-site states, the CIF's element-level states, a formula override, a single common state), and where none settles the question the calculation stops and names the elements. The source used is printed for every structure. *Z* is the greatest common divisor of the number of sites holding each element. Shared or partly occupied sites carry an occupancy-weighted mean charge, and the structure is flagged with the kind of disorder and the sublattice it is on.

`MaplePy` reports what it finds and leaves the structure as deposited. It flags two sites closer than 0.5 Å as a split site, and a contact below 1.6 Å as unphysical; the first threshold lies in an empty band of the measured distribution, and the second is a judgement, documented as one. Earlier versions corrected an origin-choice artefact in space group *Pnma* by keeping whichever of two candidate structures had the lower Ewald energy, the quantity under test. It changed 44 of 938 perovskites and turned no failing geometry into a sound one, so version 1.3.6 removed it; the record of that decision stays in the notebook, where the function was.

`Hopper` assigns its codes in a fixed order, built on one rule: a caveat must not mask a defect (\autoref{fig:order}). A structure with impossible coordinates is reported as such even when its residual is small; a disordered structure that agrees with its binaries is additive. Twenty-three reference values are estimates with no source, and the recorded source of one more does not reproduce. They are kept so that published results can be reproduced, and every decomposition that uses one says so.

![What `MaplePy` decides before the Ewald sum, and the order in which `Hopper` assigns its codes; the first code that applies is the one reported.\label{fig:order}](order.png){ width=85% }

The notebooks are the source of the code, because they are where a reader follows how a number was reached. The package is built from their cells, every edit listed; continuous integration fails if the two drift apart, and a script compares their outputs on any folder of CIFs. The tests assert three known answers independently of the notebooks (NaCl's Madelung factor, 1.7476; rutile and anatase against Hoppe's values; BaTiO~3~ additive to within 1%) and test each decision on constructed structures; no ICSD file is distributed or used.

# Research impact statement

`MaplePy` and `Hopper` underpin the first database-scale test of Hoppe's additivity theorem, on 1,410 perovskite and pyrochlore structures from the ICSD, now under review [@ReevesMcLaren2026Maple]. The release described here reproduces that study's classification of every structure from its `MaplePy` results, and is archived on Zenodo. The binary oxide reference table, with entry counts and ranges for every value derived from the ICSD, is released under CC-BY 4.0 for use with other calculators. Because the residual and the Madelung factor need only a structure and its charges, they can also screen structures proposed by calculation or generative models.

# AI usage disclosure

`MaplePy` and `Hopper` were developed with one generative AI tool, Claude (Anthropic), using Claude Opus 4.6 and later Opus models <!-- confirm the model versions -->, from the first version of each notebook (March and April 2026) to the release described here. N.R.-M. framed each problem and made the design decisions described above (failing loudly on oxidation states, deriving *Z* from the site counts, reporting rather than repairing geometry and removing the origin correction, the order of the codes, flagging the estimates, the notebooks as the source); Claude wrote the code, tests and documentation to that specification. Every change was audited, and correctness was checked independently of the code: against Hoppe's published values, by manual review of the structures flagged in the study, and by comparing each version's results with the last. This paper was drafted with Claude Opus 5.5 and revised by the author. The author has reviewed, modified and validated all AI-generated content.

# Acknowledgements

This work received no specific funding.

# References
Loading