diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/structure.md b/.github/ISSUE_TEMPLATE/structure.md new file mode 100644 index 0000000..1fe4382 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/structure.md @@ -0,0 +1,14 @@ +--- +name: A structure MaplePy or Hopper gets wrong +about: A MAPLE value, flag, code or error that looks wrong for a particular structure +--- + +**Versions.** `maplepy --version` (package, MaplePy and Hopper), or `MAPLEPY_VERSION` and `HOPPER_VERSION` from the notebooks; package or notebook? + +**Python and pandas.** `python -c "import sys, pandas; print(sys.version, pandas.__version__)"` + +**Structure.** For an ICSD entry, the collection code only (please don't attach ICSD CIFs: they are licensed). For your own refinement, the CIF if you can share it, and the oxidation states you gave (`--ox`). + +**What MaplePy or Hopper reported.** The MAPLE, Madelung factor, flags or classification code, or the error message. + +**What you expected, and why.** diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..cc30374 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,61 @@ +name: tests + +on: + push: + pull_request: + workflow_dispatch: + +env: + MPLBACKEND: Agg + +jobs: + engine: + name: package cells match the notebooks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.13" + - run: python tools/build_engine.py --check + + test: + name: py${{ matrix.python }} / pandas ${{ matrix.pandas }} / ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest] + python: ["3.11", "3.12", "3.13"] + pandas: ["2", "3"] + include: + - os: windows-latest + python: "3.13" + pandas: "3" + - os: macos-latest + python: "3.13" + pandas: "3" + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Install the package as a user would, with the pandas under test + shell: bash + run: | + python -m pip install --upgrade pip + if [ "${{ matrix.pandas }}" = "2" ]; then PANDAS="pandas>=2.0,<3"; else PANDAS="pandas>=3"; fi + python -m pip install "$PANDAS" ".[test]" + python -c "import pandas, maplepy; print('pandas', pandas.__version__, '| maplepy', maplepy.__version__, '| MaplePy', maplepy.MAPLEPY_VERSION, '| Hopper', maplepy.HOPPER_VERSION)" + - name: Known answers + run: maplepy --validate + - name: Test suite + run: python -m pytest -q + - name: Command lines, end to end + shell: bash + run: | + mkdir run && cp examples/*.cif run/ + maplepy run --workers 1 --plots + hopper run --figures + test -s run/outputs_*/additivity_classified.csv + maplepy examples/SrFeO3_no_states.cif --ox Sr=2,Fe=4,O=-2 diff --git a/.gitignore b/.gitignore index 83972fa..ef96ccd 100644 --- a/.gitignore +++ b/.gitignore @@ -216,3 +216,9 @@ __marimo__/ # Streamlit .streamlit/secrets.toml + +# MaplePy and Hopper runs, wherever they are made +outputs_*/ +# Never commit licensed structures or results made from them +*.cif +!examples/*.cif diff --git a/.zenodo.json b/.zenodo.json new file mode 100644 index 0000000..a9de5a2 --- /dev/null +++ b/.zenodo.json @@ -0,0 +1,26 @@ +{ + "title": "MaplePy: MAPLE from crystallographic information files, and Hoppe's additivity theorem tested at database scale", + "version": "1.4.0", + "upload_type": "software", + "description": "
MaplePy reads CIF files and computes the Madelung part of the lattice energy (MAPLE) of each structure, per site and in total, with the Ewald summation in pymatgen. It records where each oxidation state came from, derives Z from the site multiplicities, treats disorder by mean-field charges, and flags geometry that cannot carry a Madelung energy. Hopper decomposes each ternary oxide into its binary oxides, computes the residual of Hoppe's additivity theorem against a 112-entry reference table, and classifies each structure into one of twelve codes in three tiers, so that a residual is interpreted rather than merely reported. Both run as Jupyter notebooks or as the Python package maplepy, with the command lines maplepy and hopper.
This release is maplepy 1.4.0, running MaplePy 1.3.6 and Hopper 1.2.9. CHANGELOG.md describes every version. The code is released under the MIT licence and the data tables in data/ under CC-BY 4.0.
", + "creators": [ + { + "name": "Reeves-McLaren, Nik", + "affiliation": "University of Sheffield", + "orcid": "0000-0002-1061-1230" + } + ], + "license": "mit", + "access_right": "open", + "language": "eng", + "keywords": [ + "crystallography", + "MAPLE", + "Madelung energy", + "lattice energy", + "additivity theorem", + "crystal structure validation", + "ICSD", + "CIF" + ] +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..27d79cb --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,134 @@ +# Changelog + +maplepy is the package; MaplePy and Hopper are its two engines, each a notebook with a version of its own (`MAPLEPY_VERSION`, `HOPPER_VERSION`). A release names all three. Each engine version below records what was wrong, what changed and what it does to results; the per-version notes and the version records in the code (`# v1.3.2: ...`) give the measurements behind each. + +## maplepy + +### maplepy 1.4.0 – unreleased + +The first packaged release, running MaplePy 1.3.6 and Hopper 1.2.9. + +- `maplepy FOLDER` runs `batch_maple()` on a folder of CIFs; `maplepy FILE.cif` prints one structure; `maplepy --validate` runs the notebook's three known answers. `hopper RESULTS` runs Hopper on a MaplePy run. +- A Python interface: `maplepy.compute()`, `run_folder()`, `additivity()` and `validate()`, and the two engines' own functions through `maplepy.engine()` and `maplepy.hopper_engine()`. +- The engines are the notebooks' cells, copied by `tools/build_engine.py`; CI fails if they drift. `tools/equivalence.py` compares the notebooks' output with the package's on a folder of CIFs. +- Tests: the three sourced targets asserted independently, each of MaplePy's decisions on constructed structures, Hopper's classification of the examples, the command lines, and the release metadata; CI on Linux with Python 3.11 to 3.13 under pandas 2 and 3, and on Windows and macOS with Python 3.13. +- Constructed example CIFs, none from the ICSD. +- The notebooks' prose corrected where it still described earlier versions: in MaplePy, the validation tolerance, brookite (given for reference, not computed), the batch cell's picker and output folder, the definition of `disordered`, and the docstring of `batch_maple()`; in Hopper, see 1.2.9. No MaplePy code changed, so it keeps 1.3.6. +- The reference data in `data/`: the binary oxide table (1.1.1), `maple_library.json` (1.0.1) and `common_oxidation_states.json`. The May 2026 repository had only the binary table, so its oxidation-state chain lost two levels. + +Checked against the study: Hopper 1.2.9, run on the MaplePy 1.3.6 results for the 938 perovskites and 472 pyrochlores of the *J. Appl. Cryst.* manuscript, gives every structure the classification Hopper 1.2.8 gave it, with identical residuals. + +## Hopper + +### 1.2.9 – unreleased + +- Every decomposition that uses an estimated or unsourced reference value names it, in a new column, `estimated_binaries`, and the batch summary counts them. 23 of the 112 values are estimates with no source, and the source recorded for a 24th, Cu2O, does not reproduce (table 1.1.1). In the study, no structure uses Cu2O, and 82 of the 1,380 decomposed structures rest on one: 52 perovskites (43 of them on Ni2O3) and 30 pyrochlores. Nothing is reclassified. +- The inline fallback labels "Estimated, to be updated" read "Estimated, unsourced". +- Prose that still described the first version corrected: the table of codes and their order in section 4 and the header of the classification cell (seven codes, ascending order), a usage example naming a function that does not exist, and two notes in section 9 (that the reference values "must be replaced", and that a *Z* fix was "in progress"; MaplePy has had it since 1.1). No result changes. +- A local path in a comment generalised. + +### 1.2.8 – 25th August 2026 + +- The classification waterfall (Figure 7) places each label at the highest row where it clears its neighbour, measured from its own width, rather than alternating rows; narrow slices no longer overprint. No result changes. + +### 1.2.7 – 25th August 2026 + +- The figures read the classification registry instead of hand-written maps of seven codes, which dropped codes 1.3, 1.4, 2.6 and 2.7 from every scatter and raised `KeyError` on the first structure carrying one of the other five. Figure 2's panel (b), which zoomed on a *Z* = 1 cluster that no longer exists, is drawn only when there is a cluster. + +### 1.2.6 – 25th August 2026 + +- Codes 1.2 (upstream failure) and 2.2 (*Z* = 1 artefact) are defined and reported as zero, rather than reserved and absent; the order of the codes is derived from the registry. +- `OXI_ROUNDING_TOL` re-measured over all 29,226 sites rather than the 30 with a missing binary: there is no empty band, so the tolerance is documented as a judgement. + +### 1.2.5 – 25th August 2026 + +- The rounding of a non-integer mean charge is carried in the `missing_binaries` string, which reaches the classifier and the CSV; the parallel list it used to live in never did. This found a third route to code 1.4: means over a non-stoichiometric refinement (Nd4Cu4O11.724, Nd4Ru3.544O12). +- The folder dialog no longer hides behind the browser when the notebook is run twice in one kernel; `MAPLE_DIR_OVERRIDE` skips it. + +### 1.2.4 – 25th August 2026 + +- Lookups by structure use an index built once instead of a scan of the whole frame per structure; on the perovskite run the three loops concerned had taken about 12 s between them. No result changes. + +### 1.2.3 – 25th August 2026 + +- Code 1.1 meant four different things. It now means only that the table lacks a binary that exists; 1.3 (no binary end-member exists) and 1.4 (the charge is not an oxidation state) take the rest, from a registry of every missing binary with the reason. +- The decomposition records where it had to round a mean charge to choose a binary (Y3NbO7: Y asked for at +3.5). + +### 1.2.2 – 24th August 2026 + +- Code 2.5 has a second detector, the shortest contact below MaplePy's `SHORT_CONTACT_ANG`, beside the oxygen-site CV test, which only a 20-site *Pnma* cell can take. Each catches structures the other cannot. +- Code 2.6 (anion vacancy disorder) is assigned, from the sublattice MaplePy 1.3.3 reports; it is tested before 2.3. +- Code 2.7 (split-site disorder model) is read from MaplePy's `geometry_flag`. + +### 1.2.1 – 24th August 2026 + +- A decomposition missing a binary no longer writes a residual: 30 structures had sums missing a whole component, with residuals up to 93%, and sat in Figure 1's tail as if measured. +- Hoppe's 1% criterion is one constant, `ADDITIVE_THRESHOLD_PCT`, rather than four literals; Figure 1 and the classifier now count the same population (they disagreed by one, 662 against 661). +- `hopper_version` is written into the classified export. + +### 1.2 – 24th August 2026 + +- The released JSON table is read first, and a guard stops the run if any value differs from the inline table; the inline table had 104 of the JSON's 112 entries. + +### 1.1 – 24th August 2026 + +- A residual of exactly zero, the result the theorem predicts, was written out as missing (`if delta_abs` is false for 0.0). +- Counts removed from code descriptions, which had drifted from the data (32, 19 and 31 for one population); the notebook prints the populations it finds. +- The oxygen-balance tolerance measured over 101 decompositions and left alone: nothing lies inside its gap. + +### Hopper.ipynb – 21st May 2026 + +The version uploaded to this repository: six codes in use beside Additive, in three tiers, and three more reserved (1.2, 2.5, 2.6). + +## MaplePy + +### 1.3.6 – 25th August 2026 + +- The space group 62 origin correction is removed. It chose between the deposited structure and one with the O2 sublattice shifted by (½, ½, 0) by their Ewald energy, the quantity under test; it changed 44 of 938 perovskites, by up to 8.1%, made one shortest contact worse, and in none of the 44 turned a failing geometry into a sound one. MAPLE is now computed on the structure as deposited, and the geometry flags do the work. The reasons are kept in the notebook where the function was. + +The release copy of 1.3.6 differs from the working copy only in prose: its notes cell, which said that mixed-occupancy sites were not handled (they have been since 1.1) and cited the WAGII paper and Eir out of date; four markdown cells and a docstring that described earlier versions; and a local path in a comment. No code differs. + +### 1.3.5 – 25th August 2026 + +- The GUI is a folder picker in front of `batch_maple()`, rather than a file picker with its own copy of the batch. + +### 1.3.4 – 25th August 2026 + +- One function, `process_one_cif()`, processes a CIF, serially or on a pool of workers (`MAPLE_WORKERS`); every value is identical either way. Its printed output, which is the only record of where the oxidation states came from, is captured and printed by the caller, so a parallel run reports it too. + +### 1.3.3 – 24th August 2026 + +- A second geometry threshold, `SHORT_CONTACT_ANG` (1.6 Å), for coordinate errors: 26 perovskites have a shortest contact between 1.0 and 1.6 Å. Unlike the split-site threshold it lies in a continuum, and is documented as a judgement. +- The split-site threshold confirmed on the whole dataset: the band from 0.5 to 1.0 Å is empty. +- The disorder flag says which sublattice carries the fractional occupancy. + +### 1.3.2 – 24th August 2026 + +- A geometry test: `d_min_ang` for every structure, and two sites closer than 0.5 Å flagged as a split site. Four structures in the 1,410 had Ewald sums up to ten times the family median and were reported as ordinary results. +- Partly occupied single-species sites count as disordered: 12 of 97 probed structures had been labelled ordered. + +### 1.3.1 – 24th August 2026 + +- `batch_maple()` writes `maple_summary.csv`, which Hopper reads; only the GUI used to. +- The data directory is resolved once; the batch and the GUI had each overridden it, silently dropping two levels of the oxidation-state chain. +- The plotting cell's path to another machine's Downloads folder replaced by the run just made. +- `maplepy_version` is written into the results and summary CSVs. + +### 1.3 – 24th August 2026 + +- The cell is pinned to the primitive cell explicitly; a deprecated default had been doing it. MAPLE per formula unit, *d*ref and the Madelung factor are the same in either cell. + +### 1.2 – 24th August 2026 + +- The data directory defaults to `data/`, where the data are, rather than the working directory. + +### 1.1 – 24th August 2026 + +- *Z* from the site counts, not the reduced composition. Composition reduction had returned *Z* = 1 for 172 of the 1,410 structures, 165 of them with a fractional subscript, and inflated their MAPLE per formula unit by the true *Z*. +- *d*ref is the shortest cation–anion distance; when a structure has no cation or no anion MaplePy says so, instead of returning the distance from site 0 to anything. +- Each tolerance named once (two had been written twice, with different values); a missing data file and an unreadable one are different errors. +- The site-mean convention of the Madelung factor written down. + +### MaplePy.ipynb – 21st May 2026 + +The version uploaded to this repository. diff --git a/CITATION.cff b/CITATION.cff index 3c45a26..3c8513d 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,19 +1,23 @@ cff-version: 1.2.0 -message: "If you use MaplePy or Hopper, please cite the paper below. A versioned release with its own DOI will follow." -title: "MaplePy: MAPLE from crystallographic information files, with a test of Hoppe's additivity theorem" +message: "If you use MaplePy or Hopper, please cite the paper below and name the release you used." +title: "MaplePy: MAPLE from crystallographic information files, and Hoppe's additivity theorem tested at database scale" type: software authors: - family-names: Reeves-McLaren given-names: Nik affiliation: University of Sheffield orcid: "https://orcid.org/0000-0002-1061-1230" +version: 1.4.0 abstract: >- MaplePy computes per-site and total MAPLE (Madelung Part of Lattice - Energy) values from CIF files with the Ewald summation in pymatgen. - Hopper decomposes ternary oxides into their binary oxides, computes the - residual of Hoppe's additivity theorem against a 112-entry binary oxide - reference table, and classifies each structure. This repository holds - the unversioned notebooks uploaded on 21st May 2026. + Energy) values from CIF files with the Ewald summation in pymatgen, + recording where each oxidation state came from, deriving Z from the site + multiplicities, treating disorder by mean-field charges, and flagging + geometry that cannot carry a Madelung energy. Hopper decomposes ternary + oxides into their binary oxides, computes the residual of Hoppe's + additivity theorem against a 112-entry reference table, and classifies + each structure into one of twelve codes in three tiers. This release is + maplepy 1.4.0, running MaplePy 1.3.6 and Hopper 1.2.9. license: MIT repository-code: "https://github.com/SuperBladesman/MaplePy" keywords: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1f16cf5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Contributing to MaplePy + +MaplePy and Hopper are maintained by Nik Reeves-McLaren at the University of Sheffield, alongside his research and teaching. Issues and pull requests are read and answered as time allows; there is no guaranteed response time. + +## Reporting a structure MaplePy or Hopper gets wrong + +A structure that comes out wrong is the most useful report there is; most of the changelog began as one. Please open an issue with: + +- the versions: `maplepy --version` names the package and both engines; from the notebooks, `MAPLEPY_VERSION` and `HOPPER_VERSION`; +- your Python and pandas versions (`python -c "import sys, pandas; print(sys.version, pandas.__version__)"`); +- the structure. For an ICSD entry, give its collection code rather than attaching the CIF: ICSD files are licensed by FIZ Karlsruhe and should not be posted publicly. For your own refinement, attach the CIF if you are free to share it, with the oxidation states you used (`--ox`); +- what MaplePy or Hopper reported (the MAPLE, the flags, the code, or the error) and what you expected, and why. + +Questions about what a code means are welcome as issues too; the README's table of codes answers most of them. + +## Changing the code + +`MaplePy.ipynb` and `Hopper.ipynb` are the source of the code. The package's cells in `src/maplepy/_cells/` are copied from them by `tools/build_engine.py`, and CI fails if the two differ, so edit the notebooks, never the copied cells. [docs/PACKAGE.md](docs/PACKAGE.md) explains how they relate. + +1. Edit the notebook and raise its version (`MAPLEPY_VERSION` or `HOPPER_VERSION`). Record the change where it is made, as the code already does (`# v1.3.7: ...`): what was wrong, what you measured, what changed. Add a test in `tests/` that fails before your change and passes after it. +2. For MaplePy, run Section 2 in the notebook: all three validations must pass. +3. Copy the cells into the package: `python tools/build_engine.py`. +4. Install and test under pandas 2 and pandas 3: `pip install -e ".[test]"`, then `maplepy --validate` and `python -m pytest`. +5. Show that the notebooks and the package still agree on a folder of CIFs you know: `pip install nbclient ipykernel`, then `python tools/equivalence.py FOLDER`. +6. Describe the change in `CHANGELOG.md`, under the new version: what was wrong, what changed, and what it does to results. + +A change to a reference value needs a source, named in [data/README.md](data/README.md), and the tests check that Hopper's inline table and the JSON still agree. + +Never commit files that cannot be redistributed: ICSD CIFs, or results tables made from them. `.gitignore` refuses CIFs outside `examples/`, and the tests use constructed structures for this reason. + +## Releases + +Each release is tagged (`v1.4.0`) and published as a GitHub release, which Zenodo archives with its own DOI. Before tagging, date the changelog entries, update `version` and `date-released` in `CITATION.cff` and `version` in `.zenodo.json`; after Zenodo has archived the release, add its DOI to `CITATION.cff` and the README. `tests/test_release.py` checks that they agree. + +## Licence + +By contributing you agree that your contribution is released under the [MIT licence](LICENSE), or for the data tables in `data/`, under CC-BY 4.0. diff --git a/Hopper.ipynb b/Hopper.ipynb index beb66d7..190b40d 100644 --- a/Hopper.ipynb +++ b/Hopper.ipynb @@ -27,11 +27,7 @@ "cell_type": "code", "execution_count": null, "id": "555ce047-7861-4cb1-ae39-19ceddefbf56", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# !pip install adjustText" @@ -49,11 +45,7 @@ "cell_type": "code", "execution_count": null, "id": "7f6c406c", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", @@ -81,6 +73,81 @@ " 'powder_blue' : '#9ADBE8',\n", "}\n", "\n", + "# ── The version, named once ────────────────────────────────────────────────\n", + "# v1.2.1: written into the classified export as a column, so a CSV on disk\n", + "# says which notebook classified it. MaplePy does the same.\n", + "# v1.2.9: the decomposition records which binaries are estimates; see\n", + "# ESTIMATED_BINARIES in Section 1.\n", + "HOPPER_VERSION = '1.2.9'\n", + "\n", + "# ── Hoppe's criterion, named once ──────────────────────────────────────────\n", + "#\n", + "# v1.2.1: 1.0 was the default argument of classify_additivity, the axvline in\n", + "# Figure 1, the \"< 1%\" in the figure's annotation and the \"GOOD (<1%)\" in the\n", + "# decomposition print. Four literals for one criterion, and the figure and the\n", + "# classifier were counting different populations against it: 662 against 661\n", + "# on the perovskite run, both in the paper.\n", + "ADDITIVE_THRESHOLD_PCT = 1.0 # Hoppe's additivity criterion, per cent\n", + "\n", + "# ── When a mean oxidation state is not a state ─────────────────────────────\n", + "#\n", + "# v1.2.3: _binary_formula_for rounds abs(oxi_state) to pick a binary, and said\n", + "# nothing about having done it. On a site shared by two cations the\n", + "# occupancy-weighted mean is not an oxidation state at all: Y3NbO7 has Y and\n", + "# Nb on one site at a mean of 3.5, rounded up to 4, and the decomposition then\n", + "# asked for YO2. Yttrium has no tetravalent oxide because yttrium has no\n", + "# tetravalent state.\n", + "#\n", + "# v1.2.6: the measurement that used to be here was taken over the 30\n", + "# structures with a missing binary and claimed an empty band between 0.05 and\n", + "# 0.45 of an integer. Re-measured over ALL 29,226 sites in the two families\n", + "# there is no empty band anywhere:\n", + "#\n", + "# exactly integral 28,218 0.15 to 0.25 136\n", + "# 0.002 to 0.05 408 0.25 to 0.35 64\n", + "# 0.05 to 0.15 344 0.35 to 0.45 32\n", + "# 0.45 to 0.50 24\n", + "#\n", + "# So this is a JUDGEMENT, not a measured gap, and moving it moves the 1.4\n", + "# population: 408 sites lie inside it and 600 outside. It is small enough\n", + "# that a genuine half-integer mean is never taken for a rounding error,\n", + "# which is the whole of what it is for.\n", + "OXI_ROUNDING_TOL = 0.05 # e; a mean this far from an integer was not a\n", + " # state before it was rounded\n", + "\n", + "# ── Looking a structure up ─────────────────────────────────────────────────\n", + "#\n", + "# v1.2.4: every lookup in this notebook was `df[df['source_cif'] == cif]`,\n", + "# which scans the whole frame. Measured on the perovskite run, 938 structures\n", + "# and 18,644 per-site rows:\n", + "#\n", + "# one scan of the results frame 2.4 ms\n", + "# one groupby of the same frame 0.11 s, once\n", + "# one dict lookup afterwards 0.0000013 ms\n", + "#\n", + "# About three scans per structure, and the classifier and the\n", + "# coordinate-screen count each did their own set, so batch_additivity took\n", + "# 5.10 s, classify_additivity 3.67 s and the counting loop 3.50 s.\n", + "#\n", + "# Group once, pass the index down. Every function that takes one takes it\n", + "# optionally and falls back to the scan, so it still works called on its own.\n", + "def index_by_cif(df, column='source_cif'):\n", + " \"\"\"Every row of df, grouped by structure, once.\"\"\"\n", + " return {k: v for k, v in df.groupby(column, sort=False)}\n", + "\n", + "\n", + "def rows_for(cif, df, index=None, column='source_cif'):\n", + " \"\"\"The rows for one structure, from the index if there is one.\n", + "\n", + " Returns an empty frame where the structure is absent, which is what the\n", + " scan returned, so callers do not change.\n", + " \"\"\"\n", + " if index is not None:\n", + " got = index.get(cif)\n", + " return got if got is not None else df.iloc[0:0]\n", + " return df[df[column] == cif]\n", + "\n", + "\n", "plt.rcParams.update({\n", " 'font.family' : 'sans-serif',\n", " 'font.size' : 11,\n", @@ -103,11 +170,7 @@ "cell_type": "code", "execution_count": null, "id": "925cff09", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Uses a tkinter directory picker to select the folder containing\n", @@ -116,15 +179,43 @@ "import tkinter as tk\n", "from tkinter import filedialog\n", "\n", - "root = tk.Tk()\n", - "root.withdraw()\n", - "root.attributes('-topmost', True)\n", + "# ── Where the MaplePy output is ───────────────────────────────────────────\n", + "#\n", + "# v1.2.5: running this notebook twice in one kernel could sit on this cell\n", + "# for minutes with nothing on screen. It is not the figures and it is not the\n", + "# CSVs: it is THIS DIALOG. A second Tk root in one process opens a dialog\n", + "# that, on Windows, frequently lands BEHIND the browser, and the cell then\n", + "# waits for a click on a window nobody can see. Restarting the kernel cures\n", + "# it, which is exactly what a hidden modal looks like.\n", + "#\n", + "# MaplePy's own picker passes parent=root and this one did not. It does now,\n", + "# with an update() either side so Tk actually maps the window, and the notice\n", + "# below is printed BEFORE the dialog blocks so a hang is diagnosable.\n", + "#\n", + "# Better still: set MAPLE_DIR_OVERRIDE and no dialog opens at all.\n", + "MAPLE_DIR_OVERRIDE = None # e.g. r\"path/to/outputs_YYYYMMDD_HHMMSS\"\n", "\n", - "MAPLE_DIR = filedialog.askdirectory(\n", - " title=\"Select folder containing MaplePy output CSVs \"\n", - " \"(maple_summary.csv and maple_results.csv)\"\n", - ")\n", - "root.destroy()\n", + "if MAPLE_DIR_OVERRIDE:\n", + " MAPLE_DIR = str(MAPLE_DIR_OVERRIDE)\n", + " print(f\"Using MAPLE_DIR_OVERRIDE, no dialog: {MAPLE_DIR}\")\n", + "else:\n", + " print(\"Opening a folder picker. If nothing appears, look BEHIND this \"\n", + " \"window - a second Tk dialog in one kernel often opens there. \"\n", + " \"Set MAPLE_DIR_OVERRIDE above to skip the dialog entirely.\")\n", + " root = tk.Tk()\n", + " root.withdraw()\n", + " root.update()\n", + " root.attributes('-topmost', True)\n", + " root.lift()\n", + " root.focus_force()\n", + "\n", + " MAPLE_DIR = filedialog.askdirectory(\n", + " title=\"Select folder containing MaplePy output CSVs \"\n", + " \"(maple_summary.csv and maple_results.csv)\",\n", + " parent=root\n", + " )\n", + " root.update()\n", + " root.destroy()\n", "\n", "if not MAPLE_DIR:\n", " raise FileNotFoundError(\n", @@ -184,11 +275,7 @@ "cell_type": "code", "execution_count": null, "id": "8f09813b", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# ─────────────────────────────────────────────────────────────────────────────\n", @@ -218,7 +305,7 @@ " # Estimated rock salts\n", " \"EuO\":(902.9, \"Rock salt Fm-3m\", \"Median of 9 ambient ICSD Fm-3m entries, range 901-904; 3 zeros excluded\"),\n", " \"CuO\":(1093.6, \"Rock salt Fm-3m\", \"1 ambient ICSD Fm-3m entry; HP polymorph, not tenorite\"),\n", - " \"PbO\":(810.0, \"Litharge\", \"Estimated, to be updated\"),\n", + " \"PbO\":(810.0, \"Litharge\", \"Estimated, unsourced\"),\n", "\n", " # ── Antifluorite M2O (Fm-3m) ──────────────────────────────────────\n", " # ICSD median values\n", @@ -227,10 +314,10 @@ " \"K2O\":(599.8, \"Antifluorite Fm-3m\", \"Median of 2 ambient ICSD Fm-3m entries, range 599-600\"),\n", " \"Rb2O\":(572.6, \"Antifluorite Fm-3m\", \"Median of 2 ambient ICSD Fm-3m entries, range 572-573\"),\n", " # Estimated\n", - " \"Cs2O\":(450.0, \"Antifluorite Fm-3m\", \"Estimated, to be updated\"),\n", - " \"Ag2O\":(700.0, \"Cuprite Pn-3m\", \"Estimated, to be updated\"),\n", + " \"Cs2O\":(450.0, \"Antifluorite Fm-3m\", \"Estimated, unsourced\"),\n", + " \"Ag2O\":(700.0, \"Cuprite Pn-3m\", \"Estimated, unsourced\"),\n", " \"Cu2O\":(730.0, \"Cuprite Pn-3m\", \"MaplePy v4, a=4.270\"),\n", - " \"Tl2O\":(650.0, \"Various\", \"Estimated, to be updated\"),\n", + " \"Tl2O\":(650.0, \"Various\", \"Estimated, unsourced\"),\n", " \"Pd2O\":(700.0, \"Various\", \"Estimated, Pd1+ binary\"),\n", "\n", " # ── Rutile MO2 (P4_2/mnm) ─────────────────────────────────────────\n", @@ -256,7 +343,7 @@ " \"SiO2\":(3593.7, \"Stishovite P4_2/mnm\", \"Median of 42 ambient ICSD P4_2/mnm entries, range 3575-3664\"),\n", " # Estimated rutiles\n", " \"TcO2\":(3250.0, \"Rutile P4_2/mnm\", \"Estimated from Ru/Rh/Os trend\"),\n", - " \"SbO2\":(3100.0, \"Rutile P4_2/mnm\", \"Estimated, to be updated\"),\n", + " \"SbO2\":(3100.0, \"Rutile P4_2/mnm\", \"Estimated, unsourced\"),\n", "\n", " # ── Fluorite MO2 (Fm-3m) ──────────────────────────────────────────\n", " # ICSD median values\n", @@ -316,23 +403,23 @@ "\n", " # ── Other binaries ────────────────────────────────────────────────\n", " \"Bi2O3\":(2580.0, \"Monoclinic P2_1/c\", \"MaplePy v4, alpha-Bi2O3 — to be updated\"),\n", - " \"HgO\":(850.0, \"Various\", \"Estimated, to be updated\"),\n", + " \"HgO\":(850.0, \"Various\", \"Estimated, unsourced\"),\n", "\n", " # ── Higher-valent oxides ──────────────────────────────────────────\n", " \"V2O5\":(9454.0, \"Pmmn\", \"Median of 17 ambient ICSD Pmmn entries, range 9393-9638\"),\n", " \"Nb2O5\":(8988.2, \"C2/c\", \"Median of 2 ambient ICSD C2/c entries, range 8984-8992\"),\n", " \"Ta2O5\":(9127.2, \"C2/c\", \"1 ambient ICSD C2/c entry\"),\n", " \"Sb2O5\":(8955.4, \"C2/c\", \"Median of 2 ambient ICSD C2/c entries, range 8955-8956\"),\n", - " \"Bi2O5\":(4300.0, \"Various\", \"Estimated, to be updated\"),\n", - " \"WO3\":(4600.0, \"ReO3-type\", \"Estimated, to be updated\"),\n", - " \"MoO3\":(4500.0, \"Various\", \"Estimated, to be updated\"),\n", - " \"CrO3\":(4400.0, \"Various\", \"Estimated, to be updated\"),\n", - " \"OsO3\":(4500.0, \"Various\", \"Estimated, to be updated\"),\n", + " \"Bi2O5\":(4300.0, \"Various\", \"Estimated, unsourced\"),\n", + " \"WO3\":(4600.0, \"ReO3-type\", \"Estimated, unsourced\"),\n", + " \"MoO3\":(4500.0, \"Various\", \"Estimated, unsourced\"),\n", + " \"CrO3\":(4400.0, \"Various\", \"Estimated, unsourced\"),\n", + " \"OsO3\":(4500.0, \"Various\", \"Estimated, unsourced\"),\n", " \"RuO3\":(4500.0, \"Various\", \"Estimated, Ru6+ binary\"),\n", " \"ReO3\":(4600.0, \"ReO3-type\", \"Estimated, Re6+ binary\"),\n", " \"Re2O5\":(4400.0, \"Various\", \"Estimated, Re5+ binary\"),\n", - " \"Re2O7\":(5000.0, \"Various\", \"Estimated, to be updated\"),\n", - " \"Tc2O7\":(5000.0, \"Various\", \"Estimated, to be updated\"),\n", + " \"Re2O7\":(5000.0, \"Various\", \"Estimated, unsourced\"),\n", + " \"Tc2O7\":(5000.0, \"Various\", \"Estimated, unsourced\"),\n", " \"Ru2O5\":(4250.0, \"Various\", \"Estimated, Ru5+ binary\"),\n", " \"W2O5\":(4300.0, \"Various\", \"Estimated, W5+ binary\"),\n", " \"Mo2O3\":(3300.0, \"Various\", \"Estimated, Mo3+ binary\"),\n", @@ -387,11 +474,110 @@ " return lookup, df_out\n", "\n", "\n", - "# ── Load the table ──────────────────────────────────────────────────────────\n", - "# To use your own ICSD batch results, set BINARY_CSV below.\n", + "# ── The released reference table is the source ──────────────────────────────\n", + "#\n", + "# v1.2: BINARY_MAPLE_FALLBACK above is a 104-entry dict written inline. The\n", + "# released JSON has 112 - the extra eight are the oxyanion formers added for\n", + "# the borosulfate work, which the notebook never received. Measured formula by\n", + "# formula, no VALUE disagrees between the two, but the membership already\n", + "# does, and the copy the community downloads was not the copy the analysis\n", + "# used.\n", + "#\n", + "# The JSON is now read first. The inline dict remains for when the file is\n", + "# absent, and the guard below compares the two wherever they overlap: a value\n", + "# that has drifted stops the run and names the formula, rather than one copy\n", + "# quietly winning.\n", + "\n", + "def load_binary_reference(path=None):\n", + " \"\"\"\n", + " The binary oxide reference table, from the released JSON.\n", + "\n", + " Returns (lookup, source_string). Falls back to the inline dict only when\n", + " no JSON can be found, and says so.\n", + " \"\"\"\n", + " import json as _json\n", + " from pathlib import Path as _Path\n", + "\n", + " _names = ('binary_oxide_maple_reference_v1_1.json',\n", + " 'binary_oxide_maple_reference.json')\n", + " _dirs = ('data', '.', '..')\n", + " _cands = ([_Path(path)] if path else\n", + " [_Path(d) / n for d in _dirs for n in _names])\n", + "\n", + " for _p in _cands:\n", + " if not _p.is_file():\n", + " continue\n", + " with open(_p, 'r', encoding='utf-8') as _f:\n", + " _d = _json.load(_f)\n", + " _lookup = {e['formula']: float(e['maple_kcal_mol'])\n", + " for e in _d['entries']}\n", + " return _lookup, str(_p.resolve())\n", + "\n", + " if path:\n", + " raise FileNotFoundError(f'binary reference table not found: {path}')\n", + " return ({f: v[0] for f, v in BINARY_MAPLE_FALLBACK.items()},\n", + " 'INLINE FALLBACK - the released JSON was not found')\n", + "\n", + "\n", + "BINARY_REFERENCE_PATH = None # set to override the search\n", + "\n", + "_json_lookup, _binary_source = load_binary_reference(BINARY_REFERENCE_PATH)\n", + "\n", + "# THE GUARD. Two copies of one table are safe only while something checks\n", + "# them. Where a formula is in both, the values must agree.\n", + "_drift = [(f, BINARY_MAPLE_FALLBACK[f][0], _json_lookup[f])\n", + " for f in sorted(set(BINARY_MAPLE_FALLBACK) & set(_json_lookup))\n", + " if abs(BINARY_MAPLE_FALLBACK[f][0] - _json_lookup[f]) > 1e-6]\n", + "if _drift:\n", + " raise AssertionError(\n", + " 'the inline table and the released JSON disagree on '\n", + " + ', '.join(f'{f} ({a} vs {b})' for f, a, b in _drift[:5])\n", + " + f'{\" and others\" if len(_drift) > 5 else \"\"}. '\n", + " 'One of them is stale; decide which before running.')\n", + "\n", + "print(f' binary reference: {len(_json_lookup)} entries from {_binary_source}')\n", + "\n", + "# ── Which entries are estimates ────────────────────────────────────────\n", + "#\n", + "# v1.2.9: 23 of the 112 values are estimates, interpolated within a structure\n", + "# type or set by hand, and none has a published or computed source; Cu2O's\n", + "# recorded source, a MaplePy calculation at a = 4.270 A, gives 797.9 rather\n", + "# than 730.0 and is marked unsourced in the JSON (sourced: false). They are\n", + "# kept, so that results made with them can be reproduced, and every\n", + "# decomposition that uses one says so (`estimated_binaries`). Nothing is\n", + "# reclassified on that account: a residual resting on an estimate is a\n", + "# residual against a weaker reference, and the reader is told which.\n", + "def estimated_binaries(source_path):\n", + " \"\"\"The formulae whose reference value is an estimate, or unsourced.\n", + "\n", + " From the released JSON's `source` and `sourced` fields where the table\n", + " was read from it (Cu2O is unsourced, not estimated);\n", + " from the inline labels where it was not.\n", + " \"\"\"\n", + " import json as _json\n", + " from pathlib import Path as _Path\n", + " _p = _Path(source_path)\n", + " if _p.is_file():\n", + " with open(_p, 'r', encoding='utf-8') as _f:\n", + " return {e['formula'] for e in _json.load(_f)['entries']\n", + " if e.get('source') == 'estimated'\n", + " or e.get('sourced') is False}\n", + " return {f for f, (_v, _t, _s) in BINARY_MAPLE_FALLBACK.items()\n", + " if _s.lower().startswith(('estimated', 'interpolated'))}\n", + "\n", + "\n", + "ESTIMATED_BINARIES = estimated_binaries(_binary_source)\n", + "print(f' estimated or unsourced: {len(ESTIMATED_BINARIES)} entries')\n", + "print(f' inline fallback: {len(BINARY_MAPLE_FALLBACK)} entries, '\n", + " f'{len(set(_json_lookup) - set(BINARY_MAPLE_FALLBACK))} of the released '\n", + " f'entries not in it, no value in disagreement')\n", + "\n", + "# To use your own ICSD batch results instead, set BINARY_CSV below.\n", "BINARY_CSV = None # e.g. Path(\"binary_oxides/maple_summary.csv\")\n", "\n", "BINARY_MAPLE, df_binary = load_binary_table(csv_path=BINARY_CSV)\n", + "# the released table wins over the inline fallback for anything it carries\n", + "BINARY_MAPLE.update(_json_lookup)\n", "display(df_binary)" ] }, @@ -411,11 +597,7 @@ "cell_type": "code", "execution_count": null, "id": "518eb4f9", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# ─────────────────────────────────────────────────────────────────────────────\n", @@ -449,7 +631,8 @@ " return patterns.get(oxi, (None, None, None))\n", "\n", "\n", - "def decompose_ternary(source_cif, df_results, binary_lookup, verbose=True):\n", + "def decompose_ternary(source_cif, df_results, binary_lookup, verbose=True,\n", + " results_index=None):\n", " \"\"\"\n", " Decompose a ternary oxide into binary components using the\n", " per-site oxidation states from MaplePy output.\n", @@ -469,7 +652,9 @@ " maple_binary_sum, delta_abs, delta_pct,\n", " oxygen_balanced, missing_binaries, success\n", " \"\"\"\n", - " sites = df_results[df_results['source_cif'] == source_cif].copy()\n", + " # v1.2.4: from the index where the caller built one; the scan it\n", + " # replaces cost 2.4 ms of the 5.4 ms this function took per structure.\n", + " sites = rows_for(source_cif, df_results, results_index).copy()\n", "\n", " if sites.empty:\n", " return {\"source_cif\": source_cif, \"success\": False,\n", @@ -503,21 +688,52 @@ " maple_sum = 0.0\n", " o_from_binary = 0.0\n", " missing = []\n", + " # v1.2.3: what was asked for and why it was not there, one entry per\n", + " # missing binary. `missing_binaries` stays as it was, for the report and\n", + " # for every CSV already written.\n", + " missing_detail = []\n", + " estimated_used = [] # v1.2.9: binaries whose value is an estimate\n", "\n", " for el, info in cation_info.items():\n", " binary_formula, n_cat, n_oxy = _binary_formula_for(\n", " el, info['mean_oxi']\n", " )\n", "\n", + " # v1.2.3: did the pattern lookup have to round? A mean over a\n", + " # shared site is not an oxidation state, and the rounding was silent.\n", + " _mean = abs(info['mean_oxi'])\n", + " _rounded = abs(_mean - round(_mean)) > OXI_ROUNDING_TOL\n", + "\n", " if binary_formula is None:\n", " missing.append(f\"{el}{info['mean_oxi']:+.1f} (no pattern)\")\n", + " missing_detail.append({\n", + " 'binary': None, 'element': el,\n", + " 'mean_oxi': round(info['mean_oxi'], 3),\n", + " 'rounded_from_non_integer': _rounded,\n", + " 'reason': 'no binary pattern for this oxidation state'})\n", " continue\n", "\n", " maple_binary = binary_lookup.get(binary_formula)\n", " if maple_binary is None:\n", - " missing.append(f\"{binary_formula} (not in table)\")\n", + " # v1.2.5: the rounding fact goes IN the string. It used to live in\n", + " # missing_detail, a parallel list that batch_additivity never put\n", + " # into its frame, so the classifier's best evidence never reached\n", + " # it. One carrier, and it is the one that survives to the CSV.\n", + " missing.append(\n", + " f\"{binary_formula} (not in table\"\n", + " + (f\", mean {info['mean_oxi']:+.2f} rounded)\" if _rounded\n", + " else \")\"))\n", + " missing_detail.append({\n", + " 'binary': binary_formula, 'element': el,\n", + " 'mean_oxi': round(info['mean_oxi'], 3),\n", + " 'rounded_from_non_integer': _rounded,\n", + " 'reason': 'not in the reference table'})\n", " continue\n", "\n", + " # v1.2.9: an estimate is used, and said to be used\n", + " if binary_formula in ESTIMATED_BINARIES:\n", + " estimated_used.append(binary_formula)\n", + "\n", " coeff = info['count_per_fu'] / n_cat\n", " contribution = coeff * maple_binary\n", " o_contrib = coeff * n_oxy\n", @@ -538,11 +754,45 @@ " o_from_binary += o_contrib\n", "\n", " # ── Oxygen balance check ──────────────────────────────────────────\n", + " #\n", + " # v1.1: MEASURED, AND LEFT ALONE. This is an absolute tolerance on a\n", + " # quantity that scales as 1/Z, which is the shape of a fault. Over 101\n", + " # decompositions of real ICSD structures the imbalance is:\n", + " #\n", + " # 0 to 1e-6 97 structures exact, to floating point\n", + " # 1e-6 to 0.1 0\n", + " # 0.1 to 0.2 3 Co3O4 standing in for Co2O3\n", + " # 0.2 and above 1 Ca4Mn4O10.6\n", + " #\n", + " # Nothing lies inside the gap, so every value between about 1e-6 and 0.16\n", + " # classifies identically and the number is not doing the work. What DID\n", + " # matter was the Z error upstream: at Z = 1 the same physical imbalance\n", + " # was multiplied by the true Z, close enough to the gap to cross it.\n", + " # MaplePy v1.1 derives Z crystallographically and removes that.\n", + " #\n", + " # Note also that o_per_fu counts anion SITES, not occupancies, so an\n", + " # oxygen-deficient refinement is balanced here and non-stoichiometric in\n", + " # its composition. That is consistent with the mean-field treatment\n", + " # elsewhere and is worth stating rather than discovering.\n", + " O_BALANCE_TOL = 0.05 # O per formula unit; see the measurement above\n", " o_residual = abs(o_from_binary - o_per_fu)\n", - " o_balanced = o_residual < 0.05\n", + " o_balanced = o_residual < O_BALANCE_TOL\n", "\n", " # ── Additivity residual ───────────────────────────────────────────\n", - " delta_abs = abs(maple_tern - maple_sum) if decomposition else None\n", + " #\n", + " # v1.2.1: `if decomposition` asks whether ANY cation was decomposed, not\n", + " # whether ALL were. 30 structures across the two families are missing a\n", + " # binary reference, so their sum omitted a whole component and the\n", + " # residual against it was up to 93% (NaOsO3: ternary 5022.2 against Na2O\n", + " # alone at 347.2). success=False kept those out of the statistics, but the\n", + " # number was still written to the CSV and Figure 1 selected on\n", + " # delta.notna(), so all 30 sat in the histogram tail looking like\n", + " # measured failures.\n", + " #\n", + " # Same rule as the falsy-zero fix above: do not write a number that has no\n", + " # meaning. missing_binaries still says what was absent.\n", + " complete = bool(decomposition) and not missing\n", + " delta_abs = abs(maple_tern - maple_sum) if complete else None\n", " delta_pct = (100 * delta_abs / maple_tern\n", " if delta_abs is not None and maple_tern > 0\n", " else None)\n", @@ -555,17 +805,28 @@ " 'n_cation_elements': len(cation_info),\n", " 'decomposition' : decomposition,\n", " 'maple_binary_sum' : round(maple_sum, 2),\n", - " 'delta_abs' : round(delta_abs, 2) if delta_abs else None,\n", - " 'delta_pct' : round(delta_pct, 3) if delta_pct else None,\n", + " # v1.1: `if delta_abs` is FALSE for 0.0, so a structure whose\n", + " # ternary MAPLE exactly equalled its binary sum - the perfect result\n", + " # the theorem predicts - was written out as None and then read\n", + " # downstream as a missing value. The guard in the classifier\n", + " # attributed it to \"a rounding or serialisation artefact\"; it was\n", + " # this line.\n", + " 'delta_abs' : (round(delta_abs, 2)\n", + " if delta_abs is not None else None),\n", + " 'delta_pct' : (round(delta_pct, 3)\n", + " if delta_pct is not None else None),\n", " 'oxygen_per_fu' : round(o_per_fu, 4),\n", " 'oxygen_from_bins' : round(o_from_binary, 4),\n", " 'oxygen_balanced' : o_balanced,\n", " 'missing_binaries' : missing,\n", + " 'missing_detail' : missing_detail,\n", + " 'estimated_binaries': estimated_used,\n", " 'success' : len(decomposition) > 0 and len(missing) == 0,\n", " }\n", "\n", " if verbose and result['success']:\n", - " status = (\"GOOD (<1%)\" if delta_pct < 1.0 else\n", + " status = (f\"GOOD (<{ADDITIVE_THRESHOLD_PCT:g}%)\"\n", + " if delta_pct < ADDITIVE_THRESHOLD_PCT else\n", " \"MARGINAL (1-2%)\" if delta_pct < 2.0 else\n", " \"POOR (>2%)\")\n", " print(f\" {compound:20s} \"\n", @@ -597,11 +858,7 @@ "cell_type": "code", "execution_count": null, "id": "bd231498", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# ─────────────────────────────────────────────────────────────────────────────\n", @@ -626,11 +883,15 @@ " rows = []\n", " details = []\n", "\n", + " # v1.2.4: once, here, rather than a scan per structure inside the loop.\n", + " results_index = index_by_cif(df_results)\n", + "\n", " for _, summary_row in df_summary.iterrows():\n", " cif = summary_row['source_cif']\n", "\n", " result = decompose_ternary(\n", - " cif, df_results, binary_lookup, verbose=verbose\n", + " cif, df_results, binary_lookup, verbose=verbose,\n", + " results_index=results_index\n", " )\n", " details.append(result)\n", "\n", @@ -649,6 +910,7 @@ " 'oxygen_balanced' : result.get('oxygen_balanced'),\n", " 'n_cation_elements': result.get('n_cation_elements'),\n", " 'missing_binaries' : '; '.join(result.get('missing_binaries', [])),\n", + " 'estimated_binaries': '; '.join(result.get('estimated_binaries', [])),\n", " 'success' : result.get('success', False),\n", " })\n", "\n", @@ -674,6 +936,9 @@ " print(f\" Marginal (1-2%): {marginal}\")\n", " print(f\" Poor (>2%): {poor}\")\n", " print(f\" Incomplete (missing binaries): {n_fail}\")\n", + " _n_est = (df['success'] & (df['estimated_binaries'] != '')).sum()\n", + " print(f\" Resting on an estimated binary: {_n_est} of the {n_success} \"\n", + " f\"decomposed (see estimated_binaries)\")\n", " print(f\"{'='*65}\")\n", "\n", " return df, details\n", @@ -704,27 +969,27 @@ "| Code | Tier | Label |\n", "|------|------|-------|\n", "| Additive | 0 | Additive (Δ < 1%) |\n", - "| 1.1 | 1 | Missing binary reference |\n", + "| 1.1 | 1 | Reference table incomplete |\n", + "| 1.2 | 1 | Upstream calculation failure (always zero here) |\n", + "| 1.3 | 1 | No binary end-member exists |\n", + "| 1.4 | 1 | Oxidation state has no binary analogue |\n", "| 2.1 | 2 | Oxidation state assignment error |\n", - "| 2.2 | 2 | Z = 1 metadata artefact |\n", + "| 2.2 | 2 | Z = 1 metadata artefact (cannot arise from MaplePy) |\n", "| 2.3 | 2 | Disorder / mean-field |\n", "| 2.4 | 2 | Oxygen non-stoichiometry |\n", + "| 2.5 | 2 | Structural coordinate error |\n", + "| 2.6 | 2 | Anion vacancy disorder |\n", + "| 2.7 | 2 | Split-site disorder model |\n", "| 3.1 | 3 | Genuine violation |\n", "\n", - "**Priority:** Additive first, then 1.1 → 2.1 → 2.2 → 2.3 → 2.4 → 3.1.\n", - "\n", - "**Reserved:** 1.2 (upstream MaplePy failure), 2.5 (wrong structure type), 2.6 (anion vacancy disorder)." + "**Order:** Tier 1 (1.1, 1.3, 1.4); then the structural defects, 2.7 and 2.5, whatever the residual; then Additive; then 2.1 → 2.6 → 2.3 → 2.4; then 3.1. A caveat must not mask a defect. The registry in the cell below defines every code." ] }, { "cell_type": "code", "execution_count": null, "id": "c6569ed9", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 4. Failure Classification — Tiered Numeric Scheme\n", @@ -737,14 +1002,11 @@ "# Tier 2 (2.x) Calculation complete, result compromised\n", "# Tier 3 (3.x) Calculation complete, result trustworthy\n", "#\n", - "# Priority: additive checked first, then codes applied in ascending\n", - "# order (1.1 → 2.1 → 2.2 → 2.3 → 2.4 → 3.1). A structure triggering\n", - "# multiple flags receives the lowest applicable code.\n", - "#\n", - "# Future codes (reserved, no current data triggers them):\n", - "# 1.2 Upstream MaplePy failure (CIF never reached Hopper)\n", - "# 2.5 Wrong structure type (incorrect space group / structure type)\n", - "# 2.6 Anion vacancy disorder (O vacancies distinct from cation disorder)\n", + "# v1.2.9: the order as classify_additivity() applies it (this header had\n", + "# kept the first version's): Tier 1 (1.1, 1.3, 1.4); the structural\n", + "# defects, 2.7 then 2.5, whatever the residual; Additive; then 2.1, 2.6,\n", + "# 2.3, 2.4; then 3.1. A caveat must not mask a defect. 1.2 and 2.2 are\n", + "# defined and cannot arise from a MaplePy run (see the registry).\n", "\n", "# ── Classification registry ──────────────────────────────────────────────\n", "# Central definition of all codes. Add new codes here; the classifier\n", @@ -752,39 +1014,301 @@ "\n", "CLASSIFICATION_REGISTRY = {\n", " # code : (tier, label, description)\n", - " '1.1': (1, 'Missing binary reference',\n", - " 'One or more binary oxide components absent from the reference '\n", - " 'table. Residual cannot be computed.'),\n", - " '1.2': (1, 'Upstream MaplePy failure',\n", - " 'Reserved. MaplePy could not process the CIF (appears in '\n", - " 'maple_failed.csv, never reaches Hopper).'),\n", + " # v1.2.3: narrowed. 1.1 now means only what its name says: the binary\n", + " # oxide exists and OUR TABLE lacks it, which is a job of work rather than\n", + " # a result. The other reasons a binary can be absent have their own codes.\n", + " '1.1': (1, 'Reference table incomplete',\n", + " 'The binary oxide exists at ambient conditions and is absent from '\n", + " 'the reference table. Adding it makes the structure testable.'),\n", + " # v1.2.6: defined properly rather than 'reserved'. These structures are\n", + " # real and they are counted, just not here: MaplePy writes them to\n", + " # maple_failed.csv and they never produce a row for Hopper to classify.\n", + " # Three perovskite CIFs in this study, out of 941 retrieved.\n", + " '1.2': (1, 'Upstream calculation failure',\n", + " 'MaplePy could not compute a MAPLE value from the CIF, so there '\n", + " 'is no ternary value to test. Refined occupancies exceeding '\n", + " 'unity and parse failures both land here. These entries appear '\n", + " 'in maple_failed.csv and are excluded before classification, so '\n", + " 'this code is always zero in a Hopper output.'),\n", + " # v1.2.3: the most interesting exclusion in the study, and it used to be\n", + " # reported as a missing table entry. Fe(IV), Co(IV), Ru(III), Cu(III),\n", + " # Pd(III), Os(V), Tc(V), Rh(V) and Ir(V) are real states in these\n", + " # perovskites and pyrochlores and none of them has an ambient binary\n", + " # oxide. The theorem cannot be tested against an end-member that does not\n", + " # exist.\n", + " '1.3': (1, 'No binary end-member exists',\n", + " 'The oxidation state is real and the corresponding binary oxide '\n", + " 'does not exist at ambient conditions, so the decomposition has '\n", + " 'no end-member to sum. A limit on where additivity can be tested, '\n", + " 'not a defect in the structure or the table.'),\n", + " # v1.2.5: a THIRD route, found once the rounding evidence could\n", + " # actually reach the classifier. Nd4Cu4O11.724 asks for Cu2O3 from a mean\n", + " # of +2.86 and Nd4Ru3.544O12 asks for Ru2O3 from +3.38: means over a\n", + " # non-stoichiometric refinement, not over a shared site. Same conclusion,\n", + " # third way of getting there, and it is in the description now.\n", + " '1.4': (1, 'Oxidation state has no binary analogue',\n", + " 'The charge the decomposition asked for is not a real oxidation '\n", + " 'state of that element: a formal average over a '\n", + " 'charge-disproportionated site, an occupancy-weighted mean over a '\n", + " 'site shared by two cations, or a mean over a non-stoichiometric '\n", + " 'refinement. Where the mean was not an integer the decomposition '\n", + " 'records it and this code is assigned on that evidence.'),\n", " '2.1': (2, 'Oxidation state assignment error',\n", " 'Delta > 10% in an ordered, oxygen-balanced structure. Points to '\n", " 'incorrect oxidation states in the CIF.'),\n", + " # v1.2.6: RETAINED, not retired. MaplePy v1.1 stopped inferring Z from\n", + " # composition and derives it from the gcd of the site multiplicities, so\n", + " # this cannot fire on a MaplePy result and is zero throughout this study.\n", + " # It is kept because the failure mode is not MaplePy's: any tool that\n", + " # reads Z from the CIF, or trusts a compositional reduction, will produce\n", + " # it, and anyone adopting this scheme needs somewhere to put it. Zero\n", + " # here is a result about the calculator, not an empty slot.\n", " '2.2': (2, 'Z = 1 metadata artefact',\n", - " 'pymatgen compositional reduction yields Z = 1, inflating MAPLE '\n", - " 'per formula unit.'),\n", + " 'The number of formula units per cell has been taken as 1 when '\n", + " 'the cell contains more, inflating MAPLE per formula unit by an '\n", + " 'integer factor and raising the Madelung factor well above the '\n", + " 'family range. Arises wherever Z is inferred from composition '\n", + " 'rather than derived from the site multiplicities.'),\n", " '2.3': (2, 'Disorder / mean-field',\n", " 'Mixed-occupancy sites processed via mean-field charge '\n", " 'approximation. Residual may reflect averaging artefact.'),\n", " '2.4': (2, 'Oxygen non-stoichiometry',\n", " 'Oxygen count from binary decomposition does not match ternary. '\n", " 'Decomposition not well-defined (e.g. Co3O4 for Co2O3).'),\n", + " # v1.1: the count has been removed from this description. It read 32\n", + " # here, 19 in the detector's docstring and 31 in the manuscript, all\n", + " # shipping together. A number that lives in a string drifts from the data\n", + " # it counts; the notebook prints the population it actually found.\n", + " # v1.2.2: two detectors now, either of which is sufficient. The CV test\n", + " # needs a 20-site Pnma cell with 12 oxygens; the distance test needs\n", + " # nothing but coordinates. Each catches cases the other cannot: 22 of the\n", + " # 26 perovskites under 1.6 A were already caught by CV, and 8 structures\n", + " # caught by CV have an ordinary 1.98 A shortest contact.\n", " '2.5': (2, 'Structural coordinate error',\n", - " 'O-site MAPLE coefficient of variation exceeds 0.05, indicating '\n", - " 'unphysical interatomic distances from Wyckoff site mis-assignment '\n", - " 'or wrong fractional coordinates. 32 entries from >= 10 publications.'),\n", + " 'Either the O-site MAPLE coefficient of variation exceeds 0.05, '\n", + " 'or the shortest interatomic contact is below MaplePy\\'s '\n", + " 'SHORT_CONTACT_ANG. Both indicate unphysical interatomic '\n", + " 'distances from Wyckoff site mis-assignment or wrong fractional '\n", + " 'coordinates.'),\n", + " # v1.2.2: ACTIVE. Reserved since the first version and assignable now\n", + " # that MaplePy v1.3.3 reports which sublattice carries the fractional\n", + " # occupancy. Tested before 2.3, because an oxygen-deficient refinement\n", + " # described as \"disorder\" has lost the part that matters.\n", " '2.6': (2, 'Anion vacancy disorder',\n", - " 'Reserved. Oxygen vacancies distinct from cation disorder (2.3). '\n", - " 'Not currently distinguished.'),\n", + " 'Fractional occupancy on the anion sublattice only: an '\n", + " 'oxygen-deficient refinement, treated by mean-field charge '\n", + " 'averaging. Distinct from cation disorder (2.3) and from a '\n", + " 'decomposition that cannot balance its oxygen (2.4).'),\n", + " '2.7': (2, 'Split-site disorder model',\n", + " 'Two sites closer than MaplePy\\'s SPLIT_SITE_ANG: one '\n", + " 'crystallographic position split by a disorder model. The Ewald '\n", + " 'sum over fractionally occupied near-coincident sites is not an '\n", + " 'energy, whatever the residual comes out as.'),\n", " '3.1': (3, 'Genuine violation',\n", " 'Delta >= 1% with correct oxidation states, correct Z, balanced '\n", " 'oxygen, no disorder. Reflects genuine structural chemistry.'),\n", "}\n", "\n", + "# ── The codes, in the order they are reported ──────────────────────────────\n", + "# v1.2.1: this order was written out three times (twice here, once in the\n", + "# figure cell), and the figure's copy omitted 1.1 and 2.3, so those rows were\n", + "# in the count and not in the bars.\n", + "# v1.2.6: derived, not typed. The hand-written list named the codes that\n", + "# actually fire, which meant 1.2 and 2.2 were absent from every breakdown\n", + "# rather than present and zero. A code defined in the scheme and reported\n", + "# nowhere is indistinguishable from a code nobody thought of.\n", + "CODE_ORDER = ['Additive'] + sorted(CLASSIFICATION_REGISTRY)\n", + "\n", + "\n", + "# ── Why a binary oxide is not in the table ─────────────────────────────────\n", + "#\n", + "# v1.2.3: one entry per binary the decompositions have actually asked for and\n", + "# not found, with the reason beside it. This is chemistry, so it is written\n", + "# down and auditable rather than buried in a branch, and anything NOT here\n", + "# classifies 1.1 and says it is unclassified - a new missing binary announces\n", + "# itself instead of joining a pile.\n", + "#\n", + "# 'table' the binary exists at ambient conditions; we lack it\n", + "# 'no_binary' the oxidation state is real; no ambient binary oxide of it\n", + "# 'no_state' the charge is not a real oxidation state of that element\n", + "#\n", + "MISSING_BINARY_STATUS = {\n", + " # the binary exists and the table should have it\n", + " 'SnO': ('table',\n", + " 'Litharge-type SnO is the ambient Sn(II) oxide. Ta2Sn2O7 has '\n", + " 'Sn(II) with Ta(V), which balances, so this is a genuine gap.'),\n", + " 'PtO': ('table',\n", + " 'PtO is reported as a tetragonal ambient phase, though Pt3O4 '\n", + " 'and PtO2 are better characterised. Needs a verified structure '\n", + " 'before a MAPLE value is added.'),\n", + " 'SmO': ('table',\n", + " 'Rock-salt SmO is a real Sm(II) phase. NOTE: the structure that '\n", + " 'asks for it, SmTiO3 ICSD 51180, is assigned Sm2+ with Ti4+, '\n", + " 'while the known compound is Sm3+Ti3+O3. Both balance to 6, so '\n", + " 'charge neutrality cannot see the difference. The oxidation '\n", + " 'state assignment deserves a look.'),\n", + "\n", + " # the state is real; the binary oxide is not\n", + " 'Ru2O3': ('no_binary', 'Ru(III) has no ambient binary oxide; RuO2 is the '\n", + " 'stable oxide.'),\n", + " 'FeO2': ('no_binary', 'Fe(IV) has no ambient binary oxide. CaFeO3 and '\n", + " 'EuFeO3 really do contain Fe(IV).'),\n", + " 'CoO2': ('no_binary', 'Co(IV) has no ambient binary oxide; CoO2 exists '\n", + " 'only as a delithiated layered phase.'),\n", + " 'Cu2O3': ('no_binary', 'Cu(III) has no ambient binary oxide; Cu2O and '\n", + " 'CuO are the binaries.'),\n", + " 'Pd2O3': ('no_binary', 'Pd(III) has no ambient binary oxide.'),\n", + " 'Os2O5': ('no_binary', 'Os(V) has no ambient binary oxide; OsO2 and OsO4 '\n", + " 'are the known ones.'),\n", + " 'Tc2O5': ('no_binary', 'Tc(V) has no ambient binary oxide; TcO2 and '\n", + " 'Tc2O7 are the known ones.'),\n", + " 'Rh2O5': ('no_binary', 'Rh(V) has no ambient binary oxide; Rh2O3 and '\n", + " 'RhO2 are the binaries.'),\n", + " 'Ir2O5': ('no_binary', 'Ir(V) has no ambient binary oxide; IrO2 is the '\n", + " 'stable oxide.'),\n", + "\n", + " # the charge is not a state\n", + " 'BiO2': ('no_state',\n", + " 'Bi(IV) is a formal average. SrBiO3 is charge-disproportionated '\n", + " 'Bi(III)/Bi(V), and the CIF deposits Bi as 4+ on every site, so '\n", + " 'the rounding test cannot catch it.'),\n", + " 'YO2': ('no_state', 'Y(IV) does not exist. Y3NbO7 shares its cation '\n", + " 'site with Nb and the site mean is 3.5.'),\n", + " 'EuO2': ('no_state', 'Eu(IV) does not exist. Eu2Sn2O7 shares its cation '\n", + " 'site with Sn and the site mean is 3.5.'),\n", + " 'TlO': ('no_state', 'Tl(II) does not exist; Tl is 1+ or 3+. Nb2Tl2O7 '\n", + " 'shares its cation site with Nb.'),\n", + "}\n", + "\n", + "_MISSING_STATUS_CODE = {'table': '1.1', 'no_binary': '1.3', 'no_state': '1.4'}\n", + "\n", + "\n", + "def as_missing_list(value):\n", + " \"\"\"\n", + " The missing-binary entries as a list, whatever the caller has.\n", + "\n", + " v1.2.5: batch_additivity stores `'; '.join(missing)`, so the classifier\n", + " was handed a STRING and iterated it character by character - every one of\n", + " the 20 tier-1 perovskites came out 1.4 with a reason built from single\n", + " letters. Every test I wrote passed a list, because I built the frames\n", + " myself or read them back with literal_eval. One place converts now, and\n", + " it takes a list, a joined string, or the repr of a list.\n", + " \"\"\"\n", + " if value is None:\n", + " return []\n", + " if isinstance(value, (list, tuple)):\n", + " return [v for v in value if v]\n", + " if not isinstance(value, str):\n", + " return [] # NaN from an empty CSV cell\n", + " text = value.strip()\n", + " if not text or text in ('[]', 'nan'):\n", + " return []\n", + " if text.startswith('[') and text.endswith(']'):\n", + " import ast as _ast\n", + " try:\n", + " lit = _ast.literal_eval(text)\n", + " if isinstance(lit, (list, tuple)):\n", + " return [v for v in lit if v]\n", + " except (ValueError, SyntaxError):\n", + " pass\n", + " return [p.strip() for p in text.split(';') if p.strip()]\n", + "\n", + "\n", + "def _rounded_from_missing(entry):\n", + " \"\"\"Whether this request came from a rounded site mean, per the string.\"\"\"\n", + " return isinstance(entry, str) and 'rounded)' in entry\n", + "\n", + "\n", + "def _binary_from_missing(entry):\n", + " \"\"\"The binary formula out of one `missing_binaries` string, or None.\n", + "\n", + " The strings are written by decompose_ternary as 'Ru2O3 (not in table)'\n", + " and 'Fe+4.0 (no pattern)'. Only the first form names a binary.\n", + " \"\"\"\n", + " if not isinstance(entry, str):\n", + " return None\n", + " head = entry.split(' (')[0].strip()\n", + " return head if '(not in table)' in entry else None\n", + "\n", + "\n", + "def classify_missing_binaries(missing, detail=None):\n", + " # v1.2.5: `detail` is kept in the signature for anything that still\n", + " # passes it, and ignored: the rounding fact is in the string now.\n", + " \"\"\"\n", + " Which code a decomposition that lacked a binary belongs in, and why.\n", + "\n", + " v1.2.3: 1.1 held four different findings. Returns (code, reason).\n", + "\n", + " The rounding evidence wins where it exists: a request built on a\n", + " non-integral site mean is 1.4 whatever the registry says, because the\n", + " charge was never an oxidation state. Otherwise the registry decides, and\n", + " an unregistered binary stays 1.1 and says so.\n", + "\n", + " Where a structure is missing more than one binary the strongest finding\n", + " wins, in the order 1.4, 1.3, 1.1: a structure whose decomposition rests\n", + " on a charge that does not exist is not waiting on our table.\n", + " \"\"\"\n", + " reasons, codes = [], []\n", + " for entry in as_missing_list(missing):\n", + " formula = _binary_from_missing(entry)\n", + "\n", + " if _rounded_from_missing(entry):\n", + " codes.append('1.4')\n", + " reasons.append(f'{entry}: asked for from a rounded site mean, '\n", + " f'which was not an oxidation state')\n", + " continue\n", + "\n", + " if formula is None:\n", + " codes.append('1.4')\n", + " reasons.append(f'{entry}: no binary pattern for that charge')\n", + " continue\n", + "\n", + " status = MISSING_BINARY_STATUS.get(formula)\n", + " if status is None:\n", + " codes.append('1.1')\n", + " reasons.append(f'{formula}: UNCLASSIFIED, not in '\n", + " f'MISSING_BINARY_STATUS')\n", + " continue\n", + " codes.append(_MISSING_STATUS_CODE[status[0]])\n", + " reasons.append(f'{formula}: {status[1]}')\n", + "\n", + " if not codes:\n", + " return '1.1', 'decomposition failed with no binary named'\n", + " for code in ('1.4', '1.3', '1.1'):\n", + " if code in codes:\n", + " return code, '; '.join(reasons)\n", + " return '1.1', '; '.join(reasons)\n", + "\n", + "\n", + "# ── The population a residual statistic is drawn from ──────────────────────\n", + "def additivity_population(df):\n", + " \"\"\"\n", + " The structures whose residual IS a residual: decomposition complete and\n", + " delta computed.\n", + "\n", + " v1.2.1: Figure 1 selected on delta.notna() while the classifier counted\n", + " tier 0, so the figure said 662 within 1% and the classification said 661\n", + " additive, on the same run and in the same paper. One definition, used by\n", + " both.\n", + " \"\"\"\n", + " return df[df['success'].astype(bool) & df['delta_pct'].notna()]\n", + "\n", + "\n", + "def n_classified_additive(df):\n", + " \"\"\"How many structures the classifier called additive. One number.\"\"\"\n", + " return int((additivity_population(df)['classification'] == 'Additive').sum())\n", + "\n", + "\n", "# Convenience lookups\n", "def _tier_for_code(code):\n", - " \"\"\"Return the tier (1, 2, or 3) for a classification code.\"\"\"\n", + " \"\"\"Return the tier for a classification outcome.\n", + "\n", + " v1.2.7: 'Additive' is an outcome without a registry code, and it is\n", + " tier 0. Callers that map over CODE_ORDER meet it first, so answering\n", + " here is better than every caller special-casing it.\n", + " \"\"\"\n", + " if code == 'Additive':\n", + " return 0\n", " return CLASSIFICATION_REGISTRY[code][0]\n", "\n", "def _label_for_code(code):\n", @@ -795,24 +1319,23 @@ "Code 2.5 detector: Wyckoff 4a/4b site mis-assignment in Pnma perovskites.\n", "\n", "Detects ICSD entries where the B-site cation is deposited at Wyckoff 4a\n", - "instead of the correct 4b in GdFeO3-type perovskites (Pnma, Z=4, 20 sites).\n", + "instead of the correct 4b in GdFeO3-type perovskites (Pnma, 20 sites).\n", "\n", - "Validated against 938 Pnma perovskites: catches 19 confirmed errors from\n", - "at least 4 independent publications, zero false positives.\n", + "v1.1: the counts that used to sit here have been removed. They disagreed\n", + "with the registry and with the manuscript, and the notebook reports the\n", + "population it finds.\n", "\n", - "Usage in the Hopper classification cell:\n", - " \n", - " wyckoff_error = detect_wyckoff_site_error(\n", - " row['source_cif'], results_df, summary_df\n", - " )\n", - " if wyckoff_error:\n", - " code = '2.5'\n", - " label = 'Wyckoff site mis-assignment (B at 4a instead of 4b)'\n", + "v1.2.9: the usage example that stood here named a function that does not\n", + "exist. The detector is detect_structural_coordinate_error(), below, and\n", + "classify_additivity() calls it; since v1.2.2, code 2.5 also takes a\n", + "short contact from MaplePy's geometry_flag.\n", "\"\"\"\n", "\n", "\n", "def detect_structural_coordinate_error(cif_name, results_df, summary_df,\n", - " cv_threshold=0.05):\n", + " cv_threshold=0.05,\n", + " results_index=None,\n", + " summary_index=None):\n", " \"\"\"\n", " Detect structural coordinate errors in Pnma perovskites using the\n", " coefficient of variation (CV) of per-site oxygen MAPLE values.\n", @@ -846,16 +1369,26 @@ " False — structure is clean.\n", " None — structure is not a testable Pnma perovskite.\n", " \"\"\"\n", - " srow = summary_df[summary_df['source_cif'] == cif_name]\n", + " srow = rows_for(cif_name, summary_df, summary_index)\n", " if len(srow) == 0:\n", " return None\n", " srow = srow.iloc[0]\n", " \n", - " # Only test Z=4 Pnma perovskites with 20 sites\n", - " if srow['Z'] != 4 or srow['space_group'] != 'Pnma':\n", + " # v1.1: THE TEST NO LONGER GATES ON Z.\n", + " #\n", + " # This asked for Z == 4, so every perovskite whose Z had been lost to\n", + " # composition reduction - 101 of the 938, all non-stoichiometric - was\n", + " # returned as untestable and never screened for coordinate errors at all.\n", + " # The claim of zero false positives across 938 was really across 831.\n", + " #\n", + " # What the test actually needs is a 20-site Pnma cell with 12 oxygens,\n", + " # which is checked below and does not require Z. With MaplePy v1.1\n", + " # deriving Z from the site counts the two conditions coincide anyway, and\n", + " # a test should not depend on a quantity it does not use.\n", + " if srow['space_group'] != 'Pnma':\n", " return None\n", " \n", - " entry = results_df[results_df['source_cif'] == cif_name]\n", + " entry = rows_for(cif_name, results_df, results_index)\n", " if len(entry) != 20:\n", " return None\n", " \n", @@ -875,7 +1408,69 @@ " # Explicit bool() to avoid numpy.bool_ identity issues\n", " return bool(cv > cv_threshold)\n", "\n", - "def classify_additivity(df_add, threshold_additive=1.0):\n", + "def _summary_field(cif_name, summary_df, column, summary_index=None):\n", + " \"\"\"\n", + " One field of MaplePy's summary for one structure, or None.\n", + "\n", + " v1.2.2: the three tests below all need the same lookup, and all three\n", + " must answer None rather than False when MaplePy did not write the\n", + " column - a test that cannot run is not a test that passed.\n", + " \"\"\"\n", + " if column not in summary_df.columns:\n", + " return None\n", + " srow = rows_for(cif_name, summary_df, summary_index)\n", + " if len(srow) == 0:\n", + " return None\n", + " value = srow[column].iloc[0]\n", + " return value if isinstance(value, str) else None\n", + "\n", + "\n", + "def detect_split_site(cif_name, summary_df, summary_index=None):\n", + " \"\"\"\n", + " Whether MaplePy flagged this structure as a split-site disorder model.\n", + "\n", + " v1.2.2: reads `geometry_flag`, written by MaplePy v1.3.3. It used to read\n", + " the prefix of `geometry_status`, which is a sentence written for a human:\n", + " Hopper's classification should not depend on MaplePy's wording.\n", + "\n", + " Hopper does not recompute the geometry. MaplePy holds the structures and\n", + " the tolerances, and two implementations of one test is how they come to\n", + " disagree.\n", + " \"\"\"\n", + " flag = _summary_field(cif_name, summary_df, 'geometry_flag',\n", + " summary_index)\n", + " return None if flag is None else flag == 'split_site'\n", + "\n", + "\n", + "def detect_short_contact(cif_name, summary_df, summary_index=None):\n", + " \"\"\"\n", + " Whether the shortest contact is below MaplePy's SHORT_CONTACT_ANG.\n", + "\n", + " v1.2.2: the second detector for code 2.5. The CV test needs a 20-site\n", + " Pnma cell with 12 oxygens and cannot see a short contact anywhere else;\n", + " NdFeO3 at 1.507 A was classified Additive at delta 0.312% because of it.\n", + " \"\"\"\n", + " flag = _summary_field(cif_name, summary_df, 'geometry_flag',\n", + " summary_index)\n", + " return None if flag is None else flag == 'short_contact'\n", + "\n", + "\n", + "def detect_anion_vacancy(cif_name, summary_df, summary_index=None):\n", + " \"\"\"\n", + " Whether the fractional occupancy is on the anion sublattice alone.\n", + "\n", + " v1.2.2: code 2.6, reserved since the first version and assignable now\n", + " that MaplePy v1.3.3 writes `partial_sublattice`. Anion-only, not 'both':\n", + " a structure with cation disorder as well is a mean-field result for more\n", + " than one reason and belongs in 2.3.\n", + " \"\"\"\n", + " where = _summary_field(cif_name, summary_df, 'partial_sublattice',\n", + " summary_index)\n", + " return None if where is None else where == 'anion'\n", + "\n", + "\n", + "def classify_additivity(df_add, results_df, summary_df,\n", + " threshold_additive=ADDITIVE_THRESHOLD_PCT):\n", " \"\"\"\n", " Assign a tiered numeric classification to each structure based on\n", " its additivity residual and metadata.\n", @@ -884,6 +1479,10 @@ " ----------\n", " df_add : DataFrame\n", " Output from batch_additivity(), one row per structure.\n", + " results_df, summary_df : DataFrame\n", + " MaplePy's per-site and per-structure output. v1.1: these were read\n", + " as free variables from the notebook namespace, so re-running the\n", + " cells out of order classified against a stale frame silently.\n", " threshold_additive : float\n", " Residual threshold (%) below which a structure is classified\n", " as additive. Default 1.0 (Hoppe criterion).\n", @@ -897,24 +1496,51 @@ "\n", " Notes\n", " -----\n", - " Priority order follows ascending code number. A structure that\n", - " could trigger both 2.1 and 2.3 receives 2.1 (the lower code).\n", - " Additive status is checked first: delta < threshold -> additive, stop.\n", + " v1.2.9: the order is the one in the header of this cell, not\n", + " ascending code number: Tier 1; then 2.7 and 2.5 whatever the\n", + " residual; then Additive; then 2.1, 2.6, 2.3, 2.4; then 3.1. The\n", + " first that applies is assigned.\n", " \"\"\"\n", " df = df_add.copy()\n", + " # v1.2.4: two indexes, built once, for every lookup below.\n", + " _ridx = index_by_cif(results_df) if len(results_df) else None\n", + " _sidx = index_by_cif(summary_df) if len(summary_df) else None\n", " df['classification'] = ''\n", " df['classification_tier'] = 0\n", " df['classification_label'] = ''\n", + " df['hopper_version'] = HOPPER_VERSION\n", + " df['missing_binary_reason'] = ''\n", + "\n", + " # v1.2.1: say when a test cannot run. Against CSVs written before MaplePy\n", + " # v1.3.2 there is no geometry column, and a split-site structure would\n", + " # then be classified on whatever else it trips - which is how all four of\n", + " # them came to be called oxygen non-stoichiometry.\n", + " for _col, _tests in (('geometry_flag', 'the split-site test (2.7) and '\n", + " 'the short-contact half of 2.5'),\n", + " ('partial_sublattice', 'the anion-vacancy test (2.6)')):\n", + " if _col not in summary_df.columns:\n", + " print(f\" NOTE: no {_col} column in the summary. These CSVs were \"\n", + " f\"written by MaplePy before v1.3.3, so {_tests} did not \"\n", + " f\"run.\")\n", "\n", " for idx, row in df.iterrows():\n", "\n", - " # ── Code 1.1: missing binary reference ──────────────────────\n", - " # Decomposition could not complete because one or more binary\n", - " # oxide components are absent from the reference table.\n", - " if not row['success'] and row['missing_binaries']:\n", - " df.at[idx, 'classification'] = '1.1'\n", + " # ── Codes 1.1, 1.3, 1.4: the decomposition lacked a binary ──\n", + " # v1.2.3: three findings, not one. Which of them is decided by\n", + " # classify_missing_binaries, from the rounding evidence where\n", + " # there is any and from the registry where there is not.\n", + " if not row['success'] and as_missing_list(\n", + " row['missing_binaries']):\n", + " _code, _why = classify_missing_binaries(row['missing_binaries'])\n", + " df.at[idx, 'classification'] = _code\n", " df.at[idx, 'classification_tier'] = 1\n", - " df.at[idx, 'classification_label'] = _label_for_code('1.1')\n", + " df.at[idx, 'classification_label'] = (\n", + " f'{_label_for_code(_code)} ({_why})' if _code == '1.1'\n", + " and 'UNCLASSIFIED' in _why else _label_for_code(_code))\n", + " df.at[idx, 'missing_binary_reason'] = _why\n", + " if 'UNCLASSIFIED' in _why:\n", + " print(f\" NOTE: {row['source_cif']} asks for a binary that is \"\n", + " f\"not in MISSING_BINARY_STATUS - {_why}\")\n", " continue\n", "\n", " # Catch-all for other decomposition failures (should not occur\n", @@ -936,14 +1562,37 @@ " df.at[idx, 'classification_label'] = 'Additive'\n", " continue\n", "\n", - " # ── Code 2.5: Wyckoff site mis-assignment ──────────────────\n", - " # B-site at 4a instead of 4b in Pnma perovskites. Must be\n", - " # checked before Additive because DyCrO3 138222 passes the 1%\n", - " # threshold by coincidence despite having the structural error.\n", - " if detect_structural_coordinate_error(row['source_cif'], df_results, df_summary):\n", + " # ── Code 2.7: split-site disorder model ────────────────────\n", + " # Checked before Additive, like 2.5: a structure whose two\n", + " # half-occupied sites are 0.03 A apart is not additive when its\n", + " # residual lands under 1%, it is unmeasured. MaplePy v1.3.2\n", + " # flags these; see its SPLIT_SITE_ANG for the tolerance.\n", + " if detect_split_site(row['source_cif'], summary_df, _sidx):\n", + " df.at[idx, 'classification'] = '2.7'\n", + " df.at[idx, 'classification_tier'] = 2\n", + " df.at[idx, 'classification_label'] = _label_for_code('2.7')\n", + " continue\n", + "\n", + " # ── Code 2.5: structural coordinate error ──────────────────\n", + " # Two detectors, either sufficient, and the label says which\n", + " # found it. The CV test sees a B-site at 4a instead of 4b in a\n", + " # 20-site Pnma cell; the distance test sees any contact below\n", + " # SHORT_CONTACT_ANG anywhere.\n", + " #\n", + " # Both are checked before Additive, because DyCrO3 138222 passes\n", + " # the 1% threshold by coincidence despite the Wyckoff error and\n", + " # NdFeO3 passes it with two atoms 1.507 A apart.\n", + " _cv = detect_structural_coordinate_error(\n", + " row['source_cif'], results_df, summary_df,\n", + " results_index=_ridx, summary_index=_sidx)\n", + " _short = detect_short_contact(row['source_cif'], summary_df, _sidx)\n", + " if _cv or _short:\n", + " _how = ('O-site MAPLE CV and short contact' if _cv and _short\n", + " else 'short contact' if _short else 'O-site MAPLE CV')\n", " df.at[idx, 'classification'] = '2.5'\n", " df.at[idx, 'classification_tier'] = 2\n", - " df.at[idx, 'classification_label'] = _label_for_code('2.5')\n", + " df.at[idx, 'classification_label'] = (\n", + " f\"{_label_for_code('2.5')} ({_how})\")\n", " continue\n", " \n", " # ── Additive: delta < threshold ─────────────────────────────\n", @@ -971,14 +1620,27 @@ " df.at[idx, 'classification_label'] = _label_for_code('2.1')\n", " continue\n", "\n", - " # ── Code 2.2: Z = 1 metadata artefact ──────────────────────\n", - " # pymatgen compositional reduction gives Z = 1, inflating\n", - " # MAPLE per formula unit. All Z = 1 structures are flagged\n", - " # conservatively; genuine Z = 1 cases are rare in ICSD data.\n", - " if row['Z'] == 1:\n", - " df.at[idx, 'classification'] = '2.2'\n", + " # ── Code 2.2: defined, and unreachable from a MaplePy result ──\n", + " # There was a branch here assigning 2.2 to every Z = 1 structure,\n", + " # written when composition-derived Z made Z = 1 a reliable sign of\n", + " # an artefact. MaplePy v1.1 derives Z from the site counts, the\n", + " # population fell 107 -> 2, and the two survivors are cubic\n", + " # perovskites whose Z really is 1. So no branch assigns 2.2 here:\n", + " # a Z = 1 structure from MaplePy is classified on its residual like\n", + " # any other. The CODE stays in the registry, because the artefact is\n", + " # real for any tool that reads Z from the CIF or trusts a\n", + " # compositional reduction, and it is reported as zero rather than\n", + " # omitted.\n", + "\n", + " # ── Code 2.6: anion vacancy disorder ───────────────────────\n", + " # Fractional occupancy on the anion sublattice alone: an\n", + " # oxygen-deficient refinement. Tested before 2.3 because it is\n", + " # the more specific description of the same structure, and\n", + " # before 2.4 because it says WHY the oxygen does not balance.\n", + " if detect_anion_vacancy(row['source_cif'], summary_df, _sidx):\n", + " df.at[idx, 'classification'] = '2.6'\n", " df.at[idx, 'classification_tier'] = 2\n", - " df.at[idx, 'classification_label'] = _label_for_code('2.2')\n", + " df.at[idx, 'classification_label'] = _label_for_code('2.6')\n", " continue\n", "\n", " # ── Code 2.3: disorder / mean-field approximation ───────────\n", @@ -1014,7 +1676,23 @@ "\n", "\n", "# ── Classify ─────────────────────────────────────────────────────────────────\n", - "df_classified = classify_additivity(df_additivity)\n", + "df_classified = classify_additivity(df_additivity, df_results, df_summary)\n", + "\n", + "# v1.1: the 2.5 population, counted from the data rather than from a string.\n", + "_n25 = int((df_classified['classification'] == '2.5').sum())\n", + "# v1.2.4: the same question as before - how many structures the screen\n", + "# COULD test, which is not the same as how many the classifier reached,\n", + "# since a structure classified 1.3 or 2.7 never gets to the 2.5 branch.\n", + "# So the loop stays, and the indexes make it cost 0.1 s instead of 3.5.\n", + "_ridx_screen = index_by_cif(df_results)\n", + "_sidx_screen = index_by_cif(df_summary)\n", + "_tested = sum(1 for _c in df_classified['source_cif']\n", + " if detect_structural_coordinate_error(\n", + " _c, df_results, df_summary,\n", + " results_index=_ridx_screen,\n", + " summary_index=_sidx_screen) is not None)\n", + "print(f' coordinate-error screen: {_n25} flagged of {_tested} testable '\n", + " f'({len(df_classified)} structures in the run)')\n", "\n", "# ── Summary by tier ──────────────────────────────────────────────────────────\n", "print(\"Classification summary\")\n", @@ -1031,16 +1709,21 @@ "\n", "# Code-level summary\n", "print(\"Breakdown by classification code:\")\n", - "for code in ['Additive', '1.1', '2.1', '2.2', '2.3', '2.4', '2.5', '3.1']:\n", + "for code in CODE_ORDER:\n", " subset = df_classified[df_classified['classification'] == code]\n", " if len(subset) > 0:\n", " label = subset['classification_label'].iloc[0]\n", " print(f\" {code:10s} {label:40s} {len(subset):5d}\")\n", "print(\"=\" * 65)\n", + "_pop = additivity_population(df_classified)\n", + "print(f\" residual population: {len(_pop)} of {len(df_classified)} \"\n", + " f\"(decomposition complete), of which \"\n", + " f\"{n_classified_additive(df_classified)} classified additive at \"\n", + " f\"delta < {ADDITIVE_THRESHOLD_PCT:g}%\")\n", "print()\n", "\n", "# ── Show each classification group ──────────────────────────────────────────\n", - "for code in ['Additive', '1.1', '2.1', '2.2', '2.3', '2.4', '2.5', '3.1']:\n", + "for code in CODE_ORDER:\n", " subset = df_classified[df_classified['classification'] == code]\n", " if len(subset) > 0:\n", " label = subset['classification_label'].iloc[0]\n", @@ -1069,11 +1752,7 @@ "cell_type": "code", "execution_count": null, "id": "356fc163", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 5a. Additivity Residual Histogram (Key Paper Figure)\n", @@ -1096,20 +1775,32 @@ "CLASSIFICATION_COLOURS = {\n", " 'Additive': SHEFFIELD['pastel_green'],\n", " '1.1': SHEFFIELD['pale_violet'],\n", + " '1.2': SHEFFIELD['aqua'],\n", + " '1.3': SHEFFIELD['peak_green'],\n", + " '1.4': SHEFFIELD['spearmint'],\n", " '2.1': SHEFFIELD['coral'],\n", " '2.2': SHEFFIELD['peach'],\n", " '2.3': SHEFFIELD['powder_violet'],\n", " '2.4': SHEFFIELD['flamingo'],\n", " '2.5': SHEFFIELD['brand_violet'],\n", + " '2.6': SHEFFIELD['powder_blue'],\n", + " '2.7': SHEFFIELD['midnight'],\n", " '3.1': SHEFFIELD['teal'],\n", "}\n", "\n", "CLASSIFICATION_LABELS = {\n", - " 'Additive': r'Additive ($\\Delta$ < 1%)',\n", + " 'Additive': rf'Additive ($\\Delta$ < {ADDITIVE_THRESHOLD_PCT:g}%)',\n", + " '1.1': '1.1 Table incomplete',\n", + " '1.2': '1.2 Upstream failure',\n", + " '1.3': '1.3 No binary end-member',\n", + " '1.4': '1.4 Charge is not a state',\n", " '2.1': '2.1 Oxi state error',\n", - " '2.2': '2.2 Z = 1 artefact',\n", + " '2.2': '2.2 Z = 1 artefact (retired)',\n", + " '2.3': '2.3 Disorder / mean-field',\n", " '2.4': '2.4 O non-stoichiometry',\n", - " '2.5': '2.5 Wyckoff site error',\n", + " '2.5': '2.5 Coordinate error',\n", + " '2.6': '2.6 Anion vacancy',\n", + " '2.7': '2.7 Split-site model',\n", " '3.1': '3.1 Genuine violation',\n", "}\n", "\n", @@ -1128,7 +1819,12 @@ " Lighter pastel_green for additive structures so the failure codes\n", " (warm colours + teal) stand out.\n", " \"\"\"\n", - " df_plot = df_classified[df_classified['delta_pct'].notna()].copy()\n", + " # v1.2.1: the same population the classifier reports, from the same\n", + " # function. This selected on delta.notna() alone, which included the 30\n", + " # structures whose binary sum was incomplete (their delta is None now)\n", + " # and produced a \"within 1%\" count one larger than the classifier's\n", + " # additive count, on the same run.\n", + " df_plot = additivity_population(df_classified).copy()\n", "\n", " if len(df_plot) == 0:\n", " print(\"No structures with computed residuals to plot.\")\n", @@ -1139,10 +1835,21 @@ " gridspec_kw={'width_ratios': [3, 2], 'wspace': 0.25}\n", " )\n", "\n", - " # Stacking order: additive at the back, then by code\n", - " code_order = ['Additive', '3.1', '2.4', '2.5', '2.2', '2.1']\n", + " # Stacking order: additive at the back, then by code.\n", + " #\n", + " # v1.2.1: the old order here omitted 1.1 and 2.3, so those structures\n", + " # were counted in the annotation and drawn in neither panel. Every code\n", + " # present is drawn now, and a code with no colour raises rather than\n", + " # disappearing.\n", + " code_order = ['Additive'] + [c for c in CODE_ORDER if c != 'Additive'][::-1]\n", " codes_present = [c for c in code_order\n", " if c in df_plot['classification'].values]\n", + " _uncoloured = [c for c in df_plot['classification'].unique()\n", + " if c not in CLASSIFICATION_COLOURS]\n", + " if _uncoloured:\n", + " raise KeyError(f'no colour for classification code(s) {_uncoloured}: '\n", + " f'add them to CLASSIFICATION_COLOURS and '\n", + " f'CLASSIFICATION_LABELS rather than plotting without')\n", " colours = [CLASSIFICATION_COLOURS[c] for c in codes_present]\n", " labels = [CLASSIFICATION_LABELS[c] for c in codes_present]\n", "\n", @@ -1156,10 +1863,11 @@ " ax_main.hist(data_main, bins=bins_main, color=colours, label=labels,\n", " edgecolor='white', linewidth=0.5, stacked=True)\n", "\n", - " # Hoppe 1% threshold\n", - " ax_main.axvline(x=1.0, color=SHEFFIELD['coral'], linestyle='--',\n", - " linewidth=1.5, alpha=0.8, zorder=5)\n", - " ax_main.text(1.12, ax_main.get_ylim()[1] * 0.95, \"Hoppe 1%\",\n", + " # Hoppe's threshold, from the constant the classifier uses\n", + " ax_main.axvline(x=ADDITIVE_THRESHOLD_PCT, color=SHEFFIELD['coral'],\n", + " linestyle='--', linewidth=1.5, alpha=0.8, zorder=5)\n", + " ax_main.text(1.12, ax_main.get_ylim()[1] * 0.95,\n", + " f\"Hoppe {ADDITIVE_THRESHOLD_PCT:g}%\",\n", " fontsize=10, color=SHEFFIELD['coral'], va='top')\n", "\n", " ax_main.set_xlabel(r'Additivity residual, $\\Delta$ / %')\n", @@ -1170,12 +1878,13 @@ " ax_main.set_xlim(-0.1, 5.2)\n", " ax_main.legend(frameon=False, fontsize=9, loc='upper right')\n", "\n", - " # Annotation: fraction within 1%\n", - " n_within = (df_plot['delta_pct'] < 1.0).sum()\n", + " # Annotation: the classifier's own additive count, not a second count\n", + " # made here against the same threshold over a different population.\n", + " n_within = n_classified_additive(df_classified)\n", " n_total = len(df_plot)\n", " ax_main.text(0.97, 0.12,\n", " f'{n_within}/{n_total} ({100*n_within/n_total:.0f}%)\\n'\n", - " r'within $\\pm$1%',\n", + " 'classified additive',\n", " transform=ax_main.transAxes, ha='right', va='bottom',\n", " fontsize=10, color=SHEFFIELD['dark_violet'], style='italic')\n", "\n", @@ -1221,11 +1930,7 @@ "cell_type": "code", "execution_count": null, "id": "bb9ce9d2-6b17-484d-846b-3a18975b204c", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 5b. Madelung Factor Clustering (Key Paper Figure)\n", @@ -1272,8 +1977,10 @@ "]\n", "\n", "# ── Tier-to-marker mapping ──────────────────────────────────────────────\n", - "tier_map = {'Additive': 0, '1.1': 1, '2.1': 2, '2.2': 2,\n", - " '2.3': 2, '2.4': 2, '2.5': 2, '3.1': 3}\n", + "# v1.2.7: was a hand-written map missing 1.3, 1.4, 2.6 and 2.7, so those\n", + "# structures were dropped from every scatter. _tier_for_code has been in\n", + "# cell 12 the whole time and reads the registry.\n", + "tier_map = {c: _tier_for_code(c) for c in CODE_ORDER}\n", "\n", "\n", "def _plot_scatter_by_tier(ax, data, size_map, alpha_additive=0.5):\n", @@ -1283,7 +1990,9 @@ " if len(subset) == 0:\n", " continue\n", " if tier == 2:\n", - " for code in ['2.2', '2.4', '2.5', '2.1']:\n", + " # v1.2.7: every tier-2 code in the registry, not four of seven\n", + " for code in [c for c in CODE_ORDER\n", + " if _tier_for_code(c) == 2]:\n", " sub = subset[subset['classification'] == code]\n", " if len(sub) == 0:\n", " continue\n", @@ -1358,10 +2067,24 @@ " f\"d_ref [{pb_dref_min:.2f}, {pb_dref_max:.2f}]\")\n", "\n", " # ── Build figure ────────────────────────────────────────────────\n", - " fig, (ax_a, ax_b) = plt.subplots(\n", - " 1, 2, figsize=(14, 6.5),\n", - " gridspec_kw={'width_ratios': [3, 2], 'wspace': 0.28}\n", - " )\n", + " # v1.2.7: panel (b) zoomed the Z = 1 cluster. With Z derived from site\n", + " # multiplicities that cluster is empty, and the panel was drawing an\n", + " # empty axis titled 'n = 0' next to a dashed box around nothing. Decide\n", + " # from the data: no cluster, no panel.\n", + " cluster_b = ok[(ok['madelung_factor'] >= pb_mf_min) &\n", + " (ok['madelung_factor'] <= pb_mf_max) &\n", + " (ok['d_ref_ang'] >= pb_dref_min) &\n", + " (ok['d_ref_ang'] <= pb_dref_max)].copy()\n", + "\n", + " if len(cluster_b) == 0:\n", + " print('No high-MF cluster: panel (b) omitted.')\n", + " fig, ax_a = plt.subplots(1, 1, figsize=(9, 6.5))\n", + " ax_b = None\n", + " else:\n", + " fig, (ax_a, ax_b) = plt.subplots(\n", + " 1, 2, figsize=(14, 6.5),\n", + " gridspec_kw={'width_ratios': [3, 2], 'wspace': 0.28}\n", + " )\n", "\n", " # ── Panel (a): all structures ───────────────────────────────────\n", " _plot_scatter_by_tier(ax_a, ok, {0: 18, 2: 22, 3: 22})\n", @@ -1403,57 +2126,47 @@ " gap_y = (mf_gap_lower + mf_gap_upper) / 2\n", " ax_a.axhline(y=gap_y, color='grey', linestyle=':', linewidth=0.8, alpha=0.4)\n", "\n", - " # Box showing panel (b) region\n", - " rect = Rectangle((pb_dref_min, pb_mf_min),\n", + " # Box showing panel (b) region, only if there is a panel (b)\n", + " if ax_b is not None:\n", + " rect = Rectangle((pb_dref_min, pb_mf_min),\n", " pb_dref_max - pb_dref_min,\n", " pb_mf_max - pb_mf_min,\n", " linewidth=1.0, edgecolor=SHEFFIELD['dark_violet'],\n", " facecolor='none', linestyle='--', alpha=0.6, zorder=5)\n", - " ax_a.add_patch(rect)\n", - " ax_a.text(pb_dref_max + 0.01, pb_mf_max, '(b)',\n", - " fontsize=9, color=SHEFFIELD['dark_violet'], va='top',\n", - " fontweight='bold')\n", + " ax_a.add_patch(rect)\n", + " ax_a.text(pb_dref_max + 0.01, pb_mf_max, '(b)',\n", + " fontsize=9, color=SHEFFIELD['dark_violet'], va='top',\n", + " fontweight='bold')\n", "\n", " ax_a.set_xlabel('$d_\\\\mathrm{ref}$ / Å')\n", " ax_a.set_ylabel('Madelung factor')\n", - " ax_a.set_title('(a)', loc='left', fontweight='bold')\n", + " if ax_b is not None:\n", + " ax_a.set_title('(a)', loc='left', fontweight='bold')\n", " ax_a.spines['top'].set_visible(False)\n", " ax_a.spines['right'].set_visible(False)\n", "\n", + " # v1.2.7: built from the registry, and only for codes that actually\n", + " # appear in this dataset. The hand-written version listed 2.2, which is\n", + " # now always empty, and omitted 1.3, 1.4, 2.3, 2.6 and 2.7, which are not.\n", + " _present = [c for c in CODE_ORDER if (ok['classification'] == c).any()]\n", " legend_elements = [\n", - " Line2D([0], [0], marker='o', color='w',\n", - " markerfacecolor=SHEFFIELD['pastel_green'],\n", - " markeredgecolor='white', markersize=7,\n", - " label=r'Additive ($\\Delta$ < 1%)'),\n", - " Line2D([0], [0], marker='s', color='w',\n", - " markerfacecolor=SHEFFIELD['coral'],\n", - " markeredgecolor='white', markersize=7,\n", - " label='2.1 Oxi state error'),\n", - " Line2D([0], [0], marker='s', color='w',\n", - " markerfacecolor=SHEFFIELD['peach'],\n", - " markeredgecolor='white', markersize=7,\n", - " label='2.2 Z = 1 artefact'),\n", - " Line2D([0], [0], marker='s', color='w',\n", - " markerfacecolor=SHEFFIELD['flamingo'],\n", - " markeredgecolor='white', markersize=7,\n", - " label='2.4 O non-stoich.'),\n", - " Line2D([0], [0], marker='s', color='w',\n", - " markerfacecolor=SHEFFIELD['brand_violet'],\n", - " markeredgecolor='white', markersize=7,\n", - " label='2.5 Wyckoff site error'),\n", - " Line2D([0], [0], marker='D', color='w',\n", - " markerfacecolor=SHEFFIELD['teal'],\n", - " markeredgecolor='white', markersize=6,\n", - " label='3.1 Genuine violation'),\n", + " Line2D([0], [0],\n", + " marker={0: 'o', 3: 'D'}.get(_tier_for_code(c), 's'),\n", + " color='w', markerfacecolor=CLASSIFICATION_COLOURS[c],\n", + " markeredgecolor='white', markersize=7 if c != '3.1' else 6,\n", + " label=CLASSIFICATION_LABELS[c])\n", + " for c in _present\n", " ]\n", " ax_a.legend(handles=legend_elements, frameon=False, fontsize=8,\n", " loc='upper left', handletextpad=0.5)\n", "\n", - " # ── Panel (b): zoomed cluster ───────────────────────────────────\n", - " cluster_b = ok[(ok['madelung_factor'] >= pb_mf_min) &\n", - " (ok['madelung_factor'] <= pb_mf_max) &\n", - " (ok['d_ref_ang'] >= pb_dref_min) &\n", - " (ok['d_ref_ang'] <= pb_dref_max)].copy()\n", + " # ── Panel (b): zoomed cluster, when there is one ────────────────\n", + " if ax_b is None:\n", + " fig.tight_layout()\n", + " if save_path:\n", + " fig.savefig(save_path)\n", + " print(f' saved {save_path}')\n", + " return fig\n", "\n", " print(f\"Panel (b): {len(cluster_b)} structures in window\")\n", " _plot_scatter_by_tier(ax_b, cluster_b, {0: 35, 2: 40, 3: 40},\n", @@ -1546,11 +2259,7 @@ "cell_type": "code", "execution_count": null, "id": "00fac77e", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 6. Perovskite-Specific Analysis\n", @@ -1569,7 +2278,7 @@ "\n", "# Classification breakdown for perovskites\n", "print(f\"\\n Classification breakdown:\")\n", - "for code in ['Additive', '1.1', '2.1', '2.2', '2.3', '2.4', '3.1']:\n", + "for code in CODE_ORDER:\n", " n = (df_perov['classification'] == code).sum()\n", " if n > 0:\n", " print(f\" {code:10s} {n}\")\n", @@ -1598,11 +2307,7 @@ "cell_type": "code", "execution_count": null, "id": "55dda9cf", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 7. Pyrochlore-Specific Analysis\n", @@ -1620,7 +2325,7 @@ "\n", "# Classification breakdown for pyrochlores\n", "print(f\"\\n Classification breakdown:\")\n", - "for code in ['Additive', '1.1', '2.1', '2.2', '2.3', '2.4', '3.1']:\n", + "for code in CODE_ORDER:\n", " n = (df_pyro['classification'] == code).sum()\n", " if n > 0:\n", " print(f\" {code:10s} {n}\")\n", @@ -1664,11 +2369,7 @@ "cell_type": "code", "execution_count": null, "id": "7fa46a81", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 8. Export Results\n", @@ -1737,10 +2438,12 @@ "\n", "### Binary reference MAPLE values\n", "\n", - "The fallback table uses approximate values that **must be replaced**\n", - "with MaplePy batch results on ICSD CIFs before publication.\n", - "Values marked \"Estimated\" are placeholders; prioritise computing\n", - "these from actual structures.\n", + "Hopper reads the released table, `binary_oxide_maple_reference.json`;\n", + "the inline table is its fallback, and the two are checked against each\n", + "other. 23 values are estimates with no source, and the source recorded\n", + "for Cu$_2$O does not reproduce. They are kept so that results can be\n", + "reproduced, and every decomposition that uses one names it\n", + "(`estimated_binaries`, v1.2.9). Replace them as sources become available.\n", "\n", "### Non-integer oxidation states\n", "\n", @@ -1759,21 +2462,17 @@ "\n", "### Z = 1 problem\n", "\n", - "Code 2.2 failures arise from pymatgen’s compositional reduction\n", - "algorithm rather than from the MAPLE calculation itself. The\n", - "fix (extracting `_cell_formula_units_Z` from the CIF header) is\n", - "in progress in MaplePy and should be applied upstream." + "Code 2.2 failures arise wherever *Z* is taken from compositional\n", + "reduction. MaplePy has derived *Z* from the site multiplicities since\n", + "v1.1, so 2.2 cannot arise from a MaplePy run; the code is kept for\n", + "output from other calculators." ] }, { "cell_type": "code", "execution_count": null, "id": "4089a1f7-e76b-4f42-8133-19452b8b8774", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 10. Additional Paper Figures\n", @@ -2021,27 +2720,13 @@ " Figure 7: Classification waterfall — horizontal stacked bar showing\n", " how structures are sorted into classification tiers.\n", " \"\"\"\n", - " code_order = ['Additive', '1.1', '2.1', '2.2', '2.3', '2.4', '2.5', '3.1']\n", - " code_labels = {\n", - " 'Additive': 'Additive\\n(Δ < 1%)',\n", - " '1.1': '1.1\\nMissing\\nbinary ref.',\n", - " '2.1': '2.1\\nOxi state\\nerror',\n", - " '2.2': '2.2\\nZ = 1\\nartefact',\n", - " '2.3': '2.3\\nDisorder /\\nmean-field',\n", - " '2.4': '2.4\\nO non-\\nstoich.',\n", - " '2.5': '2.5\\nStructural\\ncoord. error',\n", - " '3.1': '3.1\\nGenuine\\nviolation',\n", - " }\n", - " code_colours = {\n", - " 'Additive': SHEFFIELD['pastel_green'],\n", - " '1.1': SHEFFIELD['pale_violet'],\n", - " '2.1': SHEFFIELD['coral'],\n", - " '2.2': SHEFFIELD['peach'],\n", - " '2.3': SHEFFIELD['powder_violet'],\n", - " '2.4': SHEFFIELD['flamingo'],\n", - " '2.5': SHEFFIELD['brand_violet'],\n", - " '3.1': SHEFFIELD['teal'],\n", - " }\n", + " code_order = CODE_ORDER\n", + " # v1.2.7: was a hand-written dict of seven codes, which raised\n", + " # KeyError on the first structure carrying any of the other five.\n", + " code_labels = CLASSIFICATION_LABELS\n", + " # v1.2.7: was a hand-written dict of seven codes, which raised\n", + " # KeyError on the first structure carrying any of the other five.\n", + " code_colours = CLASSIFICATION_COLOURS\n", "\n", " counts = []\n", " codes_present = []\n", @@ -2053,7 +2738,44 @@ "\n", " total = sum(counts)\n", "\n", - " fig, ax = plt.subplots(figsize=(10, 3.5))\n", + " # ── Plan the code labels before the figure exists ───────────────────\n", + " #\n", + " # v1.2.8: rows used to alternate on index parity, which overprints as soon\n", + " # as three narrow slices are adjacent. A label now takes the highest row\n", + " # where it clears the label already there, measured from its own width,\n", + " # and drops a row only when it has to. Planning before the figure is made\n", + " # lets the figure be tall enough for however many rows that needs, rather\n", + " # than clipping them into a fixed height.\n", + " #\n", + " # CHAR_W is one character at fontsize 8 in data units: 8 pt is about\n", + " # 4.8 pt wide, 0.067 in, and the axis is 10 in across spanning `total`.\n", + " # ROW_H must exceed the drawn text height or rows collide even when the\n", + " # horizontal test passes, which is exactly how the first attempt failed.\n", + " CHAR_W = total * 0.0067\n", + " PAD = total * 0.008\n", + " ROW_H = 0.24\n", + "\n", + " _rows, _plan = [], []\n", + " left = 0\n", + " for code, count in zip(codes_present, counts):\n", + " cx = left + count / 2\n", + " label = 'Add.' if code == 'Additive' else code\n", + " if count < 10: # narrow: carry the count in the label\n", + " label = f'{label} ({count})'\n", + " half_w = CHAR_W * len(label) / 2\n", + " row = 0\n", + " while row < len(_rows) and cx - _rows[row][0] < half_w + _rows[row][1] + PAD:\n", + " row += 1\n", + " if row == len(_rows):\n", + " _rows.append((cx, half_w))\n", + " else:\n", + " _rows[row] = (cx, half_w)\n", + " _plan.append((label, cx, row))\n", + " left += count\n", + " n_label_rows = len(_rows)\n", + "\n", + " fig, ax = plt.subplots(\n", + " figsize=(10, 3.5 + 0.45 * max(0, n_label_rows - 2)))\n", "\n", " left = 0\n", " for code, count in zip(codes_present, counts):\n", @@ -2075,26 +2797,20 @@ " ax.text(cx, 0, f'{count}',\n", " ha='center', va='center', fontsize=8,\n", " fontweight='bold', color=text_colour)\n", - " else:\n", - " ax.text(cx, 0.45, f'{count}',\n", - " ha='center', va='bottom', fontsize=8,\n", - " color=code_colours[code], fontweight='bold')\n", + " # v1.2.8: a narrow slice used to print its count above the bar,\n", + " # where it collided with the tier brackets at y = 0.48. The count\n", + " # goes into the label below instead, so each slice has exactly one\n", + " # piece of text attached to it.\n", "\n", " left += count\n", "\n", - " # Category labels below — code only, staggered with leader lines\n", - " left = 0\n", - " for i, (code, count) in enumerate(zip(codes_present, counts)):\n", - " if count > 0:\n", - " cx = left + count / 2\n", - " y_pos = -0.38 if i % 2 == 0 else -0.58\n", - " label = code if code != 'Additive' else 'Add.'\n", - " ax.annotate(label, xy=(cx, -0.30), xytext=(cx, y_pos),\n", - " ha='center', va='top', fontsize=8,\n", - " fontweight='bold', color=SHEFFIELD['midnight'],\n", - " arrowprops=dict(arrowstyle='-', color='grey',\n", - " lw=0.6, alpha=0.5))\n", - " left += count\n", + " # ── Category labels below, one per slice ────────────────────────────\n", + " for label, cx, row in _plan:\n", + " ax.annotate(label, xy=(cx, -0.30), xytext=(cx, -0.38 - ROW_H * row),\n", + " ha='center', va='top', fontsize=8,\n", + " fontweight='bold', color=SHEFFIELD['midnight'],\n", + " arrowprops=dict(arrowstyle='-', color='grey',\n", + " lw=0.6, alpha=0.5))\n", "\n", " # Tier brackets above\n", " tier_groups = {}\n", @@ -2127,7 +2843,9 @@ " fontsize=8, color=colour, fontweight='bold')\n", "\n", " ax.set_xlim(-5, total + 5)\n", - " ax.set_ylim(-1.0, 1.0)\n", + " # v1.2.8: deep enough for the rows the declutter actually used, so a\n", + " # crowded dataset is not silently clipped.\n", + " ax.set_ylim(min(-1.0, -0.55 - ROW_H * n_label_rows), 1.0)\n", " ax.set_xlabel(f'Number of structures (total = {total})')\n", " ax.set_yticks([])\n", " ax.spines['top'].set_visible(False)\n", @@ -2181,32 +2899,19 @@ "cell_type": "code", "execution_count": null, "id": "5bf98060-54e1-4446-a55e-8a237db55a34", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { - "display_name": "Python (materials_analysis_env)", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "materials_analysis_env" + "name": "python3" }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.23" + "name": "python" } }, "nbformat": 4, diff --git a/MaplePy.ipynb b/MaplePy.ipynb index ce8de89..abf2d83 100644 --- a/MaplePy.ipynb +++ b/MaplePy.ipynb @@ -17,7 +17,7 @@ "\n", "**Three validation targets (all must pass before research use):**\n", "1. **NaCl** — PMC(Na⁺) = PMC(Cl⁻) = 0.8738, MF = 1.7476 *(Hoppe 1966)*\n", - "2. **TiO₂ polymorphs** — rutile/anatase MAPLE within ~10 kcal/mol *(Hoppe 1995, Table 5)*\n", + "2. **TiO₂ polymorphs** — rutile and anatase each within 50 kcal/mol of Hoppe's values, and within 15 kcal/mol of each other *(Hoppe 1995, Table 5)*\n", "3. **BaTiO₃ additivity** — MAPLE(BaTiO₃) ≈ MAPLE(BaO) + MAPLE(TiO₂), Δ < 1% *(Hoppe 1995, p. 560)*\n", "\n", "---\n", @@ -38,11 +38,7 @@ "cell_type": "code", "execution_count": null, "id": "10d15006", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Run once to install dependencies\n", @@ -53,11 +49,7 @@ "cell_type": "code", "execution_count": null, "id": "b95774bf-a81e-4bcc-a23e-559f46c131ee", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "from pymatgen.core import __version__\n", @@ -68,11 +60,7 @@ "cell_type": "code", "execution_count": null, "id": "cd190078", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "import numpy as np\n", @@ -89,7 +77,132 @@ "# Hoppe uses 331.81 (older constants); modern value is 332.06\n", "MAPLE_FACTOR = 332.06 # Å·kcal/mol\n", "\n", - "print(\"MaplePy loaded.\")\n", + "# ── Tolerances, each named once ────────────────────────────────────────────\n", + "#\n", + "# v1.1: these were previously written twice each, with different values.\n", + "#\n", + "# CHARGE_NEUTRAL_TOL was 0.5 where the CIF's own per-site states are accepted\n", + "# and 0.05 where the result is checked - ten times apart, in one function,\n", + "# neither with a reason. One value, used for both questions: a cell whose\n", + "# charges sum to more than this is not neutral, whoever assigned them.\n", + "# 0.05 e per cell is below the rounding of a single deposited oxidation state\n", + "# and above the floating-point noise of an occupancy-weighted sum.\n", + "CHARGE_NEUTRAL_TOL = 0.05 # e per unit cell\n", + "\n", + "# OCCUPANCY_TOL was 1.05 in the CIF parser and 1.01 in the warning that\n", + "# follows it, so a site at 1.03 was silently accepted and never mentioned.\n", + "# One value: what the parser will accept is what the warning is about.\n", + "OCCUPANCY_TOL = 1.05 # site occupancy sum above which a site is\n", + " # reported as a refinement-quality issue\n", + "\n", + "\n", + "# ── When a site is not fully occupied ──────────────────────────────────────\n", + "#\n", + "# v1.3.2: the disorder test used to ask only whether a site carried more than\n", + "# one species. A single species at occupancy 0.5 is a split-site or\n", + "# vacancy-bearing refinement and is just as much a mean-field approximation,\n", + "# and 12 of 97 probed structures were labelled ordered on that basis.\n", + "#\n", + "# The number is a guard against arithmetic noise, not a scientific cut. On the\n", + "# 97-structure probe the site occupancy sums were 1.000, 0.993, 0.985, 0.950,\n", + "# 0.800, 0.731, 0.500, 0.250 and 0.167: nothing lies between 0.993 and 1.000,\n", + "# so any threshold in that gap classifies identically. Set just below 1 so\n", + "# that a refined deficiency of 0.7% is still called what it is.\n", + "FULL_OCCUPANCY_TOL = 0.995 # site occupancy sum at or above this is full\n", + "\n", + "# ── When two sites are one crystallographic position ───────────────────────\n", + "#\n", + "# v1.3.2: below this separation, two sites are the same position split by a\n", + "# disorder model, and the Ewald sum over them is not an energy. Measured over\n", + "# the 1410-structure dataset, the four structures with any contact under 1 A\n", + "# are at 0.030, 0.160, 0.441 and 0.455 A, and the shortest genuine contact\n", + "# anywhere in the 97-structure probe is 1.008 A - itself a coordinate error.\n", + "# Nothing lies between 0.455 and 1.008, so any threshold in that gap\n", + "# classifies these identically; 0.5 A is well below the shortest real\n", + "# cation-anion distance in any oxide.\n", + "#\n", + "# NOTE this is a FLAG, not a filter. d_min_ang is written for every structure\n", + "# so the cut can be fitted from a full run rather than from four examples.\n", + "SPLIT_SITE_ANG = 0.5 # A, shortest contact below which two sites are\n", + " # taken to be one position, split\n", + "#\n", + "# v1.3.3: CONFIRMED against the whole dataset now that d_min_ang is written\n", + "# for every structure. The band from 0.5 to 1.0 A is EMPTY in both families,\n", + "# and the four structures below 0.5 A are the four this was fitted on.\n", + "\n", + "# ── When a contact is too short to be a bond ───────────────────────────────\n", + "#\n", + "# v1.3.3: a second population, separate from the split sites. 26 perovskites\n", + "# have a shortest contact between 1.0 and 1.6 A, median residual 8 to 13%,\n", + "# median Madelung factor 2.5 against the family's 3.83: coordinate errors.\n", + "# Hopper's 2.5 detector catches 22 of them and structurally cannot see the\n", + "# rest, being a coefficient-of-variation test on 20-site Pnma cells. NdFeO3\n", + "# at 1.507 A was classified ADDITIVE at delta 0.312%.\n", + "#\n", + "# UNLIKE SPLIT_SITE_ANG THERE IS NO GAP HERE. It is a continuum, and this is\n", + "# a judgement rather than a fitted value. Measured, at each candidate cut:\n", + "#\n", + "# threshold flagged already 2.5 newly flagged of those, Additive\n", + "# 1.6 A 26 22 4 1\n", + "# 1.7 A 37 27 10 2\n", + "# 1.75 A 46 29 17 4\n", + "# 1.8 A 63 29 34 17\n", + "#\n", + "# 1.8 A starts taking structures whose short bond is plausible. 1.6 A is\n", + "# below any cation-anion distance these families produce and above every\n", + "# contact in the well-behaved bulk.\n", + "SHORT_CONTACT_ANG = 1.6 # A, shortest contact below which the geometry\n", + " # is reported as unphysical (a judgement)\n", + "\n", + "\n", + "# ── How many CIFs at once ──────────────────────────────────────────────────\n", + "#\n", + "# v1.3.4: every structure is independent and costs about 140 ms of CPU, and the\n", + "# 24 August perovskite run took 22 minutes. Measured on 84 real CIFs on a\n", + "# 2-core container: 10.15 s serial against 7.24 s on two workers, every value\n", + "# identical. Two cores caps that at 2x before pool startup, so on six workers\n", + "# with the startup spread over a full family, expect nearer 5x.\n", + "#\n", + "# 'auto' as many workers as cores, less two, and never more than the\n", + "# number of CIFs\n", + "# 1 serial, which is exactly what v1.3.3 did\n", + "# an int that many workers\n", + "#\n", + "# The serial and parallel paths call the SAME function, process_one_cif, so\n", + "# there is one definition of what processing a CIF means.\n", + "MAPLE_WORKERS = 'auto'\n", + "\n", + "\n", + "# ── The version, named once ────────────────────────────────────────────────\n", + "#\n", + "# v1.3.1: written into every results and summary CSV as a column, so a file\n", + "# on disk says which notebook made it. Three CSVs from three versions in one\n", + "# folder look identical otherwise, and the differences between them have been\n", + "# Z, the data directory and the cell setting.\n", + "MAPLEPY_VERSION = '1.3.6'\n", + "\n", + "\n", + "# ── Where the reference data lives ─────────────────────────────────────────\n", + "#\n", + "# v1.2: data_dir defaulted to '.', which is where the notebook is rather than\n", + "# where its data is. maple_library.json and common_oxidation_states.json sit\n", + "# in data/, so the oxidation-state priority chain silently dropped two levels\n", + "# for anyone whose working directory was the notebook's.\n", + "#\n", + "# Resolved once, here, and reported when it is used. A path given explicitly\n", + "# is checked: asking for a directory that does not exist is a mistake worth\n", + "# hearing about, not a reason to fall back.\n", + "def _default_data_dir():\n", + " for _cand in ('data', '.'):\n", + " if Path(_cand).is_dir() and any(Path(_cand).glob('*.json')):\n", + " return _cand\n", + " return '.'\n", + "\n", + "\n", + "DEFAULT_DATA_DIR = _default_data_dir()\n", + "print(f\" data directory: {Path(DEFAULT_DATA_DIR).resolve()}\")\n", + "\n", + "print(f\"MaplePy {MAPLEPY_VERSION} loaded.\")\n", "print(f\" EV_TO_KCAL_MOL = {EV_TO_KCAL_MOL}\")\n", "print(f\" MAPLE_FACTOR = {MAPLE_FACTOR} Å·kcal/mol (Hoppe 1995 uses 331.81)\")" ] @@ -107,11 +220,7 @@ "cell_type": "code", "execution_count": null, "id": "900d1430", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 1. Core Functions (v3)\n", @@ -119,6 +228,7 @@ "\n", "import re as _re\n", "import json\n", + "import math as _math\n", "import warnings\n", "warnings.filterwarnings('ignore', message='dict interface is deprecated',\n", " category=DeprecationWarning)\n", @@ -170,32 +280,161 @@ " return float(site.specie.oxi_state)\n", "\n", "\n", - "def _is_disordered(structure):\n", - " \"\"\"Check whether any site in the structure has mixed occupancy.\"\"\"\n", + "def _is_anion_site(site):\n", + " \"\"\"\n", + " Whether this site belongs to the anion sublattice.\n", + "\n", + " By oxidation state where the structure has them, and by element where it\n", + " does not: load_structure asks about disorder before the states are\n", + " assigned, and MaplePy's domain is oxides, so oxygen is the anion. Stated\n", + " rather than assumed, because it is an assumption.\n", + " \"\"\"\n", + " try:\n", + " oxi = _site_oxi_state(site)\n", + " if oxi:\n", + " return oxi < 0\n", + " except (AttributeError, TypeError, ValueError):\n", + " pass\n", + " return _site_element(site) == 'O'\n", + "\n", + "\n", + "def _disorder_detail(structure):\n", + " \"\"\"\n", + " What kind of disorder this structure carries, and where: one computation.\n", + "\n", + " v1.3.3: `partial occupancy` was not enough. Making the flag see partial\n", + " occupancy at all (v1.3.2) moved 14 oxygen-deficient refinements out of\n", + " Hopper's oxygen non-stoichiometry class and into its disorder class, which\n", + " describes them less well. Hopper has reserved a code for anion vacancy\n", + " disorder since its first version and could not assign it without knowing\n", + " which sublattice was short.\n", + "\n", + " MaplePy holds the occupancies, so MaplePy answers. Deriving this\n", + " downstream from a reduced formula undercounts split sites, whose two\n", + " half-occupied positions sum to an integer composition.\n", + "\n", + " Returns (kind, sublattice):\n", + " kind 'ordered' | 'mixed occupancy' | 'partial occupancy'\n", + " | 'mixed and partial occupancy'\n", + " sublattice 'none' | 'anion' | 'cation' | 'both'\n", + " \"\"\"\n", + " mixed = False\n", + " partial = set()\n", " for site in structure:\n", " if len(site.species) > 1:\n", - " return True\n", - " return False\n", + " mixed = True\n", + " if sum(site.species.values()) < FULL_OCCUPANCY_TOL:\n", + " partial.add('anion' if _is_anion_site(site) else 'cation')\n", + "\n", + " sublattice = ('none' if not partial else\n", + " 'both' if len(partial) > 1 else\n", + " next(iter(partial)))\n", + "\n", + " if mixed and partial:\n", + " kind = 'mixed and partial occupancy'\n", + " elif mixed:\n", + " kind = 'mixed occupancy'\n", + " elif partial:\n", + " kind = 'partial occupancy'\n", + " else:\n", + " kind = 'ordered'\n", + " return kind, sublattice\n", + "\n", + "\n", + "def _disorder_kind(structure):\n", + " \"\"\"The kind alone. Derived, so there is one computation.\"\"\"\n", + " return _disorder_detail(structure)[0]\n", + "\n", + "\n", + "def _is_disordered(structure):\n", + " \"\"\"True where the mean-field charge approximation is in use.\n", + "\n", + " Derived from _disorder_detail so there is one definition of disorder.\n", + " \"\"\"\n", + " return _disorder_kind(structure) != 'ordered'\n", + "\n", + "\n", + "def _shortest_contact(structure):\n", + " \"\"\"\n", + " The shortest interatomic distance in the cell, and the pair that makes it.\n", + "\n", + " Returns (d_ang, label_i, label_j). Any pair, not cation-anion: the fault\n", + " this exists to catch is a same-element split site, which d_ref cannot see\n", + " because d_ref only looks across the cation-anion boundary.\n", + " \"\"\"\n", + " if len(structure) < 2:\n", + " return float('inf'), None, None\n", + " dm = structure.distance_matrix.copy()\n", + " np.fill_diagonal(dm, np.inf)\n", + " i, j = np.unravel_index(np.argmin(dm), dm.shape)\n", + " return (float(dm[i, j]), _site_element(structure[int(i)]),\n", + " _site_element(structure[int(j)]))\n", + "\n", + "\n", + "def _geometry_status(structure):\n", + " \"\"\"\n", + " Whether the geometry can carry a Madelung energy, as a sentence.\n", + "\n", + " v1.3.2: MaplePy had no geometry test. Four structures in the 1410-entry\n", + " dataset put two fractionally occupied sites within half an angstrom of\n", + " each other, and their Ewald sums came out up to ten times the family\n", + " median while being reported as ordinary results.\n", + "\n", + " v1.3.3: two thresholds, because the measured distribution has two\n", + " populations - split sites below 0.5 A and coordinate errors between 1.0\n", + " and 1.6 A, with nothing at all in between. See SPLIT_SITE_ANG and\n", + " SHORT_CONTACT_ANG for both, and for which of them is a judgement.\n", + "\n", + " FLAG, KEEP, REPORT: this never drops a structure and never changes a\n", + " number. It returns (d_min, flag, status): the flag for Hopper, which\n", + " should not be matching on the prefix of a sentence, and the sentence for\n", + " whoever reads the CSV.\n", + " \"\"\"\n", + " d_min, el_i, el_j = _shortest_contact(structure)\n", + " if d_min < SPLIT_SITE_ANG:\n", + " return d_min, 'split_site', (\n", + " f'split site: {el_i}-{el_j} contact {d_min:.3f} A, below '\n", + " f'{SPLIT_SITE_ANG} A - the Ewald sum over these two sites is '\n", + " f'not an energy')\n", + " if d_min < SHORT_CONTACT_ANG:\n", + " return d_min, 'short_contact', (\n", + " f'short contact: {el_i}-{el_j} at {d_min:.3f} A, below '\n", + " f'{SHORT_CONTACT_ANG} A - shorter than any cation-anion bond '\n", + " f'these families produce, so the coordinates are suspect')\n", + " return d_min, 'ok', f\"ok: shortest contact {d_min:.3f} A\"\n", "\n", "\n", "# ── Oxidation state helpers (unchanged) ──────────────────────────────────────\n", "\n", "def _load_oxi_json(path):\n", - " \"\"\"Load the common_oxidation_states.json, returning {} on failure.\"\"\"\n", + " \"\"\"Load common_oxidation_states.json. {} if absent, raises if corrupt.\n", + "\n", + " v1.1: 'file is not there' and 'file is there and unreadable' are different\n", + " facts and were both returning {}, which the priority chain below reads as\n", + " 'this source has nothing to say' and silently drops a level.\n", + " \"\"\"\n", " try:\n", " with open(path, 'r') as f:\n", " return json.load(f)\n", - " except Exception:\n", + " except FileNotFoundError:\n", " return {}\n", + " except (json.JSONDecodeError, OSError) as e:\n", + " raise ValueError(f'{path} exists but could not be read: {e}') from e\n", "\n", "\n", - "def _load_maple_library(data_dir='.'):\n", - " \"\"\"Load maple_library.json, returning {} on failure.\"\"\"\n", + "def _load_maple_library(data_dir):\n", + " # v1.3.1: no default. The directory is resolved once, in load_structure,\n", + " # against DEFAULT_DATA_DIR; a second default here is a second answer to\n", + " # the same question, and it was the wrong one.\n", + " \"\"\"Load maple_library.json. {} if absent, raises if corrupt. See above.\"\"\"\n", " try:\n", " with open(Path(data_dir) / 'maple_library.json', 'r') as f:\n", " return json.load(f)\n", - " except Exception:\n", + " except FileNotFoundError:\n", " return {}\n", + " except (json.JSONDecodeError, OSError) as e:\n", + " raise ValueError(\n", + " f'maple_library.json in {data_dir} could not be read: {e}') from e\n", "\n", "\n", "def _extract_cif_oxidation_states(cif_path):\n", @@ -213,8 +452,12 @@ " try:\n", " with open(cif_path, 'r', encoding='utf-8', errors='ignore') as f:\n", " lines = f.readlines()\n", - " except Exception:\n", + " except FileNotFoundError:\n", " return {}\n", + " except OSError as e:\n", + " # v1.1: a CIF that cannot be read is not a CIF with no oxidation\n", + " # states in it, and the caller treats the two identically.\n", + " raise ValueError(f'could not read {cif_path}: {e}') from e\n", "\n", " in_loop = False\n", " columns = []\n", @@ -303,6 +546,36 @@ "# which collapsed mixed-valence to a single state per element and broke charge\n", "# balance for ~35% of structures. That is now a fallback, not the default.\n", "\n", + "def _parse_structures(parser):\n", + " \"\"\"\n", + " Structures from a CifParser, in the PRIMITIVE cell.\n", + "\n", + " v1.3: this was `parser.get_structures()`, whose primitive=True default is\n", + " deprecated. MaplePy has always worked in the primitive cell; nothing said\n", + " so, and `parse_structures()` defaults the other way, so a mechanical\n", + " rename at some future pymatgen release would have changed the cell\n", + " without changing a line of intent.\n", + "\n", + " The choice is not load-bearing for the numbers, which is worth recording.\n", + " Measured on the same CIFs both ways:\n", + "\n", + " pyrochlore ICSD 109080 primitive 22 sites Z 2 MAPLE 10173.38\n", + " conventional 88 sites Z 8 MAPLE 10173.38\n", + " d_ref 1.9298 and MF 8.4463 in both\n", + "\n", + " perovskite ICSD 109352 identical either way: 20 sites, Z 4,\n", + " MAPLE 3914.11, d_ref 1.9855, MF 3.9007\n", + "\n", + " MAPLE per formula unit, d_ref and the Madelung factor are invariant; the\n", + " cell and Z change together. What is NOT invariant is anything that counts\n", + " sites - the per-site table gains 66 rows per pyrochlore in the\n", + " conventional cell - so the cell is pinned rather than left to a default.\n", + " \"\"\"\n", + " if hasattr(parser, 'parse_structures'):\n", + " return parser.parse_structures(primitive=True)\n", + " return parser.get_structures()\n", + "\n", + "\n", "def _has_native_oxi_states(structure):\n", " \"\"\"\n", " Check whether pymatgen assigned oxidation states when parsing the CIF.\n", @@ -329,7 +602,7 @@ " return total\n", "\n", "\n", - "def load_structure(cif_path, oxidation_states=None, data_dir='.'):\n", + "def load_structure(cif_path, oxidation_states=None, data_dir=None):\n", " \"\"\"\n", " Load a CIF and decorate with oxidation states.\n", "\n", @@ -358,11 +631,18 @@ " \"\"\"\n", " cif_path = str(cif_path)\n", "\n", + " # v1.2: None means \"wherever the data actually is\"; an explicit path that\n", + " # does not exist is a mistake rather than a reason to fall back silently.\n", + " if data_dir is None:\n", + " data_dir = DEFAULT_DATA_DIR\n", + " elif not Path(data_dir).is_dir():\n", + " raise ValueError(f'data_dir does not exist: {data_dir}')\n", + "\n", " # ── Load CIF, catching unrecognised element labels ────────────────────\n", " try:\n", " from pymatgen.io.cif import CifParser\n", - " parser = CifParser(cif_path, occupancy_tolerance=1.05)\n", - " structures = parser.get_structures()\n", + " parser = CifParser(cif_path, occupancy_tolerance=OCCUPANCY_TOL)\n", + " structures = _parse_structures(parser)\n", " if not structures:\n", " raise ValueError(\"No valid structures parsed from CIF.\")\n", " structure = structures[0]\n", @@ -379,13 +659,15 @@ " disordered = _is_disordered(structure)\n", "\n", " if disordered:\n", - " print(f\" Note: mixed-occupancy sites detected. \"\n", - " f\"Using mean-field charge approximation.\")\n", + " _kind, _where = _disorder_detail(structure)\n", + " print(f\" Note: {_kind}\"\n", + " f\"{'' if _where == 'none' else f' on the {_where} sublattice'}\"\n", + " f\" detected. Using mean-field charge approximation.\")\n", "\n", " # ── Check for unphysical occupancies ──────────────────────────────────\n", " for site in structure:\n", " occ_sum = sum(site.species.values())\n", - " if occ_sum > 1.01:\n", + " if occ_sum > OCCUPANCY_TOL:\n", " print(f\" WARNING: site occupancy sum = {occ_sum:.3f} \"\n", " f\"(>1.0) at {site.species}. \"\n", " f\"Refinement quality issue.\")\n", @@ -400,7 +682,7 @@ " # pymatgen already assigned Species with oxi_states from the CIF.\n", " # Check charge balance to confirm they are sensible.\n", " native_q = _native_charge_balance(structure)\n", - " if abs(native_q) < 0.5:\n", + " if abs(native_q) < CHARGE_NEUTRAL_TOL:\n", " source = 'CIF (per-site, charge-neutral)'\n", " else:\n", " # Native states exist but are not charge-neutral.\n", @@ -472,7 +754,7 @@ "\n", " # ── Charge-balance check ──────────────────────────────────────────────\n", " total_charge = _native_charge_balance(structure)\n", - " if abs(total_charge) > 0.05:\n", + " if abs(total_charge) > CHARGE_NEUTRAL_TOL:\n", " print(f\" WARNING: not charge-neutral \"\n", " f\"(Σq = {total_charge:+.3f} e).\\n\"\n", " f\" Source: {source}. Check oxidation states before \"\n", @@ -527,8 +809,14 @@ " if _site_oxi_state(s) < 0]\n", "\n", " if not cat_idx or not ani_idx:\n", - " return min(structure.get_distance(0, j)\n", - " for j in range(1, len(structure)))\n", + " # v1.1: this used to return min(distance from site 0 to anything),\n", + " # which is not a cation-anion distance and may be anion-anion. d_ref\n", + " # normalises the Madelung factor, so a wrong one is not a small error\n", + " # in a diagnostic - it is a different quantity wearing the same name.\n", + " raise ValueError(\n", + " 'cannot determine d_ref: the structure has '\n", + " f'{len(cat_idx)} site(s) with positive charge and '\n", + " f'{len(ani_idx)} with negative. Check the oxidation states.')\n", "\n", " d_min = np.inf\n", " for ci in cat_idx:\n", @@ -541,88 +829,95 @@ "\n", "# ── SG 62 origin-choice correction ───────────────────────────────────────\n", "\n", - "def _fix_sg62_origin(structure, verbose=True):\n", - " \"\"\"\n", - " Fix the Pnma/Pbnm (SG 62) origin-choice artefact for GdFeO3-type\n", - " perovskites.\n", - "\n", - " Some ICSD CIF entries for SG 62 perovskites use an alternative\n", - " origin choice that places the 8d oxygen (O2) at a symmetry-equivalent\n", - " but non-standard representative position, shifted by (½, ½, 0) from\n", - " the conventional choice. pymatgen's CifParser applies the listed\n", - " symmetry operations faithfully, producing a physically valid but\n", - " *inequivalent* expanded structure whose Ewald energy differs from\n", - " that of the standard origin.\n", - "\n", - " Applicable only to SG 62 structures with exactly 20 sites (Z = 4,\n", - " ABO₃ perovskite). The method identifies O2 sites (Wyckoff 8d,\n", - " z ∉ {¼, ¾}) and constructs an alternative structure with these sites\n", - " shifted by (½, ½, 0). The Ewald energy of both versions is compared;\n", - " the structure with the more negative energy (higher |MAPLE|) is\n", - " returned, guaranteeing the correct origin is always selected.\n", - "\n", - " Typical correction magnitude: 6–8 % of MAPLE.\n", + "# ── The SG-62 origin correction, removed at v1.3.6 ─────────────────────────\n", + "#\n", + "# There was a function here, `_fix_sg62_origin`, which built a second\n", + "# structure with the 8d oxygen sublattice shifted by (1/2, 1/2, 0), computed\n", + "# the Ewald energy of both, and kept whichever was more negative. It is gone,\n", + "# and this is the record of why, because a deleted function leaves no trace\n", + "# to argue with.\n", + "#\n", + "# Measured across all 938 perovskites before removing it:\n", + "#\n", + "# corrected 44 4.7% of the family, MAPLE moved by up to 8.1%\n", + "# tested and kept 882\n", + "# not applicable 11\n", + "# declined 1\n", + "# pyrochlores 0 it never fired on Fd-3m\n", + "#\n", + "# and on the eleven corrections examined in detail:\n", + "#\n", + "# - both candidates are Pnma, with different interatomic distances and\n", + "# energies 0.3 to 8.1% apart. They are two different structures, not two\n", + "# descriptions of one, so this was a structural edit and not a setting fix\n", + "# - the shortest interatomic contact is IDENTICAL in ten of the eleven, and\n", + "# in ICSD 33482 the shift makes it WORSE, 1.658 A -> 1.462 A, and was\n", + "# applied anyway because the energy was lower. A repair that never\n", + "# improves the geometry is not repairing the geometry\n", + "# - it fired on LaCrO3 220506, whose shortest contact is 1.008 A, and on\n", + "# LuCrO3 138227, one of the RCrO3 series whose real fault is the B cation\n", + "# deposited on 4a: adjusting broken coordinates rather than reporting them\n", + "# - and on TbCrO3 85235, a sound structure agreeing with an independent 2023\n", + "# refinement and additive at 0.056%, whose MAPLE it moved by 2.8%\n", + "#\n", + "# The selection rule was the Ewald energy, which is the quantity this study\n", + "# measures, applied to structures this study is judging.\n", + "#\n", + "# NOTHING GENERAL REPLACES IT, because there is nothing mis-expanded to\n", + "# repair: the deposited structure is the deposited structure. What does the\n", + "# work instead is v1.3.3's geometry reporting - d_min_ang, geometry_flag,\n", + "# SPLIT_SITE_ANG and SHORT_CONTACT_ANG - and Hopper's codes 2.5 and 2.7. A\n", + "# structure that cannot carry a Madelung energy is now reported as such\n", + "# rather than quietly improved.\n", + "#\n", + "# If a repair is ever wanted again, the rule to meet is the one this failed:\n", + "# apply it only where the deposited structure FAILS the geometry test and the\n", + "# candidate PASSES it. On this dataset that fires on none of the 44.\n", "\n", - " Parameters\n", - " ----------\n", - " structure : pymatgen Structure with oxidation states assigned\n", - " verbose : bool\n", "\n", - " Returns\n", - " -------\n", - " structure : corrected Structure (or original if no fix needed)\n", + "def _derive_Z(structure):\n", " \"\"\"\n", - " try:\n", - " _, sg_number = structure.get_space_group_info(symprec=0.1)\n", - " except Exception:\n", - " return structure\n", - "\n", - " if sg_number != 62 or len(structure) != 20:\n", - " return structure\n", - "\n", - " # ── Identify O2 (Wyckoff 8d) sites ────────────────────────────────\n", - " # In GdFeO3-type perovskites, O1 occupies 4c (z = ¼ or ¾) and\n", - " # O2 occupies 8d (general z).\n", - " o2_mask = []\n", + " Formula units per cell, from the site counts rather than the composition.\n", + "\n", + " v1.1. `composition.get_reduced_composition_and_factor()` cannot factor a\n", + " NON-STOICHIOMETRIC composition, so it returns Z = 1 and every per-formula\n", + " -unit quantity is inflated by the true Z. Over the 1410-structure\n", + " perovskite and pyrochlore dataset:\n", + "\n", + " Z = 1 entries 172 (12.2%)\n", + " of those, with a fractional subscript 165 (96%)\n", + " Z > 1 entries with a fractional subscript 0 (0%)\n", + "\n", + " Gd4Cr3.984O12 is not a metadata error; it is a refinement with a partly\n", + " occupied Cr site, and it has four formula units in its cell like every\n", + " other GdFeO3-type perovskite.\n", + "\n", + " Z is crystallographic, so take it from the crystallography. The number of\n", + " SITES containing each element is an integer whatever the occupancies are,\n", + " and Z divides all of them, so Z is their greatest common divisor. No\n", + " composition arithmetic, no rounding of occupancies, no structure-type\n", + " knowledge.\n", + "\n", + " Verified on 103 ICSD CIFs: identical to composition reduction on all 95\n", + " where reduction works, and 4 rather than 1 on all 8 where it does not -\n", + " every one a 20-site perovskite. No disagreement in the other direction.\n", + "\n", + " Falls back to the composition factor only when the structure has no sites\n", + " to count, which cannot happen for a parsed CIF but is not worth an\n", + " exception.\n", + " \"\"\"\n", + " counts = {}\n", " for site in structure:\n", - " is_oxygen = _site_element(site) == 'O'\n", - " z = site.frac_coords[2]\n", - " is_8d = abs(z - 0.25) > 0.1 and abs(z - 0.75) > 0.1\n", - " o2_mask.append(is_oxygen and is_8d)\n", - "\n", - " if sum(o2_mask) != 8:\n", - " return structure # Not a standard ABO₃ perovskite layout\n", - "\n", - " # ── Build alternative with O2 shifted by (½, ½, 0) ────────────────\n", - " new_coords = []\n", - " for i, site in enumerate(structure):\n", - " fc = site.frac_coords.copy()\n", - " if o2_mask[i]:\n", - " fc[0] = (fc[0] + 0.5) % 1.0\n", - " fc[1] = (fc[1] + 0.5) % 1.0\n", - " new_coords.append(fc)\n", - "\n", - " alt_structure = Structure(\n", - " structure.lattice,\n", - " [site.species for site in structure],\n", - " new_coords,\n", - " )\n", - "\n", - " # ── Compare Ewald energies ────────────────────────────────────────\n", - " try:\n", - " ew_orig = EwaldSummation(structure).total_energy\n", - " ew_alt = EwaldSummation(alt_structure).total_energy\n", - " except Exception:\n", - " return structure\n", - "\n", - " if ew_alt < ew_orig: # alt is more stable → correct origin\n", - " if verbose:\n", - " delta_pct = abs(ew_alt - ew_orig) / abs(ew_orig) * 100\n", - " print(f\" Applied SG 62 origin-choice correction \"\n", - " f\"(O₂ shifted by (½,½,0), ΔE = {delta_pct:.1f}%).\")\n", - " return alt_structure\n", - "\n", - " return structure\n", + " for sp in site.species:\n", + " el = sp.element.symbol if hasattr(sp, 'element') else sp.symbol\n", + " counts[el] = counts.get(el, 0) + 1\n", + " if not counts:\n", + " _, z_float = structure.composition.get_reduced_composition_and_factor()\n", + " return max(1, int(round(z_float)))\n", + " z = 0\n", + " for n in counts.values():\n", + " z = _math.gcd(z, int(n))\n", + " return max(1, z)\n", "\n", "\n", "# ── compute_maple ────────────────────────────────────────────────────────────\n", @@ -653,19 +948,21 @@ " total_maple_kcal, per_site, Z, d_ref, madelung_factor,\n", " disordered, structure\n", " \"\"\"\n", - " disordered = _is_disordered(structure)\n", + " disorder_kind, partial_sublattice = _disorder_detail(structure)\n", + " disordered = disorder_kind != 'ordered'\n", "\n", - " # ── SG 62 origin-choice correction ────────────────────────────────────\n", - " structure = _fix_sg62_origin(structure, verbose=verbose)\n", "\n", + " # ── SG 62 origin-choice correction ────────────────────────────────────\n", " # ── Ewald summation ───────────────────────────────────────────────────\n", + " # v1.3.6: on the structure as deposited. The origin correction that used\n", + " # to run first, and hand its summation down, is gone; see the record\n", + " # above.\n", " ewald = EwaldSummation(structure)\n", " energy_matrix = ewald.total_energy_matrix\n", " per_site_eV = energy_matrix.sum(axis=1)\n", "\n", " # ── Formula units per cell (Z) ────────────────────────────────────────\n", - " _, Z_float = structure.composition.get_reduced_composition_and_factor()\n", - " Z = int(round(Z_float))\n", + " Z = _derive_Z(structure)\n", "\n", " # ── Conversion: eV/site → kcal/mol/site ──────────────────────────────\n", " per_site_maple = np.abs(per_site_eV) * EV_TO_KCAL_MOL\n", @@ -676,6 +973,10 @@ " # ── Reference distance ────────────────────────────────────────────────\n", " d_ref = _find_d_ref(structure)\n", "\n", + " # ── Geometry ──────────────────────────────────────────────────────────\n", + " # v1.3.2: measured, reported, and never used to drop anything.\n", + " d_min, geometry_flag, geometry_status = _geometry_status(structure)\n", + "\n", " # ── Per-site data ─────────────────────────────────────────────────────\n", " per_site_data = []\n", " for i, site in enumerate(structure):\n", @@ -702,6 +1003,16 @@ " })\n", "\n", " # ── Madelung factor ───────────────────────────────────────────────────\n", + " #\n", + " # v1.1: THE CONVENTION, WRITTEN DOWN. The mean charges below are means\n", + " # over SITES, not over stoichiometry and not weighted by multiplicity.\n", + " # For ABO3 with two trivalent cations the two agree; for a 2+/4+\n", + " # perovskite the site mean is 3, and for the pyrochlore 16d/16c/48f/8b\n", + " # counts it is a different average again. Nothing here is changed,\n", + " # because the classification and every published figure rest on this\n", + " # definition - but it is a choice, it was undocumented, and it scales the\n", + " # axis on which the Z = 1 population was identified. It should be checked\n", + " # against Hoppe's own normalisation before any future version moves it.\n", " try:\n", " oxi_states = [_site_oxi_state(s) for s in structure]\n", " z_pos = [z for z in oxi_states if z > 0]\n", @@ -713,7 +1024,7 @@ " mean_zn = abs(np.mean(z_neg))\n", " madelung_factor = (total_maple_kcal * d_ref\n", " / (MAPLE_FACTOR * mean_zp * mean_zn))\n", - " except Exception:\n", + " except (TypeError, ValueError, ZeroDivisionError, AttributeError):\n", " madelung_factor = None\n", "\n", " result = {\n", @@ -724,17 +1035,26 @@ " \"madelung_factor\" : (round(madelung_factor, 4)\n", " if madelung_factor is not None else None),\n", " \"disordered\" : disordered,\n", + " \"disorder_status\" : disorder_kind,\n", + " \"partial_sublattice\": partial_sublattice,\n", + " \"d_min_ang\" : round(d_min, 4),\n", + " \"geometry_flag\" : geometry_flag,\n", + " \"geometry_status\" : geometry_status,\n", " \"structure\" : structure,\n", " }\n", "\n", " if verbose:\n", " comp = structure.composition.reduced_formula\n", " sg = structure.get_space_group_info()[0]\n", - " tag = \" [MEAN-FIELD]\" if disordered else \"\"\n", + " _where = ('' if partial_sublattice in ('none', None)\n", + " else f' ({partial_sublattice})')\n", + " tag = (f\" [MEAN-FIELD: {disorder_kind}{_where}]\"\n", + " if disordered else \"\")\n", " print(f\"\\n{'─'*60}\")\n", " print(f\" Compound : {comp} ({sg}){tag}\")\n", " print(f\" Sites : {len(structure)} | Z = {Z}\")\n", " print(f\" d_ref : {d_ref:.4f} Å\")\n", + " print(f\" Geometry : {geometry_status}\")\n", " mf_str = f\"{madelung_factor:.4f}\" if madelung_factor is not None else \"n/a\"\n", " print(f\" MF : {mf_str}\")\n", " print(f\" MAPLE : {total_maple_kcal:.1f} kcal/mol \"\n", @@ -759,9 +1079,16 @@ " df[\"madelung_factor\"] = maple_result[\"madelung_factor\"]\n", " df[\"total_maple\"] = maple_result[\"total_maple_kcal\"]\n", " df[\"disordered\"] = maple_result[\"disordered\"]\n", + " df[\"disorder_status\"] = maple_result.get(\"disorder_status\")\n", + " df[\"partial_sublattice\"] = maple_result.get(\"partial_sublattice\")\n", + " df[\"d_min_ang\"] = maple_result.get(\"d_min_ang\")\n", + " df[\"geometry_flag\"] = maple_result.get(\"geometry_flag\")\n", + " df[\"geometry_status\"] = maple_result.get(\"geometry_status\")\n", "\n", " cols = [\"compound\", \"space_group\", \"Z\", \"d_ref_ang\", \"madelung_factor\",\n", - " \"total_maple\", \"disordered\", \"site_index\", \"element\",\n", + " \"total_maple\", \"disordered\", \"disorder_status\",\n", + " \"partial_sublattice\", \"d_min_ang\", \"geometry_flag\",\n", + " \"geometry_status\", \"site_index\", \"element\",\n", " \"oxidation_state\", \"mixed_site\",\n", " \"frac_x\", \"frac_y\", \"frac_z\",\n", " \"maple_kcal_mol\", \"pmc\", \"reduced_maple\"]\n", @@ -798,11 +1125,7 @@ "cell_type": "code", "execution_count": null, "id": "83be8b9d", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# NaCl: Fm-3m, a = 5.6402 Å (experimental ambient, ICSD)\n", @@ -823,11 +1146,7 @@ "cell_type": "code", "execution_count": null, "id": "fc22ae86", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# ── Validation checks ──────────────────────────────────────────────────────────\n", @@ -872,6 +1191,8 @@ "| Anatase | 3260.7 |\n", "| Brookite | 3253.7 |\n", "\n", + "Brookite is given for reference only; the checks below compute rutile and anatase.\n", + "\n", "The key result: despite radically different geometries, MAPLE values differ by only\n", "~7 kcal/mol. This is a non-trivial consequence of the additivity theorem and is what\n", "MAPLE is designed to reveal." @@ -881,11 +1202,7 @@ "cell_type": "code", "execution_count": null, "id": "cea976ed", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Rutile TiO₂: P4₂/mnm (No. 136), a = 4.5933 Å, c = 2.9592 Å\n", @@ -916,11 +1233,7 @@ "cell_type": "code", "execution_count": null, "id": "f16fa816", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "result_rutile = compute_maple(rutile, verbose=True)\n", @@ -931,11 +1244,7 @@ "cell_type": "code", "execution_count": null, "id": "d0ca3090", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "maple_r = result_rutile[\"total_maple_kcal\"]\n", @@ -982,11 +1291,7 @@ "cell_type": "code", "execution_count": null, "id": "441ed894", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# BaO: Fm-3m (rock salt), a = 5.5391 Å\n", @@ -1016,11 +1321,7 @@ "cell_type": "code", "execution_count": null, "id": "dd00a56e", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "result_bao = compute_maple(bao, verbose=True)\n", @@ -1031,11 +1332,7 @@ "cell_type": "code", "execution_count": null, "id": "4224253b", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "maple_bao = result_bao[\"total_maple_kcal\"]\n", @@ -1071,11 +1368,7 @@ "cell_type": "code", "execution_count": null, "id": "7f100ef2", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Replace with your CIF path and oxidation states if not embedded in the CIF.\n", @@ -1109,11 +1402,7 @@ "cell_type": "code", "execution_count": null, "id": "7b40674e", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "def check_additivity(polynary_result, binary_results_and_coeffs, verbose=True):\n", @@ -1158,11 +1447,7 @@ "cell_type": "code", "execution_count": null, "id": "67aaf25e", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Example: BaTiO₃ using results already computed in validation\n", @@ -1182,18 +1467,181 @@ "cell_type": "code", "execution_count": null, "id": "bf3261ce", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 5. Batch Processing (v3)\n", "# ─────────────────────────────────────────────────────────────────────────────\n", "\n", + "# ── Where the last run went ────────────────────────────────────────────────\n", + "#\n", + "# v1.3.1: Section 8 used to carry a hard-coded path to somebody's Downloads\n", + "# folder, and a run and the plots of that run were connected only by the\n", + "# reader retyping it. Both entry points record where they wrote.\n", + "LAST_OUTPUT_DIR = None # Path, set by batch_maple() and launch_maple_gui()\n", + "\n", + "# The per-structure summary, one definition. Section 8 and Hopper both open\n", + "# maple_summary.csv and read these names.\n", + "SUMMARY_COLS = [\"compound\", \"space_group\", \"Z\", \"d_ref_ang\",\n", + " \"madelung_factor\", \"total_maple\", \"disordered\",\n", + " \"disorder_status\", \"partial_sublattice\", \"d_min_ang\",\n", + " \"geometry_flag\", \"geometry_status\",\n", + " \"source_cif\", \"maplepy_version\"]\n", + "\n", + "\n", + "def _write_outputs(dfs, failed, output_dir):\n", + " \"\"\"\n", + " Write the three CSVs a MAPLE run produces, and record where they went.\n", + "\n", + " v1.3.1: batch_maple() wrote maple_results.csv and maple_failed.csv but not\n", + " maple_summary.csv, while the GUI wrote all three. Section 8 and Hopper\n", + " both look for the summary first, so a batch run could not be plotted or\n", + " decomposed and nothing said why. Written in one place now, so the two\n", + " entry points cannot drift again.\n", + "\n", + " Returns (master, summary); both empty frames if nothing was processed.\n", + " \"\"\"\n", + " global LAST_OUTPUT_DIR\n", + "\n", + " output_dir = Path(output_dir)\n", + " output_dir.mkdir(parents=True, exist_ok=True)\n", + "\n", + " if dfs:\n", + " master = pd.concat(dfs, ignore_index=True)\n", + " master[\"maplepy_version\"] = MAPLEPY_VERSION\n", + " results_csv = output_dir / 'maple_results.csv'\n", + " master.to_csv(results_csv, index=False)\n", + " print(f\"\\nSaved {len(master)} rows → {results_csv}\")\n", + "\n", + " summary = (master[SUMMARY_COLS]\n", + " .drop_duplicates(subset=\"source_cif\")\n", + " .reset_index(drop=True))\n", + " summary_csv = output_dir / 'maple_summary.csv'\n", + " summary.to_csv(summary_csv, index=False)\n", + " print(f\"Saved {len(summary)} structures → {summary_csv}\")\n", + " else:\n", + " master = pd.DataFrame()\n", + " summary = pd.DataFrame()\n", + " print(\"\\nNo structures processed successfully.\")\n", + "\n", + " if failed:\n", + " failed_df = pd.DataFrame(failed, columns=['cif_file', 'error'])\n", + " failed_csv = output_dir / 'maple_failed.csv'\n", + " failed_df.to_csv(failed_csv, index=False)\n", + " print(f\"Saved {len(failed)} failures → {failed_csv}\")\n", + "\n", + " LAST_OUTPUT_DIR = output_dir\n", + " return master, summary\n", + "\n", + "\n", + "def process_one_cif(cif_path, oxidation_states=None, data_dir=None,\n", + " verbose=False):\n", + " \"\"\"\n", + " Load, compute and tabulate ONE CIF. The one definition.\n", + "\n", + " v1.3.4: batch_maple and the GUI each had their own copy of this sequence,\n", + " which is two things to keep in step and two things to put in a worker.\n", + " Returns only picklable data, so it can run in another process:\n", + "\n", + " (name, df or None, error or None, tag, console output)\n", + "\n", + " `tag` is the mean-field marker for the progress line, so the caller can\n", + " print without reaching back into the result.\n", + " \"\"\"\n", + " import contextlib as _ctx\n", + " import io as _io\n", + " from pathlib import Path as _P\n", + "\n", + " name = _P(cif_path).name\n", + " # v1.3.4: the console output is CAPTURED and handed back, not left to\n", + " # wherever this happens to run. load_structure prints which source the\n", + " # oxidation states came from, unconditionally, and that line is the only\n", + " # record of the provenance anywhere - it is in no CSV. A worker process\n", + " # writes it to a pipe nobody reads, so a parallel run would have quietly\n", + " # stopped telling you. Captured here, printed by the caller, identical\n", + " # either way.\n", + " _said = _io.StringIO()\n", + " try:\n", + " with _ctx.redirect_stdout(_said):\n", + " s = load_structure(cif_path, oxidation_states=oxidation_states,\n", + " data_dir=data_dir)\n", + " result = compute_maple(s, verbose=verbose)\n", + " df = results_to_dataframe(result)\n", + " df[\"source_cif\"] = name\n", + " return (name, df, None, (\" [MF]\" if result[\"disordered\"] else \"\"),\n", + " _said.getvalue())\n", + " except Exception as e:\n", + " return name, None, str(e), \"\", _said.getvalue()\n", + "\n", + "\n", + "def _resolve_workers(workers, n_items):\n", + " \"\"\"How many processes to actually start. Never more than there is work.\"\"\"\n", + " if workers in (None, 1, 0):\n", + " return 1\n", + " if workers == 'auto':\n", + " try:\n", + " import os as _os\n", + " workers = max(1, (_os.cpu_count() or 2) - 2)\n", + " except Exception:\n", + " return 1\n", + " try:\n", + " workers = int(workers)\n", + " except (TypeError, ValueError):\n", + " print(f\" MAPLE_WORKERS = {workers!r} is not a number or 'auto'; \"\n", + " f\"running serially.\")\n", + " return 1\n", + " return max(1, min(workers, n_items))\n", + "\n", + "\n", + "def _map_cifs(paths, oxidation_states_map, data_dir, verbose, workers):\n", + " \"\"\"\n", + " process_one_cif over every path, in order, serially or in a pool.\n", + "\n", + " v1.3.4: the only place that decides between the two, and both branches\n", + " call the same function. A pool that will not start is reported in full\n", + " and the run continues serially - an optimisation with an exact serial\n", + " equivalent should never be the thing that stops the science.\n", + " \"\"\"\n", + " from pathlib import Path as _P\n", + " n = _resolve_workers(workers, len(paths))\n", + " jobs = [(p, (oxidation_states_map or {}).get(_P(p).stem)) for p in paths]\n", + "\n", + " if n > 1:\n", + " try:\n", + " from joblib import Parallel, delayed\n", + " except ImportError as e:\n", + " print(f\" joblib is not installed ({e}), so MAPLE_WORKERS \"\n", + " f\"cannot be honoured. Running serially. `pip install \"\n", + " f\"joblib` for the parallel path.\")\n", + " n = 1\n", + " if n > 1:\n", + " print(f\" processing on {n} workers\")\n", + " try:\n", + " try:\n", + " # joblib >= 1.3 streams results in order, so progress is\n", + " # visible during the run rather than only at the end\n", + " out = Parallel(n_jobs=n, backend='loky',\n", + " return_as='generator')(\n", + " delayed(process_one_cif)(p, oxi, data_dir, False)\n", + " for p, oxi in jobs)\n", + " except TypeError:\n", + " out = Parallel(n_jobs=n, backend='loky')(\n", + " delayed(process_one_cif)(p, oxi, data_dir, False)\n", + " for p, oxi in jobs)\n", + " for item in out:\n", + " yield item\n", + " return\n", + " except Exception as e:\n", + " print(f\" the worker pool failed to run ({type(e).__name__}: \"\n", + " f\"{e}). Falling back to serial processing; the results are \"\n", + " f\"the same either way, only slower.\")\n", + "\n", + " for p, oxi in jobs:\n", + " yield process_one_cif(p, oxi, data_dir, verbose)\n", + "\n", + "\n", "def batch_maple(cif_dir, output_dir=None, oxidation_states_map=None,\n", - " data_dir='.', verbose=False):\n", + " data_dir=None, verbose=False, workers=None):\n", " \"\"\"\n", " Process all CIFs in a directory.\n", "\n", @@ -1202,11 +1650,16 @@ " cif_dir : str or Path\n", " Directory containing CIF files.\n", " output_dir : str or Path, optional\n", - " Directory for output CSVs. If None, creates 'outputs' inside cif_dir.\n", + " Directory for output CSVs. If None, creates a timestamped\n", + " outputs_YYYYMMDD_HHMMSS folder inside cif_dir.\n", " oxidation_states_map : dict {filename_stem: {element: oxi_state}}\n", " For CIFs without embedded oxidation states.\n", - " data_dir : str\n", - " Path to folder containing common_oxidation_states.json.\n", + " data_dir : str or None\n", + " Folder holding maple_library.json and common_oxidation_states.json.\n", + " None (v1.3.1) means DEFAULT_DATA_DIR, resolved at load. It used to be\n", + " '.', which was passed on explicitly and so overrode that resolution:\n", + " every batch run silently lost two levels of the oxidation-state\n", + " priority chain.\n", " verbose : bool\n", " If True, print full MAPLE output per structure.\n", "\n", @@ -1232,37 +1685,22 @@ " print(f\"Output directory: {output_dir}\")\n", " dfs, failed = [], []\n", "\n", - " for cif_path in cif_files:\n", - " oxi = (oxidation_states_map or {}).get(cif_path.stem)\n", - " try:\n", - " s = load_structure(cif_path, oxidation_states=oxi,\n", - " data_dir=data_dir)\n", - " result = compute_maple(s, verbose=verbose)\n", - " df_i = results_to_dataframe(result)\n", - " df_i[\"source_cif\"] = cif_path.name\n", - " dfs.append(df_i)\n", - " tag = \" [MF]\" if result[\"disordered\"] else \"\"\n", - " print(f\" ✓ {cif_path.name:45s} \"\n", - " f\"MAPLE = {result['total_maple_kcal']:.1f} kcal/mol{tag}\")\n", - " except Exception as e:\n", - " failed.append((cif_path.name, str(e)))\n", - " print(f\" ✗ {cif_path.name:45s} {e}\")\n", + " # v1.3.4: one worker function, run serially or on a pool by _map_cifs.\n", + " for name, df_i, err, tag, said in _map_cifs(\n", + " [str(p) for p in cif_files], oxidation_states_map, data_dir,\n", + " verbose, MAPLE_WORKERS if workers is None else workers):\n", + " if said:\n", + " print(said, end='')\n", + " if err is not None:\n", + " failed.append((name, err))\n", + " print(f\" ✗ {name:45s} {err}\")\n", + " continue\n", + " dfs.append(df_i)\n", + " print(f\" ✓ {name:45s} \"\n", + " f\"MAPLE = {df_i['total_maple'].iloc[0]:.1f} kcal/mol{tag}\")\n", "\n", " # ── Save results ──────────────────────────────────────────────────────\n", - " if dfs:\n", - " master = pd.concat(dfs, ignore_index=True)\n", - " results_csv = output_dir / 'maple_results.csv'\n", - " master.to_csv(results_csv, index=False)\n", - " print(f\"\\nSaved {len(master)} rows → {results_csv}\")\n", - " else:\n", - " master = pd.DataFrame()\n", - " print(\"\\nNo structures processed successfully.\")\n", - "\n", - " if failed:\n", - " failed_df = pd.DataFrame(failed, columns=['cif_file', 'error'])\n", - " failed_csv = output_dir / 'maple_failed.csv'\n", - " failed_df.to_csv(failed_csv, index=False)\n", - " print(f\"Saved {len(failed)} failures → {failed_csv}\")\n", + " master, _summary = _write_outputs(dfs, failed, output_dir)\n", "\n", " # ── Summary ───────────────────────────────────────────────────────────\n", " n_total = len(cif_files)\n", @@ -1310,11 +1748,7 @@ "cell_type": "code", "execution_count": null, "id": "1900f6f1", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Rock-salt MO structures from experimental ambient ICSD parameters\n", @@ -1344,11 +1778,7 @@ "cell_type": "code", "execution_count": null, "id": "164c6cc4", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Per-site MAPLE for the cation series\n", @@ -1382,11 +1812,7 @@ "cell_type": "code", "execution_count": null, "id": "813f057e", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# Quick correlation check: does MAPLE(M²⁺) correlate with Shannon radius?\n", @@ -1428,9 +1854,9 @@ "---\n", "## 7. GUI: Load and Process Real CIFs\n", "\n", - "Tkinter file picker → compute MAPLE for each selected CIF → display results inline → save CSV.\n", + "Tkinter folder picker → `batch_maple()` on every CIF in the folder → three CSVs in a timestamped `outputs_` folder beside them.\n", "\n", - "**Oxidation states:** Edit the dict in the first cell below before launching.\n", + "**Oxidation states:** set `OXIDATION_STATES` at the top of the cell below before launching.\n", "ICSD CIFs for simple binary oxides and halides usually embed oxidation states and\n", "the dict can be left empty (`{}`). For CIFs without embedded states, or where\n", "pymatgen's auto-assignment is unreliable (transition metals, mixed valence),\n", @@ -1444,18 +1870,20 @@ "cell_type": "code", "execution_count": null, "id": "fcb983e6", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 7. GUI: Load and Process Real CIFs (v3)\n", "# ─────────────────────────────────────────────────────────────────────────────\n", "#\n", - "# Tkinter file picker → compute MAPLE for each selected CIF → display\n", - "# results inline → save CSV files to 'outputs' subdirectory.\n", + "# Tkinter FOLDER picker → batch_maple on every CIF in it → three CSVs in a\n", + "# timestamped outputs_ folder beside them.\n", + "#\n", + "# v1.3.5: this used to be a FILE picker, so every CIF had to be selected by\n", + "# hand, and the cell then carried its own copy of the output directory, the\n", + "# progress lines, the summary table and the totals - all of which batch_maple\n", + "# already did. The GUI is now a folder picker in front of batch_maple, so\n", + "# there is one implementation of the batch and the button just points at it.\n", "#\n", "# Three output files are created in an 'outputs' folder alongside the CIFs:\n", "# maple_results.csv — full site-level data (every site, every structure)\n", @@ -1472,7 +1900,11 @@ "\n", "# ── Data directory ────────────────────────────────────────────────────────────\n", "# Folder containing common_oxidation_states.json (and shannon_radii.json).\n", - "DATA_DIR = \".\"\n", + "#\n", + "# v1.3.1: None means DEFAULT_DATA_DIR, resolved once at load (Section 0). This\n", + "# was \".\" and was passed on explicitly, which overrode that resolution, so the\n", + "# GUI never read data/ however the rest of the notebook was configured.\n", + "DATA_DIR = None\n", "\n", "print(\"Oxidation state overrides:\",\n", " OXIDATION_STATES if OXIDATION_STATES else\n", @@ -1485,122 +1917,76 @@ "from tkinter import filedialog\n", "import traceback\n", "\n", - "def launch_maple_gui():\n", - " \"\"\"\n", - " Open a file picker, process selected CIFs through compute_maple(),\n", - " display results as a DataFrame, and save outputs to an 'outputs'\n", - " subdirectory alongside the selected CIFs.\n", - " \"\"\"\n", - "\n", - " # ── File picker ───────────────────────────────────────────────────────\n", - " root = tk.Tk()\n", - " root.withdraw()\n", - " root.attributes('-topmost', True)\n", - "\n", - " cif_paths = filedialog.askopenfilenames(\n", - " title=\"Select CIF files for MAPLE analysis\",\n", - " filetypes=[(\"CIF files\", \"*.cif\"), (\"All files\", \"*.*\")],\n", - " parent=root\n", - " )\n", - " root.destroy()\n", - "\n", - " if not cif_paths:\n", - " print(\"No files selected.\")\n", - " return None\n", + "# ── Where the CIFs are ────────────────────────────────────────────────────────\n", + "# Set this to a folder and no dialog opens. Useful for a second family in the\n", + "# same session, and immune to the hidden-dialog problem below.\n", + "MAPLE_CIF_DIR = None # e.g. r\"path/to/cifs\"\n", "\n", - " # ── Determine output directory ────────────────────────────────────────\n", - " from datetime import datetime\n", - " cif_parent = Path(cif_paths[0]).parent\n", - " timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')\n", - " output_dir = cif_parent / f'outputs_{timestamp}'\n", - " output_dir.mkdir(parents=True, exist_ok=True)\n", "\n", - " print(f\"Selected {len(cif_paths)} CIF(s):\")\n", - " for p in cif_paths:\n", - " print(f\" {Path(p).name}\")\n", - " print(f\"Output directory: {output_dir}\\n\")\n", + "def launch_maple_gui(cif_dir=None):\n", + " \"\"\"\n", + " Pick a folder of CIFs and run batch_maple on it.\n", "\n", - " # ── Process each CIF ──────────────────────────────────────────────────\n", - " dfs, failed = [], []\n", + " v1.3.5: a FOLDER, not a hand-picked list of files, and the work itself is\n", + " batch_maple rather than a second copy of it. Everything the batch does -\n", + " the worker pool, the three CSVs, LAST_OUTPUT_DIR, the summary - comes with\n", + " it, because it is the same function.\n", "\n", - " for cif_path in cif_paths:\n", - " name = Path(cif_path).name\n", - " print(f\"Processing: {name}\")\n", + " Pass cif_dir, or set MAPLE_CIF_DIR above, to skip the dialog.\n", + " \"\"\"\n", + " cif_dir = cif_dir or MAPLE_CIF_DIR\n", + "\n", + " if not cif_dir:\n", + " # A second Tk dialog in one kernel can open BEHIND the browser, and\n", + " # the cell then waits on a window nobody can see. The notice goes out\n", + " # before the call that blocks, so a hang is diagnosable rather than\n", + " # mysterious; parent, update() and lift() make it far less likely.\n", + " print(\"Opening a folder picker. If nothing appears, look BEHIND this \"\n", + " \"window. Set MAPLE_CIF_DIR above to skip the dialog entirely.\")\n", + " root = tk.Tk()\n", + " root.withdraw()\n", + " root.update()\n", + " root.attributes('-topmost', True)\n", + " root.lift()\n", + " root.focus_force()\n", + " cif_dir = filedialog.askdirectory(\n", + " title=\"Select the folder containing your CIF files\",\n", + " parent=root\n", + " )\n", + " root.update()\n", + " root.destroy()\n", "\n", - " try:\n", - " oxi = OXIDATION_STATES if OXIDATION_STATES else None\n", - " s = load_structure(cif_path, oxidation_states=oxi,\n", - " data_dir=DATA_DIR)\n", - " res = compute_maple(s, verbose=True)\n", - " df = results_to_dataframe(res)\n", - " df[\"source_cif\"] = name\n", - " dfs.append(df)\n", + " if not cif_dir:\n", + " print(\"No folder selected.\")\n", + " return None\n", "\n", - " except Exception as e:\n", - " failed.append((name, str(e)))\n", - " print(f\" ✗ FAILED: {e}\")\n", - " print(f\" {traceback.format_exc().splitlines()[-1]}\")\n", + " cif_dir = Path(cif_dir)\n", + " n_cifs = len(sorted(cif_dir.glob(\"*.cif\")))\n", + " print(f\"Folder: {cif_dir}\")\n", + " print(f\" {n_cifs} CIF file(s)\")\n", + " if not n_cifs:\n", + " print(\" Nothing to do: no *.cif in that folder. Note that this does \"\n", + " \"not look in subfolders.\")\n", + " return None\n", "\n", - " # ── Save results ──────────────────────────────────────────────────────\n", - " if dfs:\n", - " master = pd.concat(dfs, ignore_index=True)\n", + " oxi = ({p.stem: OXIDATION_STATES for p in cif_dir.glob(\"*.cif\")}\n", + " if OXIDATION_STATES else None)\n", "\n", - " # Site-level results\n", - " results_csv = output_dir / 'maple_results.csv'\n", - " master.to_csv(results_csv, index=False)\n", + " master = batch_maple(cif_dir, oxidation_states_map=oxi,\n", + " data_dir=DATA_DIR)\n", "\n", - " # Summary table: one row per compound\n", - " summary_cols = [\"compound\", \"space_group\", \"Z\", \"d_ref_ang\",\n", - " \"madelung_factor\", \"total_maple\", \"disordered\",\n", - " \"source_cif\"]\n", - " summary = (master[summary_cols]\n", + " if master is not None and len(master):\n", + " summary = (master[SUMMARY_COLS]\n", " .drop_duplicates(subset=\"source_cif\")\n", " .reset_index(drop=True))\n", - " summary_csv = output_dir / 'maple_summary.csv'\n", - " summary.to_csv(summary_csv, index=False)\n", - "\n", - " print(f\"\\n{'='*60}\")\n", - " print(f\"RESULTS: {len(dfs)} structure(s) processed\")\n", - " print(f\"{'='*60}\")\n", - " print(f\"Summary (per structure):\")\n", + " print(\"\\nSummary (per structure):\")\n", " display(summary)\n", - " print(f\"\\nSaved {len(master)} rows → {results_csv}\")\n", - " print(f\"Saved {len(summary)} structures → {summary_csv}\")\n", - " else:\n", - " master = None\n", - " print(\"\\nNo structures processed successfully.\")\n", - "\n", - " # ── Save failures ─────────────────────────────────────────────────────\n", - " if failed:\n", - " failed_df = pd.DataFrame(failed, columns=['cif_file', 'error'])\n", - " failed_csv = output_dir / 'maple_failed.csv'\n", - " failed_df.to_csv(failed_csv, index=False)\n", - " print(f\"Saved {len(failed)} failures → {failed_csv}\")\n", - "\n", - " print(f\"\\nFailed structures:\")\n", - " for name, err in failed:\n", - " print(f\" {name}: {err}\")\n", - "\n", - " # ── Summary statistics ────────────────────────────────────────────────\n", - " n_total = len(cif_paths)\n", - " n_ok = len(dfs)\n", - " n_fail = len(failed)\n", - " n_ordered = sum(1 for d in dfs\n", - " if not d[\"disordered\"].iloc[0]) if dfs else 0\n", - " n_disordered = n_ok - n_ordered\n", - "\n", - " print(f\"\\n{'='*60}\")\n", - " print(f\" Total CIFs : {n_total}\")\n", - " print(f\" Processed (OK) : {n_ok} \"\n", - " f\"({n_ordered} ordered, {n_disordered} mean-field)\")\n", - " print(f\" Failed : {n_fail}\")\n", - " print(f\"{'='*60}\")\n", - "\n", - " return master\n", + " return master\n", + " return None\n", "\n", "\n", "# ── Launch ────────────────────────────────────────────────────────────────────\n", - "df_loaded = launch_maple_gui()" + "df_loaded = launch_maple_gui()\n" ] }, { @@ -1610,7 +1996,7 @@ "source": [ "### Interpreting the GUI output\n", "\n", - "**Output files** (saved to `outputs/` subdirectory alongside the CIF files):\n", + "**Output files** (saved to a timestamped `outputs_YYYYMMDD_HHMMSS/` folder alongside the CIF files):\n", "\n", "| File | Contents |\n", "|------|----------|\n", @@ -1627,10 +2013,10 @@ "| `d_ref_ang` | Shortest cation–anion distance [Å]. The reference distance on which PMC is normalised. |\n", "| `pmc` | Partial Madelung constant. Geometrically invariant within a structure type; site-specific in lower-symmetry structures. |\n", "| `reduced_maple` | MAPLE / z² / d_ref. Strips charge and distance dependence; enables cross-structure, cross-valence comparison. |\n", - "| `disordered` | `True` if any site in the structure has mixed occupancy. MAPLE calculated using mean-field charge approximation. |\n", + "| `disordered` | `True` if any site is shared by more than one species or partly occupied (`disorder_status` says which). MAPLE calculated using mean-field charge approximation. |\n", "| `mixed_site` | `True` for individual sites with mixed occupancy. The `element` column reports the majority species; `oxidation_state` reports the occupancy-weighted mean charge. |\n", "\n", - "**Diagnostic plots** (saved to `outputs/` as PNG):\n", + "**Diagnostic plots** (saved to the same folder, as PNG):\n", "\n", "| Plot | What it shows | What to look for |\n", "|------|---------------|------------------|\n", @@ -1643,24 +2029,19 @@ "cell_type": "code", "execution_count": null, "id": "3f1ffba3-cac5-4a14-9e1a-5498161d7ec0", - "metadata": { - "jupyter": { - "source_hidden": true - } - }, + "metadata": {}, "outputs": [], "source": [ "# 8. Diagnostic Plots\n", "# ─────────────────────────────────────────────────────────────────────────────\n", "#\n", - "# Run this cell AFTER running the GUI (Section 7).\n", - "# It reads maple_summary.csv and maple_failed.csv from the outputs directory\n", - "# and generates three diagnostic plots, saved as PNG to the same directory.\n", + "# Run this cell AFTER a run: either the GUI (Section 7) or batch_maple()\n", + "# (Section 5). It reads maple_summary.csv, maple_results.csv and\n", + "# maple_failed.csv from that run and writes three PNGs beside them.\n", "#\n", - "# INSTRUCTIONS:\n", - "# 1. Set OUTPUT_DIR below to the 'outputs' folder created by the GUI.\n", - "# (Copy the path printed by the GUI: \"Output directory: ...\")\n", - "# 2. Run this cell.\n", + "# Nothing to set. Both entry points record where they wrote in\n", + "# LAST_OUTPUT_DIR, and this cell reads it. To plot an OLDER run instead, put\n", + "# its CIF folder in CIF_DIR below.\n", "\n", "import matplotlib.pyplot as plt\n", "import matplotlib.ticker as mticker\n", @@ -1668,30 +2049,46 @@ "import pandas as pd\n", "from pathlib import Path\n", "\n", - "# ── SET THIS PATH ─────────────────────────────────────────────────────────────\n", - "# Point to the PARENT folder containing your CIFs (the one with outputs_*\n", - "# subdirectories). The cell will automatically find the most recent run.\n", - "# Example: r\"path/to/your/cifs\"\n", + "# ── Which run to plot ─────────────────────────────────────────────────────────\n", + "#\n", + "# v1.3.1: this line used to be a literal path to another machine's Downloads\n", + "# folder, and the error it raised named the wrong cause - it reported that the\n", + "# folder held no outputs_* when the folder itself was not there.\n", + "#\n", + "# Leave CIF_DIR as None to plot the run made in this kernel. Set it to the\n", + "# folder holding your CIFs (the one containing outputs_* subdirectories), or\n", + "# to an outputs_* folder itself, to plot an earlier run.\n", "CIF_DIR = None\n", "# ──────────────────────────────────────────────────────────────────────────────\n", "\n", - "if CIF_DIR is None:\n", - " raise ValueError(\"Set CIF_DIR above to the folder holding your CIFs \"\n", - " \"(the one with the outputs_* subdirectories).\")\n", - "cif_dir = Path(CIF_DIR)\n", - "output_dirs = sorted(cif_dir.glob('outputs_*'), reverse=True)\n", - "if output_dirs:\n", - " output_dir = output_dirs[0]\n", - " print(f\"Using most recent output: {output_dir.name}\")\n", - "else:\n", - " # Fall back to plain 'outputs' from older runs\n", - " output_dir = cif_dir / 'outputs'\n", - " if not output_dir.exists():\n", + "if CIF_DIR:\n", + " cif_dir = Path(CIF_DIR)\n", + " if not cif_dir.is_dir():\n", " raise FileNotFoundError(\n", - " f\"No outputs_* folders found in {cif_dir}.\\n\"\n", - " f\"Run the GUI (Section 7) first.\"\n", - " )\n", - " print(f\"Using: {output_dir}\")\n", + " f\"CIF_DIR is not a folder on this machine: {cif_dir}\\n\"\n", + " f\"Set CIF_DIR to a folder that exists here, or set it to None to \"\n", + " f\"plot the run made in this kernel.\")\n", + " runs = sorted(cif_dir.glob('outputs_*'), reverse=True)\n", + " if runs:\n", + " output_dir = runs[0]\n", + " elif (cif_dir / 'outputs').is_dir():\n", + " output_dir = cif_dir / 'outputs' # a pre-timestamp run\n", + " elif (cif_dir / 'maple_summary.csv').exists():\n", + " output_dir = cif_dir # CIF_DIR IS the outputs folder\n", + " else:\n", + " raise FileNotFoundError(\n", + " f\"{cif_dir} exists but holds no run: no outputs_* folder, no \"\n", + " f\"outputs/ folder and no maple_summary.csv.\\n\"\n", + " f\"Run Section 7 or batch_maple() first.\")\n", + "elif globals().get('LAST_OUTPUT_DIR') is not None:\n", + " output_dir = Path(LAST_OUTPUT_DIR)\n", + "else:\n", + " raise RuntimeError(\n", + " \"No run to plot. Either run the GUI (Section 7) or batch_maple() \"\n", + " \"(Section 5) in this kernel, or set CIF_DIR above to the folder \"\n", + " \"holding an earlier run's CIFs.\")\n", + "\n", + "print(f\"Plotting: {output_dir}\")\n", "\n", "# ── Sheffield brand colours ───────────────────────────────────────────────────\n", "SHEFFIELD = {\n", @@ -1735,7 +2132,9 @@ "if not summary_csv.exists():\n", " raise FileNotFoundError(\n", " f\"No maple_summary.csv found in {output_dir}.\\n\"\n", - " f\"Run the GUI (Section 7) first, then set OUTPUT_DIR above.\"\n", + " f\"That folder is a run directory but the summary is missing: the run \"\n", + " f\"processed no structures, or it was made by MaplePy before v1.3.1, \"\n", + " f\"whose batch_maple() did not write one.\"\n", " )\n", "\n", "df_summary = pd.read_csv(summary_csv)\n", @@ -1934,10 +2333,11 @@ "\n", "### Limitations\n", "\n", - "**Disorder:** Mixed-occupancy sites are not handled. `pymatgen`'s `EwaldSummation`\n", - "requires integer oxidation states at each site. The correct extension is a mean-field\n", - "approximation: compute the weighted-average charge at each mixed site, analogous\n", - "to the WAGII extension of GII for BVS (Reeves-McLaren 2025, *Acta Cryst. B*).\n", + "**Disorder:** a site shared by more than one species, or partly occupied, carries the\n", + "occupancy-weighted mean charge of its species (a mean-field approximation; Section 1),\n", + "and the structure is flagged `disordered`, with the kind of disorder and the sublattice\n", + "it is on. The approximation smooths the electrostatic landscape of the ordered\n", + "configurations it stands for.\n", "\n", "**Molecular anions:** The additivity theorem breaks down for compounds containing\n", "molecular-like anions (SO₄²⁻, PO₄³⁻, CO₃²⁻ etc.) where covalent bonding within\n", @@ -1950,7 +2350,7 @@ "explain most discrepancies between calculated and Hoppe's MAPLE values.\n", "\n", "### Integration with Eir\n", - "- Eir v1.4.2 uses gemmi for CIF parsing; MaplePy uses pymatgen.\n", + "- Eir reads CIFs with gemmi; MaplePy reads them with pymatgen.\n", "- Integration path: add a `--maple` flag to Eir CLI that calls `compute_maple()`\n", " and appends MAPLE columns to the existing site-level CSV output.\n", "- Column names follow Eir conventions: `lowercase_snake_case`, `_kcal_mol` suffix.\n", @@ -1962,30 +2362,22 @@ "- BVS vs MAPLE correlation analysis for systematic parameter inadequacy diagnosis\n", "\n", "### Citation\n", - "When publishing results calculated with MaplePy:\n", - "> MAPLE calculations were performed using MaplePy (Reeves-McLaren, N., 2026),\n", - "> following the formalism of Hoppe (1966, *Angew. Chem. Int. Ed.* **5**, 95)\n", - "> and Hoppe (1995, *Z. Naturforsch. A* **50**, 555)." + "When publishing results calculated with MaplePy, cite the release you used (its DOI\n", + "is in `CITATION.cff`) and the paper describing the method (Reeves-McLaren and Gross,\n", + "*J. Appl. Cryst.*, under review), and name the version (`MAPLEPY_VERSION`). The\n", + "formalism is that of Hoppe (1966, *Angew. Chem. Int. Ed.* **5**, 95) and Hoppe\n", + "(1995, *Z. Naturforsch. A* **50**, 555)." ] } ], "metadata": { "kernelspec": { - "display_name": "Python (materials_analysis_env)", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "materials_analysis_env" + "name": "python3" }, "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.9.23" + "name": "python" } }, "nbformat": 4, diff --git a/README.md b/README.md index 0d7ec1f..b15973e 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,172 @@ # MaplePy -**MAPLE (Madelung Part of Lattice Energy) from crystallographic information files, and a test of Hoppe's additivity theorem at database scale.** +**MAPLE (Madelung Part of Lattice Energy) from CIF files, and Hoppe's additivity theorem tested at database scale.** -> **Status.** This repository holds the two notebooks as they were uploaded on 21st May 2026. They are unversioned and predate the versions used for the manuscript below (MaplePy 1.3.6 and Hopper 1.2.8). Those versions will be released here as a tested, installable package with a Zenodo DOI. Until then, treat these notebooks as a record of the method in May 2026, not as the code behind the manuscript's numbers. +[](LICENSE) + + +[](https://github.com/SuperBladesman/MaplePy/actions/workflows/tests.yml) -## What is here +MaplePy reads a folder of CIF files and computes the electrostatic (Madelung) part of the lattice energy of each structure, per site and in total, with the Ewald summation in *pymatgen*. Hopper takes the results and asks of each ternary oxide whether its MAPLE equals the weighted sum of its binary oxides, as Hoppe's additivity theorem predicts to within about 1%, and, where it does not, why not. -| File | What it is | +The second question is the hard one. A residual above 1% can mean covalency the point-charge model cannot see; it can equally mean a wrong oxidation state, a disorder model averaged into one charge, a binary oxide that does not exist, or coordinates that no ionic solid could have. Hopper separates these into twelve codes in three tiers, so that a residual is interpreted rather than merely reported. + +Both tools were written for a study of 1,410 perovskite and pyrochlore structures from the Inorganic Crystal Structure Database (ICSD), now under review at *J. Appl. Cryst.* This release, maplepy 1.4.0, runs the versions behind that study: MaplePy 1.3.6, unchanged, and Hopper 1.2.9, which adds one column to 1.2.8. Run on the study's MaplePy results, it reproduces the classification of all 1,410 structures. + +## What MaplePy reports + +For each structure: MAPLE per formula unit (kcal/mol), the Madelung factor, the reference distance *d*ref (the shortest cation–anion distance), *Z*, and for each site its MAPLE, partial Madelung constant and reduced MAPLE. Four decisions come before the sum, and each is recorded beside the result. + +| Decision | How MaplePy makes it | |---|---| -| `MaplePy.ipynb` | Computes per-site and total MAPLE values from CIF files with the Ewald summation in *pymatgen*, for one structure or a folder of them | -| `Hopper.ipynb` | Reads MaplePy's CSV output, decomposes each ternary oxide into its binary oxides, computes the additivity residual and classifies each structure | -| `binary_oxide_maple_reference.json` | 112 reference MAPLE values for binary oxides, in kcal/mol per formula unit (CC-BY 4.0) | +| **Oxidation states** | In order: states you give; the per-site states in the CIF; the CIF's `_atom_type_oxidation_number` loop; a formula override in `data/maple_library.json`; a single common state per element. If none settles it, MaplePy stops and names the elements, rather than guessing. Which source was used is printed for every structure. | +| ***Z*** | The greatest common divisor of the number of sites holding each element, not the reduced composition, which returns *Z* = 1 for a non-stoichiometric refinement and inflates MAPLE per formula unit by the true *Z*. | +| **Disorder** | A shared or partly occupied site carries the occupancy-weighted mean charge of its species. The structure is flagged, with the kind of disorder and the sublattice it is on. | +| **Geometry** | The shortest contact in the cell, *d*min, is written for every structure. Below 0.5 Å two sites are one position split by a disorder model, and the Ewald sum over them is not an energy (`split_site`); below 1.6 Å the contact is shorter than any cation–anion bond these families produce (`short_contact`). The first threshold sits in an empty band of the measured distribution; the second is a judgement, and the code says so. | + +MaplePy never edits a structure. Versions before 1.3.6 corrected an origin-choice artefact of the O2 sublattice in space group 62 (*Pnma*), choosing between two candidate structures by their Ewald energy, the quantity under test. It changed 44 of 938 perovskites, and in none of them turned a failing geometry into a sound one, so 1.3.6 removed it; a structure that cannot carry a Madelung energy is now reported, not repaired. The record of that decision is in the notebook, where the function used to be. + +## What Hopper reports + +Hopper decomposes each structure into binary oxides from the per-site oxidation states (ABO3 with two trivalent cations becomes ½ A2O3 + ½ B2O3; a 2+/4+ pair becomes AO + BO2), checks that the oxygen balances, and computes Δ = |MAPLE(ternary) − Σ MAPLE(binaries)| / MAPLE(ternary). Every structure then gets one code. + +| Code | Tier | Meaning | +|---|---|---| +| Additive | 0 | Δ < 1% | +| 1.1 | 1 | The binary oxide exists and the reference table lacks it | +| 1.2 | 1 | MaplePy could not compute a MAPLE value (listed in `maple_failed.csv`, so always zero here) | +| 1.3 | 1 | The oxidation state is real and has no ambient binary oxide (Fe(IV), Co(IV), ...) | +| 1.4 | 1 | The charge asked for is not an oxidation state: a mean over a shared or disproportionated site | +| 2.1 | 2 | Δ > 10% in an ordered, oxygen-balanced structure: an oxidation state is probably wrong | +| 2.2 | 2 | *Z* taken as 1 when the cell holds more (cannot arise from MaplePy; kept for other calculators) | +| 2.3 | 2 | Cation disorder, through the mean-field approximation | +| 2.4 | 2 | The oxygen of the decomposition does not balance (Co3O4 standing in for Co2O3) | +| 2.5 | 2 | Coordinate error: *d*min < 1.6 Å, or a spread of oxygen-site MAPLE values (CV > 0.05) that no sound *Pnma* perovskite has | +| 2.6 | 2 | Anion vacancies: fractional occupancy on the anion sublattice only | +| 2.7 | 2 | Split-site disorder model: two sites closer than 0.5 Å | +| 3.1 | 3 | Δ ≥ 1% with nothing above to explain it: a genuine violation | + +Tier 1 has no residual to interpret, Tier 2 has one that should not be taken at face value, and Tier 3 has one that should. The codes are assigned in a fixed order, built on one rule: a caveat must not mask a defect. So Tier 1 comes first; then the structural defects, 2.7 and then 2.5, whatever the residual; then the additive test; then the other Tier 2 caveats; then 3.1. A disordered structure that agrees with its binaries is additive; a structure with impossible coordinates is 2.5 even when its residual is small. + +From Hopper 1.2.9, every decomposition that uses an estimated or unsourced reference value says which (`estimated_binaries`). Nothing is reclassified on that account. + +## Getting started + +You need Python 3.11 or later. MaplePy is tested on Linux with Python 3.11 to 3.13 under pandas 2 and 3, and on Windows and macOS with Python 3.13. + +```bash +pip install "git+https://github.com/SuperBladesman/MaplePy.git@v1.4.0" +maplepy --validate +``` + +`--validate` runs the notebook's three known answers: NaCl (partial Madelung constants 0.8738 and Madelung factor 1.7476; Hoppe, 1966), rutile and anatase TiO2 against Hoppe (1995), and BaTiO3 additive to within 1% (Hoppe, 1995; MaplePy gives 0.348%). + +### One structure + +```bash +maplepy examples/BaTiO3_cubic.cif +``` -There is no Python package here yet: the notebooks are run cell by cell, and the `from maplepy import ...` interface that an earlier version of this README described does not exist. +``` +BaTiO3_cubic.cif · BaTiO3 · Pm-3m + + MAPLE 4108.22 kcal/mol per formula unit (17188.8 kJ/mol) + Madelung factor 4.1259 + Z, d_ref 1, 2.0009 Å + Geometry ok: shortest contact 2.001 A + Disorder ordered + Oxidation states (CIF (per-site, charge-neutral)): Ba=+2, O=-2, Ti=+4 +``` + +Most Rietveld programs write element symbols without charges, and MaplePy does not guess where the chemistry is ambiguous. Give the states with `--ox`: + +```bash +maplepy examples/SrFeO3_no_states.cif --ox Sr=2,Fe=4,O=-2 +``` + +### A folder, then Hopper + +```bash +maplepy examples/ # writes examples/outputs_YYYYMMDD_HHMMSS/ +hopper examples/ # reads the latest run and classifies it +``` -## MAPLE and the additivity theorem +`maplepy FOLDER` runs the notebook's `batch_maple()` on every file ending `.cif` in the folder (lower case, and not in subfolders), on several processes where there are several cores (`--workers 1` for serial; the results are identical). `--plots` draws the notebook's three diagnostic plots; `--additivity` runs Hopper straight after. `hopper RESULTS --figures` draws the paper's figures into the run folder too, and says which, if any, the data cannot support. -MAPLE is the electrostatic contribution to the lattice energy of an ionic crystal, computed from the Ewald sum over the full three-dimensional charge distribution. Bond valence sums assess local bonding geometry; MAPLE depends on the long-range electrostatic environment of every ion. Hoppe's additivity theorem predicts that the MAPLE of a ternary oxide equals the weighted sum of the MAPLE values of its binary oxides, typically to within 1%. +The examples are constructed structures, none from the ICSD: the validation structures as CIFs, SrTiO3, an idealised pyrochlore, a disordered (Ba,Sr)TiO3, BaTiO3 with its lattice parameter mistyped (Hopper: 2.5), and SrFeO3 without oxidation states (MaplePy stops and asks). [examples/make_examples.py](examples/make_examples.py) writes them. -## MaplePy.ipynb (May 2026) +### From Python -- MAPLE per formula unit, per-site MAPLE, partial Madelung constants, reduced MAPLE and the Madelung factor, from pymatgen's `EwaldSummation`; -- oxidation states from a priority chain that raises an error rather than assigning a charge it cannot justify; -- a mean-field charge on sites shared by more than one species; -- a correction for an origin-choice artefact of the O2 sublattice in space group 62 (*Pnma*); -- batch processing: `batch_maple()` writes `maple_results.csv` and `maple_failed.csv`, and the GUI cell (Section 7), which takes a hand-picked set of CIFs, also writes the `maple_summary.csv` that Hopper reads, each to a timestamped folder beside the CIFs; -- three validation calculations: NaCl (Madelung factor 1.7476; Hoppe, 1966), rutile and anatase TiO₂, and the additivity of BaTiO₃ to within 1% (Hoppe, 1995). +```python +import maplepy -Two limitations of this copy matter. The oxidation-state chain looks for `maple_library.json` and `common_oxidation_states.json`, which are not in the repository, so for a CIF without oxidation states it stops and asks for them. And this version takes the number of formula units per cell, *Z*, from the reduced composition, which returns *Z* = 1 for many non-stoichiometric refinements and inflates MAPLE per formula unit by the true *Z*. Later versions take *Z* from the site multiplicities, and no longer apply the space group 62 correction; both changes will be documented with the release. +r = maplepy.compute('examples/BaTiO3_cubic.cif') +r.total_maple, r.madelung_factor, r.geometry_flag # (4108.22, 4.1259, 'ok') +r.sites # the per-site table -To run it: +run = maplepy.run_folder('my_cifs/') # MaplePy's batch_maple() +df = maplepy.additivity(run) # Hopper on that run +df['classification'].value_counts() +``` + +`maplepy.engine()` and `maplepy.hopper_engine()` give every function the two notebooks define (`load_structure`, `compute_maple`, `decompose_ternary`, `classify_additivity`, ...), with the notebooks' behaviour. + +### The notebooks + +`MaplePy.ipynb` and `Hopper.ipynb` are the source of the code, and still run as before: ```bash git clone https://github.com/SuperBladesman/MaplePy.git cd MaplePy -pip install pymatgen numpy pandas matplotlib jupyterlab +pip install -r requirements.txt jupyterlab jupyter lab MaplePy.ipynb ``` -Run the three validation sections first. The GUI cell (Section 7) opens a Tk file dialog; the diagnostic plots (Section 8) need `CIF_DIR` set to the folder you processed. +The package is built from their cells by `tools/build_engine.py`, and the tests fail if the two drift apart; [docs/PACKAGE.md](docs/PACKAGE.md) explains how. + +## Output files -## Hopper.ipynb (May 2026) +| File | Written by | One row per | +|---|---|---| +| `maple_results.csv` | MaplePy | site, in every structure: element, oxidation state, fractional coordinates, MAPLE, partial Madelung constant, reduced MAPLE | +| `maple_summary.csv` | MaplePy | structure: MAPLE, Madelung factor, *d*ref, *Z*, disorder, *d*min, geometry flag, MaplePy version | +| `maple_failed.csv` | MaplePy | CIF that could not be processed, with the reason | +| `additivity_classified.csv` | Hopper | structure: binary sum, Δ, oxygen balance, missing and estimated binaries, code, tier, label, Hopper version | -Hopper reads `maple_summary.csv` and `maple_results.csv`, decomposes each structure into binary oxides using the per-site oxidation states, and reports the residual Δ = |MAPLE(ternary) − Σ MAPLE(binaries)| / MAPLE(ternary). Each structure is then classified: additive (Δ < 1%), or one of six codes in three tiers, with three more numbered and reserved (Tier 1, the decomposition is incomplete; Tier 2, the residual exists but an artefact bears on it; Tier 3, a genuine violation). The version used for the manuscript has twelve codes; the release will document the scheme in full. +Hopper also writes two subsets, chosen by space group alone: `additivity_perovskites.csv` (nine space groups, *Pnma* among them) and `additivity_pyrochlores.csv` (*Fd*3̄*m* and *Fm*3̄*m*, so a rock-salt oxide lands among the pyrochlores). `binary_oxide_reference.csv` is the notebook's inline table of 104 binaries; the values Hopper used are those of the 112-entry table below, which agrees with the inline table wherever both hold a formula (Hopper stops if they do not). -## The reference table +## The binary oxide reference table -`binary_oxide_maple_reference.json` holds 112 binary oxides. Of these, 88 are medians of MaplePy values over qualifying entries in the Inorganic Crystal Structure Database (ICSD) at ambient conditions, given with the number of entries and their range; 23 are estimates by interpolation within a structure type and carry no source; and 1 comes from a MaplePy validation structure. The file's own metadata still cites an earlier submission of the manuscript; that, and its entry counts, will be corrected with the release. +[data/binary_oxide_maple_reference.json](data/binary_oxide_maple_reference.json) contains 112 binary oxides. 88 values are medians of MaplePy MAPLE over qualifying ICSD entries at ambient conditions (273–303 K, < 0.15 MPa), each with the number of entries and their range; 23 are estimates, interpolated within a structure type or set by hand, with no published or computed source (`"sourced": false`); 1, Cu2O, was recorded as a MaplePy validation value and does not reproduce (MaplePy gives 797.9 kcal/mol for cuprite, not 730.0), so it is marked unsourced too. The table contains derived statistics only: no coordinates and no CIF content. It is released under CC-BY 4.0. Three entries carry a note saying they need re-deriving: CuO and ZnO, which rest on high-pressure rock-salt phases, and Cu2O. [data/README.md](data/README.md) describes the three data files. -No ICSD CIF files are, or will be, distributed here. +## Limitations + +- **Oxides.** The anion is identified by the sign of its charge, and by oxygen where no charges are yet assigned; the reference table and Hopper's decompositions are for oxides only. +- **Molecular anions.** Where covalent groups (SO42−, PO43−) are present, the additivity theorem needs increments rather than molecular binary oxides; Hopper does not implement them. +- **Shared sites in Hopper.** A site shared by two cations is decomposed as its majority species, at the mean charge. Such structures are flagged (2.3, or 1.4 where the mean is not an oxidation state), but their residuals are against an approximate sum. +- **Estimates.** In the study, 82 of the 1,380 decomposed structures rest on an estimated value (none on Cu2O), 43 of them on Ni2O3, which has no ambient phase to measure. `estimated_binaries` names them. +- **A user-supplied binary table.** Hopper's `BINARY_CSV` option reads your own binary values, but the bundled table then overrides any formula it also holds. To use your own values throughout, edit or replace the JSON. + +## Tests + +`maplepy --validate` runs the notebook's own validation. The test suite (`pytest`) asserts the three sourced targets independently, then tests each decision above on constructed structures, the classification of the examples, the command lines, the agreement of the package's cells with the notebooks, and the release metadata. On every push, CI runs it on Linux with Python 3.11, 3.12 and 3.13 under pandas 2 and 3, and on Windows and macOS with Python 3.13. [tools/equivalence.py](tools/equivalence.py) runs both notebooks headless on a folder of CIFs and compares their output with the package's, file by file and cell by cell. + +No ICSD file is distributed here or used in the tests. ICSD CIFs are licensed by FIZ Karlsruhe. ## Citation -The manuscript describing the method and its application to 1,410 perovskite and pyrochlore structures is under review: +If you use MaplePy or Hopper, please cite the release you used (`CITATION.cff`; GitHub's "Cite this repository" reads it) and the paper describing the method: > N. Reeves-McLaren and P. Gross, "Database-Scale Validation of Hoppe's MAPLE Additivity Theorem for Perovskite and Pyrochlore Oxides", *J. Appl. Cryst.*, under review. -`CITATION.cff` gives the same details in machine-readable form, and GitHub's "Cite this repository" reads it. +## Contributing + +A structure MaplePy or Hopper gets wrong is the most useful report there is. [CONTRIBUTING.md](CONTRIBUTING.md) says what to include, and how to change the code. -## Acknowledgements +## Acknowledgements and AI disclosure -MaplePy and Hopper were developed with an AI coding assistant (Claude, Anthropic). Scientific interpretation and validation were carried out by the authors. +MaplePy and Hopper were developed with one generative AI tool, Claude (Anthropic). Nik Reeves-McLaren framed the problems and made the design decisions; Claude wrote the code to that specification; every change was audited, and correctness was checked independently of the code, against Hoppe's published values and by manual review of the structures flagged in the study. ## Licence -Code: MIT ([LICENSE](LICENSE)). Binary oxide reference table: CC-BY 4.0. +Code: MIT ([LICENSE](LICENSE)). The data tables in `data/`, the binary oxide reference table among them: CC-BY 4.0. diff --git a/data/README.md b/data/README.md new file mode 100644 index 0000000..123b385 --- /dev/null +++ b/data/README.md @@ -0,0 +1,31 @@ +# Reference data + +MaplePy and Hopper read three files from this folder. The notebooks find it as `data/` beside them; the package carries a copy. + +| File | Read by | What it holds | Licence | +|---|---|---|---| +| `binary_oxide_maple_reference.json` | Hopper | MAPLE of 112 binary oxides, kcal/mol per formula unit, with how each was determined | CC-BY 4.0 | +| `maple_library.json` | MaplePy | Formula overrides for oxidation states (level 4 of the chain); Hoppe's reference values and isostructural constants, for reference | CC-BY 4.0 | +| `common_oxidation_states.json` | MaplePy | Common oxidation states of 80 elements (level 5 of the chain: used only where an element has one) | CC-BY 4.0 | + +## binary_oxide_maple_reference.json + +Each entry gives the formula, the value, the structure type and space group, and `source`: + +- `icsd_median` (88 entries): the median MAPLE that MaplePy computes over qualifying entries of the Inorganic Crystal Structure Database at ambient conditions (273–303 K, < 0.15 MPa), excluding high-pressure entries (identified by anomalously short *d*ref), failed calculations and non-stoichiometric compositions. `n_icsd_entries`, `icsd_range_min` and `icsd_range_max` give the number of entries and their range. The median is used for its robustness to the occasional misindexed entry. +- `estimated` (23 entries): interpolated within a structure type family, or set by hand. These have no published or computed source, and say so (`"sourced": false`). They are kept so that results made with them can be reproduced, and Hopper reports every decomposition that uses one. +- `validation` (1 entry): Cu2O, recorded as a MaplePy validation value. It does not reproduce: MaplePy gives 797.9 kcal/mol for cuprite at *a* = 4.270 Å, not 730.0. It is marked `"sourced": false`, with a review note, and kept so that results can be reproduced; no structure in the study uses it. + +`confidence` is `high` for a median over 10 or more entries, `medium` for 2 to 9 entries, and `low` for an estimate, a single entry, or an entry flagged for re-deriving (`review_note`). + +The table contains derived statistics only: no coordinates, and no content of any CIF. Eight of the 112 entries are molecular or non-metal oxides (SO3, P2O5, B2O3, As2O5, Sb2O3, SeO3, Cl2O7, H2O), added for work beyond perovskites and pyrochlores; Hopper's inline fallback table has the other 104, and the notebook stops if a value ever differs between the two. + +### Versions + +- **1.1.1** (this release): the citation names the journal the manuscript is under review at (it named an earlier submission); each entry says whether it has a source that reproduces (`sourced`); CuO, ZnO and Cu2O are marked for re-deriving, with their confidence lowered from medium to low, and Cu2O is marked unsourced. No value has changed. +- **1.1.0** (24th August 2026): entry counts and source classifications computed from the entries, rather than written by hand. +- **1.0.0** (21st May 2026): the first release, uploaded with the notebooks. + +## Changing the data + +A new or changed value needs a source: the ICSD query and the run that produced a median, or a published value. Change the JSON, raise its version, describe the change above and in `CHANGELOG.md`, and run the tests, which check that Hopper's inline table and the JSON still agree. Never commit the CIFs a median was computed from. diff --git a/binary_oxide_maple_reference.json b/data/binary_oxide_maple_reference.json similarity index 77% rename from binary_oxide_maple_reference.json rename to data/binary_oxide_maple_reference.json index 57024ae..dfc9b63 100644 --- a/binary_oxide_maple_reference.json +++ b/data/binary_oxide_maple_reference.json @@ -2,7 +2,7 @@ "_metadata": { "title": "Binary Oxide MAPLE Reference Table", "description": "Reference MAPLE (Madelung Part of Lattice Energy) values for binary oxides, for use with Hoppe's additivity theorem. Values are in kcal/mol per formula unit.", - "version": "1.0.0", + "version": "1.1.1", "authors": [ "Peter Gross", "Nik Reeves-McLaren" @@ -15,17 +15,18 @@ }, "methodology": { "icsd_calibrated": "Median MAPLE across qualifying ICSD entries at ambient conditions (273-303 K, <0.15 MPa). High-pressure entries, zero-MAPLE entries, and non-stoichiometric compositions excluded.", - "validation": "Values from MaplePy benchmark calculations (NaCl, TiO2, BaTiO3).", - "estimated": "Interpolated from chemical trends within structure type families (e.g., lanthanide contraction in bixbyite RE2O3 series). These carry additional uncertainty and should be updated when ICSD data become available." + "validation": "Recorded as a MaplePy validation calculation. The one entry so marked, Cu2O, does not reproduce (MaplePy gives 797.9 kcal/mol at a = 4.270 A) and is marked sourced: false.", + "estimated": "Interpolated from chemical trends within structure type families (e.g., lanthanide contraction in bixbyite RE2O3 series), or set by hand. These have no published or computed source (sourced: false), carry additional uncertainty, and should be replaced when a source becomes available. Hopper 1.2.9 and later report every decomposition that uses one." }, "source_classifications": { - "icsd_median": "Calibrated from ICSD median (61% of entries, 65 of 107)", - "validation": "From MaplePy validation structures (5% of entries, 5 of 107)", - "estimated": "Interpolated or estimated (35% of entries, 37 of 107)" + "icsd_median": "Calibrated from ICSD median (88 of 112, 79%)", + "estimated": "Interpolated or estimated, with no published or computed source (23 of 112, 21%)", + "validation": "From a MaplePy validation structure (1 of 112, 1%); does not reproduce, so unsourced" }, "n_entries": 112, "licence": "CC-BY-4.0", - "citation": "Gross, P.; Reeves-McLaren, N. Angew. Chem. Int. Ed., 2026 (submitted)" + "citation": "Reeves-McLaren, N.; Gross, P. Database-Scale Validation of Hoppe's MAPLE Additivity Theorem for Perovskite and Pyrochlore Oxides. J. Appl. Cryst., under review (2026).", + "metadata_note": "v1.1.1: the citation names the journal the manuscript is under review at; each entry says whether its value has a source that reproduces (sourced); CuO, ZnO and Cu2O carry a review note; n_entries and source_classifications are computed from the entries list. No value has changed since v1.0.0." }, "_field_descriptions": { "formula": "Reduced chemical formula of the binary oxide", @@ -35,7 +36,9 @@ "n_icsd_entries": "Number of qualifying ICSD entries used for the median (null if estimated)", "icsd_range_min": "Minimum MAPLE across qualifying ICSD entries (null if estimated)", "icsd_range_max": "Maximum MAPLE across qualifying ICSD entries (null if estimated)", - "confidence": "high = ICSD median from >= 10 entries; medium = ICSD median from 2-9 entries or validation; low = estimated/interpolated" + "confidence": "high = ICSD median from >= 10 entries; medium = ICSD median from 2-9 entries; low = estimated, a single entry, or a source that does not reproduce", + "sourced": "false where the value has no published or computed source, or where its recorded source does not reproduce", + "review_note": "Present where the entry needs re-deriving; states why" }, "entries": [ { @@ -46,7 +49,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Al2O3", @@ -56,7 +60,8 @@ "n_icsd_entries": 68, "icsd_range_min": 4250, "icsd_range_max": 4369, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "AmO2", @@ -66,7 +71,8 @@ "n_icsd_entries": 5, "icsd_range_min": 2867, "icsd_range_max": 2876, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "As2O5", @@ -76,7 +82,8 @@ "n_icsd_entries": 3, "icsd_range_min": 9681, "icsd_range_max": 9685, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "B2O3", @@ -86,7 +93,8 @@ "n_icsd_entries": 10, "icsd_range_min": 4931, "icsd_range_max": 5256, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "BaO", @@ -96,7 +104,8 @@ "n_icsd_entries": 4, "icsd_range_min": 838, "icsd_range_max": 842, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Bi2O3", @@ -106,7 +115,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Bi2O5", @@ -116,7 +126,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "CaO", @@ -126,7 +137,8 @@ "n_icsd_entries": 15, "icsd_range_min": 964, "icsd_range_max": 972, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "CdO", @@ -136,7 +148,8 @@ "n_icsd_entries": 14, "icsd_range_min": 982, "icsd_range_max": 992, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Ce2O3", @@ -146,7 +159,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "CeO2", @@ -156,7 +170,8 @@ "n_icsd_entries": 64, "icsd_range_min": 2796, "icsd_range_max": 2891, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Cl2O7", @@ -166,7 +181,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "CmO2", @@ -176,7 +192,8 @@ "n_icsd_entries": 2, "icsd_range_min": 2877, "icsd_range_max": 2882, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Co3O4", @@ -186,7 +203,8 @@ "n_icsd_entries": 26, "icsd_range_min": 5020, "icsd_range_max": 5508, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "CoO", @@ -196,7 +214,8 @@ "n_icsd_entries": 22, "icsd_range_min": 1086, "icsd_range_max": 1100, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Cr2O3", @@ -206,7 +225,8 @@ "n_icsd_entries": 21, "icsd_range_min": 4159, "icsd_range_max": 4190, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "CrO2", @@ -216,7 +236,8 @@ "n_icsd_entries": 14, "icsd_range_min": 3346, "icsd_range_max": 3424, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "CrO3", @@ -226,7 +247,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Cs2O", @@ -236,7 +258,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Cu2O", @@ -246,7 +269,9 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "low", + "sourced": false, + "review_note": "Recorded as a MaplePy validation value, but MaplePy gives 797.9 kcal/mol for cuprite at a = 4.270 A (Cu-O 1.849 A), not 730.0. The value is kept so that results can be reproduced; it needs re-deriving from ambient ICSD entries." }, { "formula": "CuO", @@ -256,7 +281,9 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "low", + "sourced": true, + "review_note": "The ambient phase of CuO is tenorite (C2/c), not rock salt, and this value rests on a single ICSD entry of a high-pressure rock-salt phase. Needs re-deriving." }, { "formula": "Dy2O3", @@ -266,7 +293,8 @@ "n_icsd_entries": 10, "icsd_range_min": 3624, "icsd_range_max": 3646, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Er2O3", @@ -276,7 +304,8 @@ "n_icsd_entries": 10, "icsd_range_min": 3655, "icsd_range_max": 3689, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Eu2O3", @@ -286,7 +315,8 @@ "n_icsd_entries": 6, "icsd_range_min": 3559, "icsd_range_max": 3630, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "EuO", @@ -296,7 +326,8 @@ "n_icsd_entries": 9, "icsd_range_min": 901, "icsd_range_max": 904, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Fe2O3", @@ -306,7 +337,8 @@ "n_icsd_entries": 53, "icsd_range_min": 4074, "icsd_range_max": 4207, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "FeO", @@ -316,7 +348,8 @@ "n_icsd_entries": 5, "icsd_range_min": 1073, "icsd_range_max": 1082, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Ga2O3", @@ -326,7 +359,8 @@ "n_icsd_entries": 3, "icsd_range_min": 4181, "icsd_range_max": 4198, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Gd2O3", @@ -336,7 +370,8 @@ "n_icsd_entries": 14, "icsd_range_min": 3573, "icsd_range_max": 3611, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "GeO2", @@ -346,7 +381,8 @@ "n_icsd_entries": 8, "icsd_range_min": 3386, "icsd_range_max": 3425, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "H2O", @@ -356,7 +392,8 @@ "n_icsd_entries": 32, "icsd_range_min": 256, "icsd_range_max": 1379, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "HfO2", @@ -366,7 +403,8 @@ "n_icsd_entries": 2, "icsd_range_min": 3016, "icsd_range_max": 3053, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "HgO", @@ -376,7 +414,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Ho2O3", @@ -386,7 +425,8 @@ "n_icsd_entries": 9, "icsd_range_min": 3641, "icsd_range_max": 3655, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "In2O3", @@ -396,7 +436,8 @@ "n_icsd_entries": 18, "icsd_range_min": 3793, "icsd_range_max": 3849, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "IrO2", @@ -406,7 +447,8 @@ "n_icsd_entries": 8, "icsd_range_min": 3221, "icsd_range_max": 3235, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "K2O", @@ -416,7 +458,8 @@ "n_icsd_entries": 2, "icsd_range_min": 599, "icsd_range_max": 600, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "La2O3", @@ -426,7 +469,8 @@ "n_icsd_entries": 11, "icsd_range_min": 3337, "icsd_range_max": 3436, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Li2O", @@ -436,7 +480,8 @@ "n_icsd_entries": 10, "icsd_range_min": 835, "icsd_range_max": 838, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Lu2O3", @@ -446,7 +491,8 @@ "n_icsd_entries": 12, "icsd_range_min": 3703, "icsd_range_max": 3735, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "MgO", @@ -456,7 +502,8 @@ "n_icsd_entries": 34, "icsd_range_min": 1092, "icsd_range_max": 1106, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Mn2O3", @@ -466,7 +513,8 @@ "n_icsd_entries": 10, "icsd_range_min": 4087, "icsd_range_max": 4155, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "MnO", @@ -476,7 +524,8 @@ "n_icsd_entries": 13, "icsd_range_min": 1036, "icsd_range_max": 1053, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "MnO2", @@ -486,7 +535,8 @@ "n_icsd_entries": 19, "icsd_range_min": 3332, "icsd_range_max": 3388, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Mo2O3", @@ -496,7 +546,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "MoO2", @@ -506,7 +557,8 @@ "n_icsd_entries": 2, "icsd_range_min": 3179, "icsd_range_max": 3180, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "MoO3", @@ -516,7 +568,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Na2O", @@ -526,7 +579,8 @@ "n_icsd_entries": 2, "icsd_range_min": 694, "icsd_range_max": 695, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Nb2O5", @@ -536,7 +590,8 @@ "n_icsd_entries": 2, "icsd_range_min": 8984, "icsd_range_max": 8992, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "NbO2", @@ -546,7 +601,8 @@ "n_icsd_entries": 3, "icsd_range_min": 3120, "icsd_range_max": 3154, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Nd2O3", @@ -556,7 +612,8 @@ "n_icsd_entries": 3, "icsd_range_min": 3495, "icsd_range_max": 3507, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Ni2O3", @@ -566,7 +623,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "NiO", @@ -576,7 +634,8 @@ "n_icsd_entries": 30, "icsd_range_min": 1052, "icsd_range_max": 1119, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "NpO2", @@ -586,7 +645,8 @@ "n_icsd_entries": 2, "icsd_range_min": 2843, "icsd_range_max": 2844, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "OsO2", @@ -596,7 +656,8 @@ "n_icsd_entries": 5, "icsd_range_min": 3205, "icsd_range_max": 3215, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "OsO3", @@ -606,7 +667,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "P2O5", @@ -616,7 +678,8 @@ "n_icsd_entries": 8, "icsd_range_min": 10123, "icsd_range_max": 10489, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "PbO", @@ -626,7 +689,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "PbO2", @@ -636,7 +700,8 @@ "n_icsd_entries": 11, "icsd_range_min": 2946, "icsd_range_max": 2959, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Pd2O", @@ -646,7 +711,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "PdO2", @@ -656,7 +722,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Pm2O3", @@ -666,7 +733,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Pr2O3", @@ -676,7 +744,8 @@ "n_icsd_entries": 2, "icsd_range_min": 3476, "icsd_range_max": 3476, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "PrO2", @@ -686,7 +755,8 @@ "n_icsd_entries": 5, "icsd_range_min": 2861, "icsd_range_max": 2872, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "PtO2", @@ -696,7 +766,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "PuO2", @@ -706,7 +777,8 @@ "n_icsd_entries": 3, "icsd_range_min": 2863, "icsd_range_max": 2864, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Rb2O", @@ -716,7 +788,8 @@ "n_icsd_entries": 2, "icsd_range_min": 572, "icsd_range_max": 573, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Re2O5", @@ -726,7 +799,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Re2O7", @@ -736,7 +810,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "ReO2", @@ -746,7 +821,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "ReO3", @@ -756,7 +832,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Rh2O3", @@ -766,7 +843,8 @@ "n_icsd_entries": 4, "icsd_range_min": 4024, "icsd_range_max": 4087, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "RhO2", @@ -776,7 +854,8 @@ "n_icsd_entries": 2, "icsd_range_min": 3261, "icsd_range_max": 3268, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Ru2O5", @@ -786,7 +865,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "RuO2", @@ -796,7 +876,8 @@ "n_icsd_entries": 17, "icsd_range_min": 3228, "icsd_range_max": 3252, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "RuO3", @@ -806,7 +887,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "SO3", @@ -816,7 +898,8 @@ "n_icsd_entries": 3, "icsd_range_min": 6992, "icsd_range_max": 7156, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Sb2O3", @@ -826,7 +909,8 @@ "n_icsd_entries": 14, "icsd_range_min": 3186, "icsd_range_max": 3730, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Sb2O5", @@ -836,7 +920,8 @@ "n_icsd_entries": 2, "icsd_range_min": 8955, "icsd_range_max": 8956, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "SbO2", @@ -846,7 +931,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Sc2O3", @@ -856,7 +942,8 @@ "n_icsd_entries": 8, "icsd_range_min": 3927, "icsd_range_max": 3966, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "SeO3", @@ -866,7 +953,8 @@ "n_icsd_entries": 3, "icsd_range_min": 6308, "icsd_range_max": 6367, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "SiO2", @@ -876,7 +964,8 @@ "n_icsd_entries": 42, "icsd_range_min": 3575, "icsd_range_max": 3664, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Sm2O3", @@ -886,7 +975,8 @@ "n_icsd_entries": 5, "icsd_range_min": 3541, "icsd_range_max": 3558, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "SnO2", @@ -896,7 +986,8 @@ "n_icsd_entries": 48, "icsd_range_min": 3071, "icsd_range_max": 3156, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "SrO", @@ -906,7 +997,8 @@ "n_icsd_entries": 11, "icsd_range_min": 898, "icsd_range_max": 906, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Ta2O5", @@ -916,7 +1008,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "TaO2", @@ -926,7 +1019,8 @@ "n_icsd_entries": 2, "icsd_range_min": 3130, "icsd_range_max": 3162, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Tb2O3", @@ -936,7 +1030,8 @@ "n_icsd_entries": 5, "icsd_range_min": 3592, "icsd_range_max": 3625, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "TbO2", @@ -946,7 +1041,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Tc2O7", @@ -956,7 +1052,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "TcO2", @@ -966,7 +1063,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "ThO2", @@ -976,7 +1074,8 @@ "n_icsd_entries": 15, "icsd_range_min": 2758, "icsd_range_max": 2770, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Ti2O3", @@ -986,7 +1085,8 @@ "n_icsd_entries": 12, "icsd_range_min": 4031, "icsd_range_max": 4066, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "TiO", @@ -996,7 +1096,8 @@ "n_icsd_entries": 8, "icsd_range_min": 1081, "icsd_range_max": 1113, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "TiO2", @@ -1006,7 +1107,8 @@ "n_icsd_entries": 112, "icsd_range_min": 3218, "icsd_range_max": 3505, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Tl2O", @@ -1016,7 +1118,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Tl2O3", @@ -1026,7 +1129,8 @@ "n_icsd_entries": 4, "icsd_range_min": 3663, "icsd_range_max": 3700, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "Tm2O3", @@ -1036,7 +1140,8 @@ "n_icsd_entries": 5, "icsd_range_min": 3691, "icsd_range_max": 3710, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "UO2", @@ -1046,7 +1151,8 @@ "n_icsd_entries": 25, "icsd_range_min": 2821, "icsd_range_max": 2854, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "V2O3", @@ -1056,7 +1162,8 @@ "n_icsd_entries": 14, "icsd_range_min": 4119, "icsd_range_max": 4924, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "V2O5", @@ -1066,7 +1173,8 @@ "n_icsd_entries": 17, "icsd_range_min": 9393, "icsd_range_max": 9638, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "VO", @@ -1076,7 +1184,8 @@ "n_icsd_entries": 9, "icsd_range_min": 1127, "icsd_range_max": 1143, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "VO2", @@ -1086,7 +1195,8 @@ "n_icsd_entries": 5, "icsd_range_min": 3284, "icsd_range_max": 3317, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "W2O5", @@ -1096,7 +1206,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "WO2", @@ -1106,7 +1217,8 @@ "n_icsd_entries": 1, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "medium" + "confidence": "medium", + "sourced": true }, { "formula": "WO3", @@ -1116,7 +1228,8 @@ "n_icsd_entries": null, "icsd_range_min": null, "icsd_range_max": null, - "confidence": "low" + "confidence": "low", + "sourced": false }, { "formula": "Y2O3", @@ -1126,7 +1239,8 @@ "n_icsd_entries": 38, "icsd_range_min": 3585, "icsd_range_max": 4179, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "Yb2O3", @@ -1136,7 +1250,8 @@ "n_icsd_entries": 17, "icsd_range_min": 3707, "icsd_range_max": 3724, - "confidence": "high" + "confidence": "high", + "sourced": true }, { "formula": "ZnO", @@ -1146,7 +1261,9 @@ "n_icsd_entries": 2, "icsd_range_min": 1085, "icsd_range_max": 1087, - "confidence": "medium" + "confidence": "low", + "sourced": true, + "review_note": "The ambient phase of ZnO is wurtzite (P6_3mc); the rock-salt phase is high pressure, which this table's methodology excludes. The structure type and the value both need re-deriving from ambient entries." }, { "formula": "ZrO2", @@ -1156,7 +1273,8 @@ "n_icsd_entries": 12, "icsd_range_min": 3001, "icsd_range_max": 3176, - "confidence": "high" + "confidence": "high", + "sourced": true } ] -} \ No newline at end of file +} diff --git a/data/common_oxidation_states.json b/data/common_oxidation_states.json new file mode 100644 index 0000000..849680c --- /dev/null +++ b/data/common_oxidation_states.json @@ -0,0 +1,280 @@ +{ + "H": [ + 1 + ], + "Li": [ + 1 + ], + "Be": [ + 2 + ], + "B": [ + 3 + ], + "C": [ + 4 + ], + "N": [ + -3, + 3, + 5 + ], + "O": [ + -2 + ], + "F": [ + -1 + ], + "Na": [ + 1 + ], + "Mg": [ + 2 + ], + "Al": [ + 3 + ], + "Si": [ + 4 + ], + "P": [ + 5 + ], + "S": [ + -2, + 6 + ], + "Cl": [ + -1 + ], + "K": [ + 1 + ], + "Ca": [ + 2 + ], + "Sc": [ + 3 + ], + "Ti": [ + 3, + 4 + ], + "V": [ + 3, + 4, + 5 + ], + "Cr": [ + 3, + 6 + ], + "Mn": [ + 2, + 3, + 4 + ], + "Fe": [ + 2, + 3 + ], + "Co": [ + 2, + 3 + ], + "Ni": [ + 2, + 3 + ], + "Cu": [ + 1, + 2 + ], + "Zn": [ + 2 + ], + "Ga": [ + 3 + ], + "Ge": [ + 4 + ], + "As": [ + 3, + 5 + ], + "Se": [ + -2, + 4, + 6 + ], + "Br": [ + -1 + ], + "Rb": [ + 1 + ], + "Sr": [ + 2 + ], + "Y": [ + 3 + ], + "Zr": [ + 4 + ], + "Nb": [ + 5 + ], + "Mo": [ + 4, + 6 + ], + "Tc": [ + 4, + 7 + ], + "Ru": [ + 4 + ], + "Rh": [ + 3, + 4 + ], + "Pd": [ + 2, + 4 + ], + "Ag": [ + 1 + ], + "Cd": [ + 2 + ], + "In": [ + 3 + ], + "Sn": [ + 2, + 4 + ], + "Sb": [ + 3, + 5 + ], + "Te": [ + 4, + 6 + ], + "I": [ + -1, + 5, + 7 + ], + "Cs": [ + 1 + ], + "Ba": [ + 2 + ], + "La": [ + 3 + ], + "Ce": [ + 3, + 4 + ], + "Pr": [ + 3, + 4 + ], + "Nd": [ + 3 + ], + "Pm": [ + 3 + ], + "Sm": [ + 3 + ], + "Eu": [ + 2, + 3 + ], + "Gd": [ + 3 + ], + "Tb": [ + 3, + 4 + ], + "Dy": [ + 3 + ], + "Ho": [ + 3 + ], + "Er": [ + 3 + ], + "Tm": [ + 3 + ], + "Yb": [ + 2, + 3 + ], + "Lu": [ + 3 + ], + "Hf": [ + 4 + ], + "Ta": [ + 5 + ], + "W": [ + 6 + ], + "Re": [ + 4, + 7 + ], + "Os": [ + 4, + 6 + ], + "Ir": [ + 3, + 4 + ], + "Pt": [ + 2, + 4 + ], + "Au": [ + 1, + 3 + ], + "Hg": [ + 2 + ], + "Tl": [ + 1, + 3 + ], + "Pb": [ + 2, + 4 + ], + "Bi": [ + 3 + ], + "Th": [ + 4 + ], + "U": [ + 4, + 6 + ] +} \ No newline at end of file diff --git a/data/maple_library.json b/data/maple_library.json new file mode 100644 index 0000000..711f749 --- /dev/null +++ b/data/maple_library.json @@ -0,0 +1,236 @@ +{ + "_metadata": { + "description": "MaplePy reference library: oxidation state overrides, Hoppe reference MAPLE values, and isostructural series constants.", + "version": "1.0.1", + "created": "2026-03-20", + "author": "Reeves-McLaren, N.", + "notes": [ + "oxidation_state_overrides: formula-keyed assignments for stoichiometrically unambiguous compounds whose elements have multiple entries in common_oxidation_states.json. Level 4 of the oxidation state chain in MaplePy 1.3.6 (after the user's states and the CIF's own, before the single-state fallback). Keys use pymatgen reduced_formula convention (no spaces).", + "reference_maple: Hoppe reference values for binary and selected ternary compounds, for checking computed values. Sources cited per entry.", + "isostructural_series: MAPLE x d_ref constants (kcal/mol.Ang) for well-characterised isostructural families. Constant within a structure type for all members; deviations flag topological errors or anomalous bonding.", + "mixed_valence_compounds: formulas explicitly excluded from oxidation_state_overrides because they contain sites with more than one oxidation state. Listed here to document the deliberate exclusion.", + "v1.0.1: the notes describe MaplePy 1.3.6; one series note removed. No override or value has changed." + ] + }, + + "oxidation_state_overrides": { + + "_note": "Keys: pymatgen reduced_formula. Values: {element: formal_charge}. Only compounds where charge balance uniquely determines all oxidation states. Compounds with mixed-valence or ambiguous anion states are excluded and listed in mixed_valence_compounds.", + + "MoO2": {"Mo": 4, "O": -2}, + "MoO3": {"Mo": 6, "O": -2}, + "Mo2O3": {"Mo": 3, "O": -2}, + "Mo2O5": {"Mo": 5, "O": -2}, + "MoS2": {"Mo": 4, "S": -2}, + + "VO": {"V": 2, "O": -2}, + "V2O3": {"V": 3, "O": -2}, + "VO2": {"V": 4, "O": -2}, + "V2O5": {"V": 5, "O": -2}, + + "Cr2O3": {"Cr": 3, "O": -2}, + "CrO2": {"Cr": 4, "O": -2}, + "CrO3": {"Cr": 6, "O": -2}, + "CrF2": {"Cr": 2, "F": -1}, + "CrF3": {"Cr": 3, "F": -1}, + + "FeO": {"Fe": 2, "O": -2}, + "Fe2O3": {"Fe": 3, "O": -2}, + "FeS": {"Fe": 2, "S": -2}, + "FeS2": {"Fe": 2, "S": -1}, + "Fe2S3": {"Fe": 3, "S": -2}, + "FeSe": {"Fe": 2, "Se": -2}, + "FeF2": {"Fe": 2, "F": -1}, + "FeF3": {"Fe": 3, "F": -1}, + "FeCl2": {"Fe": 2, "Cl": -1}, + "FeCl3": {"Fe": 3, "Cl": -1}, + "FeI2": {"Fe": 2, "I": -1}, + + "MnO": {"Mn": 2, "O": -2}, + "Mn2O3": {"Mn": 3, "O": -2}, + "MnO2": {"Mn": 4, "O": -2}, + "MnS": {"Mn": 2, "S": -2}, + "MnSe": {"Mn": 2, "Se": -2}, + "MnTe": {"Mn": 2, "Te": -2}, + "MnF2": {"Mn": 2, "F": -1}, + "MnF3": {"Mn": 3, "F": -1}, + "MnCl2": {"Mn": 2, "Cl": -1}, + + "CoO": {"Co": 2, "O": -2}, + "Co2O3": {"Co": 3, "O": -2}, + "CoS": {"Co": 2, "S": -2}, + "CoSe": {"Co": 2, "Se": -2}, + "CoF2": {"Co": 2, "F": -1}, + "CoF3": {"Co": 3, "F": -1}, + "CoCl2": {"Co": 2, "Cl": -1}, + + "NiO": {"Ni": 2, "O": -2}, + "Ni2O3": {"Ni": 3, "O": -2}, + "NiS": {"Ni": 2, "S": -2}, + "NiSe": {"Ni": 2, "Se": -2}, + + "Cu2O": {"Cu": 1, "O": -2}, + "CuO": {"Cu": 2, "O": -2}, + "Cu2S": {"Cu": 1, "S": -2}, + "CuS": {"Cu": 2, "S": -2}, + "CuSe": {"Cu": 2, "Se": -2}, + "CuF": {"Cu": 1, "F": -1}, + "CuF2": {"Cu": 2, "F": -1}, + "CuCl": {"Cu": 1, "Cl": -1}, + "CuCl2": {"Cu": 2, "Cl": -1}, + "CuBr": {"Cu": 1, "Br": -1}, + "CuBr2": {"Cu": 2, "Br": -1}, + + "TiO": {"Ti": 2, "O": -2}, + "Ti2O3": {"Ti": 3, "O": -2}, + "TiO2": {"Ti": 4, "O": -2}, + + "PbO": {"Pb": 2, "O": -2}, + "PbO2": {"Pb": 4, "O": -2}, + "PbS": {"Pb": 2, "S": -2}, + "PbSe": {"Pb": 2, "Se": -2}, + "PbTe": {"Pb": 2, "Te": -2}, + "PbF2": {"Pb": 2, "F": -1}, + "PbF4": {"Pb": 4, "F": -1}, + "PbCl2": {"Pb": 2, "Cl": -1}, + "PbBr2": {"Pb": 2, "Br": -1}, + "PbI2": {"Pb": 2, "I": -1}, + "Pb2O": {"Pb": 1, "O": -2}, + + "SnO": {"Sn": 2, "O": -2}, + "SnO2": {"Sn": 4, "O": -2}, + "SnS": {"Sn": 2, "S": -2}, + "SnS2": {"Sn": 4, "S": -2}, + "SnSe": {"Sn": 2, "Se": -2}, + "SnSe2": {"Sn": 4, "Se": -2}, + "SnTe": {"Sn": 2, "Te": -2}, + "SnF2": {"Sn": 2, "F": -1}, + "SnF4": {"Sn": 4, "F": -1}, + "SnCl2": {"Sn": 2, "Cl": -1}, + "SnCl4": {"Sn": 4, "Cl": -1}, + "SnI2": {"Sn": 2, "I": -1}, + + "Sb2O3": {"Sb": 3, "O": -2}, + "Sb2O5": {"Sb": 5, "O": -2}, + "SbF3": {"Sb": 3, "F": -1}, + "SbF5": {"Sb": 5, "F": -1}, + "SbCl3": {"Sb": 3, "Cl": -1}, + "SbCl5": {"Sb": 5, "Cl": -1}, + + "As2O3": {"As": 3, "O": -2}, + "As2O5": {"As": 5, "O": -2}, + + "Tl2O": {"Tl": 1, "O": -2}, + "Tl2O3": {"Tl": 3, "O": -2}, + "TlCl": {"Tl": 1, "Cl": -1}, + "TlCl3": {"Tl": 3, "Cl": -1}, + "TlBr": {"Tl": 1, "Br": -1}, + "TlI": {"Tl": 1, "I": -1}, + + "Au2O": {"Au": 1, "O": -2}, + "Au2O3": {"Au": 3, "O": -2}, + + "Ir2O3": {"Ir": 3, "O": -2}, + "IrO2": {"Ir": 4, "O": -2}, + + "OsO2": {"Os": 4, "O": -2}, + + "PtO": {"Pt": 2, "O": -2}, + "PtO2": {"Pt": 4, "O": -2}, + + "PdO": {"Pd": 2, "O": -2}, + "PdO2": {"Pd": 4, "O": -2}, + + "Rh2O3": {"Rh": 3, "O": -2}, + "RhO2": {"Rh": 4, "O": -2}, + + "UO2": {"U": 4, "O": -2}, + "UO3": {"U": 6, "O": -2}, + + "Ce2O3": {"Ce": 3, "O": -2}, + "CeO2": {"Ce": 4, "O": -2}, + + "EuO": {"Eu": 2, "O": -2}, + "Eu2O3": {"Eu": 3, "O": -2}, + + "Pr2O3": {"Pr": 3, "O": -2}, + "PrO2": {"Pr": 4, "O": -2}, + + "Tb2O3": {"Tb": 3, "O": -2}, + "TbO2": {"Tb": 4, "O": -2}, + + "Yb2O3": {"Yb": 3, "O": -2}, + "YbO": {"Yb": 2, "O": -2} + }, + + "mixed_valence_compounds": { + "_note": "Compounds explicitly excluded from oxidation_state_overrides. Charge balance is ambiguous or requires site-specific assignment. MAPLE calculation requires user-supplied oxidation_states dict.", + "Fe3O4": "Fe2+/Fe3+ mixed valence (spinel, inverse)", + "Co3O4": "Co2+/Co3+ mixed valence (spinel, normal)", + "Mn3O4": "Mn2+/Mn3+ mixed valence (hausmannite, spinel)", + "Pb2O3": "Pb2+/Pb4+ mixed valence", + "Pb3O4": "Pb2+/Pb4+ mixed valence (minium)", + "FeS2": "Assigned Fe2+/S- (pyrite) in overrides; alternative Fe4+/S2- assignment exists, verify before use" + }, + + "reference_maple": { + "_note": "Hoppe reference MAPLE values (kcal/mol per formula unit). Used to validate computed values and for additivity testing without requiring the user to compute binaries. All values from Hoppe (1966) or Hoppe (1995) unless noted.", + + "TiO2_rutile": {"maple_kcal_mol": 3254.6, "source": "Hoppe_1995_Table5", "space_group": "P4_2/mnm"}, + "TiO2_anatase": {"maple_kcal_mol": 3260.7, "source": "Hoppe_1995_Table5", "space_group": "I4_1/amd"}, + "TiO2_brookite":{"maple_kcal_mol": 3253.7, "source": "Hoppe_1995_Table5", "space_group": "Pbca"}, + "BaTiO3_cubic": {"maple_kcal_mol": 4095.0, "source": "Hoppe_1995_p560", "space_group": "Pm-3m"}, + "BaO_rocksalt": {"maple_kcal_mol": 4092.0, "_note": "Binary sum BaO+TiO2 from Hoppe 1995 p.560; individual BaO value back-calculated", "source": "Hoppe_1995_p560"} + }, + + "isostructural_series": { + "_note": "MAPLE x d_ref (kcal/mol.Ang): constant within an isostructural family. Deviations flag topological errors or anomalous bonding (wrong structure type, wrong CN). madelung_factor is dimensionless and also invariant within the family.", + + "rock_salt_AO_alkaline_earth": { + "description": "Alkaline earth oxides MO in Fm-3m (NaCl type). MAPLE x d_ref constant across MgO, CaO, SrO, BaO.", + "maple_x_dref_kcal_mol_ang": 2320.9, + "madelung_factor": 1.7476, + "members": ["MgO", "CaO", "SrO", "BaO"], + "source": "Reeves-McLaren_2026_calculated" + }, + + "rock_salt_AX_MF": { + "description": "NaCl-type structures: Madelung factor invariant at 1.7476 for all AB compositions in Fm-3m.", + "madelung_factor": 1.7476, + "partial_madelung_constant": 0.8738, + "members_examples": ["NaCl", "KCl", "MgO", "CaO", "FeO", "NiO", "CoO"], + "source": "Hoppe_1966", + "notes": "MF deviation from 1.7476 in an Fm-3m structure indicates incorrect topology assignment or severe positional error." + }, + + "zinc_blende_AX_MF": { + "description": "Zinc blende (F-43m / F4-3m) structures: Madelung factor 1.6381.", + "madelung_factor": 1.6381, + "members_examples": ["ZnS", "GaAs", "InP", "SnTe_wrong_assignment"], + "source": "standard_electrostatics", + "notes": "MF=1.638 in a structure claimed to be NaCl-type (MF should be 1.748) is a diagnostic fingerprint for a zinc blende mis-assignment. See SnTe ICSD 53956." + }, + + "fluorite_AX2_MF": { + "description": "Fluorite-type (Fm-3m, CaF2 type): Madelung factor ~5.039.", + "madelung_factor": 5.039, + "members_examples": ["CaF2", "SrF2", "BaF2", "ZrO2_cubic", "CeO2", "UO2"], + "source": "standard_electrostatics" + }, + + "rutile_AX2_MF": { + "description": "Rutile-type (P4_2/mnm): Madelung factor ~4.816.", + "madelung_factor": 4.816, + "members_examples": ["TiO2", "SnO2", "MnO2", "RuO2", "IrO2", "NbO2"], + "source": "standard_electrostatics" + }, + + "corundum_A2X3_MF": { + "description": "Corundum-type (R-3c): Madelung factor ~25.0 (structure-dependent, use as guide only).", + "madelung_factor": 25.0, + "members_examples": ["Al2O3", "Fe2O3", "Cr2O3", "V2O3", "Ti2O3"], + "source": "approximate", + "notes": "Madelung factor less diagnostic for corundum than for cubic structure types due to structural degrees of freedom." + } + } +} diff --git a/docs/PACKAGE.md b/docs/PACKAGE.md new file mode 100644 index 0000000..0e1fa78 --- /dev/null +++ b/docs/PACKAGE.md @@ -0,0 +1,39 @@ +# How the package relates to the notebooks + +`MaplePy.ipynb` and `Hopper.ipynb` are the source of the code. They are what a reader opens to see how a number was reached, cell by cell, and what most users of MaplePy have run. The package, maplepy, runs the same code at scale, from a command line or from Python, and is what the tests exercise. + +## The build + +`tools/build_engine.py` copies the code cells of each notebook into `src/maplepy/_cells/maplepy/` and `src/maplepy/_cells/hopper/`, one file per cell. Each file starts with a header naming the notebook and cell it came from. A plan in the script lists every cell: the ones copied, the role each plays, and the ones left out, each with its reason. It also lists every edit the build makes, and each edit must match the notebook exactly once, so a change to an edited line stops the build rather than going unnoticed. There are four edits, in three cells: + +| Notebook | Cell | Edit | +|---|---|---| +| MaplePy | 4 | `DEFAULT_DATA_DIR` is the package's data folder, not `data/` in the working directory | +| Hopper | 4 | the folder is passed in (`MAPLE_DIR_OVERRIDE`), so no dialog opens; and `tkinter` is not imported (two edits) | +| Hopper | 6 | the reference table is the package's copy (`BINARY_REFERENCE_PATH`) | + +One more change touches no line: Hopper's cells that act on a run (Section 3 onwards) are split where the action starts, so that their definitions load with the engine and their actions run when asked for. + +Left out: the commented pip installs; MaplePy's version print (cell 3), its demonstration on NaCl (cell 20), its application to the alkaline earth oxides (Section 6), and its GUI (Section 7), a Tk folder picker in front of `batch_maple()`, which the package calls directly. + +`python tools/build_engine.py --check` fails if the copied cells or `src/maplepy/_manifest.py` differ from what the notebooks would produce. CI runs it on every push, and `tests/test_build.py` runs it too. + +## The engines + +`maplepy._maple` and `maplepy._hopper` are modules whose namespaces play the part of a notebook kernel: the copied cells are executed in them, in notebook order, so every function a notebook defines is an attribute of its engine, with the notebook's behaviour. `maplepy.engine()` and `maplepy.hopper_engine()` return them. Three things differ from a notebook session, and only three: + +- what the cells print while loading goes to the engine's `IMPORT_LOG`, because MaplePy's worker processes import the engine; +- the actions run when asked for, and each Hopper run starts from the state the engine had on loading, as "Restart & Run All" would; +- `display()`, which Jupyter provides, prints a table as text. + +Hopper loads on first use, because its set-up cell changes matplotlib's `rcParams`, as it does in Jupyter. + +MaplePy's validation cells (Section 2) are not run on loading. `maplepy.validate()` and `maplepy --validate` run them, in notebook order, and read the pass flags each sets. + +## Showing they agree + +`python tools/equivalence.py FOLDER` runs both notebooks headless on a copy of a folder of CIFs, with the folders set so that no dialog opens, runs the package on another copy, and compares `maple_results.csv`, `maple_summary.csv`, `maple_failed.csv` and `additivity_classified.csv` cell by cell. Run it after any change, on a folder whose results you know. On the examples, every file is identical. + +## Changing the code + +Edit the notebook, never the copied cells, then `python tools/build_engine.py`. [CONTRIBUTING.md](../CONTRIBUTING.md) gives the whole sequence. diff --git a/examples/Ba0.5Sr0.5TiO3_disordered.cif b/examples/Ba0.5Sr0.5TiO3_disordered.cif new file mode 100644 index 0000000..57bb763 --- /dev/null +++ b/examples/Ba0.5Sr0.5TiO3_disordered.cif @@ -0,0 +1,86 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 3.95 A; Ba and Sr share the A site at 0.5 each. +# generated using pymatgen +data_Ba0.5Sr0.5Ti1O3 +_symmetry_space_group_name_H-M Pm-3m +_cell_length_a 3.95000000 +_cell_length_b 3.95000000 +_cell_length_c 3.95000000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 221 +_chemical_formula_structural Ba0.5Sr0.5Ti1O3 +_chemical_formula_sum 'Ba0.5 Sr0.5 Ti1 O3' +_cell_volume 61.62987500 +_cell_formula_units_Z 1 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y, x, z' + 4 'y, -x, -z' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y, -x, z' + 8 '-y, x, -z' + 9 'x, -y, -z' + 10 '-x, y, z' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x, y, -z' + 14 'x, -y, z' + 15 'y, x, -z' + 16 '-y, -x, z' + 17 'z, x, y' + 18 '-z, -x, -y' + 19 'z, -y, x' + 20 '-z, y, -x' + 21 'z, -x, -y' + 22 '-z, x, y' + 23 'z, y, -x' + 24 '-z, -y, x' + 25 '-z, x, -y' + 26 'z, -x, y' + 27 '-z, -y, -x' + 28 'z, y, x' + 29 '-z, -x, y' + 30 'z, x, -y' + 31 '-z, y, x' + 32 'z, -y, -x' + 33 'y, z, x' + 34 '-y, -z, -x' + 35 'x, z, -y' + 36 '-x, -z, y' + 37 '-y, z, -x' + 38 'y, -z, x' + 39 '-x, z, y' + 40 'x, -z, -y' + 41 '-y, -z, x' + 42 'y, z, -x' + 43 '-x, -z, -y' + 44 'x, z, y' + 45 'y, -z, -x' + 46 '-y, z, x' + 47 'x, -z, y' + 48 '-x, z, -y' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Ba2+ 2.0 + Sr2+ 2.0 + Ti4+ 4.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Ba2+ Ba0 1 0.00000000 0.00000000 0.00000000 0.5 + Sr2+ Sr1 1 0.00000000 0.00000000 0.00000000 0.5 + Ti4+ Ti2 1 0.50000000 0.50000000 0.50000000 1 + O2- O3 3 0.00000000 0.50000000 0.50000000 1 diff --git a/examples/BaO_rocksalt.cif b/examples/BaO_rocksalt.cif new file mode 100644 index 0000000..39915b6 --- /dev/null +++ b/examples/BaO_rocksalt.cif @@ -0,0 +1,226 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 5.5391 A, as in Section 2.3. +# generated using pymatgen +data_BaO +_symmetry_space_group_name_H-M Fm-3m +_cell_length_a 5.53910000 +_cell_length_b 5.53910000 +_cell_length_c 5.53910000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 225 +_chemical_formula_structural BaO +_chemical_formula_sum 'Ba4 O4' +_cell_volume 169.94861014 +_cell_formula_units_Z 4 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y, x, z' + 4 'y, -x, -z' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y, -x, z' + 8 '-y, x, -z' + 9 'x, -y, -z' + 10 '-x, y, z' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x, y, -z' + 14 'x, -y, z' + 15 'y, x, -z' + 16 '-y, -x, z' + 17 'z, x, y' + 18 '-z, -x, -y' + 19 'z, -y, x' + 20 '-z, y, -x' + 21 'z, -x, -y' + 22 '-z, x, y' + 23 'z, y, -x' + 24 '-z, -y, x' + 25 '-z, x, -y' + 26 'z, -x, y' + 27 '-z, -y, -x' + 28 'z, y, x' + 29 '-z, -x, y' + 30 'z, x, -y' + 31 '-z, y, x' + 32 'z, -y, -x' + 33 'y, z, x' + 34 '-y, -z, -x' + 35 'x, z, -y' + 36 '-x, -z, y' + 37 '-y, z, -x' + 38 'y, -z, x' + 39 '-x, z, y' + 40 'x, -z, -y' + 41 '-y, -z, x' + 42 'y, z, -x' + 43 '-x, -z, -y' + 44 'x, z, y' + 45 'y, -z, -x' + 46 '-y, z, x' + 47 'x, -z, y' + 48 '-x, z, -y' + 49 'x+1/2, y+1/2, z' + 50 '-x+1/2, -y+1/2, -z' + 51 '-y+1/2, x+1/2, z' + 52 'y+1/2, -x+1/2, -z' + 53 '-x+1/2, -y+1/2, z' + 54 'x+1/2, y+1/2, -z' + 55 'y+1/2, -x+1/2, z' + 56 '-y+1/2, x+1/2, -z' + 57 'x+1/2, -y+1/2, -z' + 58 '-x+1/2, y+1/2, z' + 59 '-y+1/2, -x+1/2, -z' + 60 'y+1/2, x+1/2, z' + 61 '-x+1/2, y+1/2, -z' + 62 'x+1/2, -y+1/2, z' + 63 'y+1/2, x+1/2, -z' + 64 '-y+1/2, -x+1/2, z' + 65 'z+1/2, x+1/2, y' + 66 '-z+1/2, -x+1/2, -y' + 67 'z+1/2, -y+1/2, x' + 68 '-z+1/2, y+1/2, -x' + 69 'z+1/2, -x+1/2, -y' + 70 '-z+1/2, x+1/2, y' + 71 'z+1/2, y+1/2, -x' + 72 '-z+1/2, -y+1/2, x' + 73 '-z+1/2, x+1/2, -y' + 74 'z+1/2, -x+1/2, y' + 75 '-z+1/2, -y+1/2, -x' + 76 'z+1/2, y+1/2, x' + 77 '-z+1/2, -x+1/2, y' + 78 'z+1/2, x+1/2, -y' + 79 '-z+1/2, y+1/2, x' + 80 'z+1/2, -y+1/2, -x' + 81 'y+1/2, z+1/2, x' + 82 '-y+1/2, -z+1/2, -x' + 83 'x+1/2, z+1/2, -y' + 84 '-x+1/2, -z+1/2, y' + 85 '-y+1/2, z+1/2, -x' + 86 'y+1/2, -z+1/2, x' + 87 '-x+1/2, z+1/2, y' + 88 'x+1/2, -z+1/2, -y' + 89 '-y+1/2, -z+1/2, x' + 90 'y+1/2, z+1/2, -x' + 91 '-x+1/2, -z+1/2, -y' + 92 'x+1/2, z+1/2, y' + 93 'y+1/2, -z+1/2, -x' + 94 '-y+1/2, z+1/2, x' + 95 'x+1/2, -z+1/2, y' + 96 '-x+1/2, z+1/2, -y' + 97 'x+1/2, y, z+1/2' + 98 '-x+1/2, -y, -z+1/2' + 99 '-y+1/2, x, z+1/2' + 100 'y+1/2, -x, -z+1/2' + 101 '-x+1/2, -y, z+1/2' + 102 'x+1/2, y, -z+1/2' + 103 'y+1/2, -x, z+1/2' + 104 '-y+1/2, x, -z+1/2' + 105 'x+1/2, -y, -z+1/2' + 106 '-x+1/2, y, z+1/2' + 107 '-y+1/2, -x, -z+1/2' + 108 'y+1/2, x, z+1/2' + 109 '-x+1/2, y, -z+1/2' + 110 'x+1/2, -y, z+1/2' + 111 'y+1/2, x, -z+1/2' + 112 '-y+1/2, -x, z+1/2' + 113 'z+1/2, x, y+1/2' + 114 '-z+1/2, -x, -y+1/2' + 115 'z+1/2, -y, x+1/2' + 116 '-z+1/2, y, -x+1/2' + 117 'z+1/2, -x, -y+1/2' + 118 '-z+1/2, x, y+1/2' + 119 'z+1/2, y, -x+1/2' + 120 '-z+1/2, -y, x+1/2' + 121 '-z+1/2, x, -y+1/2' + 122 'z+1/2, -x, y+1/2' + 123 '-z+1/2, -y, -x+1/2' + 124 'z+1/2, y, x+1/2' + 125 '-z+1/2, -x, y+1/2' + 126 'z+1/2, x, -y+1/2' + 127 '-z+1/2, y, x+1/2' + 128 'z+1/2, -y, -x+1/2' + 129 'y+1/2, z, x+1/2' + 130 '-y+1/2, -z, -x+1/2' + 131 'x+1/2, z, -y+1/2' + 132 '-x+1/2, -z, y+1/2' + 133 '-y+1/2, z, -x+1/2' + 134 'y+1/2, -z, x+1/2' + 135 '-x+1/2, z, y+1/2' + 136 'x+1/2, -z, -y+1/2' + 137 '-y+1/2, -z, x+1/2' + 138 'y+1/2, z, -x+1/2' + 139 '-x+1/2, -z, -y+1/2' + 140 'x+1/2, z, y+1/2' + 141 'y+1/2, -z, -x+1/2' + 142 '-y+1/2, z, x+1/2' + 143 'x+1/2, -z, y+1/2' + 144 '-x+1/2, z, -y+1/2' + 145 'x, y+1/2, z+1/2' + 146 '-x, -y+1/2, -z+1/2' + 147 '-y, x+1/2, z+1/2' + 148 'y, -x+1/2, -z+1/2' + 149 '-x, -y+1/2, z+1/2' + 150 'x, y+1/2, -z+1/2' + 151 'y, -x+1/2, z+1/2' + 152 '-y, x+1/2, -z+1/2' + 153 'x, -y+1/2, -z+1/2' + 154 '-x, y+1/2, z+1/2' + 155 '-y, -x+1/2, -z+1/2' + 156 'y, x+1/2, z+1/2' + 157 '-x, y+1/2, -z+1/2' + 158 'x, -y+1/2, z+1/2' + 159 'y, x+1/2, -z+1/2' + 160 '-y, -x+1/2, z+1/2' + 161 'z, x+1/2, y+1/2' + 162 '-z, -x+1/2, -y+1/2' + 163 'z, -y+1/2, x+1/2' + 164 '-z, y+1/2, -x+1/2' + 165 'z, -x+1/2, -y+1/2' + 166 '-z, x+1/2, y+1/2' + 167 'z, y+1/2, -x+1/2' + 168 '-z, -y+1/2, x+1/2' + 169 '-z, x+1/2, -y+1/2' + 170 'z, -x+1/2, y+1/2' + 171 '-z, -y+1/2, -x+1/2' + 172 'z, y+1/2, x+1/2' + 173 '-z, -x+1/2, y+1/2' + 174 'z, x+1/2, -y+1/2' + 175 '-z, y+1/2, x+1/2' + 176 'z, -y+1/2, -x+1/2' + 177 'y, z+1/2, x+1/2' + 178 '-y, -z+1/2, -x+1/2' + 179 'x, z+1/2, -y+1/2' + 180 '-x, -z+1/2, y+1/2' + 181 '-y, z+1/2, -x+1/2' + 182 'y, -z+1/2, x+1/2' + 183 '-x, z+1/2, y+1/2' + 184 'x, -z+1/2, -y+1/2' + 185 '-y, -z+1/2, x+1/2' + 186 'y, z+1/2, -x+1/2' + 187 '-x, -z+1/2, -y+1/2' + 188 'x, z+1/2, y+1/2' + 189 'y, -z+1/2, -x+1/2' + 190 '-y, z+1/2, x+1/2' + 191 'x, -z+1/2, y+1/2' + 192 '-x, z+1/2, -y+1/2' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Ba2+ 2.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Ba2+ Ba0 4 0.00000000 0.00000000 0.00000000 1 + O2- O1 4 0.00000000 0.00000000 0.50000000 1 diff --git a/examples/BaTiO3_cubic.cif b/examples/BaTiO3_cubic.cif new file mode 100644 index 0000000..520fe92 --- /dev/null +++ b/examples/BaTiO3_cubic.cif @@ -0,0 +1,84 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 4.0019 A, as in Section 2.3. +# generated using pymatgen +data_BaTiO3 +_symmetry_space_group_name_H-M Pm-3m +_cell_length_a 4.00190000 +_cell_length_b 4.00190000 +_cell_length_c 4.00190000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 221 +_chemical_formula_structural BaTiO3 +_chemical_formula_sum 'Ba1 Ti1 O3' +_cell_volume 64.09124333 +_cell_formula_units_Z 1 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y, x, z' + 4 'y, -x, -z' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y, -x, z' + 8 '-y, x, -z' + 9 'x, -y, -z' + 10 '-x, y, z' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x, y, -z' + 14 'x, -y, z' + 15 'y, x, -z' + 16 '-y, -x, z' + 17 'z, x, y' + 18 '-z, -x, -y' + 19 'z, -y, x' + 20 '-z, y, -x' + 21 'z, -x, -y' + 22 '-z, x, y' + 23 'z, y, -x' + 24 '-z, -y, x' + 25 '-z, x, -y' + 26 'z, -x, y' + 27 '-z, -y, -x' + 28 'z, y, x' + 29 '-z, -x, y' + 30 'z, x, -y' + 31 '-z, y, x' + 32 'z, -y, -x' + 33 'y, z, x' + 34 '-y, -z, -x' + 35 'x, z, -y' + 36 '-x, -z, y' + 37 '-y, z, -x' + 38 'y, -z, x' + 39 '-x, z, y' + 40 'x, -z, -y' + 41 '-y, -z, x' + 42 'y, z, -x' + 43 '-x, -z, -y' + 44 'x, z, y' + 45 'y, -z, -x' + 46 '-y, z, x' + 47 'x, -z, y' + 48 '-x, z, -y' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Ba2+ 2.0 + Ti4+ 4.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Ba2+ Ba0 1 0.00000000 0.00000000 0.00000000 1 + Ti4+ Ti1 1 0.50000000 0.50000000 0.50000000 1 + O2- O2 3 0.00000000 0.50000000 0.50000000 1 diff --git a/examples/BaTiO3_wrong_cell.cif b/examples/BaTiO3_wrong_cell.cif new file mode 100644 index 0000000..61e2838 --- /dev/null +++ b/examples/BaTiO3_wrong_cell.cif @@ -0,0 +1,84 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 3.0019 A: the 4.0019 A of BaTiO3_cubic.cif with its first digit mistyped. +# generated using pymatgen +data_BaTiO3 +_symmetry_space_group_name_H-M Pm-3m +_cell_length_a 3.00190000 +_cell_length_b 3.00190000 +_cell_length_c 3.00190000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 221 +_chemical_formula_structural BaTiO3 +_chemical_formula_sum 'Ba1 Ti1 O3' +_cell_volume 27.05133250 +_cell_formula_units_Z 1 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y, x, z' + 4 'y, -x, -z' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y, -x, z' + 8 '-y, x, -z' + 9 'x, -y, -z' + 10 '-x, y, z' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x, y, -z' + 14 'x, -y, z' + 15 'y, x, -z' + 16 '-y, -x, z' + 17 'z, x, y' + 18 '-z, -x, -y' + 19 'z, -y, x' + 20 '-z, y, -x' + 21 'z, -x, -y' + 22 '-z, x, y' + 23 'z, y, -x' + 24 '-z, -y, x' + 25 '-z, x, -y' + 26 'z, -x, y' + 27 '-z, -y, -x' + 28 'z, y, x' + 29 '-z, -x, y' + 30 'z, x, -y' + 31 '-z, y, x' + 32 'z, -y, -x' + 33 'y, z, x' + 34 '-y, -z, -x' + 35 'x, z, -y' + 36 '-x, -z, y' + 37 '-y, z, -x' + 38 'y, -z, x' + 39 '-x, z, y' + 40 'x, -z, -y' + 41 '-y, -z, x' + 42 'y, z, -x' + 43 '-x, -z, -y' + 44 'x, z, y' + 45 'y, -z, -x' + 46 '-y, z, x' + 47 'x, -z, y' + 48 '-x, z, -y' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Ba2+ 2.0 + Ti4+ 4.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Ba2+ Ba0 1 0.00000000 0.00000000 0.00000000 1 + Ti4+ Ti1 1 0.50000000 0.50000000 0.50000000 1 + O2- O2 3 0.00000000 0.50000000 0.50000000 1 diff --git a/examples/Gd2Ti2O7_pyrochlore.cif b/examples/Gd2Ti2O7_pyrochlore.cif new file mode 100644 index 0000000..1ba8590 --- /dev/null +++ b/examples/Gd2Ti2O7_pyrochlore.cif @@ -0,0 +1,229 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 10.185 A, x(48f) = 0.330, origin choice 2. +# generated using pymatgen +data_Gd2Ti2O7 +_symmetry_space_group_name_H-M Fd-3m +_cell_length_a 10.18500000 +_cell_length_b 10.18500000 +_cell_length_c 10.18500000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 227 +_chemical_formula_structural Gd2Ti2O7 +_chemical_formula_sum 'Gd16 Ti16 O56' +_cell_volume 1056.53308162 +_cell_formula_units_Z 8 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-y+1/4, x+1/4, z+1/4' + 3 '-x, -y+1/2, z+1/2' + 4 'y+3/4, -x+1/4, z+3/4' + 5 'x, -y, -z' + 6 '-y+1/4, -x+3/4, -z+3/4' + 7 '-x, y+1/2, -z+1/2' + 8 'y+3/4, x+3/4, -z+1/4' + 9 'z, x, y' + 10 'z+1/4, -y+1/4, x+1/4' + 11 'z+1/2, -x, -y+1/2' + 12 'z+3/4, y+3/4, -x+1/4' + 13 '-z, x, -y' + 14 '-z+3/4, -y+1/4, -x+3/4' + 15 '-z+1/2, -x, y+1/2' + 16 '-z+1/4, y+3/4, x+3/4' + 17 'y, z, x' + 18 'x+1/4, z+1/4, -y+1/4' + 19 '-y+1/2, z+1/2, -x' + 20 '-x+1/4, z+3/4, y+3/4' + 21 '-y, -z, x' + 22 '-x+3/4, -z+3/4, -y+1/4' + 23 'y+1/2, -z+1/2, -x' + 24 'x+3/4, -z+1/4, y+3/4' + 25 '-x+1/4, -y+1/4, -z+1/4' + 26 'y, -x, -z' + 27 'x+1/4, y+3/4, -z+3/4' + 28 '-y+1/2, x, -z+1/2' + 29 '-x+1/4, y+1/4, z+1/4' + 30 'y, x+1/2, z+1/2' + 31 'x+1/4, -y+3/4, z+3/4' + 32 '-y+1/2, -x+1/2, z' + 33 '-z+1/4, -x+1/4, -y+1/4' + 34 '-z, y, -x' + 35 '-z+3/4, x+1/4, y+3/4' + 36 '-z+1/2, -y+1/2, x' + 37 'z+1/4, -x+1/4, y+1/4' + 38 'z+1/2, y, x+1/2' + 39 'z+3/4, x+1/4, -y+3/4' + 40 'z, -y+1/2, -x+1/2' + 41 '-y+1/4, -z+1/4, -x+1/4' + 42 '-x, -z, y' + 43 'y+3/4, -z+3/4, x+1/4' + 44 'x, -z+1/2, -y+1/2' + 45 'y+1/4, z+1/4, -x+1/4' + 46 'x+1/2, z+1/2, y' + 47 '-y+3/4, z+3/4, x+1/4' + 48 '-x+1/2, z, -y+1/2' + 49 'x+1/2, y+1/2, z' + 50 '-y+3/4, x+3/4, z+1/4' + 51 '-x+1/2, -y, z+1/2' + 52 'y+1/4, -x+3/4, z+3/4' + 53 'x+1/2, -y+1/2, -z' + 54 '-y+3/4, -x+1/4, -z+3/4' + 55 '-x+1/2, y, -z+1/2' + 56 'y+1/4, x+1/4, -z+1/4' + 57 'z+1/2, x+1/2, y' + 58 'z+3/4, -y+3/4, x+1/4' + 59 'z, -x+1/2, -y+1/2' + 60 'z+1/4, y+1/4, -x+1/4' + 61 '-z+1/2, x+1/2, -y' + 62 '-z+1/4, -y+3/4, -x+3/4' + 63 '-z, -x+1/2, y+1/2' + 64 '-z+3/4, y+1/4, x+3/4' + 65 'y+1/2, z+1/2, x' + 66 'x+3/4, z+3/4, -y+1/4' + 67 '-y, z, -x' + 68 '-x+3/4, z+1/4, y+3/4' + 69 '-y+1/2, -z+1/2, x' + 70 '-x+1/4, -z+1/4, -y+1/4' + 71 'y, -z, -x' + 72 'x+1/4, -z+3/4, y+3/4' + 73 '-x+3/4, -y+3/4, -z+1/4' + 74 'y+1/2, -x+1/2, -z' + 75 'x+3/4, y+1/4, -z+3/4' + 76 '-y, x+1/2, -z+1/2' + 77 '-x+3/4, y+3/4, z+1/4' + 78 'y+1/2, x, z+1/2' + 79 'x+3/4, -y+1/4, z+3/4' + 80 '-y, -x, z' + 81 '-z+3/4, -x+3/4, -y+1/4' + 82 '-z+1/2, y+1/2, -x' + 83 '-z+1/4, x+3/4, y+3/4' + 84 '-z, -y, x' + 85 'z+3/4, -x+3/4, y+1/4' + 86 'z, y+1/2, x+1/2' + 87 'z+1/4, x+3/4, -y+3/4' + 88 'z+1/2, -y, -x+1/2' + 89 '-y+3/4, -z+3/4, -x+1/4' + 90 '-x+1/2, -z+1/2, y' + 91 'y+1/4, -z+1/4, x+1/4' + 92 'x+1/2, -z, -y+1/2' + 93 'y+3/4, z+3/4, -x+1/4' + 94 'x, z, y' + 95 '-y+1/4, z+1/4, x+1/4' + 96 '-x, z+1/2, -y+1/2' + 97 'x+1/2, y, z+1/2' + 98 '-y+3/4, x+1/4, z+3/4' + 99 '-x+1/2, -y+1/2, z' + 100 'y+1/4, -x+1/4, z+1/4' + 101 'x+1/2, -y, -z+1/2' + 102 '-y+3/4, -x+3/4, -z+1/4' + 103 '-x+1/2, y+1/2, -z' + 104 'y+1/4, x+3/4, -z+3/4' + 105 'z+1/2, x, y+1/2' + 106 'z+3/4, -y+1/4, x+3/4' + 107 'z, -x, -y' + 108 'z+1/4, y+3/4, -x+3/4' + 109 '-z+1/2, x, -y+1/2' + 110 '-z+1/4, -y+1/4, -x+1/4' + 111 '-z, -x, y' + 112 '-z+3/4, y+3/4, x+1/4' + 113 'y+1/2, z, x+1/2' + 114 'x+3/4, z+1/4, -y+3/4' + 115 '-y, z+1/2, -x+1/2' + 116 '-x+3/4, z+3/4, y+1/4' + 117 '-y+1/2, -z, x+1/2' + 118 '-x+1/4, -z+3/4, -y+3/4' + 119 'y, -z+1/2, -x+1/2' + 120 'x+1/4, -z+1/4, y+1/4' + 121 '-x+3/4, -y+1/4, -z+3/4' + 122 'y+1/2, -x, -z+1/2' + 123 'x+3/4, y+3/4, -z+1/4' + 124 '-y, x, -z' + 125 '-x+3/4, y+1/4, z+3/4' + 126 'y+1/2, x+1/2, z' + 127 'x+3/4, -y+3/4, z+1/4' + 128 '-y, -x+1/2, z+1/2' + 129 '-z+3/4, -x+1/4, -y+3/4' + 130 '-z+1/2, y, -x+1/2' + 131 '-z+1/4, x+1/4, y+1/4' + 132 '-z, -y+1/2, x+1/2' + 133 'z+3/4, -x+1/4, y+3/4' + 134 'z, y, x' + 135 'z+1/4, x+1/4, -y+1/4' + 136 'z+1/2, -y+1/2, -x' + 137 '-y+3/4, -z+1/4, -x+3/4' + 138 '-x+1/2, -z, y+1/2' + 139 'y+1/4, -z+3/4, x+3/4' + 140 'x+1/2, -z+1/2, -y' + 141 'y+3/4, z+1/4, -x+3/4' + 142 'x, z+1/2, y+1/2' + 143 '-y+1/4, z+3/4, x+3/4' + 144 '-x, z, -y' + 145 'x, y+1/2, z+1/2' + 146 '-y+1/4, x+3/4, z+3/4' + 147 '-x, -y, z' + 148 'y+3/4, -x+3/4, z+1/4' + 149 'x, -y+1/2, -z+1/2' + 150 '-y+1/4, -x+1/4, -z+1/4' + 151 '-x, y, -z' + 152 'y+3/4, x+1/4, -z+3/4' + 153 'z, x+1/2, y+1/2' + 154 'z+1/4, -y+3/4, x+3/4' + 155 'z+1/2, -x+1/2, -y' + 156 'z+3/4, y+1/4, -x+3/4' + 157 '-z, x+1/2, -y+1/2' + 158 '-z+3/4, -y+3/4, -x+1/4' + 159 '-z+1/2, -x+1/2, y' + 160 '-z+1/4, y+1/4, x+1/4' + 161 'y, z+1/2, x+1/2' + 162 'x+1/4, z+3/4, -y+3/4' + 163 '-y+1/2, z, -x+1/2' + 164 '-x+1/4, z+1/4, y+1/4' + 165 '-y, -z+1/2, x+1/2' + 166 '-x+3/4, -z+1/4, -y+3/4' + 167 'y+1/2, -z, -x+1/2' + 168 'x+3/4, -z+3/4, y+1/4' + 169 '-x+1/4, -y+3/4, -z+3/4' + 170 'y, -x+1/2, -z+1/2' + 171 'x+1/4, y+1/4, -z+1/4' + 172 '-y+1/2, x+1/2, -z' + 173 '-x+1/4, y+3/4, z+3/4' + 174 'y, x, z' + 175 'x+1/4, -y+1/4, z+1/4' + 176 '-y+1/2, -x, z+1/2' + 177 '-z+1/4, -x+3/4, -y+3/4' + 178 '-z, y+1/2, -x+1/2' + 179 '-z+3/4, x+3/4, y+1/4' + 180 '-z+1/2, -y, x+1/2' + 181 'z+1/4, -x+3/4, y+3/4' + 182 'z+1/2, y+1/2, x' + 183 'z+3/4, x+3/4, -y+1/4' + 184 'z, -y, -x' + 185 '-y+1/4, -z+3/4, -x+3/4' + 186 '-x, -z+1/2, y+1/2' + 187 'y+3/4, -z+1/4, x+3/4' + 188 'x, -z, -y' + 189 'y+1/4, z+3/4, -x+3/4' + 190 'x+1/2, z, y+1/2' + 191 '-y+3/4, z+1/4, x+3/4' + 192 '-x+1/2, z+1/2, -y' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Gd3+ 3.0 + Ti4+ 4.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Gd3+ Gd0 16 0.12500000 0.12500000 0.12500000 1 + Ti4+ Ti1 16 0.12500000 0.12500000 0.62500000 1 + O2- O2 48 0.00000000 0.00000000 0.29500000 1 + O2- O3 8 0.00000000 0.00000000 0.00000000 1 diff --git a/examples/SrFeO3_no_states.cif b/examples/SrFeO3_no_states.cif new file mode 100644 index 0000000..89a7f59 --- /dev/null +++ b/examples/SrFeO3_no_states.cif @@ -0,0 +1,78 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 3.85 A; no oxidation states. Run with --ox Sr=2,Fe=4,O=-2. +# generated using pymatgen +data_SrFeO3 +_symmetry_space_group_name_H-M Pm-3m +_cell_length_a 3.85000000 +_cell_length_b 3.85000000 +_cell_length_c 3.85000000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 221 +_chemical_formula_structural SrFeO3 +_chemical_formula_sum 'Sr1 Fe1 O3' +_cell_volume 57.06662500 +_cell_formula_units_Z 1 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y, x, z' + 4 'y, -x, -z' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y, -x, z' + 8 '-y, x, -z' + 9 'x, -y, -z' + 10 '-x, y, z' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x, y, -z' + 14 'x, -y, z' + 15 'y, x, -z' + 16 '-y, -x, z' + 17 'z, x, y' + 18 '-z, -x, -y' + 19 'z, -y, x' + 20 '-z, y, -x' + 21 'z, -x, -y' + 22 '-z, x, y' + 23 'z, y, -x' + 24 '-z, -y, x' + 25 '-z, x, -y' + 26 'z, -x, y' + 27 '-z, -y, -x' + 28 'z, y, x' + 29 '-z, -x, y' + 30 'z, x, -y' + 31 '-z, y, x' + 32 'z, -y, -x' + 33 'y, z, x' + 34 '-y, -z, -x' + 35 'x, z, -y' + 36 '-x, -z, y' + 37 '-y, z, -x' + 38 'y, -z, x' + 39 '-x, z, y' + 40 'x, -z, -y' + 41 '-y, -z, x' + 42 'y, z, -x' + 43 '-x, -z, -y' + 44 'x, z, y' + 45 'y, -z, -x' + 46 '-y, z, x' + 47 'x, -z, y' + 48 '-x, z, -y' +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Sr Sr0 1 0.00000000 0.00000000 0.00000000 1 + Fe Fe1 1 0.50000000 0.50000000 0.50000000 1 + O O2 3 0.00000000 0.50000000 0.50000000 1 diff --git a/examples/SrTiO3_cubic.cif b/examples/SrTiO3_cubic.cif new file mode 100644 index 0000000..bd10c70 --- /dev/null +++ b/examples/SrTiO3_cubic.cif @@ -0,0 +1,84 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 3.905 A. +# generated using pymatgen +data_SrTiO3 +_symmetry_space_group_name_H-M Pm-3m +_cell_length_a 3.90500000 +_cell_length_b 3.90500000 +_cell_length_c 3.90500000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 221 +_chemical_formula_structural SrTiO3 +_chemical_formula_sum 'Sr1 Ti1 O3' +_cell_volume 59.54744262 +_cell_formula_units_Z 1 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y, x, z' + 4 'y, -x, -z' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y, -x, z' + 8 '-y, x, -z' + 9 'x, -y, -z' + 10 '-x, y, z' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x, y, -z' + 14 'x, -y, z' + 15 'y, x, -z' + 16 '-y, -x, z' + 17 'z, x, y' + 18 '-z, -x, -y' + 19 'z, -y, x' + 20 '-z, y, -x' + 21 'z, -x, -y' + 22 '-z, x, y' + 23 'z, y, -x' + 24 '-z, -y, x' + 25 '-z, x, -y' + 26 'z, -x, y' + 27 '-z, -y, -x' + 28 'z, y, x' + 29 '-z, -x, y' + 30 'z, x, -y' + 31 '-z, y, x' + 32 'z, -y, -x' + 33 'y, z, x' + 34 '-y, -z, -x' + 35 'x, z, -y' + 36 '-x, -z, y' + 37 '-y, z, -x' + 38 'y, -z, x' + 39 '-x, z, y' + 40 'x, -z, -y' + 41 '-y, -z, x' + 42 'y, z, -x' + 43 '-x, -z, -y' + 44 'x, z, y' + 45 'y, -z, -x' + 46 '-y, z, x' + 47 'x, -z, y' + 48 '-x, z, -y' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Sr2+ 2.0 + Ti4+ 4.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Sr2+ Sr0 1 0.00000000 0.00000000 0.00000000 1 + Ti4+ Ti1 1 0.50000000 0.50000000 0.50000000 1 + O2- O2 3 0.00000000 0.50000000 0.50000000 1 diff --git a/examples/TiO2_rutile.cif b/examples/TiO2_rutile.cif new file mode 100644 index 0000000..41cc676 --- /dev/null +++ b/examples/TiO2_rutile.cif @@ -0,0 +1,50 @@ +# Constructed example for MaplePy; not a refinement, not from the ICSD. +# a = 4.5933 A, c = 2.9592 A, u = 0.3048, as in Section 2.2. +# generated using pymatgen +data_TiO2 +_symmetry_space_group_name_H-M P4_2/mnm +_cell_length_a 4.59330000 +_cell_length_b 4.59330000 +_cell_length_c 2.95920000 +_cell_angle_alpha 90.00000000 +_cell_angle_beta 90.00000000 +_cell_angle_gamma 90.00000000 +_symmetry_Int_Tables_number 136 +_chemical_formula_structural TiO2 +_chemical_formula_sum 'Ti2 O4' +_cell_volume 62.43439975 +_cell_formula_units_Z 2 +loop_ + _symmetry_equiv_pos_site_id + _symmetry_equiv_pos_as_xyz + 1 'x, y, z' + 2 '-x, -y, -z' + 3 '-y+1/2, x+1/2, z+1/2' + 4 'y+1/2, -x+1/2, -z+1/2' + 5 '-x, -y, z' + 6 'x, y, -z' + 7 'y+1/2, -x+1/2, z+1/2' + 8 '-y+1/2, x+1/2, -z+1/2' + 9 'x+1/2, -y+1/2, -z+1/2' + 10 '-x+1/2, y+1/2, z+1/2' + 11 '-y, -x, -z' + 12 'y, x, z' + 13 '-x+1/2, y+1/2, -z+1/2' + 14 'x+1/2, -y+1/2, z+1/2' + 15 'y, x, -z' + 16 '-y, -x, z' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Ti4+ 4.0 + O2- -2.0 +loop_ + _atom_site_type_symbol + _atom_site_label + _atom_site_symmetry_multiplicity + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + _atom_site_occupancy + Ti4+ Ti0 2 0.00000000 0.00000000 0.00000000 1 + O2- O1 4 0.19520000 0.80480000 0.50000000 1 diff --git a/examples/make_examples.py b/examples/make_examples.py new file mode 100644 index 0000000..54f4354 --- /dev/null +++ b/examples/make_examples.py @@ -0,0 +1,97 @@ +"""Write the example CIFs in this folder. + +Every structure here is constructed, from a space group, a lattice parameter +and ideal or rounded positions; none is a deposited refinement, and none +comes from the ICSD. Lattice parameters are the ones MaplePy's own +validation section uses where it has one (Section 2 of MaplePy.ipynb), and +round literature values otherwise. Run it to regenerate the files: + + python examples/make_examples.py +""" + +from pathlib import Path + +from pymatgen.core import Lattice, Structure +from pymatgen.io.cif import CifWriter + +HERE = Path(__file__).resolve().parent + + +def cubic_perovskite(a, A, B, X='O'): + return Structure.from_spacegroup('Pm-3m', Lattice.cubic(a), [A, B, X], + [[0, 0, 0], [0.5, 0.5, 0.5], + [0.5, 0.5, 0]]) + + +def write(s, name, states=True, note=''): + path = HERE / name + try: + CifWriter(s, symprec=0.01).write_file(path) + except Exception: # symmetry not found: write it in P1 + CifWriter(s, symprec=None).write_file(path) + text = path.read_text() + head = ('# Constructed example for MaplePy; not a refinement, not from ' + 'the ICSD.\n') + if note: + head += ''.join(f'# {line}\n' for line in note.splitlines()) + path.write_text(head + text) + print('wrote', name, '(with oxidation states)' if states else '') + + +def main(): + # The validation structures of Section 2, as CIFs + s = Structure.from_spacegroup('Fm-3m', Lattice.cubic(5.5391), ['Ba', 'O'], + [[0, 0, 0], [0.5, 0.5, 0.5]]) + s.add_oxidation_state_by_element({'Ba': 2, 'O': -2}) + write(s, 'BaO_rocksalt.cif', note='a = 5.5391 A, as in Section 2.3.') + + s = Structure.from_spacegroup(136, Lattice.tetragonal(4.5933, 2.9592), + ['Ti', 'O'], [[0, 0, 0], [0.3048, 0.3048, 0]]) + s.add_oxidation_state_by_element({'Ti': 4, 'O': -2}) + write(s, 'TiO2_rutile.cif', note='a = 4.5933 A, c = 2.9592 A, ' + 'u = 0.3048, as in Section 2.2.') + + s = cubic_perovskite(4.0019, 'Ba', 'Ti') + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + write(s, 'BaTiO3_cubic.cif', note='a = 4.0019 A, as in Section 2.3.') + + s = cubic_perovskite(3.905, 'Sr', 'Ti') + s.add_oxidation_state_by_element({'Sr': 2, 'Ti': 4, 'O': -2}) + write(s, 'SrTiO3_cubic.cif', note='a = 3.905 A.') + + # An ordered pyrochlore A2B2O7, Fd-3m (origin choice 2): A on 16d, B on + # 16c, O on 48f (x, 1/8, 1/8) and 8b (3/8, 3/8, 3/8) + s = Structure.from_spacegroup( + 'Fd-3m:2', Lattice.cubic(10.185), ['Gd', 'Ti', 'O', 'O'], + [[0.5, 0.5, 0.5], [0, 0, 0], [0.330, 0.125, 0.125], + [0.375, 0.375, 0.375]]) + s.add_oxidation_state_by_element({'Gd': 3, 'Ti': 4, 'O': -2}) + write(s, 'Gd2Ti2O7_pyrochlore.cif', + note='a = 10.185 A, x(48f) = 0.330, origin choice 2.') + + # A mixed A site: the mean-field charge approximation + s = cubic_perovskite(3.95, 'Ba', 'Ti') + s.replace_species({'Ba': {'Ba': 0.5, 'Sr': 0.5}}) + s.add_oxidation_state_by_element({'Ba': 2, 'Sr': 2, 'Ti': 4, 'O': -2}) + write(s, 'Ba0.5Sr0.5TiO3_disordered.cif', + note='a = 3.95 A; Ba and Sr share the A site at 0.5 each.') + + # A geometry fault: BaTiO3 with its lattice parameter mistyped, as a + # transcription error might give it. Ti-O 1.50 A is shorter than any + # cation-anion bond in an oxide, and MaplePy says so. + s = cubic_perovskite(3.0019, 'Ba', 'Ti') + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + write(s, 'BaTiO3_wrong_cell.cif', + note='a = 3.0019 A: the 4.0019 A of BaTiO3_cubic.cif with its first ' + 'digit mistyped.') + + # No oxidation states, and an element with more than one common state: + # MaplePy stops and asks, rather than guessing Fe(II) or Fe(III) + s = cubic_perovskite(3.85, 'Sr', 'Fe') + write(s, 'SrFeO3_no_states.cif', states=False, + note='a = 3.85 A; no oxidation states. Run with ' + '--ox Sr=2,Fe=4,O=-2.') + + +if __name__ == '__main__': + main() diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..faea3b7 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,62 @@ +[build-system] +requires = ["hatchling>=1.24"] +build-backend = "hatchling.build" + +[project] +name = "maplepy" +version = "1.4.0" +description = "MAPLE (Madelung Part of Lattice Energy) from CIF files, and Hoppe's additivity theorem tested at database scale" +readme = "README.md" +license = "MIT" +license-files = ["LICENSE"] +authors = [{ name = "Nik Reeves-McLaren" }] +requires-python = ">=3.11" +keywords = ["crystallography", "MAPLE", "Madelung energy", "lattice energy", + "additivity theorem", "crystal structure validation", "CIF", "ICSD"] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Science/Research", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Scientific/Engineering :: Chemistry", + "Topic :: Scientific/Engineering :: Physics", +] +dependencies = [ + "pymatgen>=2024.2.8", + "numpy>=1.26", + "pandas>=2.0", + "matplotlib>=3.8", + "adjustText>=1.0", + "joblib>=1.3", +] + +[project.optional-dependencies] +test = ["pytest>=7"] + +[project.scripts] +maplepy = "maplepy.cli:main_maplepy" +hopper = "maplepy.cli:main_hopper" + +[project.urls] +Homepage = "https://github.com/SuperBladesman/MaplePy" +Issues = "https://github.com/SuperBladesman/MaplePy/issues" +Changelog = "https://github.com/SuperBladesman/MaplePy/blob/main/CHANGELOG.md" + +[tool.hatch.build.targets.wheel] +packages = ["src/maplepy"] + +# The reference tables live in data/ at the top of the repository, where the +# notebooks read them; the wheel carries a copy as maplepy/data. +[tool.hatch.build.targets.wheel.force-include] +"data" = "maplepy/data" + +[tool.hatch.build.targets.sdist] +include = ["src/maplepy", "data", "tests", "examples", "tools", "README.md", + "LICENSE", "CHANGELOG.md", "CITATION.cff", "MaplePy.ipynb", + "Hopper.ipynb"] + +[tool.pytest.ini_options] +testpaths = ["tests"] diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..6ef136c --- /dev/null +++ b/requirements.txt @@ -0,0 +1,7 @@ +# For running the notebooks directly; the package declares the same in pyproject.toml. +pymatgen>=2024.2.8 +numpy>=1.26 +pandas>=2.0 +matplotlib>=3.8 +adjustText>=1.0 +joblib>=1.3 diff --git a/src/maplepy/__init__.py b/src/maplepy/__init__.py new file mode 100644 index 0000000..a7aebed --- /dev/null +++ b/src/maplepy/__init__.py @@ -0,0 +1,26 @@ +"""maplepy: MAPLE (Madelung Part of Lattice Energy) from CIF files with +MaplePy, and Hoppe's additivity theorem tested on the results with Hopper. + + import maplepy + r = maplepy.compute('examples/BaTiO3_cubic.cif') + r.total_maple, r.madelung_factor, r.geometry_flag + + out = maplepy.run_folder('my_cifs/') # MaplePy's batch_maple() + df = maplepy.additivity(out) # Hopper, on that run + + maplepy.validate() # the three known answers + +The engines are the notebooks MaplePy.ipynb and Hopper.ipynb, copied cell by +cell (see docs/PACKAGE.md). +""" + +from ._manifest import HOPPER_VERSION, MAPLEPY_VERSION + +__version__ = '1.4.0' + +from .api import (MapleResult, additivity, compute, engine, # noqa: E402 + hopper_engine, run_folder, validate) + +__all__ = ['__version__', 'MAPLEPY_VERSION', 'HOPPER_VERSION', 'MapleResult', + 'compute', 'run_folder', 'additivity', 'validate', 'engine', + 'hopper_engine'] diff --git a/src/maplepy/__main__.py b/src/maplepy/__main__.py new file mode 100644 index 0000000..b2fd38f --- /dev/null +++ b/src/maplepy/__main__.py @@ -0,0 +1,3 @@ +from .cli import main_maplepy + +raise SystemExit(main_maplepy()) diff --git a/src/maplepy/_cells/hopper/e03_setup_and_version.py b/src/maplepy/_cells/hopper/e03_setup_and_version.py new file mode 100644 index 0000000..ead5d76 --- /dev/null +++ b/src/maplepy/_cells/hopper/e03_setup_and_version.py @@ -0,0 +1,119 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 3. +# Edit the notebook, not this file, then rebuild. + +import numpy as np +import pandas as pd +import matplotlib.pyplot as plt +import matplotlib.ticker as mticker +from pathlib import Path + +# ── Sheffield colour palette ─────────────────────────────────────────────────── +SHEFFIELD = { + 'brand_violet' : '#440099', + 'dark_violet' : '#24125E', + 'electric' : '#7000FF', + 'powder_violet': '#A78CFA', + 'pale_violet' : '#C8BBFF', + 'teal' : '#005A8F', + 'aqua' : '#00BBCC', + 'coral' : '#E7004C', + 'flamingo' : '#FF6371', + 'peach' : '#FF9664', + 'peak_green' : '#005750', + 'spearmint' : '#3BD4AE', + 'midnight' : '#131E29', + 'pastel_green' : '#A1DED2', + 'powder_blue' : '#9ADBE8', +} + +# ── The version, named once ──────────────────────────────────────────────── +# v1.2.1: written into the classified export as a column, so a CSV on disk +# says which notebook classified it. MaplePy does the same. +# v1.2.9: the decomposition records which binaries are estimates; see +# ESTIMATED_BINARIES in Section 1. +HOPPER_VERSION = '1.2.9' + +# ── Hoppe's criterion, named once ────────────────────────────────────────── +# +# v1.2.1: 1.0 was the default argument of classify_additivity, the axvline in +# Figure 1, the "< 1%" in the figure's annotation and the "GOOD (<1%)" in the +# decomposition print. Four literals for one criterion, and the figure and the +# classifier were counting different populations against it: 662 against 661 +# on the perovskite run, both in the paper. +ADDITIVE_THRESHOLD_PCT = 1.0 # Hoppe's additivity criterion, per cent + +# ── When a mean oxidation state is not a state ───────────────────────────── +# +# v1.2.3: _binary_formula_for rounds abs(oxi_state) to pick a binary, and said +# nothing about having done it. On a site shared by two cations the +# occupancy-weighted mean is not an oxidation state at all: Y3NbO7 has Y and +# Nb on one site at a mean of 3.5, rounded up to 4, and the decomposition then +# asked for YO2. Yttrium has no tetravalent oxide because yttrium has no +# tetravalent state. +# +# v1.2.6: the measurement that used to be here was taken over the 30 +# structures with a missing binary and claimed an empty band between 0.05 and +# 0.45 of an integer. Re-measured over ALL 29,226 sites in the two families +# there is no empty band anywhere: +# +# exactly integral 28,218 0.15 to 0.25 136 +# 0.002 to 0.05 408 0.25 to 0.35 64 +# 0.05 to 0.15 344 0.35 to 0.45 32 +# 0.45 to 0.50 24 +# +# So this is a JUDGEMENT, not a measured gap, and moving it moves the 1.4 +# population: 408 sites lie inside it and 600 outside. It is small enough +# that a genuine half-integer mean is never taken for a rounding error, +# which is the whole of what it is for. +OXI_ROUNDING_TOL = 0.05 # e; a mean this far from an integer was not a + # state before it was rounded + +# ── Looking a structure up ───────────────────────────────────────────────── +# +# v1.2.4: every lookup in this notebook was `df[df['source_cif'] == cif]`, +# which scans the whole frame. Measured on the perovskite run, 938 structures +# and 18,644 per-site rows: +# +# one scan of the results frame 2.4 ms +# one groupby of the same frame 0.11 s, once +# one dict lookup afterwards 0.0000013 ms +# +# About three scans per structure, and the classifier and the +# coordinate-screen count each did their own set, so batch_additivity took +# 5.10 s, classify_additivity 3.67 s and the counting loop 3.50 s. +# +# Group once, pass the index down. Every function that takes one takes it +# optionally and falls back to the scan, so it still works called on its own. +def index_by_cif(df, column='source_cif'): + """Every row of df, grouped by structure, once.""" + return {k: v for k, v in df.groupby(column, sort=False)} + + +def rows_for(cif, df, index=None, column='source_cif'): + """The rows for one structure, from the index if there is one. + + Returns an empty frame where the structure is absent, which is what the + scan returned, so callers do not change. + """ + if index is not None: + got = index.get(cif) + return got if got is not None else df.iloc[0:0] + return df[df[column] == cif] + + +plt.rcParams.update({ + 'font.family' : 'sans-serif', + 'font.size' : 11, + 'axes.labelsize' : 13, + 'axes.titlesize' : 14, + 'figure.dpi' : 150, + 'savefig.dpi' : 300, + 'savefig.bbox' : 'tight', + 'axes.linewidth' : 1.0, + 'xtick.direction' : 'in', + 'ytick.direction' : 'in', + 'xtick.major.width': 1.0, + 'ytick.major.width': 1.0, +}) + +print("Hoppe Additivity Analysis loaded.") \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/e06_binary_reference_table.py b/src/maplepy/_cells/hopper/e06_binary_reference_table.py new file mode 100644 index 0000000..ee18bd4 --- /dev/null +++ b/src/maplepy/_cells/hopper/e06_binary_reference_table.py @@ -0,0 +1,305 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 6. +# Edit the notebook, not this file, then rebuild. + +# ───────────────────────────────────────────────────────────────────────────── +# +# Fallback values from MaplePy validation structures and Hoppe (1995). +# Format: {reduced_formula: (maple_kcal_mol, structure_type, source)} +# +# UPDATE these with your own MaplePy batch results on ICSD CIFs. +# The fallback values are a starting point, not a definitive reference. + +BINARY_MAPLE_FALLBACK = { + + # ── Rock salt MO (Fm-3m) ────────────────────────────────────────── + # ICSD median values + "MgO":(1102.2, "Rock salt Fm-3m", "Median of 34 ambient ICSD Fm-3m entries, range 1092-1106"), + "CaO":(965.0, "Rock salt Fm-3m", "Median of 15 ambient ICSD Fm-3m entries, range 964-972"), + "SrO":(900.0, "Rock salt Fm-3m", "Median of 11 ambient ICSD Fm-3m entries, range 898-906"), + "BaO":(838.5, "Rock salt Fm-3m", "Median of 4 ambient ICSD Fm-3m entries, range 838-842; 1 zero excluded"), + "MnO":(1044.7, "Rock salt Fm-3m", "Median of 13 ambient ICSD Fm-3m entries, range 1036-1053; 1 zero excluded"), + "FeO":(1077.4, "Rock salt Fm-3m", "Median of 5 ambient ICSD Fm-3m entries, range 1073-1082; 2 zeros excluded"), + "CoO":(1090.4, "Rock salt Fm-3m", "Median of 22 ambient ICSD Fm-3m entries, range 1086-1100"), + "NiO":(1111.1, "Rock salt Fm-3m", "Median of 30 ambient ICSD Fm-3m entries, range 1052-1119"), + "CdO":(988.6, "Rock salt Fm-3m", "Median of 14 ambient ICSD Fm-3m entries, range 982-992; 3 zeros excluded"), + "TiO":(1110.6, "Rock salt Fm-3m", "Median of 8 ambient ICSD Fm-3m entries, range 1081-1113; 2 zeros excluded"), + "VO":(1136.8, "Rock salt Fm-3m", "Median of 9 ambient ICSD Fm-3m entries, range 1127-1143; 1 zero excluded"), + "ZnO":(1086.0, "Rock salt Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 1085-1087; HP polymorph"), + # Estimated rock salts + "EuO":(902.9, "Rock salt Fm-3m", "Median of 9 ambient ICSD Fm-3m entries, range 901-904; 3 zeros excluded"), + "CuO":(1093.6, "Rock salt Fm-3m", "1 ambient ICSD Fm-3m entry; HP polymorph, not tenorite"), + "PbO":(810.0, "Litharge", "Estimated, unsourced"), + + # ── Antifluorite M2O (Fm-3m) ────────────────────────────────────── + # ICSD median values + "Li2O":(837.7, "Antifluorite Fm-3m", "Median of 10 ambient ICSD Fm-3m entries, range 835-838"), + "Na2O":(694.5, "Antifluorite Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 694-695"), + "K2O":(599.8, "Antifluorite Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 599-600"), + "Rb2O":(572.6, "Antifluorite Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 572-573"), + # Estimated + "Cs2O":(450.0, "Antifluorite Fm-3m", "Estimated, unsourced"), + "Ag2O":(700.0, "Cuprite Pn-3m", "Estimated, unsourced"), + "Cu2O":(730.0, "Cuprite Pn-3m", "MaplePy v4, a=4.270"), + "Tl2O":(650.0, "Various", "Estimated, unsourced"), + "Pd2O":(700.0, "Various", "Estimated, Pd1+ binary"), + + # ── Rutile MO2 (P4_2/mnm) ───────────────────────────────────────── + # ICSD median values + "TiO2":(3256.2, "Rutile P4_2/mnm", "Median of 112 ambient ICSD P4_2/mnm entries, range 3218-3505"), + "SnO2":(3110.2, "Rutile P4_2/mnm", "Median of 48 ambient ICSD P4_2/mnm entries, range 3071-3156"), + "MnO2":(3382.9, "Rutile P4_2/mnm", "Median of 19 ambient ICSD P4_2/mnm entries, range 3332-3388; 1 zero excluded"), + "GeO2":(3389.6, "Rutile P4_2/mnm", "Median of 8 ambient ICSD P4_2/mnm entries, range 3386-3425"), + "RuO2":(3244.8, "Rutile P4_2/mnm", "Median of 17 ambient ICSD P4_2/mnm entries, range 3228-3252"), + "IrO2":(3225.5, "Rutile P4_2/mnm", "Median of 8 ambient ICSD P4_2/mnm entries, range 3221-3235"), + "PbO2":(2955.0, "Rutile P4_2/mnm", "Median of 11 ambient ICSD P4_2/mnm entries, range 2946-2959"), + "VO2":(3291.8, "Rutile P4_2/mnm", "Median of 5 ambient ICSD P4_2/mnm entries, range 3284-3317"), + "CrO2":(3352.8, "Rutile P4_2/mnm", "Median of 14 ambient ICSD P4_2/mnm entries, range 3346-3424"), + "OsO2":(3210.8, "Rutile P4_2/mnm", "Median of 5 ambient ICSD P4_2/mnm entries, range 3205-3215"), + "NbO2":(3153.4, "Rutile P4_2/mnm", "Median of 3 ambient ICSD P4_2/mnm entries, range 3120-3154"), + "MoO2":(3179.7, "Rutile P4_2/mnm", "Median of 2 ambient ICSD P4_2/mnm entries, range 3179-3180"), + "WO2":(3196.9, "Rutile P4_2/mnm", "1 ambient ICSD P4_2/mnm entry"), + "RhO2":(3264.4, "Rutile P4_2/mnm", "Median of 2 ambient ICSD P4_2/mnm entries, range 3261-3268; 1 zero excluded"), + "PtO2":(3239.7, "Rutile P4_2/mnm", "1 ambient ICSD P4_2/mnm entry"), + "PdO2":(3251.9, "Rutile P4_2/mnm", "1 ambient ICSD P4_2/mnm entry"), + "ReO2":(3177.5, "Rutile P4_2/mnm", "1 ambient ICSD P4_2/mnm entry"), + "TaO2":(3145.9, "Rutile P4_2/mnm", "Median of 2 ambient ICSD P4_2/mnm entries, range 3130-3162"), + "SiO2":(3593.7, "Stishovite P4_2/mnm", "Median of 42 ambient ICSD P4_2/mnm entries, range 3575-3664"), + # Estimated rutiles + "TcO2":(3250.0, "Rutile P4_2/mnm", "Estimated from Ru/Rh/Os trend"), + "SbO2":(3100.0, "Rutile P4_2/mnm", "Estimated, unsourced"), + + # ── Fluorite MO2 (Fm-3m) ────────────────────────────────────────── + # ICSD median values + "CeO2":(2856.3, "Fluorite Fm-3m", "Median of 64 ambient ICSD Fm-3m entries, range 2796-2891; 4 zeros excluded"), + "ZrO2":(3020.0, "Fluorite Fm-3m", "Median of 12 ambient ICSD Fm-3m entries, range 3001-3176"), + "HfO2":(3034.4, "Fluorite Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 3016-3053"), + "ThO2":(2761.6, "Fluorite Fm-3m", "Median of 15 ambient ICSD Fm-3m entries, range 2758-2770; 3 zeros excluded"), + "UO2":(2826.6, "Fluorite Fm-3m", "Median of 25 ambient ICSD Fm-3m entries, range 2821-2854; 2 zeros excluded"), + "PrO2":(2865.5, "Fluorite Fm-3m", "Median of 5 ambient ICSD Fm-3m entries, range 2861-2872; 3 zeros excluded"), + "TbO2":(2965.0, "Fluorite Fm-3m", "1 ambient ICSD Fm-3m entry; 2 zeros excluded"), + "NpO2":(2843.9, "Fluorite Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 2843-2844; 4 zeros excluded"), + "AmO2":(2874.0, "Fluorite Fm-3m", "Median of 5 ambient ICSD Fm-3m entries, range 2867-2876"), + "CmO2":(2879.4, "Fluorite Fm-3m", "Median of 2 ambient ICSD Fm-3m entries, range 2877-2882; 5 zeros excluded"), + "PuO2":(2863.9, "Fluorite Fm-3m", "Median of 3 ambient ICSD Fm-3m entries, range 2863-2864; 2 zeros excluded"), + + # ── Corundum M2O3 (R-3c) ────────────────────────────────────────── + # ICSD median values + "Al2O3":(4356.2, "Corundum R-3c", "Median of 68 ambient ICSD R-3c entries, range 4250-4369"), + "Cr2O3":(4170.3, "Corundum R-3c", "Median of 21 ambient ICSD R-3c entries, range 4159-4190"), + "Fe2O3":(4121.9, "Corundum R-3c", "Median of 53 ambient ICSD R-3c entries, range 4074-4207; 2 outliers excluded"), + "V2O3":(4124.1, "Corundum R-3c", "Median of 14 ambient ICSD R-3c entries, range 4119-4924"), + "Ti2O3":(4036.2, "Corundum R-3c", "Median of 12 ambient ICSD R-3c entries, range 4031-4066"), + "Ga2O3":(4183.4, "Corundum R-3c", "Median of 3 ambient ICSD R-3c entries, range 4181-4198"), + "Rh2O3":(4072.3, "Corundum R-3c", "Median of 4 ambient ICSD R-3c entries, range 4024-4087"), + # Estimated corundums + "Ni2O3":(4100.0, "Estimated", "Interpolated from 3d corundum trend Ti-V-Cr-Fe; no stable ambient phase in ICSD"), + + # ── Spinel (Fd-3m) ──────────────────────────────────────────────── + # Co2O3 does not exist as a stable ambient phase; Co3O4 spinel used instead + "Co3O4":(5445.2, "Spinel Fd-3m", "Median of 26 ambient ICSD Fd-3m entries, range 5020-5508"), + + # ── Bixbyite M2O3 (Ia-3) ───────────────────────────────────────── + # ICSD median values + "Mn2O3":(4133.9, "Bixbyite Ia-3", "Median of 10 ambient ICSD Ia-3 entries, range 4087-4155"), + "Y2O3":(3652.0, "Bixbyite Ia-3", "Median of 38 ambient ICSD Ia-3 entries, range 3585-4179; 2 zeros excluded"), + "Sc2O3":(3929.6, "Bixbyite Ia-3", "Median of 8 ambient ICSD Ia-3 entries, range 3927-3966"), + "Tl2O3":(3675.2, "Bixbyite Ia-3", "Median of 4 ambient ICSD Ia-3 entries, range 3663-3700"), + "In2O3":(3822.4, "Bixbyite Ia-3", "Median of 18 ambient ICSD Ia-3 entries, range 3793-3849"), + + # ── RE sesquioxides ─────────────────────────────────────────────── + # ICSD median values — A-type (P-3m1) for La; bixbyite (Ia-3) for rest + "La2O3":(3390.9, "A-type P-3m1", "Median of 11 ambient ICSD P-3m1 entries, range 3337-3436"), + "Ce2O3":(3483.6, "Bixbyite Ia-3", "1 ambient ICSD Ia-3 entry"), + "Pr2O3":(3475.6, "Bixbyite Ia-3", "Median of 2 ambient ICSD Ia-3 entries, range 3476-3476"), + "Nd2O3":(3496.8, "Bixbyite Ia-3", "Median of 3 ambient ICSD Ia-3 entries, range 3495-3507"), + "Pm2O3":(3525.4, "Bixbyite Ia-3", "1 ambient ICSD Ia-3 entry"), + "Sm2O3":(3545.1, "Bixbyite Ia-3", "Median of 5 ambient ICSD Ia-3 entries, range 3541-3558"), + "Eu2O3":(3569.8, "Bixbyite Ia-3", "Median of 6 ambient ICSD Ia-3 entries, range 3559-3630"), + "Gd2O3":(3581.4, "Bixbyite Ia-3", "Median of 14 ambient ICSD Ia-3 entries, range 3573-3611"), + "Tb2O3":(3608.5, "Bixbyite Ia-3", "Median of 5 ambient ICSD Ia-3 entries, range 3592-3625"), + "Dy2O3":(3631.2, "Bixbyite Ia-3", "Median of 10 ambient ICSD Ia-3 entries, range 3624-3646"), + "Ho2O3":(3650.6, "Bixbyite Ia-3", "Median of 9 ambient ICSD Ia-3 entries, range 3641-3655"), + "Er2O3":(3670.2, "Bixbyite Ia-3", "Median of 10 ambient ICSD Ia-3 entries, range 3655-3689"), + "Tm2O3":(3698.6, "Bixbyite Ia-3", "Median of 5 ambient ICSD Ia-3 entries, range 3691-3710"), + "Yb2O3":(3712.0, "Bixbyite Ia-3", "Median of 17 ambient ICSD Ia-3 entries, range 3707-3724"), + "Lu2O3":(3727.0, "Bixbyite Ia-3", "Median of 12 ambient ICSD Ia-3 entries, range 3703-3735"), + + # ── Other binaries ──────────────────────────────────────────────── + "Bi2O3":(2580.0, "Monoclinic P2_1/c", "MaplePy v4, alpha-Bi2O3 — to be updated"), + "HgO":(850.0, "Various", "Estimated, unsourced"), + + # ── Higher-valent oxides ────────────────────────────────────────── + "V2O5":(9454.0, "Pmmn", "Median of 17 ambient ICSD Pmmn entries, range 9393-9638"), + "Nb2O5":(8988.2, "C2/c", "Median of 2 ambient ICSD C2/c entries, range 8984-8992"), + "Ta2O5":(9127.2, "C2/c", "1 ambient ICSD C2/c entry"), + "Sb2O5":(8955.4, "C2/c", "Median of 2 ambient ICSD C2/c entries, range 8955-8956"), + "Bi2O5":(4300.0, "Various", "Estimated, unsourced"), + "WO3":(4600.0, "ReO3-type", "Estimated, unsourced"), + "MoO3":(4500.0, "Various", "Estimated, unsourced"), + "CrO3":(4400.0, "Various", "Estimated, unsourced"), + "OsO3":(4500.0, "Various", "Estimated, unsourced"), + "RuO3":(4500.0, "Various", "Estimated, Ru6+ binary"), + "ReO3":(4600.0, "ReO3-type", "Estimated, Re6+ binary"), + "Re2O5":(4400.0, "Various", "Estimated, Re5+ binary"), + "Re2O7":(5000.0, "Various", "Estimated, unsourced"), + "Tc2O7":(5000.0, "Various", "Estimated, unsourced"), + "Ru2O5":(4250.0, "Various", "Estimated, Ru5+ binary"), + "W2O5":(4300.0, "Various", "Estimated, W5+ binary"), + "Mo2O3":(3300.0, "Various", "Estimated, Mo3+ binary"), +} + + +def load_binary_table(csv_path=None, fallback=True): + """ + Load the binary oxide MAPLE reference table. + + Priority: + 1. CSV from a MaplePy batch run on binary CIFs (if csv_path given) + 2. Fallback dict above + + Returns + ------- + dict {reduced_formula: maple_kcal_mol} + pd.DataFrame for display + """ + lookup = {} + rows = [] + + if csv_path is not None and Path(csv_path).exists(): + df = pd.read_csv(csv_path) + print(f"Loaded binary reference from {csv_path}") + name_col = 'compound' if 'compound' in df.columns else 'formula' + for _, r in df.iterrows(): + formula = r[name_col] + maple = r['total_maple'] if 'total_maple' in df.columns \ + else r.get('maple_kcal_mol') + if pd.notna(maple): + lookup[formula] = float(maple) + rows.append({"formula": formula, + "maple_kcal_mol": float(maple), + "source": "ICSD CIF batch"}) + print(f" {len(lookup)} binaries loaded from CSV.") + + if fallback: + n_added = 0 + for formula, (maple, stype, source) in BINARY_MAPLE_FALLBACK.items(): + if formula not in lookup: + lookup[formula] = maple + rows.append({"formula": formula, + "maple_kcal_mol": maple, + "source": source}) + n_added += 1 + if n_added > 0: + print(f" {n_added} binaries added from fallback table.") + + df_out = pd.DataFrame(rows).sort_values("formula").reset_index(drop=True) + print(f" Total binary references: {len(lookup)}") + return lookup, df_out + + +# ── The released reference table is the source ────────────────────────────── +# +# v1.2: BINARY_MAPLE_FALLBACK above is a 104-entry dict written inline. The +# released JSON has 112 - the extra eight are the oxyanion formers added for +# the borosulfate work, which the notebook never received. Measured formula by +# formula, no VALUE disagrees between the two, but the membership already +# does, and the copy the community downloads was not the copy the analysis +# used. +# +# The JSON is now read first. The inline dict remains for when the file is +# absent, and the guard below compares the two wherever they overlap: a value +# that has drifted stops the run and names the formula, rather than one copy +# quietly winning. + +def load_binary_reference(path=None): + """ + The binary oxide reference table, from the released JSON. + + Returns (lookup, source_string). Falls back to the inline dict only when + no JSON can be found, and says so. + """ + import json as _json + from pathlib import Path as _Path + + _names = ('binary_oxide_maple_reference_v1_1.json', + 'binary_oxide_maple_reference.json') + _dirs = ('data', '.', '..') + _cands = ([_Path(path)] if path else + [_Path(d) / n for d in _dirs for n in _names]) + + for _p in _cands: + if not _p.is_file(): + continue + with open(_p, 'r', encoding='utf-8') as _f: + _d = _json.load(_f) + _lookup = {e['formula']: float(e['maple_kcal_mol']) + for e in _d['entries']} + return _lookup, str(_p.resolve()) + + if path: + raise FileNotFoundError(f'binary reference table not found: {path}') + return ({f: v[0] for f, v in BINARY_MAPLE_FALLBACK.items()}, + 'INLINE FALLBACK - the released JSON was not found') + + +BINARY_REFERENCE_PATH = _HOPPER_REFERENCE_PATH # maplepy package: the bundled table +# # set to override the search + +_json_lookup, _binary_source = load_binary_reference(BINARY_REFERENCE_PATH) + +# THE GUARD. Two copies of one table are safe only while something checks +# them. Where a formula is in both, the values must agree. +_drift = [(f, BINARY_MAPLE_FALLBACK[f][0], _json_lookup[f]) + for f in sorted(set(BINARY_MAPLE_FALLBACK) & set(_json_lookup)) + if abs(BINARY_MAPLE_FALLBACK[f][0] - _json_lookup[f]) > 1e-6] +if _drift: + raise AssertionError( + 'the inline table and the released JSON disagree on ' + + ', '.join(f'{f} ({a} vs {b})' for f, a, b in _drift[:5]) + + f'{" and others" if len(_drift) > 5 else ""}. ' + 'One of them is stale; decide which before running.') + +print(f' binary reference: {len(_json_lookup)} entries from {_binary_source}') + +# ── Which entries are estimates ──────────────────────────────────────── +# +# v1.2.9: 23 of the 112 values are estimates, interpolated within a structure +# type or set by hand, and none has a published or computed source; Cu2O's +# recorded source, a MaplePy calculation at a = 4.270 A, gives 797.9 rather +# than 730.0 and is marked unsourced in the JSON (sourced: false). They are +# kept, so that results made with them can be reproduced, and every +# decomposition that uses one says so (`estimated_binaries`). Nothing is +# reclassified on that account: a residual resting on an estimate is a +# residual against a weaker reference, and the reader is told which. +def estimated_binaries(source_path): + """The formulae whose reference value is an estimate, or unsourced. + + From the released JSON's `source` and `sourced` fields where the table + was read from it (Cu2O is unsourced, not estimated); + from the inline labels where it was not. + """ + import json as _json + from pathlib import Path as _Path + _p = _Path(source_path) + if _p.is_file(): + with open(_p, 'r', encoding='utf-8') as _f: + return {e['formula'] for e in _json.load(_f)['entries'] + if e.get('source') == 'estimated' + or e.get('sourced') is False} + return {f for f, (_v, _t, _s) in BINARY_MAPLE_FALLBACK.items() + if _s.lower().startswith(('estimated', 'interpolated'))} + + +ESTIMATED_BINARIES = estimated_binaries(_binary_source) +print(f' estimated or unsourced: {len(ESTIMATED_BINARIES)} entries') +print(f' inline fallback: {len(BINARY_MAPLE_FALLBACK)} entries, ' + f'{len(set(_json_lookup) - set(BINARY_MAPLE_FALLBACK))} of the released ' + f'entries not in it, no value in disagreement') + +# To use your own ICSD batch results instead, set BINARY_CSV below. +BINARY_CSV = None # e.g. Path("binary_oxides/maple_summary.csv") + +BINARY_MAPLE, df_binary = load_binary_table(csv_path=BINARY_CSV) +# the released table wins over the inline fallback for anything it carries +BINARY_MAPLE.update(_json_lookup) +display(df_binary) \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/e08_decomposition.py b/src/maplepy/_cells/hopper/e08_decomposition.py new file mode 100644 index 0000000..a77da2c --- /dev/null +++ b/src/maplepy/_cells/hopper/e08_decomposition.py @@ -0,0 +1,244 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 8. +# Edit the notebook, not this file, then rebuild. + +# ───────────────────────────────────────────────────────────────────────────── + +def _binary_formula_for(element, oxi_state): + """ + Return the expected binary oxide formula for a cation at a + given oxidation state, plus the cation and oxygen counts + per formula unit of that binary. + + Returns (formula_str, n_cations, n_oxygens) or (None, None, None). + """ + oxi = round(abs(oxi_state)) + + # ── Special cases ───────────────────────────────────────────── + # Co3O4 spinel: Co2+[Co3+]2O4. Use as the Co3+ reference. + # Decomposition: 1 Co3+ requires 1/3 Co3O4 (3 Co per fu), + # contributing 4/3 O per Co3+. + if element == "Co" and oxi == 3: + return ("Co3O4", 3, 4) + + patterns = { + 1: (f"{element}2O", 2, 1), + 2: (f"{element}O", 1, 1), + 3: (f"{element}2O3", 2, 3), + 4: (f"{element}O2", 1, 2), + 5: (f"{element}2O5", 2, 5), + 6: (f"{element}O3", 1, 3), + 7: (f"{element}2O7", 2, 7), + } + return patterns.get(oxi, (None, None, None)) + + +def decompose_ternary(source_cif, df_results, binary_lookup, verbose=True, + results_index=None): + """ + Decompose a ternary oxide into binary components using the + per-site oxidation states from MaplePy output. + + Parameters + ---------- + source_cif : str filename from maple_summary/results + df_results : DataFrame site-level MaplePy output + binary_lookup : dict {formula: maple_kcal_mol} + verbose : bool + + Returns + ------- + dict with keys: + source_cif, compound, maple_ternary, + decomposition (list of dicts per cation element), + maple_binary_sum, delta_abs, delta_pct, + oxygen_balanced, missing_binaries, success + """ + # v1.2.4: from the index where the caller built one; the scan it + # replaces cost 2.4 ms of the 5.4 ms this function took per structure. + sites = rows_for(source_cif, df_results, results_index).copy() + + if sites.empty: + return {"source_cif": source_cif, "success": False, + "error": "No site data found"} + + compound = sites['compound'].iloc[0] + maple_tern = sites['total_maple'].iloc[0] + Z = sites['Z'].iloc[0] + + # ── Identify cations and their mean oxidation states ────────────── + cation_sites = sites[sites['oxidation_state'] > 0] + anion_sites = sites[sites['oxidation_state'] < 0] + + if cation_sites.empty: + return {"source_cif": source_cif, "compound": compound, + "success": False, "error": "No cation sites identified"} + + cation_info = {} + for el in cation_sites['element'].unique(): + el_sites = cation_sites[cation_sites['element'] == el] + cation_info[el] = { + 'count_per_fu': len(el_sites) / Z, + 'mean_oxi': el_sites['oxidation_state'].mean(), + 'sites_in_cell': len(el_sites), + } + + o_per_fu = len(anion_sites) / Z + + # ── Decompose each cation into its binary ───────────────────────── + decomposition = [] + maple_sum = 0.0 + o_from_binary = 0.0 + missing = [] + # v1.2.3: what was asked for and why it was not there, one entry per + # missing binary. `missing_binaries` stays as it was, for the report and + # for every CSV already written. + missing_detail = [] + estimated_used = [] # v1.2.9: binaries whose value is an estimate + + for el, info in cation_info.items(): + binary_formula, n_cat, n_oxy = _binary_formula_for( + el, info['mean_oxi'] + ) + + # v1.2.3: did the pattern lookup have to round? A mean over a + # shared site is not an oxidation state, and the rounding was silent. + _mean = abs(info['mean_oxi']) + _rounded = abs(_mean - round(_mean)) > OXI_ROUNDING_TOL + + if binary_formula is None: + missing.append(f"{el}{info['mean_oxi']:+.1f} (no pattern)") + missing_detail.append({ + 'binary': None, 'element': el, + 'mean_oxi': round(info['mean_oxi'], 3), + 'rounded_from_non_integer': _rounded, + 'reason': 'no binary pattern for this oxidation state'}) + continue + + maple_binary = binary_lookup.get(binary_formula) + if maple_binary is None: + # v1.2.5: the rounding fact goes IN the string. It used to live in + # missing_detail, a parallel list that batch_additivity never put + # into its frame, so the classifier's best evidence never reached + # it. One carrier, and it is the one that survives to the CSV. + missing.append( + f"{binary_formula} (not in table" + + (f", mean {info['mean_oxi']:+.2f} rounded)" if _rounded + else ")")) + missing_detail.append({ + 'binary': binary_formula, 'element': el, + 'mean_oxi': round(info['mean_oxi'], 3), + 'rounded_from_non_integer': _rounded, + 'reason': 'not in the reference table'}) + continue + + # v1.2.9: an estimate is used, and said to be used + if binary_formula in ESTIMATED_BINARIES: + estimated_used.append(binary_formula) + + coeff = info['count_per_fu'] / n_cat + contribution = coeff * maple_binary + o_contrib = coeff * n_oxy + + decomposition.append({ + 'element' : el, + 'oxi_state' : round(info['mean_oxi'], 2), + 'binary' : binary_formula, + 'n_cat_binary' : n_cat, + 'n_oxy_binary' : n_oxy, + 'coeff' : round(coeff, 4), + 'maple_binary' : round(maple_binary, 2), + 'contribution' : round(contribution, 2), + 'o_from_binary': round(o_contrib, 4), + }) + + maple_sum += contribution + o_from_binary += o_contrib + + # ── Oxygen balance check ────────────────────────────────────────── + # + # v1.1: MEASURED, AND LEFT ALONE. This is an absolute tolerance on a + # quantity that scales as 1/Z, which is the shape of a fault. Over 101 + # decompositions of real ICSD structures the imbalance is: + # + # 0 to 1e-6 97 structures exact, to floating point + # 1e-6 to 0.1 0 + # 0.1 to 0.2 3 Co3O4 standing in for Co2O3 + # 0.2 and above 1 Ca4Mn4O10.6 + # + # Nothing lies inside the gap, so every value between about 1e-6 and 0.16 + # classifies identically and the number is not doing the work. What DID + # matter was the Z error upstream: at Z = 1 the same physical imbalance + # was multiplied by the true Z, close enough to the gap to cross it. + # MaplePy v1.1 derives Z crystallographically and removes that. + # + # Note also that o_per_fu counts anion SITES, not occupancies, so an + # oxygen-deficient refinement is balanced here and non-stoichiometric in + # its composition. That is consistent with the mean-field treatment + # elsewhere and is worth stating rather than discovering. + O_BALANCE_TOL = 0.05 # O per formula unit; see the measurement above + o_residual = abs(o_from_binary - o_per_fu) + o_balanced = o_residual < O_BALANCE_TOL + + # ── Additivity residual ─────────────────────────────────────────── + # + # v1.2.1: `if decomposition` asks whether ANY cation was decomposed, not + # whether ALL were. 30 structures across the two families are missing a + # binary reference, so their sum omitted a whole component and the + # residual against it was up to 93% (NaOsO3: ternary 5022.2 against Na2O + # alone at 347.2). success=False kept those out of the statistics, but the + # number was still written to the CSV and Figure 1 selected on + # delta.notna(), so all 30 sat in the histogram tail looking like + # measured failures. + # + # Same rule as the falsy-zero fix above: do not write a number that has no + # meaning. missing_binaries still says what was absent. + complete = bool(decomposition) and not missing + delta_abs = abs(maple_tern - maple_sum) if complete else None + delta_pct = (100 * delta_abs / maple_tern + if delta_abs is not None and maple_tern > 0 + else None) + + result = { + 'source_cif' : source_cif, + 'compound' : compound, + 'maple_ternary' : round(maple_tern, 2), + 'Z' : Z, + 'n_cation_elements': len(cation_info), + 'decomposition' : decomposition, + 'maple_binary_sum' : round(maple_sum, 2), + # v1.1: `if delta_abs` is FALSE for 0.0, so a structure whose + # ternary MAPLE exactly equalled its binary sum - the perfect result + # the theorem predicts - was written out as None and then read + # downstream as a missing value. The guard in the classifier + # attributed it to "a rounding or serialisation artefact"; it was + # this line. + 'delta_abs' : (round(delta_abs, 2) + if delta_abs is not None else None), + 'delta_pct' : (round(delta_pct, 3) + if delta_pct is not None else None), + 'oxygen_per_fu' : round(o_per_fu, 4), + 'oxygen_from_bins' : round(o_from_binary, 4), + 'oxygen_balanced' : o_balanced, + 'missing_binaries' : missing, + 'missing_detail' : missing_detail, + 'estimated_binaries': estimated_used, + 'success' : len(decomposition) > 0 and len(missing) == 0, + } + + if verbose and result['success']: + status = (f"GOOD (<{ADDITIVE_THRESHOLD_PCT:g}%)" + if delta_pct < ADDITIVE_THRESHOLD_PCT else + "MARGINAL (1-2%)" if delta_pct < 2.0 else + "POOR (>2%)") + print(f" {compound:20s} " + f"MAPLE={maple_tern:8.1f} " + f"sum={maple_sum:8.1f} " + f"delta={delta_pct:.2f}% {status}" + f"{' [O imbalanced]' if not o_balanced else ''}") + elif verbose and not result['success']: + print(f" {compound:20s} INCOMPLETE: missing {missing}") + + return result + + +print("Decomposition function defined.") \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/e10_batch_additivity.py b/src/maplepy/_cells/hopper/e10_batch_additivity.py new file mode 100644 index 0000000..21cebd3 --- /dev/null +++ b/src/maplepy/_cells/hopper/e10_batch_additivity.py @@ -0,0 +1,84 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 10. +# Edit the notebook, not this file, then rebuild. +# The action at the end of this cell is in r10_batch_additivity.py. +# ───────────────────────────────────────────────────────────────────────────── + +def batch_additivity(df_summary, df_results, binary_lookup, + verbose=False): + """ + Compute additivity residuals for all structures. + + Parameters + ---------- + df_summary : DataFrame from maple_summary.csv + df_results : DataFrame from maple_results.csv + binary_lookup : dict {formula: maple_kcal_mol} + verbose : bool + + Returns + ------- + pd.DataFrame one row per structure with additivity results + list of dicts full decomposition details (for inspection) + """ + rows = [] + details = [] + + # v1.2.4: once, here, rather than a scan per structure inside the loop. + results_index = index_by_cif(df_results) + + for _, summary_row in df_summary.iterrows(): + cif = summary_row['source_cif'] + + result = decompose_ternary( + cif, df_results, binary_lookup, verbose=verbose, + results_index=results_index + ) + details.append(result) + + rows.append({ + 'source_cif' : cif, + 'compound' : result.get('compound', ''), + 'space_group' : summary_row['space_group'], + 'Z' : result.get('Z'), + 'disordered' : summary_row['disordered'], + 'maple_ternary' : result.get('maple_ternary'), + 'maple_binary_sum' : result.get('maple_binary_sum'), + 'delta_abs' : result.get('delta_abs'), + 'delta_pct' : result.get('delta_pct'), + 'madelung_factor' : summary_row['madelung_factor'], + 'd_ref_ang' : summary_row['d_ref_ang'], + 'oxygen_balanced' : result.get('oxygen_balanced'), + 'n_cation_elements': result.get('n_cation_elements'), + 'missing_binaries' : '; '.join(result.get('missing_binaries', [])), + 'estimated_binaries': '; '.join(result.get('estimated_binaries', [])), + 'success' : result.get('success', False), + }) + + df = pd.DataFrame(rows) + + # Summary statistics + n_total = len(df) + n_success = df['success'].sum() + n_fail = n_total - n_success + + if n_success > 0: + good = (df['success'] & (df['delta_pct'] < 1.0)).sum() + marginal = (df['success'] & (df['delta_pct'] >= 1.0) + & (df['delta_pct'] < 2.0)).sum() + poor = (df['success'] & (df['delta_pct'] >= 2.0)).sum() + else: + good = marginal = poor = 0 + + print(f"\n{'='*65}") + print(f" Additivity analysis: {n_total} structures") + print(f" Decomposed successfully: {n_success}") + print(f" Good (<1%): {good}") + print(f" Marginal (1-2%): {marginal}") + print(f" Poor (>2%): {poor}") + print(f" Incomplete (missing binaries): {n_fail}") + _n_est = (df['success'] & (df['estimated_binaries'] != '')).sum() + print(f" Resting on an estimated binary: {_n_est} of the {n_success} " + f"decomposed (see estimated_binaries)") + print(f"{'='*65}") + + return df, details diff --git a/src/maplepy/_cells/hopper/e12_classification.py b/src/maplepy/_cells/hopper/e12_classification.py new file mode 100644 index 0000000..b924214 --- /dev/null +++ b/src/maplepy/_cells/hopper/e12_classification.py @@ -0,0 +1,684 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 12. +# Edit the notebook, not this file, then rebuild. +# The action at the end of this cell is in r12_classification.py. +# 4. Failure Classification — Tiered Numeric Scheme +# ───────────────────────────────────────────────────────────────────────────── +# +# Every structure receives a classification: +# +# Additive Δ < 1%, no failure code assigned +# Tier 1 (1.x) Calculation incomplete +# Tier 2 (2.x) Calculation complete, result compromised +# Tier 3 (3.x) Calculation complete, result trustworthy +# +# v1.2.9: the order as classify_additivity() applies it (this header had +# kept the first version's): Tier 1 (1.1, 1.3, 1.4); the structural +# defects, 2.7 then 2.5, whatever the residual; Additive; then 2.1, 2.6, +# 2.3, 2.4; then 3.1. A caveat must not mask a defect. 1.2 and 2.2 are +# defined and cannot arise from a MaplePy run (see the registry). + +# ── Classification registry ────────────────────────────────────────────── +# Central definition of all codes. Add new codes here; the classifier +# and all downstream plotting/summary code reads from this dict. + +CLASSIFICATION_REGISTRY = { + # code : (tier, label, description) + # v1.2.3: narrowed. 1.1 now means only what its name says: the binary + # oxide exists and OUR TABLE lacks it, which is a job of work rather than + # a result. The other reasons a binary can be absent have their own codes. + '1.1': (1, 'Reference table incomplete', + 'The binary oxide exists at ambient conditions and is absent from ' + 'the reference table. Adding it makes the structure testable.'), + # v1.2.6: defined properly rather than 'reserved'. These structures are + # real and they are counted, just not here: MaplePy writes them to + # maple_failed.csv and they never produce a row for Hopper to classify. + # Three perovskite CIFs in this study, out of 941 retrieved. + '1.2': (1, 'Upstream calculation failure', + 'MaplePy could not compute a MAPLE value from the CIF, so there ' + 'is no ternary value to test. Refined occupancies exceeding ' + 'unity and parse failures both land here. These entries appear ' + 'in maple_failed.csv and are excluded before classification, so ' + 'this code is always zero in a Hopper output.'), + # v1.2.3: the most interesting exclusion in the study, and it used to be + # reported as a missing table entry. Fe(IV), Co(IV), Ru(III), Cu(III), + # Pd(III), Os(V), Tc(V), Rh(V) and Ir(V) are real states in these + # perovskites and pyrochlores and none of them has an ambient binary + # oxide. The theorem cannot be tested against an end-member that does not + # exist. + '1.3': (1, 'No binary end-member exists', + 'The oxidation state is real and the corresponding binary oxide ' + 'does not exist at ambient conditions, so the decomposition has ' + 'no end-member to sum. A limit on where additivity can be tested, ' + 'not a defect in the structure or the table.'), + # v1.2.5: a THIRD route, found once the rounding evidence could + # actually reach the classifier. Nd4Cu4O11.724 asks for Cu2O3 from a mean + # of +2.86 and Nd4Ru3.544O12 asks for Ru2O3 from +3.38: means over a + # non-stoichiometric refinement, not over a shared site. Same conclusion, + # third way of getting there, and it is in the description now. + '1.4': (1, 'Oxidation state has no binary analogue', + 'The charge the decomposition asked for is not a real oxidation ' + 'state of that element: a formal average over a ' + 'charge-disproportionated site, an occupancy-weighted mean over a ' + 'site shared by two cations, or a mean over a non-stoichiometric ' + 'refinement. Where the mean was not an integer the decomposition ' + 'records it and this code is assigned on that evidence.'), + '2.1': (2, 'Oxidation state assignment error', + 'Delta > 10% in an ordered, oxygen-balanced structure. Points to ' + 'incorrect oxidation states in the CIF.'), + # v1.2.6: RETAINED, not retired. MaplePy v1.1 stopped inferring Z from + # composition and derives it from the gcd of the site multiplicities, so + # this cannot fire on a MaplePy result and is zero throughout this study. + # It is kept because the failure mode is not MaplePy's: any tool that + # reads Z from the CIF, or trusts a compositional reduction, will produce + # it, and anyone adopting this scheme needs somewhere to put it. Zero + # here is a result about the calculator, not an empty slot. + '2.2': (2, 'Z = 1 metadata artefact', + 'The number of formula units per cell has been taken as 1 when ' + 'the cell contains more, inflating MAPLE per formula unit by an ' + 'integer factor and raising the Madelung factor well above the ' + 'family range. Arises wherever Z is inferred from composition ' + 'rather than derived from the site multiplicities.'), + '2.3': (2, 'Disorder / mean-field', + 'Mixed-occupancy sites processed via mean-field charge ' + 'approximation. Residual may reflect averaging artefact.'), + '2.4': (2, 'Oxygen non-stoichiometry', + 'Oxygen count from binary decomposition does not match ternary. ' + 'Decomposition not well-defined (e.g. Co3O4 for Co2O3).'), + # v1.1: the count has been removed from this description. It read 32 + # here, 19 in the detector's docstring and 31 in the manuscript, all + # shipping together. A number that lives in a string drifts from the data + # it counts; the notebook prints the population it actually found. + # v1.2.2: two detectors now, either of which is sufficient. The CV test + # needs a 20-site Pnma cell with 12 oxygens; the distance test needs + # nothing but coordinates. Each catches cases the other cannot: 22 of the + # 26 perovskites under 1.6 A were already caught by CV, and 8 structures + # caught by CV have an ordinary 1.98 A shortest contact. + '2.5': (2, 'Structural coordinate error', + 'Either the O-site MAPLE coefficient of variation exceeds 0.05, ' + 'or the shortest interatomic contact is below MaplePy\'s ' + 'SHORT_CONTACT_ANG. Both indicate unphysical interatomic ' + 'distances from Wyckoff site mis-assignment or wrong fractional ' + 'coordinates.'), + # v1.2.2: ACTIVE. Reserved since the first version and assignable now + # that MaplePy v1.3.3 reports which sublattice carries the fractional + # occupancy. Tested before 2.3, because an oxygen-deficient refinement + # described as "disorder" has lost the part that matters. + '2.6': (2, 'Anion vacancy disorder', + 'Fractional occupancy on the anion sublattice only: an ' + 'oxygen-deficient refinement, treated by mean-field charge ' + 'averaging. Distinct from cation disorder (2.3) and from a ' + 'decomposition that cannot balance its oxygen (2.4).'), + '2.7': (2, 'Split-site disorder model', + 'Two sites closer than MaplePy\'s SPLIT_SITE_ANG: one ' + 'crystallographic position split by a disorder model. The Ewald ' + 'sum over fractionally occupied near-coincident sites is not an ' + 'energy, whatever the residual comes out as.'), + '3.1': (3, 'Genuine violation', + 'Delta >= 1% with correct oxidation states, correct Z, balanced ' + 'oxygen, no disorder. Reflects genuine structural chemistry.'), +} + +# ── The codes, in the order they are reported ────────────────────────────── +# v1.2.1: this order was written out three times (twice here, once in the +# figure cell), and the figure's copy omitted 1.1 and 2.3, so those rows were +# in the count and not in the bars. +# v1.2.6: derived, not typed. The hand-written list named the codes that +# actually fire, which meant 1.2 and 2.2 were absent from every breakdown +# rather than present and zero. A code defined in the scheme and reported +# nowhere is indistinguishable from a code nobody thought of. +CODE_ORDER = ['Additive'] + sorted(CLASSIFICATION_REGISTRY) + + +# ── Why a binary oxide is not in the table ───────────────────────────────── +# +# v1.2.3: one entry per binary the decompositions have actually asked for and +# not found, with the reason beside it. This is chemistry, so it is written +# down and auditable rather than buried in a branch, and anything NOT here +# classifies 1.1 and says it is unclassified - a new missing binary announces +# itself instead of joining a pile. +# +# 'table' the binary exists at ambient conditions; we lack it +# 'no_binary' the oxidation state is real; no ambient binary oxide of it +# 'no_state' the charge is not a real oxidation state of that element +# +MISSING_BINARY_STATUS = { + # the binary exists and the table should have it + 'SnO': ('table', + 'Litharge-type SnO is the ambient Sn(II) oxide. Ta2Sn2O7 has ' + 'Sn(II) with Ta(V), which balances, so this is a genuine gap.'), + 'PtO': ('table', + 'PtO is reported as a tetragonal ambient phase, though Pt3O4 ' + 'and PtO2 are better characterised. Needs a verified structure ' + 'before a MAPLE value is added.'), + 'SmO': ('table', + 'Rock-salt SmO is a real Sm(II) phase. NOTE: the structure that ' + 'asks for it, SmTiO3 ICSD 51180, is assigned Sm2+ with Ti4+, ' + 'while the known compound is Sm3+Ti3+O3. Both balance to 6, so ' + 'charge neutrality cannot see the difference. The oxidation ' + 'state assignment deserves a look.'), + + # the state is real; the binary oxide is not + 'Ru2O3': ('no_binary', 'Ru(III) has no ambient binary oxide; RuO2 is the ' + 'stable oxide.'), + 'FeO2': ('no_binary', 'Fe(IV) has no ambient binary oxide. CaFeO3 and ' + 'EuFeO3 really do contain Fe(IV).'), + 'CoO2': ('no_binary', 'Co(IV) has no ambient binary oxide; CoO2 exists ' + 'only as a delithiated layered phase.'), + 'Cu2O3': ('no_binary', 'Cu(III) has no ambient binary oxide; Cu2O and ' + 'CuO are the binaries.'), + 'Pd2O3': ('no_binary', 'Pd(III) has no ambient binary oxide.'), + 'Os2O5': ('no_binary', 'Os(V) has no ambient binary oxide; OsO2 and OsO4 ' + 'are the known ones.'), + 'Tc2O5': ('no_binary', 'Tc(V) has no ambient binary oxide; TcO2 and ' + 'Tc2O7 are the known ones.'), + 'Rh2O5': ('no_binary', 'Rh(V) has no ambient binary oxide; Rh2O3 and ' + 'RhO2 are the binaries.'), + 'Ir2O5': ('no_binary', 'Ir(V) has no ambient binary oxide; IrO2 is the ' + 'stable oxide.'), + + # the charge is not a state + 'BiO2': ('no_state', + 'Bi(IV) is a formal average. SrBiO3 is charge-disproportionated ' + 'Bi(III)/Bi(V), and the CIF deposits Bi as 4+ on every site, so ' + 'the rounding test cannot catch it.'), + 'YO2': ('no_state', 'Y(IV) does not exist. Y3NbO7 shares its cation ' + 'site with Nb and the site mean is 3.5.'), + 'EuO2': ('no_state', 'Eu(IV) does not exist. Eu2Sn2O7 shares its cation ' + 'site with Sn and the site mean is 3.5.'), + 'TlO': ('no_state', 'Tl(II) does not exist; Tl is 1+ or 3+. Nb2Tl2O7 ' + 'shares its cation site with Nb.'), +} + +_MISSING_STATUS_CODE = {'table': '1.1', 'no_binary': '1.3', 'no_state': '1.4'} + + +def as_missing_list(value): + """ + The missing-binary entries as a list, whatever the caller has. + + v1.2.5: batch_additivity stores `'; '.join(missing)`, so the classifier + was handed a STRING and iterated it character by character - every one of + the 20 tier-1 perovskites came out 1.4 with a reason built from single + letters. Every test I wrote passed a list, because I built the frames + myself or read them back with literal_eval. One place converts now, and + it takes a list, a joined string, or the repr of a list. + """ + if value is None: + return [] + if isinstance(value, (list, tuple)): + return [v for v in value if v] + if not isinstance(value, str): + return [] # NaN from an empty CSV cell + text = value.strip() + if not text or text in ('[]', 'nan'): + return [] + if text.startswith('[') and text.endswith(']'): + import ast as _ast + try: + lit = _ast.literal_eval(text) + if isinstance(lit, (list, tuple)): + return [v for v in lit if v] + except (ValueError, SyntaxError): + pass + return [p.strip() for p in text.split(';') if p.strip()] + + +def _rounded_from_missing(entry): + """Whether this request came from a rounded site mean, per the string.""" + return isinstance(entry, str) and 'rounded)' in entry + + +def _binary_from_missing(entry): + """The binary formula out of one `missing_binaries` string, or None. + + The strings are written by decompose_ternary as 'Ru2O3 (not in table)' + and 'Fe+4.0 (no pattern)'. Only the first form names a binary. + """ + if not isinstance(entry, str): + return None + head = entry.split(' (')[0].strip() + return head if '(not in table)' in entry else None + + +def classify_missing_binaries(missing, detail=None): + # v1.2.5: `detail` is kept in the signature for anything that still + # passes it, and ignored: the rounding fact is in the string now. + """ + Which code a decomposition that lacked a binary belongs in, and why. + + v1.2.3: 1.1 held four different findings. Returns (code, reason). + + The rounding evidence wins where it exists: a request built on a + non-integral site mean is 1.4 whatever the registry says, because the + charge was never an oxidation state. Otherwise the registry decides, and + an unregistered binary stays 1.1 and says so. + + Where a structure is missing more than one binary the strongest finding + wins, in the order 1.4, 1.3, 1.1: a structure whose decomposition rests + on a charge that does not exist is not waiting on our table. + """ + reasons, codes = [], [] + for entry in as_missing_list(missing): + formula = _binary_from_missing(entry) + + if _rounded_from_missing(entry): + codes.append('1.4') + reasons.append(f'{entry}: asked for from a rounded site mean, ' + f'which was not an oxidation state') + continue + + if formula is None: + codes.append('1.4') + reasons.append(f'{entry}: no binary pattern for that charge') + continue + + status = MISSING_BINARY_STATUS.get(formula) + if status is None: + codes.append('1.1') + reasons.append(f'{formula}: UNCLASSIFIED, not in ' + f'MISSING_BINARY_STATUS') + continue + codes.append(_MISSING_STATUS_CODE[status[0]]) + reasons.append(f'{formula}: {status[1]}') + + if not codes: + return '1.1', 'decomposition failed with no binary named' + for code in ('1.4', '1.3', '1.1'): + if code in codes: + return code, '; '.join(reasons) + return '1.1', '; '.join(reasons) + + +# ── The population a residual statistic is drawn from ────────────────────── +def additivity_population(df): + """ + The structures whose residual IS a residual: decomposition complete and + delta computed. + + v1.2.1: Figure 1 selected on delta.notna() while the classifier counted + tier 0, so the figure said 662 within 1% and the classification said 661 + additive, on the same run and in the same paper. One definition, used by + both. + """ + return df[df['success'].astype(bool) & df['delta_pct'].notna()] + + +def n_classified_additive(df): + """How many structures the classifier called additive. One number.""" + return int((additivity_population(df)['classification'] == 'Additive').sum()) + + +# Convenience lookups +def _tier_for_code(code): + """Return the tier for a classification outcome. + + v1.2.7: 'Additive' is an outcome without a registry code, and it is + tier 0. Callers that map over CODE_ORDER meet it first, so answering + here is better than every caller special-casing it. + """ + if code == 'Additive': + return 0 + return CLASSIFICATION_REGISTRY[code][0] + +def _label_for_code(code): + """Return the human-readable label for a classification code.""" + return CLASSIFICATION_REGISTRY[code][1] + +""" +Code 2.5 detector: Wyckoff 4a/4b site mis-assignment in Pnma perovskites. + +Detects ICSD entries where the B-site cation is deposited at Wyckoff 4a +instead of the correct 4b in GdFeO3-type perovskites (Pnma, 20 sites). + +v1.1: the counts that used to sit here have been removed. They disagreed +with the registry and with the manuscript, and the notebook reports the +population it finds. + +v1.2.9: the usage example that stood here named a function that does not +exist. The detector is detect_structural_coordinate_error(), below, and +classify_additivity() calls it; since v1.2.2, code 2.5 also takes a +short contact from MaplePy's geometry_flag. +""" + + +def detect_structural_coordinate_error(cif_name, results_df, summary_df, + cv_threshold=0.05, + results_index=None, + summary_index=None): + """ + Detect structural coordinate errors in Pnma perovskites using the + coefficient of variation (CV) of per-site oxygen MAPLE values. + + In a correctly refined GdFeO3-type perovskite (Pnma, Z=4, 20 sites), + the 12 oxygen sites occupy two crystallographically distinct positions + (Wyckoff 4c and 8d) but experience similar electrostatic environments, + giving per-site MAPLE values within ~5% of each other (CV < 0.045). + + Structural coordinate errors distort the local coordination geometry + and produce anomalously different MAPLE values between O1 and O2 + sublattices, pushing CV above 0.05. + + Parameters + ---------- + cif_name : str + Source CIF filename (must match a row in summary_df). + results_df : pd.DataFrame + Per-site MAPLE results with columns: source_cif, element, + maple_kcal_mol. + summary_df : pd.DataFrame + Per-structure summary with columns: source_cif, Z, space_group. + cv_threshold : float + CV threshold above which the structure is flagged. + Default 0.05 (validated gap: 0.045-0.050). + + Returns + ------- + bool or None + True — structural coordinate error detected (classify as 2.5). + False — structure is clean. + None — structure is not a testable Pnma perovskite. + """ + srow = rows_for(cif_name, summary_df, summary_index) + if len(srow) == 0: + return None + srow = srow.iloc[0] + + # v1.1: THE TEST NO LONGER GATES ON Z. + # + # This asked for Z == 4, so every perovskite whose Z had been lost to + # composition reduction - 101 of the 938, all non-stoichiometric - was + # returned as untestable and never screened for coordinate errors at all. + # The claim of zero false positives across 938 was really across 831. + # + # What the test actually needs is a 20-site Pnma cell with 12 oxygens, + # which is checked below and does not require Z. With MaplePy v1.1 + # deriving Z from the site counts the two conditions coincide anyway, and + # a test should not depend on a quantity it does not use. + if srow['space_group'] != 'Pnma': + return None + + entry = rows_for(cif_name, results_df, results_index) + if len(entry) != 20: + return None + + oxygens = entry[entry['element'] == 'O'] + if len(oxygens) != 12: + return None + + # Coefficient of variation of per-site oxygen MAPLE + o_maples = oxygens['maple_kcal_mol'].values.astype(float) + o_mean = np.mean(o_maples) + + if o_mean <= 0: + return None + + cv = float(np.std(o_maples) / o_mean) + + # Explicit bool() to avoid numpy.bool_ identity issues + return bool(cv > cv_threshold) + +def _summary_field(cif_name, summary_df, column, summary_index=None): + """ + One field of MaplePy's summary for one structure, or None. + + v1.2.2: the three tests below all need the same lookup, and all three + must answer None rather than False when MaplePy did not write the + column - a test that cannot run is not a test that passed. + """ + if column not in summary_df.columns: + return None + srow = rows_for(cif_name, summary_df, summary_index) + if len(srow) == 0: + return None + value = srow[column].iloc[0] + return value if isinstance(value, str) else None + + +def detect_split_site(cif_name, summary_df, summary_index=None): + """ + Whether MaplePy flagged this structure as a split-site disorder model. + + v1.2.2: reads `geometry_flag`, written by MaplePy v1.3.3. It used to read + the prefix of `geometry_status`, which is a sentence written for a human: + Hopper's classification should not depend on MaplePy's wording. + + Hopper does not recompute the geometry. MaplePy holds the structures and + the tolerances, and two implementations of one test is how they come to + disagree. + """ + flag = _summary_field(cif_name, summary_df, 'geometry_flag', + summary_index) + return None if flag is None else flag == 'split_site' + + +def detect_short_contact(cif_name, summary_df, summary_index=None): + """ + Whether the shortest contact is below MaplePy's SHORT_CONTACT_ANG. + + v1.2.2: the second detector for code 2.5. The CV test needs a 20-site + Pnma cell with 12 oxygens and cannot see a short contact anywhere else; + NdFeO3 at 1.507 A was classified Additive at delta 0.312% because of it. + """ + flag = _summary_field(cif_name, summary_df, 'geometry_flag', + summary_index) + return None if flag is None else flag == 'short_contact' + + +def detect_anion_vacancy(cif_name, summary_df, summary_index=None): + """ + Whether the fractional occupancy is on the anion sublattice alone. + + v1.2.2: code 2.6, reserved since the first version and assignable now + that MaplePy v1.3.3 writes `partial_sublattice`. Anion-only, not 'both': + a structure with cation disorder as well is a mean-field result for more + than one reason and belongs in 2.3. + """ + where = _summary_field(cif_name, summary_df, 'partial_sublattice', + summary_index) + return None if where is None else where == 'anion' + + +def classify_additivity(df_add, results_df, summary_df, + threshold_additive=ADDITIVE_THRESHOLD_PCT): + """ + Assign a tiered numeric classification to each structure based on + its additivity residual and metadata. + + Parameters + ---------- + df_add : DataFrame + Output from batch_additivity(), one row per structure. + results_df, summary_df : DataFrame + MaplePy's per-site and per-structure output. v1.1: these were read + as free variables from the notebook namespace, so re-running the + cells out of order classified against a stale frame silently. + threshold_additive : float + Residual threshold (%) below which a structure is classified + as additive. Default 1.0 (Hoppe criterion). + + Returns + ------- + DataFrame with added columns: + classification str 'Additive' or code ('1.1', '2.1', etc.) + classification_tier int 0 for additive, 1/2/3 for failures + classification_label str human-readable label + + Notes + ----- + v1.2.9: the order is the one in the header of this cell, not + ascending code number: Tier 1; then 2.7 and 2.5 whatever the + residual; then Additive; then 2.1, 2.6, 2.3, 2.4; then 3.1. The + first that applies is assigned. + """ + df = df_add.copy() + # v1.2.4: two indexes, built once, for every lookup below. + _ridx = index_by_cif(results_df) if len(results_df) else None + _sidx = index_by_cif(summary_df) if len(summary_df) else None + df['classification'] = '' + df['classification_tier'] = 0 + df['classification_label'] = '' + df['hopper_version'] = HOPPER_VERSION + df['missing_binary_reason'] = '' + + # v1.2.1: say when a test cannot run. Against CSVs written before MaplePy + # v1.3.2 there is no geometry column, and a split-site structure would + # then be classified on whatever else it trips - which is how all four of + # them came to be called oxygen non-stoichiometry. + for _col, _tests in (('geometry_flag', 'the split-site test (2.7) and ' + 'the short-contact half of 2.5'), + ('partial_sublattice', 'the anion-vacancy test (2.6)')): + if _col not in summary_df.columns: + print(f" NOTE: no {_col} column in the summary. These CSVs were " + f"written by MaplePy before v1.3.3, so {_tests} did not " + f"run.") + + for idx, row in df.iterrows(): + + # ── Codes 1.1, 1.3, 1.4: the decomposition lacked a binary ── + # v1.2.3: three findings, not one. Which of them is decided by + # classify_missing_binaries, from the rounding evidence where + # there is any and from the registry where there is not. + if not row['success'] and as_missing_list( + row['missing_binaries']): + _code, _why = classify_missing_binaries(row['missing_binaries']) + df.at[idx, 'classification'] = _code + df.at[idx, 'classification_tier'] = 1 + df.at[idx, 'classification_label'] = ( + f'{_label_for_code(_code)} ({_why})' if _code == '1.1' + and 'UNCLASSIFIED' in _why else _label_for_code(_code)) + df.at[idx, 'missing_binary_reason'] = _why + if 'UNCLASSIFIED' in _why: + print(f" NOTE: {row['source_cif']} asks for a binary that is " + f"not in MISSING_BINARY_STATUS - {_why}") + continue + + # Catch-all for other decomposition failures (should not occur + # with current data, but defensive) + if not row['success']: + df.at[idx, 'classification'] = '1.1' + df.at[idx, 'classification_tier'] = 1 + df.at[idx, 'classification_label'] = 'Decomposition failed' + continue + + # ── Guard: success=True but delta_pct unavailable ─────────── + # Can occur when maple_ternary == maple_binary_sum exactly, + # producing delta_abs = 0.0 that becomes NaN through a + # rounding or serialisation artefact. Treat as additive. + if row['delta_pct'] is None or (isinstance(row['delta_pct'], float) + and row['delta_pct'] != row['delta_pct']): + df.at[idx, 'classification'] = 'Additive' + df.at[idx, 'classification_tier'] = 0 + df.at[idx, 'classification_label'] = 'Additive' + continue + + # ── Code 2.7: split-site disorder model ──────────────────── + # Checked before Additive, like 2.5: a structure whose two + # half-occupied sites are 0.03 A apart is not additive when its + # residual lands under 1%, it is unmeasured. MaplePy v1.3.2 + # flags these; see its SPLIT_SITE_ANG for the tolerance. + if detect_split_site(row['source_cif'], summary_df, _sidx): + df.at[idx, 'classification'] = '2.7' + df.at[idx, 'classification_tier'] = 2 + df.at[idx, 'classification_label'] = _label_for_code('2.7') + continue + + # ── Code 2.5: structural coordinate error ────────────────── + # Two detectors, either sufficient, and the label says which + # found it. The CV test sees a B-site at 4a instead of 4b in a + # 20-site Pnma cell; the distance test sees any contact below + # SHORT_CONTACT_ANG anywhere. + # + # Both are checked before Additive, because DyCrO3 138222 passes + # the 1% threshold by coincidence despite the Wyckoff error and + # NdFeO3 passes it with two atoms 1.507 A apart. + _cv = detect_structural_coordinate_error( + row['source_cif'], results_df, summary_df, + results_index=_ridx, summary_index=_sidx) + _short = detect_short_contact(row['source_cif'], summary_df, _sidx) + if _cv or _short: + _how = ('O-site MAPLE CV and short contact' if _cv and _short + else 'short contact' if _short else 'O-site MAPLE CV') + df.at[idx, 'classification'] = '2.5' + df.at[idx, 'classification_tier'] = 2 + df.at[idx, 'classification_label'] = ( + f"{_label_for_code('2.5')} ({_how})") + continue + + # ── Additive: delta < threshold ───────────────────────────── + # Check additive status before entering the failure logic. + # Structures within Hoppe range get no failure code. + if (row['delta_pct'] is not None + and row['delta_pct'] < threshold_additive): + df.at[idx, 'classification'] = 'Additive' + df.at[idx, 'classification_tier'] = 0 + df.at[idx, 'classification_label'] = 'Additive' + continue + + # ── From here, delta >= threshold: assign failure codes ───── + # Applied in ascending code order so the lowest applicable + # code wins. + + # ── Code 2.1: oxidation state assignment error ────────────── + # Very large residual (>10%) in an ordered structure with + # balanced oxygen points to incorrect oxidation states in the + # CIF, producing a wrong binary decomposition. + if (row['delta_pct'] is not None and row['delta_pct'] > 10.0 + and not row['disordered'] and row['oxygen_balanced']): + df.at[idx, 'classification'] = '2.1' + df.at[idx, 'classification_tier'] = 2 + df.at[idx, 'classification_label'] = _label_for_code('2.1') + continue + + # ── Code 2.2: defined, and unreachable from a MaplePy result ── + # There was a branch here assigning 2.2 to every Z = 1 structure, + # written when composition-derived Z made Z = 1 a reliable sign of + # an artefact. MaplePy v1.1 derives Z from the site counts, the + # population fell 107 -> 2, and the two survivors are cubic + # perovskites whose Z really is 1. So no branch assigns 2.2 here: + # a Z = 1 structure from MaplePy is classified on its residual like + # any other. The CODE stays in the registry, because the artefact is + # real for any tool that reads Z from the CIF or trusts a + # compositional reduction, and it is reported as zero rather than + # omitted. + + # ── Code 2.6: anion vacancy disorder ─────────────────────── + # Fractional occupancy on the anion sublattice alone: an + # oxygen-deficient refinement. Tested before 2.3 because it is + # the more specific description of the same structure, and + # before 2.4 because it says WHY the oxygen does not balance. + if detect_anion_vacancy(row['source_cif'], summary_df, _sidx): + df.at[idx, 'classification'] = '2.6' + df.at[idx, 'classification_tier'] = 2 + df.at[idx, 'classification_label'] = _label_for_code('2.6') + continue + + # ── Code 2.3: disorder / mean-field approximation ─────────── + # Structure has mixed-occupancy sites processed via mean-field + # charge averaging. The residual may partly reflect the + # averaging artefact rather than genuine structural chemistry. + if row['disordered']: + df.at[idx, 'classification'] = '2.3' + df.at[idx, 'classification_tier'] = 2 + df.at[idx, 'classification_label'] = _label_for_code('2.3') + continue + + # ── Code 2.4: oxygen non-stoichiometry ────────────────────── + # Oxygen count from binary decomposition does not match the + # ternary oxygen count. Principal cause: Co3O4 used in place + # of the non-existent Co2O3. + if not row['oxygen_balanced']: + df.at[idx, 'classification'] = '2.4' + df.at[idx, 'classification_tier'] = 2 + df.at[idx, 'classification_label'] = _label_for_code('2.4') + continue + + # ── Code 3.1: genuine violation ───────────────────────────── + # delta >= threshold with correct oxidation states, correct Z, + # balanced oxygen, no disorder. The residual reflects genuine + # structural chemistry (covalency, strain, etc.). + if row['delta_pct'] is not None and row['delta_pct'] >= threshold_additive: + df.at[idx, 'classification'] = '3.1' + df.at[idx, 'classification_tier'] = 3 + df.at[idx, 'classification_label'] = _label_for_code('3.1') + + return df diff --git a/src/maplepy/_cells/hopper/e14_residual_histogram.py b/src/maplepy/_cells/hopper/e14_residual_histogram.py new file mode 100644 index 0000000..5506df1 --- /dev/null +++ b/src/maplepy/_cells/hopper/e14_residual_histogram.py @@ -0,0 +1,165 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 14. +# Edit the notebook, not this file, then rebuild. +# The action at the end of this cell is in r14_residual_histogram.py. +# 5a. Additivity Residual Histogram (Key Paper Figure) +# ───────────────────────────────────────────────────────────────────────────── +# +# Two-panel figure: +# (a) 0-5% at 0.25% bins — shows the bulk of the data +# (b) >5% at 2.5% bins — shows the failure tail in detail +# +# Colour scheme (Sheffield brand palette): +# Additive pastel_green (light, recessive — the expected result) +# 3.1 Genuine teal (stands out against the green) +# 2.4 O-nonstoich flamingo (warm pink) +# 2.2 Z=1 peach (warm orange) +# 2.1 Oxi state coral (warm red) + +from matplotlib.lines import Line2D + +# ── Sheffield-palette colour map for classification codes ──────────────── +CLASSIFICATION_COLOURS = { + 'Additive': SHEFFIELD['pastel_green'], + '1.1': SHEFFIELD['pale_violet'], + '1.2': SHEFFIELD['aqua'], + '1.3': SHEFFIELD['peak_green'], + '1.4': SHEFFIELD['spearmint'], + '2.1': SHEFFIELD['coral'], + '2.2': SHEFFIELD['peach'], + '2.3': SHEFFIELD['powder_violet'], + '2.4': SHEFFIELD['flamingo'], + '2.5': SHEFFIELD['brand_violet'], + '2.6': SHEFFIELD['powder_blue'], + '2.7': SHEFFIELD['midnight'], + '3.1': SHEFFIELD['teal'], +} + +CLASSIFICATION_LABELS = { + 'Additive': rf'Additive ($\Delta$ < {ADDITIVE_THRESHOLD_PCT:g}%)', + '1.1': '1.1 Table incomplete', + '1.2': '1.2 Upstream failure', + '1.3': '1.3 No binary end-member', + '1.4': '1.4 Charge is not a state', + '2.1': '2.1 Oxi state error', + '2.2': '2.2 Z = 1 artefact (retired)', + '2.3': '2.3 Disorder / mean-field', + '2.4': '2.4 O non-stoichiometry', + '2.5': '2.5 Coordinate error', + '2.6': '2.6 Anion vacancy', + '2.7': '2.7 Split-site model', + '3.1': '3.1 Genuine violation', +} + +# Marker shapes per tier for greyscale accessibility +TIER_MARKERS = {0: 'o', 1: 'v', 2: 's', 3: 'D'} + + +def plot_additivity_histogram(df_classified, save_path=None): + """ + Two-panel histogram of additivity residuals. + + Panel (a): 0-5% range at 0.25% bins with Hoppe 1% threshold. + Panel (b): >5% tail at 2.5% bins showing failure breakdown. + + Coloured by classification code using the Sheffield brand palette. + Lighter pastel_green for additive structures so the failure codes + (warm colours + teal) stand out. + """ + # v1.2.1: the same population the classifier reports, from the same + # function. This selected on delta.notna() alone, which included the 30 + # structures whose binary sum was incomplete (their delta is None now) + # and produced a "within 1%" count one larger than the classifier's + # additive count, on the same run. + df_plot = additivity_population(df_classified).copy() + + if len(df_plot) == 0: + print("No structures with computed residuals to plot.") + return + + fig, (ax_main, ax_tail) = plt.subplots( + 1, 2, figsize=(12, 5), + gridspec_kw={'width_ratios': [3, 2], 'wspace': 0.25} + ) + + # Stacking order: additive at the back, then by code. + # + # v1.2.1: the old order here omitted 1.1 and 2.3, so those structures + # were counted in the annotation and drawn in neither panel. Every code + # present is drawn now, and a code with no colour raises rather than + # disappearing. + code_order = ['Additive'] + [c for c in CODE_ORDER if c != 'Additive'][::-1] + codes_present = [c for c in code_order + if c in df_plot['classification'].values] + _uncoloured = [c for c in df_plot['classification'].unique() + if c not in CLASSIFICATION_COLOURS] + if _uncoloured: + raise KeyError(f'no colour for classification code(s) {_uncoloured}: ' + f'add them to CLASSIFICATION_COLOURS and ' + f'CLASSIFICATION_LABELS rather than plotting without') + colours = [CLASSIFICATION_COLOURS[c] for c in codes_present] + labels = [CLASSIFICATION_LABELS[c] for c in codes_present] + + # ── Panel (a): 0 to 5% ────────────────────────────────────────── + bins_main = np.arange(0, 5.25, 0.25) + df_main = df_plot[df_plot['delta_pct'] <= 5.0] + + data_main = [df_main[df_main['classification'] == c]['delta_pct'].values + for c in codes_present] + + ax_main.hist(data_main, bins=bins_main, color=colours, label=labels, + edgecolor='white', linewidth=0.5, stacked=True) + + # Hoppe's threshold, from the constant the classifier uses + ax_main.axvline(x=ADDITIVE_THRESHOLD_PCT, color=SHEFFIELD['coral'], + linestyle='--', linewidth=1.5, alpha=0.8, zorder=5) + ax_main.text(1.12, ax_main.get_ylim()[1] * 0.95, + f"Hoppe {ADDITIVE_THRESHOLD_PCT:g}%", + fontsize=10, color=SHEFFIELD['coral'], va='top') + + ax_main.set_xlabel(r'Additivity residual, $\Delta$ / %') + ax_main.set_ylabel('Count') + ax_main.set_title('(a)', loc='left', fontweight='bold') + ax_main.spines['top'].set_visible(False) + ax_main.spines['right'].set_visible(False) + ax_main.set_xlim(-0.1, 5.2) + ax_main.legend(frameon=False, fontsize=9, loc='upper right') + + # Annotation: the classifier's own additive count, not a second count + # made here against the same threshold over a different population. + n_within = n_classified_additive(df_classified) + n_total = len(df_plot) + ax_main.text(0.97, 0.12, + f'{n_within}/{n_total} ({100*n_within/n_total:.0f}%)\n' + 'classified additive', + transform=ax_main.transAxes, ha='right', va='bottom', + fontsize=10, color=SHEFFIELD['dark_violet'], style='italic') + + # ── Panel (b): > 5%, uniform 2.5% bins ────────────────────────── + df_tail = df_plot[df_plot['delta_pct'] > 5.0] + bins_tail = np.arange(5, 100, 2.5) + + codes_tail = [c for c in code_order + if c in df_tail['classification'].values] + data_tail = [df_tail[df_tail['classification'] == c]['delta_pct'].values + for c in codes_tail] + colours_tail = [CLASSIFICATION_COLOURS[c] for c in codes_tail] + + ax_tail.hist(data_tail, bins=bins_tail, color=colours_tail, + edgecolor='white', linewidth=0.5, stacked=True) + + ax_tail.set_xlabel(r'Additivity residual, $\Delta$ / %') + ax_tail.set_ylabel('Count') + ax_tail.set_title(r'(b) $\Delta$ > 5%' + f' (n = {len(df_tail)})', + loc='left', fontweight='bold') + ax_tail.spines['top'].set_visible(False) + ax_tail.spines['right'].set_visible(False) + ax_tail.set_xlim(5, 100) + + fig.tight_layout() + + if save_path: + fig.savefig(save_path) + print(f"Saved: {save_path}") + + plt.show() + return fig diff --git a/src/maplepy/_cells/hopper/e15_madelung_factor_clustering.py b/src/maplepy/_cells/hopper/e15_madelung_factor_clustering.py new file mode 100644 index 0000000..4d4892d --- /dev/null +++ b/src/maplepy/_cells/hopper/e15_madelung_factor_clustering.py @@ -0,0 +1,306 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 15. +# Edit the notebook, not this file, then rebuild. +# The action at the end of this cell is in r15_madelung_factor_clustering.py. +# 5b. Madelung Factor Clustering (Key Paper Figure) +# ───────────────────────────────────────────────────────────────────────────── +# +# Two-panel figure: +# (a) All structures — overview with labelled common phases +# (b) Z=1 cluster detail — auto-detected zoom window with ICSD codes +# +# Panel (b) window is auto-detected from the gap in the MF distribution +# between the main perovskite band and the Z=1 cluster. Override by +# setting the PANEL_B_* variables below to explicit values. +# +# Label strategy: +# Panel (a): common phases (n >= 5) at median positions +# Panel (b): clustered compositions (n >= 3) with entry counts, +# edge singletons/pairs with compound + ICSD CollCode +# +# Marker shapes per tier for greyscale accessibility: +# Additive (Tier 0): circles +# Tier 2 (compromised): squares +# Tier 3 (genuine): diamonds + +from adjustText import adjust_text +from matplotlib.lines import Line2D +from matplotlib.patches import Rectangle + +# ── User-configurable panel (b) window ─────────────────────────────────── +# Set to explicit values to override auto-detection. +# Set to None to auto-detect from the data. +PANEL_B_MF_MIN = None # e.g. 8.0 +PANEL_B_MF_MAX = None # e.g. 17.5 +PANEL_B_DREF_MIN = None # e.g. 1.6 +PANEL_B_DREF_MAX = None # e.g. 2.3 + +# ── Compounds to label in panel (a) ───────────────────────────────────── +# Edit this list to control which phases are labelled in the main band. +# Only compounds with MF < 6 (i.e. in the main perovskite band) are +# labelled; the list is ignored for compounds not in the data. +LABEL_COMPOUNDS_PANEL_A = [ + 'MgSiO3', 'CaMnO3', 'CaTiO3', 'LaMnO3', 'LaFeO3', + 'NdNiO3', 'BaCeO3', 'SrCeO3', 'NaNbO3', 'NaTaO3', + 'SrRuO3', 'LaCrO3', +] + +# ── Tier-to-marker mapping ────────────────────────────────────────────── +# v1.2.7: was a hand-written map missing 1.3, 1.4, 2.6 and 2.7, so those +# structures were dropped from every scatter. _tier_for_code has been in +# cell 12 the whole time and reads the registry. +tier_map = {c: _tier_for_code(c) for c in CODE_ORDER} + + +def _plot_scatter_by_tier(ax, data, size_map, alpha_additive=0.5): + """Plot scatter points with tier-based marker shapes and classification colours.""" + for tier in [0, 2, 3]: + subset = data[data['tier'] == tier] + if len(subset) == 0: + continue + if tier == 2: + # v1.2.7: every tier-2 code in the registry, not four of seven + for code in [c for c in CODE_ORDER + if _tier_for_code(c) == 2]: + sub = subset[subset['classification'] == code] + if len(sub) == 0: + continue + ax.scatter(sub['d_ref_ang'], sub['madelung_factor'], + c=CLASSIFICATION_COLOURS[code], + marker=TIER_MARKERS[tier], s=size_map.get(tier, 22), + alpha=0.75, edgecolors='white', linewidth=0.3, + zorder=3) + else: + code = 'Additive' if tier == 0 else '3.1' + ax.scatter(subset['d_ref_ang'], subset['madelung_factor'], + c=CLASSIFICATION_COLOURS[code], + marker=TIER_MARKERS[tier], s=size_map.get(tier, 22), + alpha=alpha_additive if tier == 0 else 0.8, + edgecolors='white', linewidth=0.3, + zorder=2 if tier == 0 else 4) + + +def plot_mf_clustering(df_classified, save_path=None): + """ + Two-panel Madelung factor vs d_ref scatter plot. + + Panel (a): all successfully decomposed structures, with common + phases labelled at their median position. Dashed box indicates + the region shown in panel (b). + + Panel (b): zoomed view of the Z=1 / high-MF cluster. Edge and + outlier ICSD entries are labelled with compound + CollCode; + clustered compositions (n >= 3) are labelled with entry count. + + The panel (b) window is auto-detected from the largest gap in the + MF distribution above the main perovskite band, unless overridden + by the PANEL_B_* variables. + """ + ok = df_classified[df_classified['success'] == True].copy() + ok['tier'] = ok['classification'].map(tier_map).fillna(-1).astype(int) + ok['coll_code'] = ok['source_cif'].str.extract(r'CollCode(\d+)', expand=False) + + # ── Auto-detect panel (b) window ──────────────────────────────── + # Find the first significant gap (> 2.0) in MF above the main band + mf_sorted = ok['madelung_factor'].sort_values().values + all_gaps = np.diff(mf_sorted) + mf_gap_lower = 5.0 + mf_gap_upper = 10.0 + for i in range(len(all_gaps)): + if all_gaps[i] > 2.0 and mf_sorted[i] > 4.0: + mf_gap_lower = mf_sorted[i] + mf_gap_upper = mf_sorted[i + 1] + break + + auto_mf_min = mf_gap_upper - 0.5 + + # Exclude extreme outliers (e.g. SrRuO3 at MF~34) + high_cluster = ok[(ok['madelung_factor'] >= auto_mf_min) & + (ok['madelung_factor'] < 20)] + + if len(high_cluster) > 0: + auto_mf_max = high_cluster['madelung_factor'].max() + 0.5 + auto_dref_min = high_cluster['d_ref_ang'].min() - 0.05 + auto_dref_max = high_cluster['d_ref_ang'].max() + 0.05 + else: + auto_mf_max = 18.0 + auto_dref_min = 1.6 + auto_dref_max = 2.3 + + pb_mf_min = PANEL_B_MF_MIN if PANEL_B_MF_MIN is not None else auto_mf_min + pb_mf_max = PANEL_B_MF_MAX if PANEL_B_MF_MAX is not None else auto_mf_max + pb_dref_min = PANEL_B_DREF_MIN if PANEL_B_DREF_MIN is not None else auto_dref_min + pb_dref_max = PANEL_B_DREF_MAX if PANEL_B_DREF_MAX is not None else auto_dref_max + + print(f"Panel (b) window: MF [{pb_mf_min:.1f}, {pb_mf_max:.1f}], " + f"d_ref [{pb_dref_min:.2f}, {pb_dref_max:.2f}]") + + # ── Build figure ──────────────────────────────────────────────── + # v1.2.7: panel (b) zoomed the Z = 1 cluster. With Z derived from site + # multiplicities that cluster is empty, and the panel was drawing an + # empty axis titled 'n = 0' next to a dashed box around nothing. Decide + # from the data: no cluster, no panel. + cluster_b = ok[(ok['madelung_factor'] >= pb_mf_min) & + (ok['madelung_factor'] <= pb_mf_max) & + (ok['d_ref_ang'] >= pb_dref_min) & + (ok['d_ref_ang'] <= pb_dref_max)].copy() + + if len(cluster_b) == 0: + print('No high-MF cluster: panel (b) omitted.') + fig, ax_a = plt.subplots(1, 1, figsize=(9, 6.5)) + ax_b = None + else: + fig, (ax_a, ax_b) = plt.subplots( + 1, 2, figsize=(14, 6.5), + gridspec_kw={'width_ratios': [3, 2], 'wspace': 0.28} + ) + + # ── Panel (a): all structures ─────────────────────────────────── + _plot_scatter_by_tier(ax_a, ok, {0: 18, 2: 22, 3: 22}) + + # Labels for common phases in the main band + grouped_main = ok[ok['madelung_factor'] < 6].groupby('compound').agg( + n=('compound', 'size'), + mf_med=('madelung_factor', 'median'), + dref_med=('d_ref_ang', 'median'), + ).reset_index() + + texts_a = [] + for comp in LABEL_COMPOUNDS_PANEL_A: + row = grouped_main[grouped_main['compound'] == comp] + if len(row) == 0: + continue + r = row.iloc[0] + n_str = f' ({int(r["n"])})' if r['n'] >= 5 else '' + texts_a.append(ax_a.text(r['dref_med'], r['mf_med'], + f'{comp}{n_str}', + fontsize=7, color=SHEFFIELD['midnight'], + fontstyle='italic')) + + # Label the SrRuO3 outlier at MF~34 + sr_out = ok[(ok['compound'] == 'SrRuO3') & (ok['madelung_factor'] > 30)] + if len(sr_out) > 0: + r = sr_out.iloc[0] + texts_a.append(ax_a.text(r['d_ref_ang'], r['madelung_factor'], + f'SrRuO3\nCollCode{r["coll_code"]}', + fontsize=7, color=SHEFFIELD['midnight'], + fontstyle='italic', ha='right')) + + adjust_text(texts_a, ax=ax_a, + arrowprops=dict(arrowstyle='-', color='grey', alpha=0.4, lw=0.5), + expand=(1.5, 1.5), force_text=(0.8, 0.8), + ensure_inside_axes=True) + + # Gap reference line + gap_y = (mf_gap_lower + mf_gap_upper) / 2 + ax_a.axhline(y=gap_y, color='grey', linestyle=':', linewidth=0.8, alpha=0.4) + + # Box showing panel (b) region, only if there is a panel (b) + if ax_b is not None: + rect = Rectangle((pb_dref_min, pb_mf_min), + pb_dref_max - pb_dref_min, + pb_mf_max - pb_mf_min, + linewidth=1.0, edgecolor=SHEFFIELD['dark_violet'], + facecolor='none', linestyle='--', alpha=0.6, zorder=5) + ax_a.add_patch(rect) + ax_a.text(pb_dref_max + 0.01, pb_mf_max, '(b)', + fontsize=9, color=SHEFFIELD['dark_violet'], va='top', + fontweight='bold') + + ax_a.set_xlabel('$d_\\mathrm{ref}$ / Å') + ax_a.set_ylabel('Madelung factor') + if ax_b is not None: + ax_a.set_title('(a)', loc='left', fontweight='bold') + ax_a.spines['top'].set_visible(False) + ax_a.spines['right'].set_visible(False) + + # v1.2.7: built from the registry, and only for codes that actually + # appear in this dataset. The hand-written version listed 2.2, which is + # now always empty, and omitted 1.3, 1.4, 2.3, 2.6 and 2.7, which are not. + _present = [c for c in CODE_ORDER if (ok['classification'] == c).any()] + legend_elements = [ + Line2D([0], [0], + marker={0: 'o', 3: 'D'}.get(_tier_for_code(c), 's'), + color='w', markerfacecolor=CLASSIFICATION_COLOURS[c], + markeredgecolor='white', markersize=7 if c != '3.1' else 6, + label=CLASSIFICATION_LABELS[c]) + for c in _present + ] + ax_a.legend(handles=legend_elements, frameon=False, fontsize=8, + loc='upper left', handletextpad=0.5) + + # ── Panel (b): zoomed cluster, when there is one ──────────────── + if ax_b is None: + fig.tight_layout() + if save_path: + fig.savefig(save_path) + print(f' saved {save_path}') + return fig + + print(f"Panel (b): {len(cluster_b)} structures in window") + _plot_scatter_by_tier(ax_b, cluster_b, {0: 35, 2: 40, 3: 40}, + alpha_additive=0.6) + + # ── Label strategy for panel (b) ──────────────────────────────── + cluster_grouped = cluster_b.groupby('compound').agg( + n=('compound', 'size'), + mf_med=('madelung_factor', 'median'), + dref_med=('d_ref_ang', 'median'), + cls=('classification', 'first'), + codes=('coll_code', lambda x: list(x)), + ).reset_index() + + texts_b = [] + + # Clustered compositions (n >= 3): label at median with count + clustered = cluster_grouped[cluster_grouped['n'] >= 3] + for _, r in clustered.iterrows(): + texts_b.append(ax_b.text( + r['dref_med'], r['mf_med'], + f'{r["compound"]} ({int(r["n"])})', + fontsize=6.5, color=SHEFFIELD['midnight'], + fontstyle='italic', fontweight='bold')) + + # Edge/outlier points: singletons and pairs at the edges + if len(cluster_b) > 0: + mf_hi = cluster_b['madelung_factor'].quantile(0.92) + mf_lo = cluster_b['madelung_factor'].quantile(0.08) + dref_hi = cluster_b['d_ref_ang'].quantile(0.92) + dref_lo = cluster_b['d_ref_ang'].quantile(0.08) + + edge_candidates = cluster_grouped[cluster_grouped['n'] <= 2] + for _, r in edge_candidates.iterrows(): + is_edge = (r['mf_med'] >= mf_hi or r['mf_med'] <= mf_lo or + r['dref_med'] >= dref_hi or r['dref_med'] <= dref_lo) + if is_edge: + cc = r['codes'][0] if r['codes'] else '' + n_str = f' ({int(r["n"])})' if r['n'] == 2 else '' + label = f'{r["compound"]}{n_str}\n{cc}' if cc else r['compound'] + texts_b.append(ax_b.text( + r['dref_med'], r['mf_med'], label, + fontsize=5.5, color=SHEFFIELD['midnight'], + fontstyle='italic')) + + if texts_b: + adjust_text(texts_b, ax=ax_b, + arrowprops=dict(arrowstyle='-', color='grey', + alpha=0.4, lw=0.5), + expand=(2.0, 2.0), force_text=(1.2, 1.2), + ensure_inside_axes=True) + + ax_b.set_xlabel('$d_\\mathrm{ref}$ / Å') + ax_b.set_ylabel('Madelung factor') + ax_b.set_title(f'(b) Z = 1 cluster detail (n = {len(cluster_b)})', + loc='left', fontweight='bold') + ax_b.spines['top'].set_visible(False) + ax_b.spines['right'].set_visible(False) + ax_b.set_xlim(pb_dref_min, pb_dref_max) + ax_b.set_ylim(pb_mf_min, pb_mf_max) + + fig.subplots_adjust(wspace=0.28) + + if save_path: + fig.savefig(save_path) + print(f"Saved: {save_path}") + + plt.show() + return fig diff --git a/src/maplepy/_cells/hopper/e23_series_figures.py b/src/maplepy/_cells/hopper/e23_series_figures.py new file mode 100644 index 0000000..48d197a --- /dev/null +++ b/src/maplepy/_cells/hopper/e23_series_figures.py @@ -0,0 +1,387 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 23. +# Edit the notebook, not this file, then rebuild. +# The action at the end of this cell is in r23_series_figures.py. +# 10. Additional Paper Figures +# ───────────────────────────────────────────────────────────────────────────── +# +# Figure 4: RE₂Ti₂O₇ titanate pyrochlore series +# Figure 5: RE₂Sn₂O₇ stannate pyrochlore series +# Figure 6: Lanthanide contraction in RE₂O₃ binary reference table +# Figure 7: Classification waterfall +# +# All figures use the Sheffield colour palette and style conventions +# established in earlier cells. +# ───────────────────────────────────────────────────────────────────────────── + +import re as regex + +# Shannon ionic radii (Å), CN = 8, oxidation state +3 +# (pyrochlore A-site is 8-coordinate) +SHANNON_CN8 = { + 'La': 1.160, 'Ce': 1.143, 'Pr': 1.126, 'Nd': 1.109, 'Pm': 1.093, + 'Sm': 1.079, 'Eu': 1.066, 'Gd': 1.053, 'Tb': 1.040, 'Dy': 1.027, + 'Ho': 1.015, 'Er': 1.004, 'Tm': 0.994, 'Yb': 0.985, 'Lu': 0.977, + 'Y': 1.019, +} + +# Shannon ionic radii (Å), CN = 6, oxidation state +3 +# (used for binary RE₂O₃ figure) +SHANNON_CN6 = { + 'La': 1.032, 'Ce': 1.01, 'Pr': 0.99, 'Nd': 0.983, 'Pm': 0.97, + 'Sm': 0.958, 'Eu': 0.947, 'Gd': 0.938, 'Tb': 0.923, 'Dy': 0.912, + 'Ho': 0.901, 'Er': 0.89, 'Tm': 0.88, 'Yb': 0.868, 'Lu': 0.861, +} + + +def _build_pyrochlore_series(df_classified, pattern, shannon=SHANNON_CN8): + """ + Extract median Δ and MF per RE element for a pyrochlore series. + + Uses only Additive + 3.1 entries (excludes disorder, Z=1, oxi-state + artefacts). Returns a DataFrame sorted by decreasing ionic radius. + """ + rows = [] + for comp in sorted(df_classified['compound'].unique()): + m = regex.match(pattern, comp) + if not m: + continue + re_el = m.group(1) + if re_el not in shannon: + continue + + clean = df_classified[ + (df_classified['compound'] == comp) & + (df_classified['classification'].isin(['Additive', '3.1'])) + ] + if len(clean) == 0: + continue + + all_entries = df_classified[df_classified['compound'] == comp] + radius = shannon[re_el] + + rows.append({ + 'element': re_el, 'compound': comp, 'radius': radius, + 'delta_median': clean['delta_pct'].median(), + 'delta_mean': clean['delta_pct'].mean(), + 'delta_std': clean['delta_pct'].std() if len(clean) > 1 else 0, + 'delta_min': clean['delta_pct'].min(), + 'delta_max': clean['delta_pct'].max(), + 'mf_median': clean['madelung_factor'].median(), + 'n_clean': len(clean), + 'n_total': len(all_entries), + }) + + df = pd.DataFrame(rows) + if len(df) == 0: + return df + return df.sort_values('radius', ascending=False) + + +def plot_pyrochlore_series(df_classified, pattern, series_label, + fig_label='(a)', save_path=None): + """ + Two-panel figure for a pyrochlore RE series: + (a) Δ vs ionic radius — median ± range, with 1% threshold line + (b) Madelung factor vs ionic radius + """ + df = _build_pyrochlore_series(df_classified, pattern) + if len(df) == 0: + print(f"No data found for pattern {pattern}") + return + + fig, (ax_a, ax_b) = plt.subplots( + 1, 2, figsize=(12, 5), + gridspec_kw={'width_ratios': [3, 2], 'wspace': 0.30} + ) + + radii = df['radius'].values + delta_med = df['delta_median'].values + delta_min = df['delta_min'].values + delta_max = df['delta_max'].values + mf_med = df['mf_median'].values + elements = df['element'].values + n_clean = df['n_clean'].values + + # ── Panel (a): Δ vs ionic radius ───────────────────────────────── + # Error bars showing full range + yerr_lo = delta_med - delta_min + yerr_hi = delta_max - delta_med + ax_a.errorbar(radii, delta_med, yerr=[yerr_lo, yerr_hi], + fmt='o', color=SHEFFIELD['brand_violet'], + markerfacecolor=SHEFFIELD['brand_violet'], + markeredgecolor='white', markersize=8, + ecolor=SHEFFIELD['powder_violet'], elinewidth=1.2, + capsize=3, capthick=1.0, zorder=3) + + # 1% threshold line + ax_a.axhline(y=1.0, color=SHEFFIELD['coral'], linestyle='--', + linewidth=1.2, alpha=0.7, zorder=1) + ax_a.text(ax_a.get_xlim()[0] + 0.003, 1.05, 'Hoppe 1%', + fontsize=9, color=SHEFFIELD['coral'], va='bottom') + + # Label each point + for el, r, d, n in zip(elements, radii, delta_med, n_clean): + n_str = f' ({n})' if n > 1 else '' + ax_a.annotate(f'{el}{n_str}', (r, d), + textcoords='offset points', xytext=(0, 10), + ha='center', fontsize=8, color=SHEFFIELD['midnight']) + + ax_a.set_xlabel('Shannon ionic radius (CN = 8, 3+) / Å') + ax_a.set_ylabel(r'Additivity residual, $\Delta$ / %') + ax_a.set_title(f'{fig_label} {series_label}', loc='left', fontweight='bold') + ax_a.spines['top'].set_visible(False) + ax_a.spines['right'].set_visible(False) + ax_a.invert_xaxis() + + # ── Panel (b): MF vs ionic radius ──────────────────────────────── + ax_b.plot(radii, mf_med, 'o-', + color=SHEFFIELD['teal'], markerfacecolor=SHEFFIELD['teal'], + markeredgecolor='white', markersize=8, linewidth=1.5, zorder=3) + + for el, r, mf in zip(elements, radii, mf_med): + ax_b.annotate(el, (r, mf), textcoords='offset points', + xytext=(0, 10), ha='center', fontsize=8, + color=SHEFFIELD['midnight']) + + ax_b.set_xlabel('Shannon ionic radius (CN = 8, 3+) / Å') + ax_b.set_ylabel('Madelung factor') + ax_b.set_title('(b) Madelung factor', loc='left', fontweight='bold') + ax_b.spines['top'].set_visible(False) + ax_b.spines['right'].set_visible(False) + ax_b.invert_xaxis() + + fig.tight_layout() + + if save_path: + fig.savefig(save_path) + print(f"Saved: {save_path}") + + plt.show() + + +def plot_lanthanide_contraction(binary_lookup, save_path=None): + """ + Figure 6: Lanthanide contraction in RE₂O₃ binary MAPLE values. + """ + lanthanides = ['La','Ce','Pr','Nd','Pm','Sm','Eu','Gd', + 'Tb','Dy','Ho','Er','Tm','Yb','Lu'] + + elements, radii, maples = [], [], [] + for el in lanthanides: + formula = f"{el}2O3" + if formula in binary_lookup and el in SHANNON_CN6: + elements.append(el) + radii.append(SHANNON_CN6[el]) + maples.append(binary_lookup[formula]) + + if not elements: + print("No RE₂O₃ entries found in binary reference table.") + return + + fig, ax = plt.subplots(figsize=(8, 5)) + + # La₂O₃ is P-3m1, rest are Ia-3 + ia3_idx = [i for i, el in enumerate(elements) if el != 'La'] + la_idx = [i for i, el in enumerate(elements) if el == 'La'] + + # Plot Ia-3 series + ia3_r = [radii[i] for i in ia3_idx] + ia3_m = [maples[i] for i in ia3_idx] + ax.plot(ia3_r, ia3_m, 'o-', + color=SHEFFIELD['brand_violet'], markerfacecolor=SHEFFIELD['brand_violet'], + markeredgecolor='white', markersize=8, linewidth=1.5, zorder=3) + + # Linear fit to Ia-3 entries + coeffs = np.polyfit(ia3_r, ia3_m, 1) + fit_r = np.linspace(min(ia3_r) - 0.02, max(ia3_r) + 0.02, 100) + fit_m = np.polyval(coeffs, fit_r) + ax.plot(fit_r, fit_m, '--', color=SHEFFIELD['powder_violet'], + linewidth=1.0, alpha=0.7, zorder=1) + + # Plot La separately (different structure type) + if la_idx: + i = la_idx[0] + ax.plot(radii[i], maples[i], 's', + color=SHEFFIELD['coral'], markeredgecolor='white', + markersize=10, zorder=4) + ax.annotate(r'$P\overline{3}m1$', (radii[i], maples[i]), + textcoords='offset points', xytext=(-20, -18), + fontsize=8, color=SHEFFIELD['coral'], fontstyle='italic', + arrowprops=dict(arrowstyle='-', color=SHEFFIELD['coral'], + lw=0.8, alpha=0.6)) + + # Label each point + for el, r, m in zip(elements, radii, maples): + idx = elements.index(el) + va = 'bottom' if idx % 2 == 0 else 'top' + offset = 12 if va == 'bottom' else -12 + ax.annotate(el, (r, m), textcoords='offset points', + xytext=(0, offset), ha='center', va=va, + fontsize=8, color=SHEFFIELD['midnight']) + + slope = coeffs[0] + ax.text(0.03, 0.95, + f'$Ia\\overline{{3}}$ fit: slope = {slope:.0f}' + r' kcal mol$^{-1}$ Å$^{-1}$', + transform=ax.transAxes, fontsize=9, + color=SHEFFIELD['powder_violet'], va='top') + + ax.set_xlabel('Shannon ionic radius (CN = 6, 3+) / Å') + ax.set_ylabel(r'MAPLE(RE$_2$O$_3$) / kcal mol$^{-1}$') + ax.spines['top'].set_visible(False) + ax.spines['right'].set_visible(False) + ax.invert_xaxis() + + fig.tight_layout() + + if save_path: + fig.savefig(save_path) + print(f"Saved: {save_path}") + + plt.show() + + +def plot_classification_waterfall(df_classified, save_path=None): + """ + Figure 7: Classification waterfall — horizontal stacked bar showing + how structures are sorted into classification tiers. + """ + code_order = CODE_ORDER + # v1.2.7: was a hand-written dict of seven codes, which raised + # KeyError on the first structure carrying any of the other five. + code_labels = CLASSIFICATION_LABELS + # v1.2.7: was a hand-written dict of seven codes, which raised + # KeyError on the first structure carrying any of the other five. + code_colours = CLASSIFICATION_COLOURS + + counts = [] + codes_present = [] + for code in code_order: + n = (df_classified['classification'] == code).sum() + if n > 0: + counts.append(n) + codes_present.append(code) + + total = sum(counts) + + # ── Plan the code labels before the figure exists ─────────────────── + # + # v1.2.8: rows used to alternate on index parity, which overprints as soon + # as three narrow slices are adjacent. A label now takes the highest row + # where it clears the label already there, measured from its own width, + # and drops a row only when it has to. Planning before the figure is made + # lets the figure be tall enough for however many rows that needs, rather + # than clipping them into a fixed height. + # + # CHAR_W is one character at fontsize 8 in data units: 8 pt is about + # 4.8 pt wide, 0.067 in, and the axis is 10 in across spanning `total`. + # ROW_H must exceed the drawn text height or rows collide even when the + # horizontal test passes, which is exactly how the first attempt failed. + CHAR_W = total * 0.0067 + PAD = total * 0.008 + ROW_H = 0.24 + + _rows, _plan = [], [] + left = 0 + for code, count in zip(codes_present, counts): + cx = left + count / 2 + label = 'Add.' if code == 'Additive' else code + if count < 10: # narrow: carry the count in the label + label = f'{label} ({count})' + half_w = CHAR_W * len(label) / 2 + row = 0 + while row < len(_rows) and cx - _rows[row][0] < half_w + _rows[row][1] + PAD: + row += 1 + if row == len(_rows): + _rows.append((cx, half_w)) + else: + _rows[row] = (cx, half_w) + _plan.append((label, cx, row)) + left += count + n_label_rows = len(_rows) + + fig, ax = plt.subplots( + figsize=(10, 3.5 + 0.45 * max(0, n_label_rows - 2))) + + left = 0 + for code, count in zip(codes_present, counts): + ax.barh(0, count, left=left, height=0.6, + color=code_colours[code], + edgecolor='white', linewidth=1.5) + + if count > 0: + pct = count / total * 100 + cx = left + count / 2 + dark_codes = {'Additive', '2.2', '2.4', '1.1', '2.3'} + text_colour = SHEFFIELD['midnight'] if code in dark_codes else 'white' + + if count >= 30: + ax.text(cx, 0, f'{count}\n({pct:.0f}%)', + ha='center', va='center', fontsize=9, + fontweight='bold', color=text_colour) + elif count >= 10: + ax.text(cx, 0, f'{count}', + ha='center', va='center', fontsize=8, + fontweight='bold', color=text_colour) + # v1.2.8: a narrow slice used to print its count above the bar, + # where it collided with the tier brackets at y = 0.48. The count + # goes into the label below instead, so each slice has exactly one + # piece of text attached to it. + + left += count + + # ── Category labels below, one per slice ──────────────────────────── + for label, cx, row in _plan: + ax.annotate(label, xy=(cx, -0.30), xytext=(cx, -0.38 - ROW_H * row), + ha='center', va='top', fontsize=8, + fontweight='bold', color=SHEFFIELD['midnight'], + arrowprops=dict(arrowstyle='-', color='grey', + lw=0.6, alpha=0.5)) + + # Tier brackets above + tier_groups = {} + left = 0 + for code, count in zip(codes_present, counts): + tier = 0 if code == 'Additive' else int(code[0]) + tier_name = f'Tier {tier}' + if tier_name not in tier_groups: + tier_groups[tier_name] = [left, left + count] + else: + tier_groups[tier_name][1] = left + count + left += count + + tier_colours = { + 'Tier 0': SHEFFIELD['peak_green'], + 'Tier 1': SHEFFIELD['powder_violet'], + 'Tier 2': SHEFFIELD['coral'], + 'Tier 3': SHEFFIELD['teal'], + } + + for tier_name, (x0, x1) in tier_groups.items(): + width = x1 - x0 + if width > 15: + mid = (x0 + x1) / 2 + colour = tier_colours.get(tier_name, SHEFFIELD['midnight']) + ax.annotate('', xy=(x0, 0.48), xytext=(x1, 0.48), + arrowprops=dict(arrowstyle='|-|', color=colour, + lw=1.2, mutation_scale=4)) + ax.text(mid, 0.58, tier_name, ha='center', va='bottom', + fontsize=8, color=colour, fontweight='bold') + + ax.set_xlim(-5, total + 5) + # v1.2.8: deep enough for the rows the declutter actually used, so a + # crowded dataset is not silently clipped. + ax.set_ylim(min(-1.0, -0.55 - ROW_H * n_label_rows), 1.0) + ax.set_xlabel(f'Number of structures (total = {total})') + ax.set_yticks([]) + ax.spines['top'].set_visible(False) + ax.spines['right'].set_visible(False) + ax.spines['left'].set_visible(False) + + fig.tight_layout() + + if save_path: + fig.savefig(save_path) + print(f"Saved: {save_path}") + + plt.show() diff --git a/src/maplepy/_cells/hopper/r04_load_maplepy_output.py b/src/maplepy/_cells/hopper/r04_load_maplepy_output.py new file mode 100644 index 0000000..441b17b --- /dev/null +++ b/src/maplepy/_cells/hopper/r04_load_maplepy_output.py @@ -0,0 +1,89 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 4. +# Edit the notebook, not this file, then rebuild. + +# Uses a tkinter directory picker to select the folder containing +# maple_summary.csv and maple_results.csv from a MaplePy batch run. + +# maplepy package: no folder dialog; the folder is passed in + +# ── Where the MaplePy output is ─────────────────────────────────────────── +# +# v1.2.5: running this notebook twice in one kernel could sit on this cell +# for minutes with nothing on screen. It is not the figures and it is not the +# CSVs: it is THIS DIALOG. A second Tk root in one process opens a dialog +# that, on Windows, frequently lands BEHIND the browser, and the cell then +# waits for a click on a window nobody can see. Restarting the kernel cures +# it, which is exactly what a hidden modal looks like. +# +# MaplePy's own picker passes parent=root and this one did not. It does now, +# with an update() either side so Tk actually maps the window, and the notice +# below is printed BEFORE the dialog blocks so a hang is diagnosable. +# +# Better still: set MAPLE_DIR_OVERRIDE and no dialog opens at all. +MAPLE_DIR_OVERRIDE = _HOPPER_RUN_DIRECTORY # maplepy package: the folder passed in +# # e.g. r"path/to/outputs_YYYYMMDD_HHMMSS" + +if MAPLE_DIR_OVERRIDE: + MAPLE_DIR = str(MAPLE_DIR_OVERRIDE) + print(f"Using MAPLE_DIR_OVERRIDE, no dialog: {MAPLE_DIR}") +else: + print("Opening a folder picker. If nothing appears, look BEHIND this " + "window - a second Tk dialog in one kernel often opens there. " + "Set MAPLE_DIR_OVERRIDE above to skip the dialog entirely.") + root = tk.Tk() + root.withdraw() + root.update() + root.attributes('-topmost', True) + root.lift() + root.focus_force() + + MAPLE_DIR = filedialog.askdirectory( + title="Select folder containing MaplePy output CSVs " + "(maple_summary.csv and maple_results.csv)", + parent=root + ) + root.update() + root.destroy() + +if not MAPLE_DIR: + raise FileNotFoundError( + "No directory selected. Re-run this cell and choose the " + "folder containing your MaplePy output CSVs." + ) + +MAPLE_DIR = Path(MAPLE_DIR) +print(f"Selected directory: {MAPLE_DIR}") + +# ── Locate CSVs ────────────────────────────────────────────────────────── +summary_csv = MAPLE_DIR / "maple_summary.csv" +results_csv = MAPLE_DIR / "maple_results.csv" + +if not summary_csv.exists(): + # Check for outputs_* subdirectories (MaplePy timestamped folders) + output_dirs = sorted(MAPLE_DIR.glob('outputs_*'), reverse=True) + if output_dirs: + MAPLE_DIR = output_dirs[0] + summary_csv = MAPLE_DIR / 'maple_summary.csv' + results_csv = MAPLE_DIR / 'maple_results.csv' + print(f" Using most recent output: {MAPLE_DIR.name}") + +if not summary_csv.exists(): + raise FileNotFoundError( + f"maple_summary.csv not found in {MAPLE_DIR}.\n" + f"Run MaplePy batch processing (Section 5 or 7) first." + ) +if not results_csv.exists(): + raise FileNotFoundError( + f"maple_results.csv not found in {MAPLE_DIR}.\n" + f"Run MaplePy batch processing (Section 5 or 7) first." + ) + +# ── Load ───────────────────────────────────────────────────────────────── +df_summary = pd.read_csv(summary_csv) +df_results = pd.read_csv(results_csv) + +print(f"\nLoaded: {len(df_summary)} structures from {summary_csv.name}") +print(f" {len(df_results)} site-level rows from {results_csv.name}") +print(f" {df_summary['compound'].nunique()} unique compositions") +print(f" {df_summary['space_group'].nunique()} space groups") +print(f" {df_summary['disordered'].sum()} disordered structures") \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/r10_batch_additivity.py b/src/maplepy/_cells/hopper/r10_batch_additivity.py new file mode 100644 index 0000000..ade3d0b --- /dev/null +++ b/src/maplepy/_cells/hopper/r10_batch_additivity.py @@ -0,0 +1,16 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 10. +# Edit the notebook, not this file, then rebuild. +# The action at the end of the cell; its definitions are in e10_batch_additivity.py. +# ── Run the batch ──────────────────────────────────────────────────────────── +print("Computing additivity residuals for all structures...") +df_additivity, additivity_details = batch_additivity( + df_summary, df_results, BINARY_MAPLE, verbose=False +) + +# Show the successful decompositions +df_ok = df_additivity[df_additivity['success']].sort_values('delta_pct') +print(f"\nSuccessfully decomposed: {len(df_ok)} structures") +if len(df_ok) > 0: + display(df_ok[['compound','space_group','Z','maple_ternary', + 'maple_binary_sum','delta_abs','delta_pct', + 'oxygen_balanced','disordered']].head(30)) \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/r12_classification.py b/src/maplepy/_cells/hopper/r12_classification.py new file mode 100644 index 0000000..3439d37 --- /dev/null +++ b/src/maplepy/_cells/hopper/r12_classification.py @@ -0,0 +1,63 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 12. +# Edit the notebook, not this file, then rebuild. +# The action at the end of the cell; its definitions are in e12_classification.py. +# ── Classify ───────────────────────────────────────────────────────────────── +df_classified = classify_additivity(df_additivity, df_results, df_summary) + +# v1.1: the 2.5 population, counted from the data rather than from a string. +_n25 = int((df_classified['classification'] == '2.5').sum()) +# v1.2.4: the same question as before - how many structures the screen +# COULD test, which is not the same as how many the classifier reached, +# since a structure classified 1.3 or 2.7 never gets to the 2.5 branch. +# So the loop stays, and the indexes make it cost 0.1 s instead of 3.5. +_ridx_screen = index_by_cif(df_results) +_sidx_screen = index_by_cif(df_summary) +_tested = sum(1 for _c in df_classified['source_cif'] + if detect_structural_coordinate_error( + _c, df_results, df_summary, + results_index=_ridx_screen, + summary_index=_sidx_screen) is not None) +print(f' coordinate-error screen: {_n25} flagged of {_tested} testable ' + f'({len(df_classified)} structures in the run)') + +# ── Summary by tier ────────────────────────────────────────────────────────── +print("Classification summary") +print("=" * 65) + +# Tier-level summary +tier_labels = {0: 'Additive', 1: 'Tier 1 (incomplete)', + 2: 'Tier 2 (compromised)', 3: 'Tier 3 (trustworthy)'} +for tier_num in [0, 1, 2, 3]: + count = (df_classified['classification_tier'] == tier_num).sum() + if count > 0: + print(f" {tier_labels[tier_num]:30s} {count:5d}") +print() + +# Code-level summary +print("Breakdown by classification code:") +for code in CODE_ORDER: + subset = df_classified[df_classified['classification'] == code] + if len(subset) > 0: + label = subset['classification_label'].iloc[0] + print(f" {code:10s} {label:40s} {len(subset):5d}") +print("=" * 65) +_pop = additivity_population(df_classified) +print(f" residual population: {len(_pop)} of {len(df_classified)} " + f"(decomposition complete), of which " + f"{n_classified_additive(df_classified)} classified additive at " + f"delta < {ADDITIVE_THRESHOLD_PCT:g}%") +print() + +# ── Show each classification group ────────────────────────────────────────── +for code in CODE_ORDER: + subset = df_classified[df_classified['classification'] == code] + if len(subset) > 0: + label = subset['classification_label'].iloc[0] + tier = subset['classification_tier'].iloc[0] + tier_str = f"Tier {tier}" if tier > 0 else "Additive" + print(f"\n{code} — {label} [{tier_str}] ({len(subset)} structures)") + cols = ['compound', 'space_group', 'Z', 'delta_pct', + 'disordered', 'oxygen_balanced'] + if code == '1.1': + cols.append('missing_binaries') + display(subset[cols].head(15)) diff --git a/src/maplepy/_cells/hopper/r14_residual_histogram.py b/src/maplepy/_cells/hopper/r14_residual_histogram.py new file mode 100644 index 0000000..e17977a --- /dev/null +++ b/src/maplepy/_cells/hopper/r14_residual_histogram.py @@ -0,0 +1,8 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 14. +# Edit the notebook, not this file, then rebuild. +# The action at the end of the cell; its definitions are in e14_residual_histogram.py. +# ── Plot ───────────────────────────────────────────────────────────────────── +fig_hist = plot_additivity_histogram( + df_classified, + save_path=MAPLE_DIR / 'fig1_additivity_histogram.png' +) \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/r15_madelung_factor_clustering.py b/src/maplepy/_cells/hopper/r15_madelung_factor_clustering.py new file mode 100644 index 0000000..e07f5c8 --- /dev/null +++ b/src/maplepy/_cells/hopper/r15_madelung_factor_clustering.py @@ -0,0 +1,8 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 15. +# Edit the notebook, not this file, then rebuild. +# The action at the end of the cell; its definitions are in e15_madelung_factor_clustering.py. +# ── Plot ───────────────────────────────────────────────────────────────────── +fig_mf = plot_mf_clustering( + df_classified, + save_path=MAPLE_DIR / 'fig2_mf_clustering.png' +) \ No newline at end of file diff --git a/src/maplepy/_cells/hopper/r17_perovskites.py b/src/maplepy/_cells/hopper/r17_perovskites.py new file mode 100644 index 0000000..92d15d8 --- /dev/null +++ b/src/maplepy/_cells/hopper/r17_perovskites.py @@ -0,0 +1,32 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 17. +# Edit the notebook, not this file, then rebuild. + +# 6. Perovskite-Specific Analysis +# ───────────────────────────────────────────────────────────────────────────── + +PEROVSKITE_SGS = ['Pnma', 'Pm-3m', 'R-3c', 'P4mm', 'I4/mcm', + 'Cmcm', 'R3c', 'P2_1/n', 'Imma'] + +df_perov = df_classified[ + df_classified['space_group'].isin(PEROVSKITE_SGS) +].copy() + +print(f"Perovskite candidates: {len(df_perov)} structures") +print(f" Space groups: {df_perov['space_group'].value_counts().to_dict()}") +print(f" Successfully decomposed: {df_perov['success'].sum()}") + +# Classification breakdown for perovskites +print(f"\n Classification breakdown:") +for code in CODE_ORDER: + n = (df_perov['classification'] == code).sum() + if n > 0: + print(f" {code:10s} {n}") +print() + +if len(df_perov) > 0: + df_perov_ok = df_perov[df_perov['success']].sort_values('delta_pct') + print("Perovskite additivity results (sorted by residual):") + display(df_perov_ok[['compound', 'space_group', 'Z', 'maple_ternary', + 'maple_binary_sum', 'delta_pct', 'classification', + 'classification_label', 'madelung_factor']]) + diff --git a/src/maplepy/_cells/hopper/r19_pyrochlores.py b/src/maplepy/_cells/hopper/r19_pyrochlores.py new file mode 100644 index 0000000..18240a6 --- /dev/null +++ b/src/maplepy/_cells/hopper/r19_pyrochlores.py @@ -0,0 +1,48 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 19. +# Edit the notebook, not this file, then rebuild. + +# 7. Pyrochlore-Specific Analysis +# ───────────────────────────────────────────────────────────────────────────── + +PYROCHLORE_SGS = ['Fd-3m', 'Fm-3m'] + +df_pyro = df_classified[ + df_classified['space_group'].isin(PYROCHLORE_SGS) +].copy() + +print(f"Fd-3m / Fm-3m candidates: {len(df_pyro)} structures") +print(f" Space groups: {df_pyro['space_group'].value_counts().to_dict()}") +print(f" Successfully decomposed: {df_pyro['success'].sum()}") + +# Classification breakdown for pyrochlores +print(f"\n Classification breakdown:") +for code in CODE_ORDER: + n = (df_pyro['classification'] == code).sum() + if n > 0: + print(f" {code:10s} {n}") +print() + +if len(df_pyro) > 0: + df_pyro_ok = df_pyro[df_pyro['success']].sort_values('delta_pct') + print("Pyrochlore/fluorite additivity results:") + display(df_pyro_ok[['compound', 'space_group', 'Z', 'maple_ternary', + 'maple_binary_sum', 'delta_pct', 'classification', + 'classification_label', 'disordered', + 'madelung_factor']]) + + # ── Look for specific composition series ────────────────────────── + ti_pyro = df_pyro_ok[df_pyro_ok['compound'].str.contains('Ti2', + na=False)] + if len(ti_pyro) > 1: + print(f"\nRE2Ti2O7 series ({len(ti_pyro)} entries):") + display(ti_pyro[['compound', 'space_group', 'maple_ternary', + 'delta_pct', 'madelung_factor', 'disordered', + 'classification']]) + + zr_pyro = df_pyro_ok[df_pyro_ok['compound'].str.contains('Zr', + na=False)] + if len(zr_pyro) > 1: + print(f"\nRE2Zr2O7 series ({len(zr_pyro)} entries):") + display(zr_pyro[['compound', 'space_group', 'maple_ternary', + 'delta_pct', 'madelung_factor', 'disordered', + 'classification']]) diff --git a/src/maplepy/_cells/hopper/r21_export.py b/src/maplepy/_cells/hopper/r21_export.py new file mode 100644 index 0000000..1baee2f --- /dev/null +++ b/src/maplepy/_cells/hopper/r21_export.py @@ -0,0 +1,58 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 21. +# Edit the notebook, not this file, then rebuild. + +# 8. Export Results +# ───────────────────────────────────────────────────────────────────────────── + +OUTPUT_DIR = MAPLE_DIR + +# Full classified table +out_csv = OUTPUT_DIR / 'additivity_classified.csv' +df_classified.to_csv(out_csv, index=False) +print(f"Saved: {out_csv} ({len(df_classified)} rows)") + +# Verify the new columns are present in the export +expected_cols = ['classification', 'classification_tier', 'classification_label'] +missing_cols = [c for c in expected_cols if c not in df_classified.columns] +if missing_cols: + print(f" WARNING: missing columns in export: {missing_cols}") +else: + print(f" Columns: {expected_cols} — all present") + +# Perovskite subset +if len(df_perov) > 0: + perov_csv = OUTPUT_DIR / 'additivity_perovskites.csv' + df_perov.to_csv(perov_csv, index=False) + print(f"Saved: {perov_csv} ({len(df_perov)} rows)") + +# Pyrochlore subset +if len(df_pyro) > 0: + pyro_csv = OUTPUT_DIR / 'additivity_pyrochlores.csv' + df_pyro.to_csv(pyro_csv, index=False) + print(f"Saved: {pyro_csv} ({len(df_pyro)} rows)") + +# Binary reference table +binary_csv = OUTPUT_DIR / 'binary_oxide_reference.csv' +df_binary.to_csv(binary_csv, index=False) +print(f"Saved: {binary_csv} ({len(df_binary)} rows)") + +# Missing binaries summary +if df_additivity[~df_additivity['success']]['missing_binaries'].any(): + missing_series = (df_additivity[~df_additivity['success']] + ['missing_binaries'] + .str.split('; ') + .explode() + .value_counts()) + print(f"\nMissing binary references (add these to the table):") + print(missing_series.head(20)) + +# Classification summary for the export log +print(f"\nExport classification summary:") +print(f" Total structures: {len(df_classified)}") +for tier_num, tier_name in {0: 'Additive', 1: 'Tier 1', 2: 'Tier 2', + 3: 'Tier 3'}.items(): + n = (df_classified['classification_tier'] == tier_num).sum() + if n > 0: + print(f" {tier_name:12s} {n}") + +print("\nDone.") diff --git a/src/maplepy/_cells/hopper/r23_series_figures.py b/src/maplepy/_cells/hopper/r23_series_figures.py new file mode 100644 index 0000000..0ffa894 --- /dev/null +++ b/src/maplepy/_cells/hopper/r23_series_figures.py @@ -0,0 +1,35 @@ +# Generated by tools/build_engine.py from Hopper.ipynb, cell 23. +# Edit the notebook, not this file, then rebuild. +# The action at the end of the cell; its definitions are in e23_series_figures.py. +# ── Generate Figures ───────────────────────────────────────────────────────── + +# Figure 4: Titanate pyrochlore series +plot_pyrochlore_series( + df_classified, + pattern=r'^([A-Z][a-z]?)2Ti2O7$', + series_label=r'RE$_2$Ti$_2$O$_7$ titanate series', + fig_label='(a)', + save_path=MAPLE_DIR / 'fig4_titanate_series.png' +) + +# Figure 5: Stannate pyrochlore series +plot_pyrochlore_series( + df_classified, + pattern=r'^([A-Z][a-z]?)2Sn2O7$', + series_label=r'RE$_2$Sn$_2$O$_7$ stannate series', + fig_label='(a)', + save_path=MAPLE_DIR / 'fig5_stannate_series.png' +) + +# Figure 6: Lanthanide contraction in binary RE₂O₃ +binary_lookup_fig6 = dict(zip(df_binary['formula'], df_binary['maple_kcal_mol'])) +plot_lanthanide_contraction( + binary_lookup_fig6, + save_path=MAPLE_DIR / 'fig6_lanthanide_contraction.png' +) + +# Figure 7: Classification waterfall +plot_classification_waterfall( + df_classified, + save_path=MAPLE_DIR / 'fig7_classification_waterfall.png' +) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/e04_constants_and_version.py b/src/maplepy/_cells/maplepy/e04_constants_and_version.py new file mode 100644 index 0000000..597ce33 --- /dev/null +++ b/src/maplepy/_cells/maplepy/e04_constants_and_version.py @@ -0,0 +1,145 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 4. +# Edit the notebook, not this file, then rebuild. + +import numpy as np +import pandas as pd +from pathlib import Path + +from pymatgen.core import Structure, Lattice +from pymatgen.analysis.ewald import EwaldSummation + +# ── Physical constants ───────────────────────────────────────────────────────── +EV_TO_KCAL_MOL = 23.0609 # 1 eV (per particle) = 23.0609 kcal/mol (per mole) +KCAL_TO_KJ = 4.184 # 1 kcal = 4.184 kJ +# MAPLE conversion factor: e²Nₐ / 4πε₀ in units of Å·kcal/mol +# Hoppe uses 331.81 (older constants); modern value is 332.06 +MAPLE_FACTOR = 332.06 # Å·kcal/mol + +# ── Tolerances, each named once ──────────────────────────────────────────── +# +# v1.1: these were previously written twice each, with different values. +# +# CHARGE_NEUTRAL_TOL was 0.5 where the CIF's own per-site states are accepted +# and 0.05 where the result is checked - ten times apart, in one function, +# neither with a reason. One value, used for both questions: a cell whose +# charges sum to more than this is not neutral, whoever assigned them. +# 0.05 e per cell is below the rounding of a single deposited oxidation state +# and above the floating-point noise of an occupancy-weighted sum. +CHARGE_NEUTRAL_TOL = 0.05 # e per unit cell + +# OCCUPANCY_TOL was 1.05 in the CIF parser and 1.01 in the warning that +# follows it, so a site at 1.03 was silently accepted and never mentioned. +# One value: what the parser will accept is what the warning is about. +OCCUPANCY_TOL = 1.05 # site occupancy sum above which a site is + # reported as a refinement-quality issue + + +# ── When a site is not fully occupied ────────────────────────────────────── +# +# v1.3.2: the disorder test used to ask only whether a site carried more than +# one species. A single species at occupancy 0.5 is a split-site or +# vacancy-bearing refinement and is just as much a mean-field approximation, +# and 12 of 97 probed structures were labelled ordered on that basis. +# +# The number is a guard against arithmetic noise, not a scientific cut. On the +# 97-structure probe the site occupancy sums were 1.000, 0.993, 0.985, 0.950, +# 0.800, 0.731, 0.500, 0.250 and 0.167: nothing lies between 0.993 and 1.000, +# so any threshold in that gap classifies identically. Set just below 1 so +# that a refined deficiency of 0.7% is still called what it is. +FULL_OCCUPANCY_TOL = 0.995 # site occupancy sum at or above this is full + +# ── When two sites are one crystallographic position ─────────────────────── +# +# v1.3.2: below this separation, two sites are the same position split by a +# disorder model, and the Ewald sum over them is not an energy. Measured over +# the 1410-structure dataset, the four structures with any contact under 1 A +# are at 0.030, 0.160, 0.441 and 0.455 A, and the shortest genuine contact +# anywhere in the 97-structure probe is 1.008 A - itself a coordinate error. +# Nothing lies between 0.455 and 1.008, so any threshold in that gap +# classifies these identically; 0.5 A is well below the shortest real +# cation-anion distance in any oxide. +# +# NOTE this is a FLAG, not a filter. d_min_ang is written for every structure +# so the cut can be fitted from a full run rather than from four examples. +SPLIT_SITE_ANG = 0.5 # A, shortest contact below which two sites are + # taken to be one position, split +# +# v1.3.3: CONFIRMED against the whole dataset now that d_min_ang is written +# for every structure. The band from 0.5 to 1.0 A is EMPTY in both families, +# and the four structures below 0.5 A are the four this was fitted on. + +# ── When a contact is too short to be a bond ─────────────────────────────── +# +# v1.3.3: a second population, separate from the split sites. 26 perovskites +# have a shortest contact between 1.0 and 1.6 A, median residual 8 to 13%, +# median Madelung factor 2.5 against the family's 3.83: coordinate errors. +# Hopper's 2.5 detector catches 22 of them and structurally cannot see the +# rest, being a coefficient-of-variation test on 20-site Pnma cells. NdFeO3 +# at 1.507 A was classified ADDITIVE at delta 0.312%. +# +# UNLIKE SPLIT_SITE_ANG THERE IS NO GAP HERE. It is a continuum, and this is +# a judgement rather than a fitted value. Measured, at each candidate cut: +# +# threshold flagged already 2.5 newly flagged of those, Additive +# 1.6 A 26 22 4 1 +# 1.7 A 37 27 10 2 +# 1.75 A 46 29 17 4 +# 1.8 A 63 29 34 17 +# +# 1.8 A starts taking structures whose short bond is plausible. 1.6 A is +# below any cation-anion distance these families produce and above every +# contact in the well-behaved bulk. +SHORT_CONTACT_ANG = 1.6 # A, shortest contact below which the geometry + # is reported as unphysical (a judgement) + + +# ── How many CIFs at once ────────────────────────────────────────────────── +# +# v1.3.4: every structure is independent and costs about 140 ms of CPU, and the +# 24 August perovskite run took 22 minutes. Measured on 84 real CIFs on a +# 2-core container: 10.15 s serial against 7.24 s on two workers, every value +# identical. Two cores caps that at 2x before pool startup, so on six workers +# with the startup spread over a full family, expect nearer 5x. +# +# 'auto' as many workers as cores, less two, and never more than the +# number of CIFs +# 1 serial, which is exactly what v1.3.3 did +# an int that many workers +# +# The serial and parallel paths call the SAME function, process_one_cif, so +# there is one definition of what processing a CIF means. +MAPLE_WORKERS = 'auto' + + +# ── The version, named once ──────────────────────────────────────────────── +# +# v1.3.1: written into every results and summary CSV as a column, so a file +# on disk says which notebook made it. Three CSVs from three versions in one +# folder look identical otherwise, and the differences between them have been +# Z, the data directory and the cell setting. +MAPLEPY_VERSION = '1.3.6' + + +# ── Where the reference data lives ───────────────────────────────────────── +# +# v1.2: data_dir defaulted to '.', which is where the notebook is rather than +# where its data is. maple_library.json and common_oxidation_states.json sit +# in data/, so the oxidation-state priority chain silently dropped two levels +# for anyone whose working directory was the notebook's. +# +# Resolved once, here, and reported when it is used. A path given explicitly +# is checked: asking for a directory that does not exist is a mistake worth +# hearing about, not a reason to fall back. +def _default_data_dir(): + for _cand in ('data', '.'): + if Path(_cand).is_dir() and any(Path(_cand).glob('*.json')): + return _cand + return '.' + + +DEFAULT_DATA_DIR = _MAPLEPY_DATA_DIR # maplepy package: the bundled tables +print(f" data directory: {Path(DEFAULT_DATA_DIR).resolve()}") + +print(f"MaplePy {MAPLEPY_VERSION} loaded.") +print(f" EV_TO_KCAL_MOL = {EV_TO_KCAL_MOL}") +print(f" MAPLE_FACTOR = {MAPLE_FACTOR} Å·kcal/mol (Hoppe 1995 uses 331.81)") \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/e06_core_functions.py b/src/maplepy/_cells/maplepy/e06_core_functions.py new file mode 100644 index 0000000..700f755 --- /dev/null +++ b/src/maplepy/_cells/maplepy/e06_core_functions.py @@ -0,0 +1,873 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 6. +# Edit the notebook, not this file, then rebuild. + +# 1. Core Functions (v3) +# ───────────────────────────────────────────────────────────────────────────── + +import re as _re +import json +import math as _math +import warnings +warnings.filterwarnings('ignore', message='dict interface is deprecated', + category=DeprecationWarning) +warnings.filterwarnings('ignore', message='Issues encountered while parsing CIF', + category=UserWarning) +warnings.filterwarnings('ignore', category=DeprecationWarning, + module='pymatgen') + +# ── Helpers: safe extraction of element symbol and oxi_state ───────────────── +# pymatgen sites can hold either a Species object (ordered) or a Composition +# (disordered). These helpers handle both transparently. + +def _site_element(site): + """ + Return the majority element symbol for a site. + For mixed-occupancy sites, returns the species with highest occupancy. + """ + sp = site.species + if len(sp) > 1: + majority = max(sp.items(), key=lambda x: x[1]) + el = majority[0] + return el.element.symbol if hasattr(el, 'element') else el.symbol + if hasattr(sp, 'elements') and len(sp.elements) > 0: + el = sp.elements[0] + return el.symbol if hasattr(el, 'symbol') else str(el) + return site.specie.element.symbol + + +def _site_oxi_state(site): + """ + Return the oxidation state (float) for a site. + For mixed-occupancy sites, returns the occupancy-weighted mean charge. + """ + sp = site.species + if len(sp) > 1: + total_oxi = 0.0 + total_occ = 0.0 + for species, occ in sp.items(): + if hasattr(species, 'oxi_state'): + total_oxi += species.oxi_state * occ + total_occ += occ + if total_occ > 0: + return total_oxi / total_occ + return 0.0 + if hasattr(sp, 'elements') and len(sp.elements) > 0: + el = sp.elements[0] + if hasattr(el, 'oxi_state'): + return float(el.oxi_state) + return float(site.specie.oxi_state) + + +def _is_anion_site(site): + """ + Whether this site belongs to the anion sublattice. + + By oxidation state where the structure has them, and by element where it + does not: load_structure asks about disorder before the states are + assigned, and MaplePy's domain is oxides, so oxygen is the anion. Stated + rather than assumed, because it is an assumption. + """ + try: + oxi = _site_oxi_state(site) + if oxi: + return oxi < 0 + except (AttributeError, TypeError, ValueError): + pass + return _site_element(site) == 'O' + + +def _disorder_detail(structure): + """ + What kind of disorder this structure carries, and where: one computation. + + v1.3.3: `partial occupancy` was not enough. Making the flag see partial + occupancy at all (v1.3.2) moved 14 oxygen-deficient refinements out of + Hopper's oxygen non-stoichiometry class and into its disorder class, which + describes them less well. Hopper has reserved a code for anion vacancy + disorder since its first version and could not assign it without knowing + which sublattice was short. + + MaplePy holds the occupancies, so MaplePy answers. Deriving this + downstream from a reduced formula undercounts split sites, whose two + half-occupied positions sum to an integer composition. + + Returns (kind, sublattice): + kind 'ordered' | 'mixed occupancy' | 'partial occupancy' + | 'mixed and partial occupancy' + sublattice 'none' | 'anion' | 'cation' | 'both' + """ + mixed = False + partial = set() + for site in structure: + if len(site.species) > 1: + mixed = True + if sum(site.species.values()) < FULL_OCCUPANCY_TOL: + partial.add('anion' if _is_anion_site(site) else 'cation') + + sublattice = ('none' if not partial else + 'both' if len(partial) > 1 else + next(iter(partial))) + + if mixed and partial: + kind = 'mixed and partial occupancy' + elif mixed: + kind = 'mixed occupancy' + elif partial: + kind = 'partial occupancy' + else: + kind = 'ordered' + return kind, sublattice + + +def _disorder_kind(structure): + """The kind alone. Derived, so there is one computation.""" + return _disorder_detail(structure)[0] + + +def _is_disordered(structure): + """True where the mean-field charge approximation is in use. + + Derived from _disorder_detail so there is one definition of disorder. + """ + return _disorder_kind(structure) != 'ordered' + + +def _shortest_contact(structure): + """ + The shortest interatomic distance in the cell, and the pair that makes it. + + Returns (d_ang, label_i, label_j). Any pair, not cation-anion: the fault + this exists to catch is a same-element split site, which d_ref cannot see + because d_ref only looks across the cation-anion boundary. + """ + if len(structure) < 2: + return float('inf'), None, None + dm = structure.distance_matrix.copy() + np.fill_diagonal(dm, np.inf) + i, j = np.unravel_index(np.argmin(dm), dm.shape) + return (float(dm[i, j]), _site_element(structure[int(i)]), + _site_element(structure[int(j)])) + + +def _geometry_status(structure): + """ + Whether the geometry can carry a Madelung energy, as a sentence. + + v1.3.2: MaplePy had no geometry test. Four structures in the 1410-entry + dataset put two fractionally occupied sites within half an angstrom of + each other, and their Ewald sums came out up to ten times the family + median while being reported as ordinary results. + + v1.3.3: two thresholds, because the measured distribution has two + populations - split sites below 0.5 A and coordinate errors between 1.0 + and 1.6 A, with nothing at all in between. See SPLIT_SITE_ANG and + SHORT_CONTACT_ANG for both, and for which of them is a judgement. + + FLAG, KEEP, REPORT: this never drops a structure and never changes a + number. It returns (d_min, flag, status): the flag for Hopper, which + should not be matching on the prefix of a sentence, and the sentence for + whoever reads the CSV. + """ + d_min, el_i, el_j = _shortest_contact(structure) + if d_min < SPLIT_SITE_ANG: + return d_min, 'split_site', ( + f'split site: {el_i}-{el_j} contact {d_min:.3f} A, below ' + f'{SPLIT_SITE_ANG} A - the Ewald sum over these two sites is ' + f'not an energy') + if d_min < SHORT_CONTACT_ANG: + return d_min, 'short_contact', ( + f'short contact: {el_i}-{el_j} at {d_min:.3f} A, below ' + f'{SHORT_CONTACT_ANG} A - shorter than any cation-anion bond ' + f'these families produce, so the coordinates are suspect') + return d_min, 'ok', f"ok: shortest contact {d_min:.3f} A" + + +# ── Oxidation state helpers (unchanged) ────────────────────────────────────── + +def _load_oxi_json(path): + """Load common_oxidation_states.json. {} if absent, raises if corrupt. + + v1.1: 'file is not there' and 'file is there and unreadable' are different + facts and were both returning {}, which the priority chain below reads as + 'this source has nothing to say' and silently drops a level. + """ + try: + with open(path, 'r') as f: + return json.load(f) + except FileNotFoundError: + return {} + except (json.JSONDecodeError, OSError) as e: + raise ValueError(f'{path} exists but could not be read: {e}') from e + + +def _load_maple_library(data_dir): + # v1.3.1: no default. The directory is resolved once, in load_structure, + # against DEFAULT_DATA_DIR; a second default here is a second answer to + # the same question, and it was the wrong one. + """Load maple_library.json. {} if absent, raises if corrupt. See above.""" + try: + with open(Path(data_dir) / 'maple_library.json', 'r') as f: + return json.load(f) + except FileNotFoundError: + return {} + except (json.JSONDecodeError, OSError) as e: + raise ValueError( + f'maple_library.json in {data_dir} could not be read: {e}') from e + + +def _extract_cif_oxidation_states(cif_path): + """ + Parse _atom_type_oxidation_number loop from a CIF file. + + Mirrors Eir's extract_cif_oxidation_states() — the most reliable source + for ICSD CIFs, which always embed oxidation states in this loop. + + Returns + ------- + dict {element: charge} e.g. {'Na': 1, 'Cl': -1}, or {} if not found. + """ + oxidation_states = {} + try: + with open(cif_path, 'r', encoding='utf-8', errors='ignore') as f: + lines = f.readlines() + except FileNotFoundError: + return {} + except OSError as e: + # v1.1: a CIF that cannot be read is not a CIF with no oxidation + # states in it, and the caller treats the two identically. + raise ValueError(f'could not read {cif_path}: {e}') from e + + in_loop = False + columns = [] + symbol_col = None + oxi_col = None + + for line in lines: + ls = line.strip() + + if ls == 'loop_': + in_loop = False + columns = [] + symbol_col = None + oxi_col = None + continue + + if ls.startswith('_atom_type_'): + idx = len(columns) + columns.append(ls) + if ls == '_atom_type_symbol': + symbol_col = idx + elif ls == '_atom_type_oxidation_number': + oxi_col = idx + in_loop = True + continue + + if in_loop and columns and not ls.startswith('_'): + if not ls or ls.startswith('#') or ls.startswith('loop_'): + in_loop = False + continue + parts = ls.split() + if symbol_col is not None and symbol_col < len(parts): + raw = parts[symbol_col] + element = _re.sub(r'[0-9+\-]+', '', raw) + element = (element.capitalize() if len(element) > 1 + else element.upper()) + if oxi_col is not None and oxi_col < len(parts): + ox_str = parts[oxi_col] + if ox_str not in ['?', '.']: + try: + oxidation_states[element] = round(float(ox_str)) + except ValueError: + pass + + return oxidation_states + + +def _oxi_from_library(elements, reduced_formula, library): + """ + Look up oxidation states by reduced formula in maple_library.json. + Returns dict or None if formula not found or elements not fully covered. + """ + overrides = library.get('oxidation_state_overrides', {}) + entry = overrides.get(reduced_formula) + if entry and isinstance(entry, dict): + if all(el in entry for el in elements): + return {el: entry[el] for el in elements} + return None + + +def _oxi_from_json_fallback(elements, oxi_json): + """ + Attempt oxidation state assignment using common_oxidation_states.json. + Returns dict or None if any element is ambiguous (multiple common states). + """ + assignment = {} + for el in elements: + states = oxi_json.get(el, []) + if len(states) == 1: + assignment[el] = states[0] + else: + return None + return assignment + +# ── load_structure (v4) ────────────────────────────────────────────────────── +# +# KEY CHANGE from v3: pymatgen's native per-site oxidation state assignment +# is now the FIRST choice after user override. ICSD CIFs embed oxidation +# states in the _atom_site_type_symbol column (e.g., Mn3+, Mn4+), and +# pymatgen correctly assigns these per-site, preserving: +# - Non-integer states (Pr3.8+ for mixed-valence) +# - Different states on different sites (Mn3+ on site 1, Mn4+ on site 2) +# - Charge neutrality +# +# The previous approach read element-level values from _atom_type_oxidation_number, +# which collapsed mixed-valence to a single state per element and broke charge +# balance for ~35% of structures. That is now a fallback, not the default. + +def _parse_structures(parser): + """ + Structures from a CifParser, in the PRIMITIVE cell. + + v1.3: this was `parser.get_structures()`, whose primitive=True default is + deprecated. MaplePy has always worked in the primitive cell; nothing said + so, and `parse_structures()` defaults the other way, so a mechanical + rename at some future pymatgen release would have changed the cell + without changing a line of intent. + + The choice is not load-bearing for the numbers, which is worth recording. + Measured on the same CIFs both ways: + + pyrochlore ICSD 109080 primitive 22 sites Z 2 MAPLE 10173.38 + conventional 88 sites Z 8 MAPLE 10173.38 + d_ref 1.9298 and MF 8.4463 in both + + perovskite ICSD 109352 identical either way: 20 sites, Z 4, + MAPLE 3914.11, d_ref 1.9855, MF 3.9007 + + MAPLE per formula unit, d_ref and the Madelung factor are invariant; the + cell and Z change together. What is NOT invariant is anything that counts + sites - the per-site table gains 66 rows per pyrochlore in the + conventional cell - so the cell is pinned rather than left to a default. + """ + if hasattr(parser, 'parse_structures'): + return parser.parse_structures(primitive=True) + return parser.get_structures() + + +def _has_native_oxi_states(structure): + """ + Check whether pymatgen assigned oxidation states when parsing the CIF. + Returns True if all sites contain Species (not bare Element) objects. + """ + from pymatgen.core.periodic_table import Species + for site in structure: + for sp in site.species: + if not isinstance(sp, Species): + return False + return True + + +def _native_charge_balance(structure): + """ + Compute the total charge using pymatgen's native per-site assignments. + Handles mixed-occupancy sites correctly via occupancy weighting. + """ + total = 0.0 + for site in structure: + for sp, occ in site.species.items(): + if hasattr(sp, 'oxi_state'): + total += sp.oxi_state * occ + return total + + +def load_structure(cif_path, oxidation_states=None, data_dir=None): + """ + Load a CIF and decorate with oxidation states. + + Mixed-occupancy sites are handled via mean-field charge averaging + in the downstream compute_maple() function. + + Priority chain for oxidation state assignment: + 1. User-supplied oxidation_states dict (highest priority) + 2. pymatgen native per-site assignment from CIF (preserves mixed valence, + non-integer states, and per-site distinctions) + 3. _atom_type_oxidation_number loop in the CIF (element-level fallback) + 4. maple_library.json formula override (unambiguous binaries) + 5. common_oxidation_states.json fallback (single-state elements) + 6. Raises ValueError with a helpful message (never silently zeros) + + Parameters + ---------- + cif_path : str or Path + oxidation_states: dict, optional e.g. {'Na': 1, 'Cl': -1} + data_dir : str path to folder containing maple_library.json + and common_oxidation_states.json + + Returns + ------- + pymatgen Structure with oxidation states applied. + """ + cif_path = str(cif_path) + + # v1.2: None means "wherever the data actually is"; an explicit path that + # does not exist is a mistake rather than a reason to fall back silently. + if data_dir is None: + data_dir = DEFAULT_DATA_DIR + elif not Path(data_dir).is_dir(): + raise ValueError(f'data_dir does not exist: {data_dir}') + + # ── Load CIF, catching unrecognised element labels ──────────────────── + try: + from pymatgen.io.cif import CifParser + parser = CifParser(cif_path, occupancy_tolerance=OCCUPANCY_TOL) + structures = _parse_structures(parser) + if not structures: + raise ValueError("No valid structures parsed from CIF.") + structure = structures[0] + except Exception as e: + if "not a valid Element" in str(e): + raise ValueError( + f"Unrecognised element label in CIF: {e}. " + f"Common causes: D (deuterium) in neutron data, " + f"or generic labels (M, X) for disordered sites." + ) from e + raise + + source = None + disordered = _is_disordered(structure) + + if disordered: + _kind, _where = _disorder_detail(structure) + print(f" Note: {_kind}" + f"{'' if _where == 'none' else f' on the {_where} sublattice'}" + f" detected. Using mean-field charge approximation.") + + # ── Check for unphysical occupancies ────────────────────────────────── + for site in structure: + occ_sum = sum(site.species.values()) + if occ_sum > OCCUPANCY_TOL: + print(f" WARNING: site occupancy sum = {occ_sum:.3f} " + f"(>1.0) at {site.species}. " + f"Refinement quality issue.") + + # ── Priority 1: user override ───────────────────────────────────────── + if oxidation_states is not None: + structure.add_oxidation_state_by_element(oxidation_states) + source = 'user' + + # ── Priority 2: pymatgen native per-site assignment ─────────────────── + elif _has_native_oxi_states(structure): + # pymatgen already assigned Species with oxi_states from the CIF. + # Check charge balance to confirm they are sensible. + native_q = _native_charge_balance(structure) + if abs(native_q) < CHARGE_NEUTRAL_TOL: + source = 'CIF (per-site, charge-neutral)' + else: + # Native states exist but are not charge-neutral. + # This happens for genuinely non-stoichiometric compounds. + # Still use them — they are the best available assignment. + source = (f'CIF (per-site, Σq={native_q:+.2f})') + # No action needed: structure already has the correct states. + + else: + # ── pymatgen did not assign oxi states — fall back ──────────────── + # Extract element set + elements = set() + for site in structure: + for sp in site.species: + el = (sp.element.symbol if hasattr(sp, 'element') + else sp.symbol) + elements.add(el) + + # ── Priority 3: CIF _atom_type loop (element-level) ────────────── + cif_oxi = _extract_cif_oxidation_states(cif_path) + + if (cif_oxi + and all(el in cif_oxi for el in elements) + and any(v != 0 for v in cif_oxi.values())): + structure.add_oxidation_state_by_element(cif_oxi) + source = 'CIF (_atom_type, element-level fallback)' + + else: + # ── Priority 4: maple_library.json ──────────────────────────── + library = _load_maple_library(data_dir) + reduced = structure.composition.reduced_formula + lib_oxi = _oxi_from_library(elements, reduced, library) + + if lib_oxi is not None: + structure.add_oxidation_state_by_element(lib_oxi) + source = f'maple_library.json ({reduced})' + + else: + # ── Priority 5: common_oxidation_states.json ────────────── + oxi_json = _load_oxi_json( + Path(data_dir) / 'common_oxidation_states.json' + ) + json_oxi = _oxi_from_json_fallback(elements, oxi_json) + + if json_oxi is not None: + structure.add_oxidation_state_by_element(json_oxi) + source = 'common_oxidation_states.json' + + # ── Priority 6: informative failure ─────────────────────── + else: + missing = [el for el in elements + if el not in (cif_oxi or {})] + multi = [el for el in elements + if len(oxi_json.get(el, [])) > 1] + raise ValueError( + f"Could not determine oxidation states for: " + f"{missing + multi}.\n" + f" CIF embedded states found for: " + f"{sorted(cif_oxi.keys()) if cif_oxi else 'none'}.\n" + f" Elements with multiple common states: " + f"{multi}.\n" + f" Reduced formula '{reduced}' not found in " + f"maple_library.json.\n" + f" Solution: pass oxidation_states={{...}} " + f"explicitly, e.g.:\n" + f" load_structure(path, oxidation_states=" + f"{{'Mo': 6, 'O': -2}})" + ) + + # ── Charge-balance check ────────────────────────────────────────────── + total_charge = _native_charge_balance(structure) + if abs(total_charge) > CHARGE_NEUTRAL_TOL: + print(f" WARNING: not charge-neutral " + f"(Σq = {total_charge:+.3f} e).\n" + f" Source: {source}. Check oxidation states before " + f"using MAPLE results.") + else: + # Build display of oxi states per element + oxi_display = {} + for s in structure: + el = _site_element(s) + oxi = _site_oxi_state(s) + if el in oxi_display: + # Multiple sites with different oxi states — show range + if isinstance(oxi_display[el], list): + if oxi not in oxi_display[el]: + oxi_display[el].append(oxi) + else: + if oxi != oxi_display[el]: + oxi_display[el] = [oxi_display[el], oxi] + else: + oxi_display[el] = oxi + + parts = [] + for el in sorted(oxi_display.keys()): + v = oxi_display[el] + if isinstance(v, list): + vals = '/'.join(f"{x:+.1f}" if x != int(x) + else f"{int(x):+d}" for x in sorted(v)) + parts.append(f"{el}={vals}") + else: + if v != int(v): + parts.append(f"{el}={v:+.2f}") + else: + parts.append(f"{el}={int(v):+d}") + + print(f" Oxidation states ({source}): " + ", ".join(parts)) + + return structure + + +# ── _find_d_ref ────────────────────────────────────────────────────────────── + +def _find_d_ref(structure): + """ + Shortest cation-anion distance in the structure. + + This is Hoppe's reference distance d₁ (or d_KA) — the normalisation + distance on which the Madelung constant and MAPLE are based. + """ + cat_idx = [i for i, s in enumerate(structure) + if _site_oxi_state(s) > 0] + ani_idx = [i for i, s in enumerate(structure) + if _site_oxi_state(s) < 0] + + if not cat_idx or not ani_idx: + # v1.1: this used to return min(distance from site 0 to anything), + # which is not a cation-anion distance and may be anion-anion. d_ref + # normalises the Madelung factor, so a wrong one is not a small error + # in a diagnostic - it is a different quantity wearing the same name. + raise ValueError( + 'cannot determine d_ref: the structure has ' + f'{len(cat_idx)} site(s) with positive charge and ' + f'{len(ani_idx)} with negative. Check the oxidation states.') + + d_min = np.inf + for ci in cat_idx: + for ai in ani_idx: + d = structure.get_distance(ci, ai) + if d < d_min: + d_min = d + return float(d_min) + + +# ── SG 62 origin-choice correction ─────────────────────────────────────── + +# ── The SG-62 origin correction, removed at v1.3.6 ───────────────────────── +# +# There was a function here, `_fix_sg62_origin`, which built a second +# structure with the 8d oxygen sublattice shifted by (1/2, 1/2, 0), computed +# the Ewald energy of both, and kept whichever was more negative. It is gone, +# and this is the record of why, because a deleted function leaves no trace +# to argue with. +# +# Measured across all 938 perovskites before removing it: +# +# corrected 44 4.7% of the family, MAPLE moved by up to 8.1% +# tested and kept 882 +# not applicable 11 +# declined 1 +# pyrochlores 0 it never fired on Fd-3m +# +# and on the eleven corrections examined in detail: +# +# - both candidates are Pnma, with different interatomic distances and +# energies 0.3 to 8.1% apart. They are two different structures, not two +# descriptions of one, so this was a structural edit and not a setting fix +# - the shortest interatomic contact is IDENTICAL in ten of the eleven, and +# in ICSD 33482 the shift makes it WORSE, 1.658 A -> 1.462 A, and was +# applied anyway because the energy was lower. A repair that never +# improves the geometry is not repairing the geometry +# - it fired on LaCrO3 220506, whose shortest contact is 1.008 A, and on +# LuCrO3 138227, one of the RCrO3 series whose real fault is the B cation +# deposited on 4a: adjusting broken coordinates rather than reporting them +# - and on TbCrO3 85235, a sound structure agreeing with an independent 2023 +# refinement and additive at 0.056%, whose MAPLE it moved by 2.8% +# +# The selection rule was the Ewald energy, which is the quantity this study +# measures, applied to structures this study is judging. +# +# NOTHING GENERAL REPLACES IT, because there is nothing mis-expanded to +# repair: the deposited structure is the deposited structure. What does the +# work instead is v1.3.3's geometry reporting - d_min_ang, geometry_flag, +# SPLIT_SITE_ANG and SHORT_CONTACT_ANG - and Hopper's codes 2.5 and 2.7. A +# structure that cannot carry a Madelung energy is now reported as such +# rather than quietly improved. +# +# If a repair is ever wanted again, the rule to meet is the one this failed: +# apply it only where the deposited structure FAILS the geometry test and the +# candidate PASSES it. On this dataset that fires on none of the 44. + + +def _derive_Z(structure): + """ + Formula units per cell, from the site counts rather than the composition. + + v1.1. `composition.get_reduced_composition_and_factor()` cannot factor a + NON-STOICHIOMETRIC composition, so it returns Z = 1 and every per-formula + -unit quantity is inflated by the true Z. Over the 1410-structure + perovskite and pyrochlore dataset: + + Z = 1 entries 172 (12.2%) + of those, with a fractional subscript 165 (96%) + Z > 1 entries with a fractional subscript 0 (0%) + + Gd4Cr3.984O12 is not a metadata error; it is a refinement with a partly + occupied Cr site, and it has four formula units in its cell like every + other GdFeO3-type perovskite. + + Z is crystallographic, so take it from the crystallography. The number of + SITES containing each element is an integer whatever the occupancies are, + and Z divides all of them, so Z is their greatest common divisor. No + composition arithmetic, no rounding of occupancies, no structure-type + knowledge. + + Verified on 103 ICSD CIFs: identical to composition reduction on all 95 + where reduction works, and 4 rather than 1 on all 8 where it does not - + every one a 20-site perovskite. No disagreement in the other direction. + + Falls back to the composition factor only when the structure has no sites + to count, which cannot happen for a parsed CIF but is not worth an + exception. + """ + counts = {} + for site in structure: + for sp in site.species: + el = sp.element.symbol if hasattr(sp, 'element') else sp.symbol + counts[el] = counts.get(el, 0) + 1 + if not counts: + _, z_float = structure.composition.get_reduced_composition_and_factor() + return max(1, int(round(z_float))) + z = 0 + for n in counts.values(): + z = _math.gcd(z, int(n)) + return max(1, z) + + +# ── compute_maple ──────────────────────────────────────────────────────────── + +def compute_maple(structure, verbose=True): + """ + Compute partial MAPLE values for all sites in the structure. + + Uses pymatgen's EwaldSummation for the electrostatic energy. + Per-site contributions are the row sums of the energy matrix, + which sum to the total Ewald energy without double-counting. + + For mixed-occupancy sites, the occupancy-weighted mean charge is used. + + Sign convention + --------------- + pymatgen energies are negative (bound state). + MAPLE is reported positive, following Hoppe's convention. + + Parameters + ---------- + structure : pymatgen Structure with oxidation states + verbose : bool + + Returns + ------- + dict with keys: + total_maple_kcal, per_site, Z, d_ref, madelung_factor, + disordered, structure + """ + disorder_kind, partial_sublattice = _disorder_detail(structure) + disordered = disorder_kind != 'ordered' + + + # ── SG 62 origin-choice correction ──────────────────────────────────── + # ── Ewald summation ─────────────────────────────────────────────────── + # v1.3.6: on the structure as deposited. The origin correction that used + # to run first, and hand its summation down, is gone; see the record + # above. + ewald = EwaldSummation(structure) + energy_matrix = ewald.total_energy_matrix + per_site_eV = energy_matrix.sum(axis=1) + + # ── Formula units per cell (Z) ──────────────────────────────────────── + Z = _derive_Z(structure) + + # ── Conversion: eV/site → kcal/mol/site ────────────────────────────── + per_site_maple = np.abs(per_site_eV) * EV_TO_KCAL_MOL + + # ── Total MAPLE per formula unit ────────────────────────────────────── + total_maple_kcal = np.abs(ewald.total_energy) * EV_TO_KCAL_MOL / Z + + # ── Reference distance ──────────────────────────────────────────────── + d_ref = _find_d_ref(structure) + + # ── Geometry ────────────────────────────────────────────────────────── + # v1.3.2: measured, reported, and never used to drop anything. + d_min, geometry_flag, geometry_status = _geometry_status(structure) + + # ── Per-site data ───────────────────────────────────────────────────── + per_site_data = [] + for i, site in enumerate(structure): + oxi = _site_oxi_state(site) + maple_i = float(per_site_maple[i]) + + pmc = (maple_i * d_ref / (MAPLE_FACTOR * abs(oxi)) + ) if oxi != 0 else None + + reduced = (maple_i / (oxi ** 2) / d_ref + ) if oxi != 0 else None + + per_site_data.append({ + "site_index" : i, + "element" : _site_element(site), + "oxidation_state" : round(oxi, 4), + "mixed_site" : len(site.species) > 1, + "frac_x" : round(float(site.frac_coords[0]), 6), + "frac_y" : round(float(site.frac_coords[1]), 6), + "frac_z" : round(float(site.frac_coords[2]), 6), + "maple_kcal_mol" : round(maple_i, 3), + "pmc" : round(pmc, 5) if pmc is not None else None, + "reduced_maple" : round(reduced, 4) if reduced is not None else None, + }) + + # ── Madelung factor ─────────────────────────────────────────────────── + # + # v1.1: THE CONVENTION, WRITTEN DOWN. The mean charges below are means + # over SITES, not over stoichiometry and not weighted by multiplicity. + # For ABO3 with two trivalent cations the two agree; for a 2+/4+ + # perovskite the site mean is 3, and for the pyrochlore 16d/16c/48f/8b + # counts it is a different average again. Nothing here is changed, + # because the classification and every published figure rest on this + # definition - but it is a choice, it was undocumented, and it scales the + # axis on which the Z = 1 population was identified. It should be checked + # against Hoppe's own normalisation before any future version moves it. + try: + oxi_states = [_site_oxi_state(s) for s in structure] + z_pos = [z for z in oxi_states if z > 0] + z_neg = [z for z in oxi_states if z < 0] + if not z_pos or not z_neg: + madelung_factor = None + else: + mean_zp = np.mean(z_pos) + mean_zn = abs(np.mean(z_neg)) + madelung_factor = (total_maple_kcal * d_ref + / (MAPLE_FACTOR * mean_zp * mean_zn)) + except (TypeError, ValueError, ZeroDivisionError, AttributeError): + madelung_factor = None + + result = { + "total_maple_kcal" : round(total_maple_kcal, 2), + "per_site" : per_site_data, + "Z" : Z, + "d_ref" : round(d_ref, 4), + "madelung_factor" : (round(madelung_factor, 4) + if madelung_factor is not None else None), + "disordered" : disordered, + "disorder_status" : disorder_kind, + "partial_sublattice": partial_sublattice, + "d_min_ang" : round(d_min, 4), + "geometry_flag" : geometry_flag, + "geometry_status" : geometry_status, + "structure" : structure, + } + + if verbose: + comp = structure.composition.reduced_formula + sg = structure.get_space_group_info()[0] + _where = ('' if partial_sublattice in ('none', None) + else f' ({partial_sublattice})') + tag = (f" [MEAN-FIELD: {disorder_kind}{_where}]" + if disordered else "") + print(f"\n{'─'*60}") + print(f" Compound : {comp} ({sg}){tag}") + print(f" Sites : {len(structure)} | Z = {Z}") + print(f" d_ref : {d_ref:.4f} Å") + print(f" Geometry : {geometry_status}") + mf_str = f"{madelung_factor:.4f}" if madelung_factor is not None else "n/a" + print(f" MF : {mf_str}") + print(f" MAPLE : {total_maple_kcal:.1f} kcal/mol " + f"({total_maple_kcal * KCAL_TO_KJ:.1f} kJ/mol)") + print(f"{'─'*60}") + + return result + + +# ── results_to_dataframe ───────────────────────────────────────────────────── + +def results_to_dataframe(maple_result): + """Convert compute_maple() output to a tidy pandas DataFrame.""" + df = pd.DataFrame(maple_result["per_site"]) + + comp = maple_result["structure"].composition.reduced_formula + sg = maple_result["structure"].get_space_group_info()[0] + df["compound"] = comp + df["space_group"] = sg + df["Z"] = maple_result["Z"] + df["d_ref_ang"] = maple_result["d_ref"] + df["madelung_factor"] = maple_result["madelung_factor"] + df["total_maple"] = maple_result["total_maple_kcal"] + df["disordered"] = maple_result["disordered"] + df["disorder_status"] = maple_result.get("disorder_status") + df["partial_sublattice"] = maple_result.get("partial_sublattice") + df["d_min_ang"] = maple_result.get("d_min_ang") + df["geometry_flag"] = maple_result.get("geometry_flag") + df["geometry_status"] = maple_result.get("geometry_status") + + cols = ["compound", "space_group", "Z", "d_ref_ang", "madelung_factor", + "total_maple", "disordered", "disorder_status", + "partial_sublattice", "d_min_ang", "geometry_flag", + "geometry_status", "site_index", "element", + "oxidation_state", "mixed_site", + "frac_x", "frac_y", "frac_z", + "maple_kcal_mol", "pmc", "reduced_maple"] + return df[cols] \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/e22_additivity_checker.py b/src/maplepy/_cells/maplepy/e22_additivity_checker.py new file mode 100644 index 0000000..65a8f3b --- /dev/null +++ b/src/maplepy/_cells/maplepy/e22_additivity_checker.py @@ -0,0 +1,39 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 22. +# Edit the notebook, not this file, then rebuild. + +def check_additivity(polynary_result, binary_results_and_coeffs, verbose=True): + """ + Check Hoppe's additivity theorem: MAPLE(polynary) ≈ Σ coeff_i × MAPLE(binary_i) + + Parameters + ---------- + polynary_result : dict from compute_maple() + binary_results_and_coeffs : list of (result_dict, float) tuples + e.g. [(result_bao, 1), (result_tio2, 1)] for BaTiO₃ = BaO + TiO₂ + + Returns + ------- + dict with keys: maple_polynary, maple_binary_sum, delta_abs, delta_pct + """ + maple_poly = polynary_result["total_maple_kcal"] + maple_sum = sum(c * r["total_maple_kcal"] for r, c in binary_results_and_coeffs) + + delta_abs = abs(maple_poly - maple_sum) + delta_pct = 100 * delta_abs / maple_poly if maple_poly else 0 + + if verbose: + comp = polynary_result["structure"].composition.reduced_formula + print(f"Additivity: {comp}") + for r, c in binary_results_and_coeffs: + bc = r["structure"].composition.reduced_formula + print(f" {c:+.0f} × MAPLE({bc}) = {c * r['total_maple_kcal']:.1f} kcal/mol") + print(f" Binary sum = {maple_sum:.1f} kcal/mol") + print(f" Polynary = {maple_poly:.1f} kcal/mol") + print(f" |Δ| = {delta_abs:.1f} kcal/mol = {delta_pct:.3f}%") + status = ("✓ GOOD (<1%)" if delta_pct < 1.0 else + "⚠ MARGINAL (1–2%)" if delta_pct < 2.0 else + "✗ POOR (>2%)") + print(f" Additivity : {status}") + + return {"maple_polynary": maple_poly, "maple_binary_sum": maple_sum, + "delta_abs": delta_abs, "delta_pct": delta_pct} \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/e25_batch_processing.py b/src/maplepy/_cells/maplepy/e25_batch_processing.py new file mode 100644 index 0000000..a838383 --- /dev/null +++ b/src/maplepy/_cells/maplepy/e25_batch_processing.py @@ -0,0 +1,256 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 25. +# Edit the notebook, not this file, then rebuild. + +# 5. Batch Processing (v3) +# ───────────────────────────────────────────────────────────────────────────── + +# ── Where the last run went ──────────────────────────────────────────────── +# +# v1.3.1: Section 8 used to carry a hard-coded path to somebody's Downloads +# folder, and a run and the plots of that run were connected only by the +# reader retyping it. Both entry points record where they wrote. +LAST_OUTPUT_DIR = None # Path, set by batch_maple() and launch_maple_gui() + +# The per-structure summary, one definition. Section 8 and Hopper both open +# maple_summary.csv and read these names. +SUMMARY_COLS = ["compound", "space_group", "Z", "d_ref_ang", + "madelung_factor", "total_maple", "disordered", + "disorder_status", "partial_sublattice", "d_min_ang", + "geometry_flag", "geometry_status", + "source_cif", "maplepy_version"] + + +def _write_outputs(dfs, failed, output_dir): + """ + Write the three CSVs a MAPLE run produces, and record where they went. + + v1.3.1: batch_maple() wrote maple_results.csv and maple_failed.csv but not + maple_summary.csv, while the GUI wrote all three. Section 8 and Hopper + both look for the summary first, so a batch run could not be plotted or + decomposed and nothing said why. Written in one place now, so the two + entry points cannot drift again. + + Returns (master, summary); both empty frames if nothing was processed. + """ + global LAST_OUTPUT_DIR + + output_dir = Path(output_dir) + output_dir.mkdir(parents=True, exist_ok=True) + + if dfs: + master = pd.concat(dfs, ignore_index=True) + master["maplepy_version"] = MAPLEPY_VERSION + results_csv = output_dir / 'maple_results.csv' + master.to_csv(results_csv, index=False) + print(f"\nSaved {len(master)} rows → {results_csv}") + + summary = (master[SUMMARY_COLS] + .drop_duplicates(subset="source_cif") + .reset_index(drop=True)) + summary_csv = output_dir / 'maple_summary.csv' + summary.to_csv(summary_csv, index=False) + print(f"Saved {len(summary)} structures → {summary_csv}") + else: + master = pd.DataFrame() + summary = pd.DataFrame() + print("\nNo structures processed successfully.") + + if failed: + failed_df = pd.DataFrame(failed, columns=['cif_file', 'error']) + failed_csv = output_dir / 'maple_failed.csv' + failed_df.to_csv(failed_csv, index=False) + print(f"Saved {len(failed)} failures → {failed_csv}") + + LAST_OUTPUT_DIR = output_dir + return master, summary + + +def process_one_cif(cif_path, oxidation_states=None, data_dir=None, + verbose=False): + """ + Load, compute and tabulate ONE CIF. The one definition. + + v1.3.4: batch_maple and the GUI each had their own copy of this sequence, + which is two things to keep in step and two things to put in a worker. + Returns only picklable data, so it can run in another process: + + (name, df or None, error or None, tag, console output) + + `tag` is the mean-field marker for the progress line, so the caller can + print without reaching back into the result. + """ + import contextlib as _ctx + import io as _io + from pathlib import Path as _P + + name = _P(cif_path).name + # v1.3.4: the console output is CAPTURED and handed back, not left to + # wherever this happens to run. load_structure prints which source the + # oxidation states came from, unconditionally, and that line is the only + # record of the provenance anywhere - it is in no CSV. A worker process + # writes it to a pipe nobody reads, so a parallel run would have quietly + # stopped telling you. Captured here, printed by the caller, identical + # either way. + _said = _io.StringIO() + try: + with _ctx.redirect_stdout(_said): + s = load_structure(cif_path, oxidation_states=oxidation_states, + data_dir=data_dir) + result = compute_maple(s, verbose=verbose) + df = results_to_dataframe(result) + df["source_cif"] = name + return (name, df, None, (" [MF]" if result["disordered"] else ""), + _said.getvalue()) + except Exception as e: + return name, None, str(e), "", _said.getvalue() + + +def _resolve_workers(workers, n_items): + """How many processes to actually start. Never more than there is work.""" + if workers in (None, 1, 0): + return 1 + if workers == 'auto': + try: + import os as _os + workers = max(1, (_os.cpu_count() or 2) - 2) + except Exception: + return 1 + try: + workers = int(workers) + except (TypeError, ValueError): + print(f" MAPLE_WORKERS = {workers!r} is not a number or 'auto'; " + f"running serially.") + return 1 + return max(1, min(workers, n_items)) + + +def _map_cifs(paths, oxidation_states_map, data_dir, verbose, workers): + """ + process_one_cif over every path, in order, serially or in a pool. + + v1.3.4: the only place that decides between the two, and both branches + call the same function. A pool that will not start is reported in full + and the run continues serially - an optimisation with an exact serial + equivalent should never be the thing that stops the science. + """ + from pathlib import Path as _P + n = _resolve_workers(workers, len(paths)) + jobs = [(p, (oxidation_states_map or {}).get(_P(p).stem)) for p in paths] + + if n > 1: + try: + from joblib import Parallel, delayed + except ImportError as e: + print(f" joblib is not installed ({e}), so MAPLE_WORKERS " + f"cannot be honoured. Running serially. `pip install " + f"joblib` for the parallel path.") + n = 1 + if n > 1: + print(f" processing on {n} workers") + try: + try: + # joblib >= 1.3 streams results in order, so progress is + # visible during the run rather than only at the end + out = Parallel(n_jobs=n, backend='loky', + return_as='generator')( + delayed(process_one_cif)(p, oxi, data_dir, False) + for p, oxi in jobs) + except TypeError: + out = Parallel(n_jobs=n, backend='loky')( + delayed(process_one_cif)(p, oxi, data_dir, False) + for p, oxi in jobs) + for item in out: + yield item + return + except Exception as e: + print(f" the worker pool failed to run ({type(e).__name__}: " + f"{e}). Falling back to serial processing; the results are " + f"the same either way, only slower.") + + for p, oxi in jobs: + yield process_one_cif(p, oxi, data_dir, verbose) + + +def batch_maple(cif_dir, output_dir=None, oxidation_states_map=None, + data_dir=None, verbose=False, workers=None): + """ + Process all CIFs in a directory. + + Parameters + ---------- + cif_dir : str or Path + Directory containing CIF files. + output_dir : str or Path, optional + Directory for output CSVs. If None, creates a timestamped + outputs_YYYYMMDD_HHMMSS folder inside cif_dir. + oxidation_states_map : dict {filename_stem: {element: oxi_state}} + For CIFs without embedded oxidation states. + data_dir : str or None + Folder holding maple_library.json and common_oxidation_states.json. + None (v1.3.1) means DEFAULT_DATA_DIR, resolved at load. It used to be + '.', which was passed on explicitly and so overrode that resolution: + every batch run silently lost two levels of the oxidation-state + priority chain. + verbose : bool + If True, print full MAPLE output per structure. + + Returns + ------- + pd.DataFrame, one row per site per structure + """ + cif_dir = Path(cif_dir) + cif_files = sorted(cif_dir.glob("*.cif")) + if not cif_files: + print(f"No CIF files found in {cif_dir}") + return pd.DataFrame() + + # ── Create output directory ─────────────────────────────────────────── + if output_dir is None: + from datetime import datetime + timestamp = datetime.now().strftime('%Y%m%d_%H%M%S') + output_dir = cif_dir / f'outputs_{timestamp}' + output_dir = Path(output_dir) + output_dir.mkdir(parents=True, exist_ok=True) + + print(f"Processing {len(cif_files)} CIFs in {cif_dir}") + print(f"Output directory: {output_dir}") + dfs, failed = [], [] + + # v1.3.4: one worker function, run serially or on a pool by _map_cifs. + for name, df_i, err, tag, said in _map_cifs( + [str(p) for p in cif_files], oxidation_states_map, data_dir, + verbose, MAPLE_WORKERS if workers is None else workers): + if said: + print(said, end='') + if err is not None: + failed.append((name, err)) + print(f" ✗ {name:45s} {err}") + continue + dfs.append(df_i) + print(f" ✓ {name:45s} " + f"MAPLE = {df_i['total_maple'].iloc[0]:.1f} kcal/mol{tag}") + + # ── Save results ────────────────────────────────────────────────────── + master, _summary = _write_outputs(dfs, failed, output_dir) + + # ── Summary ─────────────────────────────────────────────────────────── + n_total = len(cif_files) + n_ok = len(dfs) + n_fail = len(failed) + n_ordered = sum(1 for d in dfs + if not d["disordered"].iloc[0]) if dfs else 0 + n_disordered = n_ok - n_ordered + + print(f"\n{'='*60}") + print(f" Total CIFs : {n_total}") + print(f" Processed (OK) : {n_ok} " + f"({n_ordered} ordered, {n_disordered} mean-field)") + print(f" Failed : {n_fail}") + print(f"{'='*60}") + + return master + + +# Usage: +# df = batch_maple(Path("/path/to/cifs")) +# df = batch_maple(Path("/path/to/cifs"), output_dir=Path("/custom/output")) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k09_nacl.py b/src/maplepy/_cells/maplepy/k09_nacl.py new file mode 100644 index 0000000..6112f2a --- /dev/null +++ b/src/maplepy/_cells/maplepy/k09_nacl.py @@ -0,0 +1,15 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 9. +# Edit the notebook, not this file, then rebuild. + +# NaCl: Fm-3m, a = 5.6402 Å (experimental ambient, ICSD) +nacl = Structure.from_spacegroup( + "Fm-3m", + Lattice.cubic(5.6402), + ["Na", "Cl"], + [[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]] +) +nacl.add_oxidation_state_by_element({"Na": 1, "Cl": -1}) + +result_nacl = compute_maple(nacl) +df_nacl = results_to_dataframe(result_nacl) +print(df_nacl[["element","oxidation_state","maple_kcal_mol","pmc","reduced_maple"]].to_string(index=False)) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k10_nacl_checks.py b/src/maplepy/_cells/maplepy/k10_nacl_checks.py new file mode 100644 index 0000000..ae029d3 --- /dev/null +++ b/src/maplepy/_cells/maplepy/k10_nacl_checks.py @@ -0,0 +1,29 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 10. +# Edit the notebook, not this file, then rebuild. + +# ── Validation checks ────────────────────────────────────────────────────────── +pmc_na = df_nacl[df_nacl["element"] == "Na"]["pmc"].mean() +pmc_cl = df_nacl[df_nacl["element"] == "Cl"]["pmc"].mean() +mf = result_nacl["madelung_factor"] + +TARGET_PMC = 0.8738 +TARGET_MF = 1.7476 +TOL = 0.005 # 0.5% + +print("── NaCl Validation ───────────────────────────────────────────────────────") +print(f" PMC(Na⁺) = {pmc_na:.4f} target {TARGET_PMC} Δ = {abs(pmc_na-TARGET_PMC):.4f}") +print(f" PMC(Cl⁻) = {pmc_cl:.4f} target {TARGET_PMC} Δ = {abs(pmc_cl-TARGET_PMC):.4f}") +print(f" MF (total) = {mf:.4f} target {TARGET_MF} Δ = {abs(mf-TARGET_MF):.4f}") +print(f" Symmetry |PMC_Na - PMC_Cl| = {abs(pmc_na-pmc_cl):.2e} (must be ~0)") + +pass_na = abs(pmc_na - TARGET_PMC) < TOL +pass_cl = abs(pmc_cl - TARGET_PMC) < TOL +pass_mf = abs(mf - TARGET_MF) < TOL +pass_sym = abs(pmc_na - pmc_cl) < 1e-4 + +overall = all([pass_na, pass_cl, pass_mf, pass_sym]) +print(f"\n PMC(Na) : {'✓ PASS' if pass_na else '✗ FAIL'}") +print(f" PMC(Cl) : {'✓ PASS' if pass_cl else '✗ FAIL'}") +print(f" MF : {'✓ PASS' if pass_mf else '✗ FAIL'}") +print(f" Symmetry: {'✓ PASS' if pass_sym else '✗ FAIL'}") +print(f"\n {'✅ NaCl VALIDATION PASSED' if overall else '❌ NaCl VALIDATION FAILED — check implementation'}") \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k12_tio2_structures.py b/src/maplepy/_cells/maplepy/k12_tio2_structures.py new file mode 100644 index 0000000..c7b8b98 --- /dev/null +++ b/src/maplepy/_cells/maplepy/k12_tio2_structures.py @@ -0,0 +1,25 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 12. +# Edit the notebook, not this file, then rebuild. + +# Rutile TiO₂: P4₂/mnm (No. 136), a = 4.5933 Å, c = 2.9592 Å +# Ti: 2a (0,0,0); O: 4f (u,u,0) with u = 0.3048 +rutile = Structure.from_spacegroup( + 136, + Lattice.tetragonal(4.5933, 2.9592), + ["Ti", "O"], + [[0.0, 0.0, 0.0], [0.3048, 0.3048, 0.0]] +) +rutile.add_oxidation_state_by_element({"Ti": 4, "O": -2}) + +# Anatase TiO₂: I4₁/amd (No. 141), a = 3.7845 Å, c = 9.5143 Å +# Ti: 4a; O: 8e (0,0,z) with z = 0.2082 +anatase = Structure.from_spacegroup( + 141, + Lattice.tetragonal(3.7845, 9.5143), + ["Ti", "O"], + [[0.0, 0.0, 0.0], [0.0, 0.0, 0.2082]] +) +anatase.add_oxidation_state_by_element({"Ti": 4, "O": -2}) + +print("Rutile :", rutile.composition, " | sites:", len(rutile)) +print("Anatase :", anatase.composition, " | sites:", len(anatase)) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k13_tio2.py b/src/maplepy/_cells/maplepy/k13_tio2.py new file mode 100644 index 0000000..eda7a66 --- /dev/null +++ b/src/maplepy/_cells/maplepy/k13_tio2.py @@ -0,0 +1,5 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 13. +# Edit the notebook, not this file, then rebuild. + +result_rutile = compute_maple(rutile, verbose=True) +result_anatase = compute_maple(anatase, verbose=True) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k14_tio2_checks.py b/src/maplepy/_cells/maplepy/k14_tio2_checks.py new file mode 100644 index 0000000..5bedbe3 --- /dev/null +++ b/src/maplepy/_cells/maplepy/k14_tio2_checks.py @@ -0,0 +1,23 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 14. +# Edit the notebook, not this file, then rebuild. + +maple_r = result_rutile["total_maple_kcal"] +maple_a = result_anatase["total_maple_kcal"] +delta = abs(maple_r - maple_a) + +print("── TiO₂ Validation ───────────────────────────────────────────────────────") +print(f" MAPLE(rutile) = {maple_r:.1f} kcal/mol (Hoppe: 3254.6)") +print(f" MAPLE(anatase) = {maple_a:.1f} kcal/mol (Hoppe: 3260.7)") +print(f" |Δ| rutile–anatase = {delta:.1f} kcal/mol") + +# Tolerances: 50 kcal/mol absolute (allows for slightly different CIF sources), +# and < 15 kcal/mol inter-polymorph (the near-degeneracy is the key result) +pass_r = abs(maple_r - 3254.6) < 50 +pass_a = abs(maple_a - 3260.7) < 50 +pass_diff = delta < 15 + +overall = all([pass_r, pass_a, pass_diff]) +print(f"\n Rutile vs Hoppe 3254.6 : {'✓ PASS' if pass_r else '✗ FAIL'} (Δ={abs(maple_r-3254.6):.1f})") +print(f" Anatase vs Hoppe 3260.7 : {'✓ PASS' if pass_a else '✗ FAIL'} (Δ={abs(maple_a-3260.7):.1f})") +print(f" Polymorphs within 15 kcal: {'✓ PASS' if pass_diff else '✗ FAIL'} (Δ={delta:.1f})") +print(f"\n {'✅ TiO₂ VALIDATION PASSED' if overall else '❌ TiO₂ VALIDATION FAILED'}") \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k16_batio3_structures.py b/src/maplepy/_cells/maplepy/k16_batio3_structures.py new file mode 100644 index 0000000..d1cf56b --- /dev/null +++ b/src/maplepy/_cells/maplepy/k16_batio3_structures.py @@ -0,0 +1,24 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 16. +# Edit the notebook, not this file, then rebuild. + +# BaO: Fm-3m (rock salt), a = 5.5391 Å +bao = Structure.from_spacegroup( + "Fm-3m", + Lattice.cubic(5.5391), + ["Ba", "O"], + [[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]] +) +bao.add_oxidation_state_by_element({"Ba": 2, "O": -2}) + +# Cubic BaTiO₃: Pm-3m (No. 221), a = 4.0019 Å +# Ba: 1a (0,0,0) Ti: 1b (½,½,½) O: 3c (½,½,0) +batibo3 = Structure.from_spacegroup( + "Pm-3m", + Lattice.cubic(4.0019), + ["Ba", "Ti", "O"], + [[0.0, 0.0, 0.0], [0.5, 0.5, 0.5], [0.5, 0.5, 0.0]] +) +batibo3.add_oxidation_state_by_element({"Ba": 2, "Ti": 4, "O": -2}) + +print("BaO: ", bao.composition, "| sites:", len(bao)) +print("BaTiO₃: ", batibo3.composition, "| sites:", len(batibo3)) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k17_batio3.py b/src/maplepy/_cells/maplepy/k17_batio3.py new file mode 100644 index 0000000..ee52f7a --- /dev/null +++ b/src/maplepy/_cells/maplepy/k17_batio3.py @@ -0,0 +1,5 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 17. +# Edit the notebook, not this file, then rebuild. + +result_bao = compute_maple(bao, verbose=True) +result_batio3 = compute_maple(batibo3, verbose=True) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k18_batio3_checks.py b/src/maplepy/_cells/maplepy/k18_batio3_checks.py new file mode 100644 index 0000000..8151072 --- /dev/null +++ b/src/maplepy/_cells/maplepy/k18_batio3_checks.py @@ -0,0 +1,21 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 18. +# Edit the notebook, not this file, then rebuild. + +maple_bao = result_bao["total_maple_kcal"] +maple_tio2 = result_rutile["total_maple_kcal"] # from validation 2.2 +maple_batio3 = result_batio3["total_maple_kcal"] + +maple_sum = maple_bao + maple_tio2 +delta_abs = abs(maple_batio3 - maple_sum) +delta_pct = 100 * delta_abs / maple_batio3 + +print("── BaTiO₃ Additivity Validation ──────────────────────────────────────────") +print(f" MAPLE(BaO) = {maple_bao:.1f} kcal/mol") +print(f" MAPLE(TiO₂, rutile) = {maple_tio2:.1f} kcal/mol") +print(f" Binary sum = {maple_sum:.1f} kcal/mol (Hoppe: 4092)") +print(f" MAPLE(BaTiO₃, cubic) = {maple_batio3:.1f} kcal/mol (Hoppe: 4095)") +print(f" Residual |Δ| = {delta_abs:.1f} kcal/mol = {delta_pct:.3f}%") + +pass_add = delta_pct < 1.0 +print(f"\n Additivity < 1% : {'✓ PASS' if pass_add else '✗ FAIL'} ({delta_pct:.3f}%)") +print(f" {'✅ ADDITIVITY VALIDATION PASSED' if pass_add else '❌ ADDITIVITY VALIDATION FAILED'}") \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/k23_batio3_additivity_example.py b/src/maplepy/_cells/maplepy/k23_batio3_additivity_example.py new file mode 100644 index 0000000..73adca3 --- /dev/null +++ b/src/maplepy/_cells/maplepy/k23_batio3_additivity_example.py @@ -0,0 +1,5 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 23. +# Edit the notebook, not this file, then rebuild. + +# Example: BaTiO₃ using results already computed in validation +check_additivity(result_batio3, [(result_bao, 1), (result_rutile, 1)]) \ No newline at end of file diff --git a/src/maplepy/_cells/maplepy/r33_diagnostic_plots.py b/src/maplepy/_cells/maplepy/r33_diagnostic_plots.py new file mode 100644 index 0000000..6e433f7 --- /dev/null +++ b/src/maplepy/_cells/maplepy/r33_diagnostic_plots.py @@ -0,0 +1,292 @@ +# Generated by tools/build_engine.py from MaplePy.ipynb, cell 33. +# Edit the notebook, not this file, then rebuild. + +# 8. Diagnostic Plots +# ───────────────────────────────────────────────────────────────────────────── +# +# Run this cell AFTER a run: either the GUI (Section 7) or batch_maple() +# (Section 5). It reads maple_summary.csv, maple_results.csv and +# maple_failed.csv from that run and writes three PNGs beside them. +# +# Nothing to set. Both entry points record where they wrote in +# LAST_OUTPUT_DIR, and this cell reads it. To plot an OLDER run instead, put +# its CIF folder in CIF_DIR below. + +import matplotlib.pyplot as plt +import matplotlib.ticker as mticker +import numpy as np +import pandas as pd +from pathlib import Path + +# ── Which run to plot ───────────────────────────────────────────────────────── +# +# v1.3.1: this line used to be a literal path to another machine's Downloads +# folder, and the error it raised named the wrong cause - it reported that the +# folder held no outputs_* when the folder itself was not there. +# +# Leave CIF_DIR as None to plot the run made in this kernel. Set it to the +# folder holding your CIFs (the one containing outputs_* subdirectories), or +# to an outputs_* folder itself, to plot an earlier run. +CIF_DIR = None +# ────────────────────────────────────────────────────────────────────────────── + +if CIF_DIR: + cif_dir = Path(CIF_DIR) + if not cif_dir.is_dir(): + raise FileNotFoundError( + f"CIF_DIR is not a folder on this machine: {cif_dir}\n" + f"Set CIF_DIR to a folder that exists here, or set it to None to " + f"plot the run made in this kernel.") + runs = sorted(cif_dir.glob('outputs_*'), reverse=True) + if runs: + output_dir = runs[0] + elif (cif_dir / 'outputs').is_dir(): + output_dir = cif_dir / 'outputs' # a pre-timestamp run + elif (cif_dir / 'maple_summary.csv').exists(): + output_dir = cif_dir # CIF_DIR IS the outputs folder + else: + raise FileNotFoundError( + f"{cif_dir} exists but holds no run: no outputs_* folder, no " + f"outputs/ folder and no maple_summary.csv.\n" + f"Run Section 7 or batch_maple() first.") +elif globals().get('LAST_OUTPUT_DIR') is not None: + output_dir = Path(LAST_OUTPUT_DIR) +else: + raise RuntimeError( + "No run to plot. Either run the GUI (Section 7) or batch_maple() " + "(Section 5) in this kernel, or set CIF_DIR above to the folder " + "holding an earlier run's CIFs.") + +print(f"Plotting: {output_dir}") + +# ── Sheffield brand colours ─────────────────────────────────────────────────── +SHEFFIELD = { + 'brand_violet' : '#440099', + 'dark_violet' : '#24125E', + 'electric' : '#7000FF', + 'powder_violet': '#A78CFA', + 'pale_violet' : '#C8BBFF', + 'teal' : '#005A8F', + 'aqua' : '#00BBCC', + 'coral' : '#E7004C', + 'flamingo' : '#FF6371', + 'peach' : '#FF9664', + 'peak_green' : '#005750', + 'spearmint' : '#3BD4AE', + 'midnight' : '#131E29', +} + +# ── Global plot styling ─────────────────────────────────────────────────────── +plt.rcParams.update({ + 'font.family' : 'sans-serif', + 'font.size' : 11, + 'axes.labelsize' : 13, + 'axes.titlesize' : 14, + 'figure.dpi' : 150, + 'savefig.dpi' : 300, + 'savefig.bbox' : 'tight', + 'axes.linewidth' : 1.0, + 'xtick.direction' : 'in', + 'ytick.direction' : 'in', + 'xtick.major.width': 1.0, + 'ytick.major.width': 1.0, +}) + + +# ── Load data ───────────────────────────────────────────────────────────────── +summary_csv = output_dir / 'maple_summary.csv' +failed_csv = output_dir / 'maple_failed.csv' +results_csv = output_dir / 'maple_results.csv' + +if not summary_csv.exists(): + raise FileNotFoundError( + f"No maple_summary.csv found in {output_dir}.\n" + f"That folder is a run directory but the summary is missing: the run " + f"processed no structures, or it was made by MaplePy before v1.3.1, " + f"whose batch_maple() did not write one." + ) + +df_summary = pd.read_csv(summary_csv) +df_results = pd.read_csv(results_csv) if results_csv.exists() else None + +if failed_csv.exists(): + df_failed = pd.read_csv(failed_csv) +else: + df_failed = pd.DataFrame(columns=['cif_file', 'error']) + +n_ordered = (~df_summary['disordered']).sum() +n_disordered = df_summary['disordered'].sum() +n_failed = len(df_failed) +n_total = n_ordered + n_disordered + n_failed + +print(f"Loaded: {len(df_summary)} successful structures, " + f"{n_failed} failures, {n_total} total") + + +# ═════════════════════════════════════════════════════════════════════════════ +# PLOT 1: Success / Failure Overview +# ═════════════════════════════════════════════════════════════════════════════ + +fig1, ax1 = plt.subplots(figsize=(8, 4)) + +# Classify failures +if len(df_failed) > 0: + conditions = [ + df_failed['error'].str.contains('Mixed-occupancy', na=False), + df_failed['error'].str.contains('not a valid Element', na=False), + df_failed['error'].str.contains('Unrecognised element', na=False), + df_failed['error'].str.contains('Invalid cif', na=False), + df_failed['error'].str.contains('charge-neutral', na=False) + | df_failed['error'].str.contains('NoneType', na=False), + ] + labels_fail = ['Mixed occupancy', 'Invalid element (D, M, ...)', + 'Invalid CIF', 'Charge imbalance'] + + # Count each failure type + fail_counts = {} + accounted = pd.Series(False, index=df_failed.index) + for cond, label in zip(conditions, labels_fail): + mask = cond & ~accounted + fail_counts[label] = mask.sum() + accounted = accounted | cond + fail_counts['Other'] = (~accounted).sum() + # Remove zero-count categories + fail_counts = {k: v for k, v in fail_counts.items() if v > 0} +else: + fail_counts = {} + +# Build bar data +categories = [] +counts = [] +colours = [] + +categories.append('Ordered') +counts.append(int(n_ordered)) +colours.append(SHEFFIELD['brand_violet']) + +categories.append('Mean-field') +counts.append(int(n_disordered)) +colours.append(SHEFFIELD['powder_violet']) + +fail_colours = [SHEFFIELD['coral'], SHEFFIELD['peach'], + SHEFFIELD['flamingo'], SHEFFIELD['aqua'], + SHEFFIELD['spearmint']] +for i, (label, count) in enumerate(fail_counts.items()): + categories.append(label) + counts.append(count) + colours.append(fail_colours[i % len(fail_colours)]) + +bars = ax1.barh(categories, counts, color=colours, edgecolor='white', + linewidth=0.5) + +# Add count labels on bars +for bar, count in zip(bars, counts): + if count > 0: + ax1.text(bar.get_width() + max(sum(counts)*0.01, 0.5), + bar.get_y() + bar.get_height()/2, + str(count), va='center', ha='left', fontsize=10, + color=SHEFFIELD['midnight']) + +ax1.set_xlabel('Number of CIF files') +ax1.set_title('MaplePy Processing Results') +ax1.invert_yaxis() +ax1.spines['top'].set_visible(False) +ax1.spines['right'].set_visible(False) + +# Add percentage annotation +pct_ok = 100 * (n_ordered + n_disordered) / n_total if n_total > 0 else 0 +ax1.text(0.98, 0.02, f'{pct_ok:.1f}% processed successfully', + transform=ax1.transAxes, ha='right', va='bottom', + fontsize=10, color=SHEFFIELD['dark_violet'], style='italic') + +fig1.tight_layout() +fig1.savefig(output_dir / 'plot_1_processing_overview.png') +print(f"Saved: {output_dir / 'plot_1_processing_overview.png'}") +plt.show() + + +# ═════════════════════════════════════════════════════════════════════════════ +# PLOT 2: Total MAPLE vs formula complexity +# ═════════════════════════════════════════════════════════════════════════════ + +if df_results is not None and len(df_summary) > 1: + + # Count atoms per formula unit from site-level data + atoms_per_fu = (df_results.groupby('source_cif') + .apply(lambda g: len(g) / g['Z'].iloc[0], + include_groups=False) + .reset_index(name='atoms_per_fu')) + + df_plot = df_summary.merge(atoms_per_fu, on='source_cif', how='left') + + fig2, ax2 = plt.subplots(figsize=(7, 6)) + + # Ordered vs mean-field + mask_ord = ~df_plot['disordered'] + mask_dis = df_plot['disordered'] + + ax2.scatter(df_plot.loc[mask_ord, 'atoms_per_fu'], + df_plot.loc[mask_ord, 'total_maple'], + c=SHEFFIELD['brand_violet'], s=25, alpha=0.7, + edgecolors='white', linewidth=0.3, + label=f'Ordered ({mask_ord.sum()})', zorder=3) + + if mask_dis.any(): + ax2.scatter(df_plot.loc[mask_dis, 'atoms_per_fu'], + df_plot.loc[mask_dis, 'total_maple'], + c=SHEFFIELD['powder_violet'], s=25, alpha=0.7, + edgecolors='white', linewidth=0.3, marker='D', + label=f'Mean-field ({mask_dis.sum()})', zorder=3) + + ax2.set_xlabel('Atoms per formula unit') + ax2.set_ylabel('Total MAPLE / kcal mol$^{-1}$') + ax2.set_title('MAPLE vs formula complexity') + ax2.legend(frameon=False, fontsize=10) + ax2.spines['top'].set_visible(False) + ax2.spines['right'].set_visible(False) + + fig2.tight_layout() + fig2.savefig(output_dir / 'plot_2_maple_vs_complexity.png') + print(f"Saved: {output_dir / 'plot_2_maple_vs_complexity.png'}") + plt.show() + +else: + print("Plot 2 skipped: need >1 structure in maple_summary.csv") + + +# ═════════════════════════════════════════════════════════════════════════════ +# PLOT 3: Madelung factor distribution +# ═════════════════════════════════════════════════════════════════════════════ + +if len(df_summary) > 1: + + mf_vals = df_summary['madelung_factor'].dropna() + + fig3, ax3 = plt.subplots(figsize=(7, 5)) + + ax3.hist(mf_vals, bins=min(50, max(10, len(mf_vals)//5)), + color=SHEFFIELD['teal'], edgecolor='white', linewidth=0.5, + alpha=0.85) + + ax3.set_xlabel('Madelung factor') + ax3.set_ylabel('Count') + ax3.set_title('Distribution of Madelung factors') + ax3.spines['top'].set_visible(False) + ax3.spines['right'].set_visible(False) + + # Annotate common structure types if recognisable peaks appear + ax3.axvline(x=1.7476, color=SHEFFIELD['coral'], linestyle='--', + linewidth=1, alpha=0.7) + ax3.text(1.7476, ax3.get_ylim()[1]*0.95, ' NaCl\n (1.748)', + fontsize=8, color=SHEFFIELD['coral'], va='top') + + fig3.tight_layout() + fig3.savefig(output_dir / 'plot_3_madelung_factor_distribution.png') + print(f"Saved: {output_dir / 'plot_3_madelung_factor_distribution.png'}") + plt.show() + +else: + print("Plot 3 skipped: need >1 structure in maple_summary.csv") + + +print(f"\nAll plots saved to: {output_dir}") \ No newline at end of file diff --git a/src/maplepy/_hopper.py b/src/maplepy/_hopper.py new file mode 100644 index 0000000..b020313 --- /dev/null +++ b/src/maplepy/_hopper.py @@ -0,0 +1,50 @@ +"""The Hopper engine: the code of Hopper.ipynb, cell by cell, in this +module's namespace (see _loader). Imported on first use, because the +notebook's set-up cell changes matplotlib's rcParams, as it does in Jupyter. +Use maplepy.additivity(); this module is its machinery. +""" + +from pathlib import Path as _P + +from . import _loader, _manifest + +_HOPPER_REFERENCE_PATH = str(_P(_loader.data_dir()) + / 'binary_oxide_maple_reference.json') + +IMPORT_LOG = _loader.load(globals(), 'hopper', _manifest.HOPPER_ENGINE_CELLS) + + + +def reset_state(): + _loader.reset(globals(), _LOADED_NAMES, _LOADED_STATE) + + +def run_pipeline(directory, figures=False): + """Hopper's actions on one MaplePy output folder, from Section 0 to + Section 8, as Restart & Run All would after picking that folder. With + figures, the paper figures (Sections 5 and 10) are drawn as well, after + the export; a figure that cannot be drawn from this data is reported and + skipped. Returns {figure: error} for the skipped ones.""" + reset_state() + globals()['_HOPPER_RUN_DIRECTORY'] = str(_P(directory).resolve()) + for key in _manifest.HOPPER_PIPELINE: + _loader.run(globals(), 'hopper', _manifest.HOPPER_RUN_CELLS[key]) + skipped = {} + if figures: + import matplotlib.pyplot as plt + for key in _manifest.HOPPER_FIGURES: + try: + _loader.run(globals(), 'hopper', + _manifest.HOPPER_RUN_CELLS[key]) + except Exception as e: # reported, never hidden + skipped[key] = f'{type(e).__name__}: {e}' + print(f' figure step {key!r} skipped: {skipped[key]}') + finally: + plt.close('all') + return skipped + + +# The state a fresh notebook session has once every definition has run, +# this module's own functions included; reset_state() returns to it. +_LOADED_NAMES, _LOADED_STATE = _loader.snapshot(globals()) +_LOADED_NAMES = _LOADED_NAMES | {'_LOADED_NAMES', '_LOADED_STATE'} diff --git a/src/maplepy/_loader.py b/src/maplepy/_loader.py new file mode 100644 index 0000000..6f443a2 --- /dev/null +++ b/src/maplepy/_loader.py @@ -0,0 +1,96 @@ +"""How the package runs a notebook's cells: the machinery behind _maple and +_hopper, kept here so that the two engines load in the same way. + +A notebook runs its cells, top to bottom, in one namespace. Each engine is a +module whose namespace plays that part: the cells tools/build_engine.py +copied from the notebook are executed in it, in notebook order, so every +function a notebook defines is an attribute of its engine module, with the +behaviour it has in the notebook. Three things differ from a notebook +session, and only three: + +* what the cells print while loading is kept in the engine's IMPORT_LOG + rather than shown, because MaplePy's worker processes import the engine; +* the actions run when asked for rather than when the module loads, and each + run starts from the state the module had on loading, as "Restart & Run + All" would; +* `display`, which Jupyter provides, prints a table as text. +""" + +import contextlib +import copy +import io +import os +from pathlib import Path + +CELL_DIR = Path(__file__).resolve().parent / '_cells' + + +def data_dir(): + """The reference tables: $MAPLEPY_DATA_DIR, the installed copy, or + data/ at the root of a source checkout (an editable install).""" + env = os.environ.get('MAPLEPY_DATA_DIR') + here = Path(__file__).resolve().parent + candidates = ([Path(env)] if env else []) + [here / 'data', + here.parents[1] / 'data'] + for c in candidates: + if (c / 'binary_oxide_maple_reference.json').exists(): + return str(c) + raise FileNotFoundError( + 'maplepy cannot find its reference tables ' + '(binary_oxide_maple_reference.json and two others). Looked in: ' + + ', '.join(str(c) for c in candidates) + + '. Reinstall maplepy, or set MAPLEPY_DATA_DIR to the folder ' + 'holding them.') + + +def display(*objs, **_kw): + """Jupyter's display(), as text.""" + for o in objs: + print(o.to_string() if hasattr(o, 'to_string') else o) + + +def compile_cell(engine, name): + path = CELL_DIR / engine / name + return compile(path.read_text(encoding='utf-8'), str(path), 'exec', + dont_inherit=True) + + +def load(g, engine, cells): + """Execute an engine's cells in namespace g; return what they printed.""" + g.setdefault('display', display) + log = io.StringIO() + with contextlib.redirect_stdout(log): + for name in cells: + exec(compile_cell(engine, name), g) + return log + + +def snapshot(g): + """What reset() returns the namespace to: the names it holds, and a copy + of every container kept at module level by a private name.""" + names = frozenset(g) + state = {k: copy.deepcopy(v) for k, v in g.items() + if k.startswith('_') and not k.startswith('__') + and type(v) in (dict, list, set)} + return names, state + + +def reset(g, names, state, keep=()): + """Forget every name a previous run created and restore the containers. + Names in `keep` survive.""" + for k in [k for k in g if k not in names and k not in keep]: + del g[k] + for k, v in state.items(): + cur = g.get(k) + if type(cur) is not type(v): + g[k] = copy.deepcopy(v) + elif isinstance(cur, list): + cur[:] = copy.deepcopy(v) + else: + cur.clear() + cur.update(copy.deepcopy(v)) + + +def run(g, engine, name): + """Run one cell file in namespace g, printing as it goes.""" + exec(compile_cell(engine, name), g) diff --git a/src/maplepy/_manifest.py b/src/maplepy/_manifest.py new file mode 100644 index 0000000..6ed52e5 --- /dev/null +++ b/src/maplepy/_manifest.py @@ -0,0 +1,109 @@ +"""Generated by tools/build_engine.py. Do not edit.""" + +# MaplePy.ipynb +MAPLEPY_VERSION = '1.3.6' +MAPLEPY_NOTEBOOK_SHA256 = '98afc23b5e31e15d30a22de35f6cdcfb1852df5ccd16b4e4c588bd4262a3551d' + +# Loaded, in this order, into one namespace when the engine starts. +MAPLEPY_ENGINE_CELLS = [ + 'e04_constants_and_version.py', + 'e06_core_functions.py', + 'e22_additivity_checker.py', + 'e25_batch_processing.py', +] + +# The actions, by the name the package runs them under. +MAPLEPY_RUN_CELLS = { + 'plots': 'r33_diagnostic_plots.py', +} + +MAPLEPY_PIPELINE = [] +MAPLEPY_FIGURES = ['plots'] + +# Run by maplepy.validate(), with the pass flags each sets. +MAPLEPY_CHECK_CELLS = [ + ('k09_nacl.py', []), + ('k10_nacl_checks.py', ['pass_na', 'pass_cl', 'pass_mf', 'pass_sym']), + ('k12_tio2_structures.py', []), + ('k13_tio2.py', []), + ('k14_tio2_checks.py', ['pass_r', 'pass_a', 'pass_diff']), + ('k16_batio3_structures.py', []), + ('k17_batio3.py', []), + ('k18_batio3_checks.py', ['pass_add']), + ('k23_batio3_additivity_example.py', []), +] + +# Every packaged cell in notebook order. +MAPLEPY_NOTEBOOK_ORDER = [ + 'e04_constants_and_version.py', + 'e06_core_functions.py', + 'k09_nacl.py', + 'k10_nacl_checks.py', + 'k12_tio2_structures.py', + 'k13_tio2.py', + 'k14_tio2_checks.py', + 'k16_batio3_structures.py', + 'k17_batio3.py', + 'k18_batio3_checks.py', + 'e22_additivity_checker.py', + 'k23_batio3_additivity_example.py', + 'e25_batch_processing.py', + 'r33_diagnostic_plots.py', +] + +# Hopper.ipynb +HOPPER_VERSION = '1.2.9' +HOPPER_NOTEBOOK_SHA256 = '88c77bd38adeb1f9c48c0ff02ea67d95b8e28df5822add75f20d1fa6b7e2d007' + +# Loaded, in this order, into one namespace when the engine starts. +HOPPER_ENGINE_CELLS = [ + 'e03_setup_and_version.py', + 'e06_binary_reference_table.py', + 'e08_decomposition.py', + 'e10_batch_additivity.py', + 'e12_classification.py', + 'e14_residual_histogram.py', + 'e15_madelung_factor_clustering.py', + 'e23_series_figures.py', +] + +# The actions, by the name the package runs them under. +HOPPER_RUN_CELLS = { + 'load': 'r04_load_maplepy_output.py', + 'batch': 'r10_batch_additivity.py', + 'classify': 'r12_classification.py', + 'figure_residuals': 'r14_residual_histogram.py', + 'figure_madelung': 'r15_madelung_factor_clustering.py', + 'perovskites': 'r17_perovskites.py', + 'pyrochlores': 'r19_pyrochlores.py', + 'export': 'r21_export.py', + 'figures_series': 'r23_series_figures.py', +} + +HOPPER_PIPELINE = ['load', 'batch', 'classify', 'perovskites', 'pyrochlores', 'export'] +HOPPER_FIGURES = ['figure_residuals', 'figure_madelung', 'figures_series'] + +# Run by maplepy.validate(), with the pass flags each sets. +HOPPER_CHECK_CELLS = [ +] + +# Every packaged cell in notebook order. +HOPPER_NOTEBOOK_ORDER = [ + 'e03_setup_and_version.py', + 'r04_load_maplepy_output.py', + 'e06_binary_reference_table.py', + 'e08_decomposition.py', + 'e10_batch_additivity.py', + 'r10_batch_additivity.py', + 'e12_classification.py', + 'r12_classification.py', + 'e14_residual_histogram.py', + 'r14_residual_histogram.py', + 'e15_madelung_factor_clustering.py', + 'r15_madelung_factor_clustering.py', + 'r17_perovskites.py', + 'r19_pyrochlores.py', + 'r21_export.py', + 'e23_series_figures.py', + 'r23_series_figures.py', +] diff --git a/src/maplepy/_maple.py b/src/maplepy/_maple.py new file mode 100644 index 0000000..ec13663 --- /dev/null +++ b/src/maplepy/_maple.py @@ -0,0 +1,43 @@ +"""The MaplePy engine: the code of MaplePy.ipynb, cell by cell, in this +module's namespace (see _loader). Every function the notebook defines, such +as load_structure(), compute_maple() and batch_maple(), is an attribute of +this module. Use the interface in maplepy.api; this module is its machinery. +""" + +from . import _loader, _manifest + +_MAPLEPY_DATA_DIR = _loader.data_dir() + +IMPORT_LOG = _loader.load(globals(), 'maplepy', + _manifest.MAPLEPY_ENGINE_CELLS) + + + +def reset_state(): + _loader.reset(globals(), _LOADED_NAMES, _LOADED_STATE) + + +def run_plots(): + """Section 8: the three diagnostic plots of the last batch_maple() run.""" + _loader.run(globals(), 'maplepy', _manifest.MAPLEPY_RUN_CELLS['plots']) + + +def run_checks(): + """Section 2, the three validation targets, in notebook order. Returns + {flag: bool} for every pass flag the cells set; the namespace is reset + afterwards.""" + flags = {} + try: + for name, names in _manifest.MAPLEPY_CHECK_CELLS: + _loader.run(globals(), 'maplepy', name) + for f in names: + flags[f] = bool(globals()[f]) + finally: + reset_state() + return flags + + +# The state a fresh notebook session has once every definition has run, +# this module's own functions included; reset_state() returns to it. +_LOADED_NAMES, _LOADED_STATE = _loader.snapshot(globals()) +_LOADED_NAMES = _LOADED_NAMES | {'_LOADED_NAMES', '_LOADED_STATE'} diff --git a/src/maplepy/api.py b/src/maplepy/api.py new file mode 100644 index 0000000..fb65f80 --- /dev/null +++ b/src/maplepy/api.py @@ -0,0 +1,160 @@ +"""The Python interface to the two engines. + +Everything here calls the notebooks' own functions: load_structure(), +compute_maple() and batch_maple() from MaplePy, and Hopper's pipeline from +loading a run to the export. Nothing is recomputed differently. +""" + +from dataclasses import dataclass, field +from pathlib import Path + +__all__ = ['MapleResult', 'compute', 'run_folder', 'additivity', 'validate', + 'engine', 'hopper_engine'] + + +def engine(): + """The MaplePy engine module: every function MaplePy.ipynb defines.""" + from . import _maple + return _maple + + +def hopper_engine(): + """The Hopper engine module: every function Hopper.ipynb defines.""" + from . import _hopper + return _hopper + + +@dataclass +class MapleResult: + """One structure through load_structure() and compute_maple(). + + `result` is compute_maple()'s dictionary, `sites` the per-site table of + results_to_dataframe(), and `log` what MaplePy printed, which includes + where the oxidation states came from: the only record of that anywhere. + """ + source: str + result: dict + sites: object + log: str = '' + total_maple: float = field(init=False) + madelung_factor: float = field(init=False) + Z: int = field(init=False) + d_ref: float = field(init=False) + disordered: bool = field(init=False) + geometry_flag: str = field(init=False) + geometry_status: str = field(init=False) + + def __post_init__(self): + r = self.result + self.total_maple = float(r['total_maple_kcal']) + self.madelung_factor = (None if r['madelung_factor'] is None + else float(r['madelung_factor'])) + self.Z = int(r['Z']) + self.d_ref = float(r['d_ref']) + self.disordered = bool(r['disordered']) + self.geometry_flag = r['geometry_flag'] + self.geometry_status = r['geometry_status'] + + def summary(self): + s = self.result['structure'] + mf = ('n/a' if self.madelung_factor is None + else f'{self.madelung_factor:.4f}') + lines = [ + f'{Path(self.source).name} · {s.composition.reduced_formula} ' + f'· {s.get_space_group_info()[0]}', + '', + f' MAPLE {self.total_maple:.2f} kcal/mol per formula ' + f'unit ({self.total_maple * 4.184:.1f} kJ/mol)', + f' Madelung factor {mf}', + f' Z, d_ref {self.Z}, {self.d_ref:.4f} Å', + f' Geometry {self.geometry_status}', + f' Disorder {self.result["disorder_status"]}' + + ('' if self.result['partial_sublattice'] in ('none', None) + else f' ({self.result["partial_sublattice"]} sublattice; ' + f'mean-field charges)'), + ] + prov = [l.strip() for l in self.log.splitlines() + if l.strip().startswith(('Oxidation states', 'WARNING'))] + lines += [f' {p}' for p in prov] + return '\n'.join(lines) + + +def compute(cif, oxidation_states=None): + """MAPLE for one CIF: MaplePy's load_structure() then compute_maple(). + + oxidation_states, e.g. {'Ba': 2, 'Ti': 4, 'O': -2}, is level 1 of the + oxidation-state chain; without it the CIF's own states are used, then the + bundled tables, and a ValueError names the elements that need one. + """ + import contextlib + import io + m = engine() + log = io.StringIO() + with contextlib.redirect_stdout(log): + s = m.load_structure(str(cif), oxidation_states=oxidation_states) + r = m.compute_maple(s, verbose=False) + df = m.results_to_dataframe(r) + return MapleResult(str(cif), r, df, log.getvalue()) + + +def run_folder(folder, output_dir=None, oxidation_states=None, workers=None, + plots=False, verbose=False): + """Every CIF in a folder through MaplePy's batch_maple(), as the + notebook's batch section and GUI do. Writes maple_results.csv, + maple_summary.csv and maple_failed.csv to output_dir, or to a + timestamped outputs_ folder inside `folder`, and returns that folder. + + oxidation_states applies one assignment to every CIF in the folder, as + the GUI's OXIDATION_STATES does. plots draws Section 8's three + diagnostic plots into the same folder. + """ + m = engine() + folder = Path(folder) + if not folder.is_dir(): + raise NotADirectoryError(f'not a folder: {folder}') + oxi = ({p.stem: oxidation_states for p in folder.glob('*.cif')} + if oxidation_states else None) + m.LAST_OUTPUT_DIR = None # so a folder with no CIFs cannot + # return the previous run's folder + m.batch_maple(folder, output_dir=output_dir, oxidation_states_map=oxi, + verbose=verbose, workers=workers) + out = m.LAST_OUTPUT_DIR + if out is None: + raise FileNotFoundError(f'no CIF files in {folder}') + if plots: + import matplotlib + matplotlib.use('Agg', force=False) + m.run_plots() + return Path(out) + + +def additivity(results, figures=False): + """Hopper on a MaplePy run: decomposition into binary oxides, the + additivity residual, the classification, and the export. + + `results` is a folder holding maple_summary.csv and maple_results.csv, + or a folder of CIFs with outputs_* runs inside, in which case the latest + is used, as in the notebook. Writes additivity_classified.csv (and the + perovskite and pyrochlore subsets, and the reference table) into the run + folder and returns the classified table. figures draws the paper figures + as well; any that cannot be drawn from this data are reported. + """ + h = hopper_engine() + skipped = h.run_pipeline(results, figures=figures) + df = h.df_classified.copy() + df.attrs['run_folder'] = str(h.MAPLE_DIR) + df.attrs['figures_skipped'] = skipped + return df + + +def validate(): + """MaplePy's three known answers, as Section 2 of the notebook runs them: + NaCl (partial Madelung constants 0.8738, Madelung factor 1.7476; Hoppe, + 1966), rutile and anatase TiO2 against Hoppe (1995), Table 5, and BaTiO3 + additivity to within 1% (Hoppe, 1995, p. 560). Returns the pass flags; + raises AssertionError naming any that failed.""" + flags = engine().run_checks() + failed = [k for k, v in flags.items() if not v] + if failed: + raise AssertionError('MaplePy validation failed: ' + ', '.join(failed)) + return flags diff --git a/src/maplepy/cli.py b/src/maplepy/cli.py new file mode 100644 index 0000000..9f02013 --- /dev/null +++ b/src/maplepy/cli.py @@ -0,0 +1,187 @@ +"""The two command lines. + + maplepy FOLDER every CIF in FOLDER through MaplePy's batch_maple() + maplepy FILE.cif one structure, printed + maplepy --validate the three known answers (Section 2 of the notebook) + + hopper RESULTS Hopper on a MaplePy run folder (or a CIF folder + holding outputs_* runs: the latest is used) +""" + +import argparse +import sys +from pathlib import Path + + +def _utf8_output(): + """The notebooks print ✓ and ✗ as they go. A Windows console + redirected to a file or a pipe encodes as cp1252, which cannot write + them, so the run would stop on its first progress line. Write UTF-8.""" + for stream in (sys.stdout, sys.stderr): + try: + stream.reconfigure(encoding='utf-8', errors='replace') + except (AttributeError, ValueError): # pragma: no cover + pass + + +def _versions(): + from . import HOPPER_VERSION, MAPLEPY_VERSION, __version__ + try: + from pymatgen.core import __version__ as pmg + except Exception: # pragma: no cover + pmg = 'not found' + return (f'maplepy {__version__} (MaplePy {MAPLEPY_VERSION}, ' + f'Hopper {HOPPER_VERSION}; pymatgen {pmg})') + + +def _parse_ox(text): + """'Ba=2,Ti=4,O=-2' -> {'Ba': 2, 'Ti': 4, 'O': -2}""" + out = {} + for part in filter(None, (p.strip() for p in text.split(','))): + el, _, v = part.partition('=') + if not _ or not el.strip(): + raise argparse.ArgumentTypeError( + f'--ox expects Element=charge pairs, e.g. Ba=2,Ti=4,O=-2; ' + f'got {part!r}') + try: + out[el.strip()] = float(v) if '.' in v else int(v) + except ValueError: + raise argparse.ArgumentTypeError(f'not a charge: {v!r} in {part!r}') + return out + + +def main_maplepy(argv=None): + _utf8_output() + ap = argparse.ArgumentParser( + prog='maplepy', + description='MAPLE (Madelung Part of Lattice Energy) from CIF files. ' + 'Give a folder to run every CIF in it, or one CIF.') + ap.add_argument('path', nargs='?', help='a folder of CIFs, or one CIF') + ap.add_argument('--ox', type=_parse_ox, metavar='EL=Q,...', + help='oxidation states for every structure, e.g. ' + 'Ba=2,Ti=4,O=-2 (otherwise the CIF\'s own are used, ' + 'then the bundled tables)') + ap.add_argument('--out', metavar='DIR', + help='where a folder run writes its CSVs (default: a ' + 'timestamped outputs_ folder inside FOLDER)') + ap.add_argument('--workers', metavar='N', + help="worker processes: 'auto' (the default), 1 for " + "serial, or a number") + ap.add_argument('--plots', action='store_true', + help='draw the three diagnostic plots of Section 8') + ap.add_argument('--additivity', action='store_true', + help='run Hopper on the results afterwards') + ap.add_argument('--validate', action='store_true', + help='run the three known-answer validations and exit') + ap.add_argument('-v', '--verbose', action='store_true', + help="print the notebook's own output as well") + ap.add_argument('--version', action='version', version=_versions()) + a = ap.parse_args(argv) + + from . import api + if a.validate: + import contextlib + import io + said = io.StringIO() + try: + with contextlib.redirect_stdout(said): + flags = api.engine().run_checks() + except Exception as e: + print(said.getvalue()) + print(f'Validation could not run: {type(e).__name__}: {e}') + return 1 + if a.verbose or not all(flags.values()): + print(said.getvalue()) + names = {'pass_na': 'NaCl PMC(Na+) = 0.8738', 'pass_cl': 'NaCl PMC(Cl-) = 0.8738', + 'pass_mf': 'NaCl Madelung factor = 1.7476', + 'pass_sym': 'NaCl PMC(Na+) = PMC(Cl-)', + 'pass_r': 'TiO2 rutile within 50 kcal/mol of Hoppe (1995)', + 'pass_a': 'TiO2 anatase within 50 kcal/mol of Hoppe (1995)', + 'pass_diff': 'TiO2 rutile and anatase within 15 kcal/mol', + 'pass_add': 'BaTiO3 additive to within 1%'} + for k, ok in flags.items(): + print(f" {'pass' if ok else 'FAIL'} {names.get(k, k)}") + bad = [k for k, ok in flags.items() if not ok] + print(f'\n{len(flags) - len(bad)} of {len(flags)} passed.') + return 1 if bad else 0 + + if not a.path: + ap.print_usage() + print('maplepy: give a folder of CIFs or one CIF, or --validate') + return 2 + p = Path(a.path) + if p.is_file(): + try: + r = api.compute(p, oxidation_states=a.ox) + except Exception as e: + print(f'{p.name}: {e}') + return 1 + print(r.summary()) + return 0 + if not p.is_dir(): + print(f'maplepy: no such file or folder: {p}') + return 2 + workers = a.workers + if workers not in (None, 'auto'): + try: + workers = int(workers) + except ValueError: + print(f"maplepy: --workers takes 'auto' or a number, not {workers!r}") + return 2 + try: + out = api.run_folder(p, output_dir=a.out, oxidation_states=a.ox, + workers=workers, plots=a.plots, + verbose=a.verbose) + except FileNotFoundError as e: + print(f'maplepy: {e}') + return 1 + print(f'\nResults: {out}') + if a.additivity: + df = api.additivity(out) + print(f"Hopper: {len(df)} structures classified; " + f"{out / 'additivity_classified.csv'}") + else: + print(f'Next: hopper "{out}"') + return 0 + + +def main_hopper(argv=None): + _utf8_output() + ap = argparse.ArgumentParser( + prog='hopper', + description="Hoppe's additivity theorem on a MaplePy run: " + 'decomposition into binary oxides, the residual, the ' + 'classification, and the export.') + ap.add_argument('results', nargs='?', + help='a MaplePy run folder (maple_summary.csv and ' + 'maple_results.csv), or a CIF folder holding ' + 'outputs_* runs') + ap.add_argument('--figures', action='store_true', + help='draw the paper figures into the run folder as well') + ap.add_argument('--version', action='version', version=_versions()) + a = ap.parse_args(argv) + if not a.results: + ap.print_usage() + return 2 + from . import api + try: + df = api.additivity(a.results, figures=a.figures) + except FileNotFoundError as e: + print(f'hopper: {e}') + return 1 + run = Path(df.attrs['run_folder']) + counts = df['classification'].value_counts() + print(f'\n{len(df)} structures from {run}') + from . import hopper_engine + for code in hopper_engine().CODE_ORDER: + n = int(counts.get(code, 0)) + if n: + print(f' {code:9s} {n:5d} {hopper_engine()._label_for_code(code) if code != "Additive" else "Additive (residual below 1%)"}') + print(f"\nWritten: {run / 'additivity_classified.csv'}") + for k, why in df.attrs.get('figures_skipped', {}).items(): + print(f' figure {k} not drawn: {why}') + return 0 + + +if __name__ == '__main__': # pragma: no cover + sys.exit(main_maplepy()) diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..fe06409 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,34 @@ +import os +import shutil +from pathlib import Path + +import pytest + +os.environ.setdefault('MPLBACKEND', 'Agg') + +ROOT = Path(__file__).resolve().parents[1] +EXAMPLES = ROOT / 'examples' + + +@pytest.fixture +def examples(tmp_path): + """A copy of the example CIFs, so that runs write outside the repository.""" + d = tmp_path / 'cifs' + d.mkdir() + for f in EXAMPLES.glob('*.cif'): + shutil.copy2(f, d / f.name) + return d + + +@pytest.fixture(scope='session') +def example_run(tmp_path_factory): + """One MaplePy run over the examples, then Hopper on it, shared by the + tests that only read the results.""" + import maplepy + d = tmp_path_factory.mktemp('run') / 'cifs' + d.mkdir() + for f in EXAMPLES.glob('*.cif'): + shutil.copy2(f, d / f.name) + out = maplepy.run_folder(d, workers=1) + df = maplepy.additivity(out) + return out, df diff --git a/tests/test_build.py b/tests/test_build.py new file mode 100644 index 0000000..9659e7c --- /dev/null +++ b/tests/test_build.py @@ -0,0 +1,39 @@ +"""The package's cells are the notebooks' cells.""" +import json +import re +import subprocess +import sys +from pathlib import Path + +import maplepy + +ROOT = Path(__file__).resolve().parents[1] + + +def test_the_cells_match_the_notebooks(): + p = subprocess.run([sys.executable, str(ROOT / 'tools' / 'build_engine.py'), + '--check'], capture_output=True, text=True) + assert p.returncode == 0, p.stdout + p.stderr + + +def _version(nb, name): + src = '\n'.join(''.join(c['source']) for c in json.loads( + (ROOT / nb).read_text(encoding='utf-8'))['cells']) + return re.search(rf"^{name} = '([^']+)'", src, re.M).group(1) + + +def test_the_versions_are_the_notebooks(): + assert maplepy.MAPLEPY_VERSION == _version('MaplePy.ipynb', 'MAPLEPY_VERSION') + assert maplepy.HOPPER_VERSION == _version('Hopper.ipynb', 'HOPPER_VERSION') + assert maplepy.engine().MAPLEPY_VERSION == maplepy.MAPLEPY_VERSION + assert maplepy.hopper_engine().HOPPER_VERSION == maplepy.HOPPER_VERSION + + +def test_the_notebooks_carry_no_outputs_or_local_paths(): + for nb in ('MaplePy.ipynb', 'Hopper.ipynb'): + text = (ROOT / nb).read_text(encoding='utf-8') + d = json.loads(text) + assert all(not c.get('outputs') for c in d['cells']), nb + for pat in (r'[A-Z]:\\\\', r'/Users/', r'[\\/]Downloads[\\/]', + r'/home/[a-z]', r'My Drive'): + assert not re.search(pat, text), (nb, pat) diff --git a/tests/test_cli.py b/tests/test_cli.py new file mode 100644 index 0000000..f059b45 --- /dev/null +++ b/tests/test_cli.py @@ -0,0 +1,73 @@ +import subprocess +import sys +from pathlib import Path + +import maplepy + +ROOT = Path(__file__).resolve().parents[1] + + +def run(*args, cwd=None, env=None): + p = subprocess.run([sys.executable, '-c', + 'import sys; from maplepy.cli import main_maplepy, ' + 'main_hopper; f = main_hopper if sys.argv[1] == ' + '"hopper" else main_maplepy; ' + 'raise SystemExit(f(sys.argv[2:]))', *args], + capture_output=True, text=True, cwd=cwd, + env={'MPLBACKEND': 'Agg', **__import__('os').environ, + **(env or {})}) + return p.returncode, p.stdout + p.stderr + + +def test_version_names_both_engines(): + code, out = run('maplepy', '--version') + assert code == 0 + assert f'MaplePy {maplepy.MAPLEPY_VERSION}' in out + assert f'Hopper {maplepy.HOPPER_VERSION}' in out + + +def test_validate_passes(): + code, out = run('maplepy', '--validate') + assert code == 0, out + assert '8 of 8 passed.' in out + + +def test_one_cif(): + code, out = run('maplepy', str(ROOT / 'examples' / 'BaTiO3_cubic.cif')) + assert code == 0, out + assert 'MAPLE 4108.22 kcal/mol' in out + assert 'Madelung factor 4.1259' in out + + +def test_one_cif_that_needs_states(): + p = str(ROOT / 'examples' / 'SrFeO3_no_states.cif') + code, out = run('maplepy', p) + assert code == 1 and 'Could not determine oxidation states' in out + code, out = run('maplepy', p, '--ox', 'Sr=2,Fe=4,O=-2') + assert code == 0, out + + +def test_a_folder_then_hopper(examples): + code, out = run('maplepy', str(examples), '--workers', '1') + assert code == 0, out + runs = sorted(examples.glob('outputs_*')) + assert len(runs) == 1 + assert (runs[0] / 'maple_summary.csv').exists() + code, out = run('hopper', str(examples)) # finds the latest run + assert code == 0, out + assert (runs[0] / 'additivity_classified.csv').exists() + assert '2.5' in out and 'Structural coordinate error' in out + + +def test_bad_arguments(): + assert run('maplepy', '--ox', 'Ba2')[0] != 0 + assert run('maplepy', 'no/such/folder')[0] == 2 + assert run('maplepy')[0] == 2 + + +def test_a_console_that_cannot_write_unicode(examples): + # A Windows console redirected to a file encodes as cp1252, and the + # notebook prints check marks as it goes + code, out = run('maplepy', str(examples), '--workers', '1', + env={'PYTHONIOENCODING': 'cp1252'}) + assert code == 0, out diff --git a/tests/test_engine.py b/tests/test_engine.py new file mode 100644 index 0000000..ddcf23e --- /dev/null +++ b/tests/test_engine.py @@ -0,0 +1,169 @@ +"""MaplePy's decisions: where the oxidation states come from, Z, disorder, +and geometry. Each on a constructed structure.""" +import pytest +from pymatgen.core import Lattice, Structure +from pymatgen.io.cif import CifWriter + +import maplepy + +m = maplepy.engine() + + +def perovskite(a=4.0019, A='Ba', B='Ti'): + return Structure.from_spacegroup('Pm-3m', Lattice.cubic(a), [A, B, 'O'], + [[0, 0, 0], [0.5, 0.5, 0.5], [0.5, 0.5, 0]]) + + +def write(s, path): + CifWriter(s).write_file(path) + return path + + +def test_states_written_in_the_cif_are_used(tmp_path): + s = perovskite() + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + r = maplepy.compute(write(s, tmp_path / 'bt.cif')) + assert 'CIF (per-site, charge-neutral)' in r.log + assert r.total_maple == pytest.approx(4108.22, abs=0.01) + + +def test_the_bundled_library_supplies_states_the_cif_lacks(tmp_path): + # TiO2 carries no states here; Ti has two common states, so only the + # formula override in maple_library.json can settle it (level 4) + s = Structure.from_spacegroup(136, Lattice.tetragonal(4.5933, 2.9592), + ['Ti', 'O'], [[0, 0, 0], [0.3048, 0.3048, 0]]) + r = maplepy.compute(write(s, tmp_path / 'rutile.cif')) + assert 'maple_library.json (TiO2)' in r.log + assert r.total_maple == pytest.approx(3255.8, abs=0.05) + + +ATOM_TYPE_CIF = """data_CaO +_symmetry_space_group_name_H-M 'F m -3 m' +_symmetry_Int_Tables_number 225 +_cell_length_a 4.81 +_cell_length_b 4.81 +_cell_length_c 4.81 +_cell_angle_alpha 90 +_cell_angle_beta 90 +_cell_angle_gamma 90 +loop_ + _space_group_symop_operation_xyz + 'x, y, z' + 'x, y+1/2, z+1/2' + 'x+1/2, y, z+1/2' + 'x+1/2, y+1/2, z' +loop_ + _atom_type_symbol + _atom_type_oxidation_number + Ca2+ 2 + O2- -2 +loop_ + _atom_site_label + _atom_site_type_symbol + _atom_site_fract_x + _atom_site_fract_y + _atom_site_fract_z + Ca1 Ca 0 0 0 + O1 O 0.5 0.5 0.5 +""" + + +def test_the_atom_type_loop_is_parsed(): + # Level 3 reads the loop itself, element by element + import tempfile, pathlib + p = pathlib.Path(tempfile.mkdtemp()) / 'cao.cif' + p.write_text(ATOM_TYPE_CIF) + assert m._extract_cif_oxidation_states(p) == {'Ca': 2, 'O': -2} + + +def test_the_atom_type_loop_is_used_when_pymatgen_assigns_nothing(tmp_path, monkeypatch): + # Level 3. Current pymatgen reads this loop itself (level 2), so level 3 + # is reached only when its own assignment fails; that is simulated here. + p = tmp_path / 'cao.cif' + p.write_text(ATOM_TYPE_CIF) + assert 'CIF (per-site, charge-neutral)' in maplepy.compute(p).log + monkeypatch.setattr(m, '_has_native_oxi_states', lambda s: False) + r = maplepy.compute(p) + assert 'CIF (_atom_type, element-level fallback)' in r.log + assert r.madelung_factor == pytest.approx(1.7476, abs=1e-4) + + +def test_single_state_elements_need_no_library_entry(tmp_path): + # Level 5: Ca and O each have one common state, and CaO has no formula + # override, so common_oxidation_states.json settles it + s = Structure.from_spacegroup('Fm-3m', Lattice.cubic(4.81), ['Ca', 'O'], + [[0, 0, 0], [0.5, 0.5, 0.5]]) + r = maplepy.compute(write(s, tmp_path / 'cao.cif')) + assert 'common_oxidation_states.json' in r.log + assert r.madelung_factor == pytest.approx(1.7476, abs=1e-4) + + +def test_an_ambiguous_state_stops_the_calculation(tmp_path): + # Fe could be 2+ or 3+ (or, here, 4+): MaplePy asks rather than guesses + p = write(perovskite(3.85, 'Sr', 'Fe'), tmp_path / 'sfo.cif') + with pytest.raises(ValueError, match='Could not determine oxidation states'): + maplepy.compute(p) + r = maplepy.compute(p, oxidation_states={'Sr': 2, 'Fe': 4, 'O': -2}) + assert r.log.count('Oxidation states (user)') == 1 + + +def test_z_comes_from_the_site_counts_not_the_composition(): + # Two cells of BaTiO3 with a part-occupied Ti site: the composition does + # not reduce, but there are two formula units in the cell + s = perovskite() + s.make_supercell([2, 1, 1]) + s.replace_species({'Ti': {'Ti': 0.98}}) + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + _, z_comp = s.composition.get_reduced_composition_and_factor() + assert round(z_comp) == 1 + assert m._derive_Z(s) == 2 + + +def test_a_shared_site_takes_the_mean_charge_and_is_flagged(): + s = perovskite(3.95) + s.replace_species({'Ba': {'Ba': 0.5, 'Sr': 0.5}}) + s.add_oxidation_state_by_element({'Ba': 2, 'Sr': 2, 'Ti': 4, 'O': -2}) + r = m.compute_maple(s, verbose=False) + assert r['disordered'] and r['disorder_status'] == 'mixed occupancy' + assert r['partial_sublattice'] == 'none' + + +def test_a_partly_occupied_anion_site_is_named(): + s = perovskite() + s.replace_species({'O': {'O': 0.9}}) + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + kind, where = m._disorder_detail(s) + assert kind == 'partial occupancy' and where == 'anion' + + +@pytest.mark.parametrize('a, flag', [(4.0019, 'ok'), (3.0019, 'short_contact')]) +def test_short_contacts_are_reported_never_repaired(a, flag): + s = perovskite(a) + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + before = s.copy() + r = m.compute_maple(s, verbose=False) + assert r['geometry_flag'] == flag + assert s == before # the structure is not edited + assert r['total_maple_kcal'] > 0 + + +def test_two_sites_closer_than_half_an_angstrom_are_a_split_site(): + s = perovskite() + s.replace_species({'Ba': {'Ba': 0.5}}) + s.append({'Ba': 0.5}, [0.05, 0, 0]) + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + d, flag, _ = m._geometry_status(s) + assert d < 0.5 and flag == 'split_site' + + +def test_the_shortest_cation_anion_distance_is_d_ref(): + s = perovskite() + s.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + assert m._find_d_ref(s) == pytest.approx(4.0019 / 2, abs=1e-6) + + +def test_a_structure_without_anions_has_no_d_ref(): + s = Structure(Lattice.cubic(3), ['Ba'], [[0, 0, 0]]) + s.add_oxidation_state_by_element({'Ba': 2}) + with pytest.raises(ValueError, match='cannot determine d_ref'): + m._find_d_ref(s) diff --git a/tests/test_hopper.py b/tests/test_hopper.py new file mode 100644 index 0000000..31c70c5 --- /dev/null +++ b/tests/test_hopper.py @@ -0,0 +1,137 @@ +"""Hopper on MaplePy runs: decomposition, residual, classification, and the +estimate flag of 1.2.9.""" +import json +from pathlib import Path + +import pandas as pd +import pytest +from pymatgen.core import Lattice, Structure +from pymatgen.io.cif import CifWriter + +import maplepy + +ROOT = Path(__file__).resolve().parents[1] +TABLE = ROOT / 'data' / 'binary_oxide_maple_reference.json' + + +def by_cif(df): + return df.set_index('source_cif') + + +def test_the_examples_classify_as_documented(example_run): + _, df = example_run + c = by_cif(df)['classification'].to_dict() + assert c['BaTiO3_cubic.cif'] == 'Additive' + assert c['Gd2Ti2O7_pyrochlore.cif'] == 'Additive' + assert c['BaO_rocksalt.cif'] == 'Additive' + assert c['TiO2_rutile.cif'] == 'Additive' + assert c['BaTiO3_wrong_cell.cif'] == '2.5' # the short Ti-O contact + assert c['Ba0.5Sr0.5TiO3_disordered.cif'] == '2.3' + assert c['SrTiO3_cubic.cif'] == '3.1' + assert 'SrFeO3_no_states.cif' not in c # failed upstream (1.2) + + +def test_the_residual_is_the_one_hoppe_defines(example_run): + _, df = example_run + r = by_cif(df).loc['BaTiO3_cubic.cif'] + table = {e['formula']: e['maple_kcal_mol'] + for e in json.loads(TABLE.read_text())['entries']} + assert r['maple_binary_sum'] == pytest.approx(table['BaO'] + table['TiO2']) + expected = 100 * abs(r['maple_ternary'] - r['maple_binary_sum']) / r['maple_ternary'] + assert r['delta_pct'] == pytest.approx(expected, abs=1e-3) + + +def test_the_export_is_written_beside_the_run(example_run): + out, df = example_run + disk = pd.read_csv(out / 'additivity_classified.csv') + assert len(disk) == len(df) + assert set(disk['hopper_version']) == {maplepy.HOPPER_VERSION} + assert {'classification', 'classification_tier', 'estimated_binaries'} <= set(disk) + + +def _run(tmp_path, structures, ox=None): + d = tmp_path / 'cifs' + d.mkdir() + for name, s in structures.items(): + CifWriter(s).write_file(d / name) + return maplepy.additivity(maplepy.run_folder(d, workers=1, + oxidation_states=ox)) + + +def perovskite(a, A, B): + return Structure.from_spacegroup('Pm-3m', Lattice.cubic(a), [A, B, 'O'], + [[0, 0, 0], [0.5, 0.5, 0.5], [0.5, 0.5, 0]]) + + +def test_a_residual_resting_on_an_estimate_says_so(tmp_path): + # PbO's reference value is an estimate, with no source; TiO2's is an + # ICSD median. The residual is computed and classified as before. + s = perovskite(3.97, 'Pb', 'Ti') + s.add_oxidation_state_by_element({'Pb': 2, 'Ti': 4, 'O': -2}) + t = Structure.from_spacegroup('Pm-3m', Lattice.cubic(4.0019), ['Ba', 'Ti', 'O'], + [[0, 0, 0], [0.5, 0.5, 0.5], [0.5, 0.5, 0]]) + t.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + df = by_cif(_run(tmp_path, {'PbTiO3.cif': s, 'BaTiO3.cif': t})) + assert df.loc['PbTiO3.cif', 'estimated_binaries'] == 'PbO' + assert pd.isna(df.loc['BaTiO3.cif', 'estimated_binaries']) or \ + df.loc['BaTiO3.cif', 'estimated_binaries'] == '' + assert df.loc['PbTiO3.cif', 'success'] + + +def test_an_oxidation_state_with_no_binary_oxide_is_tier_1(tmp_path): + # Fe(IV) has no ambient binary oxide: nothing to sum against (code 1.3) + s = perovskite(3.85, 'Sr', 'Fe') + df = _run(tmp_path, {'SrFeO3.cif': s}, ox={'Sr': 2, 'Fe': 4, 'O': -2}) + r = df.iloc[0] + assert r['classification'] == '1.3' + assert pd.isna(r['delta_pct']) # no number without a meaning + + +def test_the_reference_table_and_its_flags(): + d = json.loads(TABLE.read_text()) + e = d['entries'] + assert len(e) == d['_metadata']['n_entries'] == 112 + est = {x['formula'] for x in e if x['source'] == 'estimated'} + assert len(est) == 23 + # Cu2O's recorded validation source does not reproduce (797.9, not 730.0) + unsourced = {x['formula'] for x in e if not x['sourced']} + assert unsourced == est | {'Cu2O'} + assert all('review_note' in x for x in e if x['formula'] in ('CuO', 'ZnO', 'Cu2O')) + assert maplepy.hopper_engine().ESTIMATED_BINARIES == unsourced + assert 'J. Appl. Cryst.' in d['_metadata']['citation'] + + +def test_the_inline_fallback_never_disagrees_with_the_released_table(): + h = maplepy.hopper_engine() + table = {x['formula']: x['maple_kcal_mol'] + for x in json.loads(TABLE.read_text())['entries']} + for f, (v, _t, _s) in h.BINARY_MAPLE_FALLBACK.items(): + assert table[f] == pytest.approx(v), f + + +def test_hopper_reads_the_bundled_table(): + h = maplepy.hopper_engine() + assert Path(h._binary_source).resolve() == TABLE.resolve() or \ + Path(h._binary_source).name == TABLE.name + + +def test_a_folder_without_maplepy_output_fails_loudly(tmp_path): + with pytest.raises(FileNotFoundError, match='maple_summary.csv'): + maplepy.additivity(tmp_path) + + +def test_the_recorded_cu2o_value_does_not_reproduce(tmp_path): + # The table records 730.0 for cuprite as a MaplePy validation value. + # MaplePy gives 797.9 at a = 4.270 A (Cu-O 1.849 A), so the entry is + # marked unsourced and Hopper names it wherever it is used. + s = Structure(Lattice.cubic(4.270), ['O', 'O', 'Cu', 'Cu', 'Cu', 'Cu'], + [[0, 0, 0], [.5, .5, .5], [.25, .25, .25], [.75, .75, .25], + [.75, .25, .75], [.25, .75, .75]]) + s.add_oxidation_state_by_element({'Cu': 1, 'O': -2}) + CifWriter(s).write_file(tmp_path / 'cu2o.cif') + r = maplepy.compute(tmp_path / 'cu2o.cif') + assert r.total_maple == pytest.approx(797.9, abs=0.1) + cu2o = next(x for x in json.loads(TABLE.read_text())['entries'] + if x['formula'] == 'Cu2O') + assert cu2o['maple_kcal_mol'] == 730.0 and cu2o['sourced'] is False + diff --git a/tests/test_known_answers.py b/tests/test_known_answers.py new file mode 100644 index 0000000..5fc55b4 --- /dev/null +++ b/tests/test_known_answers.py @@ -0,0 +1,75 @@ +"""The three sourced validation targets, asserted here independently of the +notebook's own PASS/FAIL cells (which maplepy.validate() runs, below).""" +import pytest +from pymatgen.core import Lattice, Structure + +import maplepy + +m = maplepy.engine() + + +def rock_salt(a, A, X, qa, qx): + s = Structure.from_spacegroup('Fm-3m', Lattice.cubic(a), [A, X], + [[0, 0, 0], [0.5, 0.5, 0.5]]) + s.add_oxidation_state_by_element({A: qa, X: qx}) + return s + + +def test_nacl_partial_madelung_constants_and_madelung_factor(): + # Hoppe (1966): PMC(Na+) = PMC(Cl-) = 0.8738, MF = 1.7476 for rock salt + r = m.compute_maple(rock_salt(5.6402, 'Na', 'Cl', 1, -1), verbose=False) + pmc = {s['element']: s['pmc'] for s in r['per_site']} + assert pmc['Na'] == pytest.approx(0.8738, abs=5e-4) + assert pmc['Cl'] == pytest.approx(0.8738, abs=5e-4) + assert pmc['Na'] == pytest.approx(pmc['Cl'], abs=1e-6) # exact by symmetry + assert r['madelung_factor'] == pytest.approx(1.7476, abs=1e-4) + + +@pytest.mark.parametrize('a', [4.2112, 4.8105, 5.1408, 5.5391]) +def test_madelung_factor_is_invariant_across_rock_salts(a): + r = m.compute_maple(rock_salt(a, 'Mg', 'O', 2, -2), verbose=False) + assert r['madelung_factor'] == pytest.approx(1.7476, abs=1e-4) + + +def test_tio2_rutile_and_anatase_against_hoppe_1995(): + # Hoppe (1995), Table 5: rutile 3254.6, anatase 3260.7 kcal/mol + rutile = Structure.from_spacegroup(136, Lattice.tetragonal(4.5933, 2.9592), + ['Ti', 'O'], [[0, 0, 0], [0.3048, 0.3048, 0]]) + anatase = Structure.from_spacegroup(141, Lattice.tetragonal(3.7845, 9.5143), + ['Ti', 'O'], [[0, 0, 0], [0, 0, 0.2082]]) + for s in (rutile, anatase): + s.add_oxidation_state_by_element({'Ti': 4, 'O': -2}) + r = m.compute_maple(rutile, verbose=False)['total_maple_kcal'] + a = m.compute_maple(anatase, verbose=False)['total_maple_kcal'] + assert abs(r - 3254.6) < 50 and abs(a - 3260.7) < 50 + assert abs(r - a) < 15 # the near-degeneracy is the result + assert r == pytest.approx(3255.8, abs=0.05) # regression: MaplePy 1.3.6 + assert a == pytest.approx(3262.74, abs=0.05) + + +def test_batio3_is_additive_to_within_one_percent(): + # Hoppe (1995), p. 560: MAPLE(BaTiO3) = MAPLE(BaO) + MAPLE(TiO2) to 0.07% + bao = rock_salt(5.5391, 'Ba', 'O', 2, -2) + rutile = Structure.from_spacegroup(136, Lattice.tetragonal(4.5933, 2.9592), + ['Ti', 'O'], [[0, 0, 0], [0.3048, 0.3048, 0]]) + rutile.add_oxidation_state_by_element({'Ti': 4, 'O': -2}) + bt = Structure.from_spacegroup('Pm-3m', Lattice.cubic(4.0019), ['Ba', 'Ti', 'O'], + [[0, 0, 0], [0.5, 0.5, 0.5], [0.5, 0.5, 0]]) + bt.add_oxidation_state_by_element({'Ba': 2, 'Ti': 4, 'O': -2}) + rb, rr, rt = (m.compute_maple(s, verbose=False) for s in (bao, rutile, bt)) + out = m.check_additivity(rt, [(rb, 1), (rr, 1)], verbose=False) + assert out['delta_pct'] < 1.0 + assert out['delta_pct'] == pytest.approx(0.348, abs=0.001) # as reported + + +def test_validate_runs_the_notebook_section_2_and_passes(): + flags = maplepy.validate() + assert set(flags) == {'pass_na', 'pass_cl', 'pass_mf', 'pass_sym', + 'pass_r', 'pass_a', 'pass_diff', 'pass_add'} + assert all(flags.values()) + + +def test_validate_leaves_the_engine_as_it_was(): + names = set(vars(m)) + maplepy.validate() + assert set(vars(m)) == names diff --git a/tests/test_release.py b/tests/test_release.py new file mode 100644 index 0000000..bbdb996 --- /dev/null +++ b/tests/test_release.py @@ -0,0 +1,74 @@ +"""The release metadata agree with each other and with the code. + +Zenodo reads .zenodo.json and ignores CITATION.cff when both are present; +GitHub's "Cite this repository" reads CITATION.cff. The two must name the +same software, version and authors, and the version must be the package's. +The checks on the release date and the DOI apply once CITATION.cff carries +them, which is on release day. +""" +import json +import re +from pathlib import Path + +import maplepy + +ROOT = Path(__file__).resolve().parents[1] +CFF = (ROOT / 'CITATION.cff').read_text(encoding='utf-8') +ZEN = json.loads((ROOT / '.zenodo.json').read_text(encoding='utf-8')) +NIK = '0000-0002-1061-1230' + + +def cff(field): + m = re.search(rf'^{field}:\s*"?(.*?)"?\s*$', CFF, re.M) + return m.group(1) if m else None + + +def software_authors(): + block = CFF.split('\nauthors:\n', 1)[1].split('\nversion:', 1)[0] + return re.findall(r'family-names: (.+)\n\s+given-names: (.+)', block) + + +def test_zenodo_and_citation_files_agree(): + assert ZEN['version'] == cff('version') == maplepy.__version__ + assert ZEN['title'] == cff('title') + assert ZEN['upload_type'] == 'software' and ZEN['license'] == 'mit' + assert cff('license') == 'MIT' + names = [f'{f}, {g}' for f, g in software_authors()] + assert names == [c['name'] for c in ZEN['creators']] + assert ZEN['creators'][0]['orcid'] == NIK + assert f'orcid: "https://orcid.org/{NIK}"' in CFF + + +def test_the_engine_versions_are_named_where_the_release_is_described(): + for text in (CFF, ZEN['description']): + assert maplepy.MAPLEPY_VERSION in text and maplepy.HOPPER_VERSION in text + + +def test_package_version_matches_pyproject(): + toml = (ROOT / 'pyproject.toml').read_text(encoding='utf-8') + assert re.search(r'^version = "(.*)"', toml, re.M).group(1) == maplepy.__version__ + + +def test_every_released_version_has_a_changelog_entry(): + log = (ROOT / 'CHANGELOG.md').read_text(encoding='utf-8') + released = cff('date-released') + for v in (f'maplepy {maplepy.__version__}', maplepy.MAPLEPY_VERSION, + maplepy.HOPPER_VERSION): + m = re.search(rf'^### {re.escape(v)} – (.+)$', log, re.M) + assert m, v + if released: # on release day the entries must be dated + assert m.group(1) != 'unreleased', (v, 'CHANGELOG says unreleased') + if released: + assert re.fullmatch(r'\d{4}-\d{2}-\d{2}', released) + + +def test_the_readme_gives_the_citation_doi_once_there_is_one(): + doi = cff('doi') + if doi: + readme = (ROOT / 'README.md').read_text(encoding='utf-8') + assert f'https://doi.org/{doi}' in readme, doi + + +def test_the_licence_names_the_author_and_the_university(): + text = (ROOT / 'LICENSE').read_text(encoding='utf-8') + assert 'Copyright (c) 2026 Nik Reeves-McLaren, University of Sheffield' in text diff --git a/tools/build_engine.py b/tools/build_engine.py new file mode 100644 index 0000000..31b7e38 --- /dev/null +++ b/tools/build_engine.py @@ -0,0 +1,310 @@ +"""Build the maplepy package's engines from MaplePy.ipynb and Hopper.ipynb. + +The notebooks are the source of the code. This script copies their code +cells into src/maplepy/_cells/maplepy/ and src/maplepy/_cells/hopper/, one +file per cell, so that the package runs the same code the notebooks run, in +the same order, each notebook in a namespace of its own. It changes nothing +else, and everything it does change is listed in the two plans below: + +* cells that only install packages, print a version, demonstrate a call or + carry the analysis of one study are left out, each with the reason; +* MaplePy's three validation targets (Section 2) are not run on import; they + run when maplepy.validate() is called; +* the reference tables are read from the package's data folder rather than + from ./data in the working directory; +* the cells that open a folder dialog are replaced by the folder passed in: + MaplePy's GUI cell (Section 7) is left out, because maplepy.run_folder() + calls the batch_maple() it fronts, and Hopper's loading cell takes the + folder instead of a dialog; +* Hopper's cells that act on a MaplePy run (Section 3 onwards) are split + into the definitions, which load with the engine, and the action, which + runs when maplepy.additivity() is called, in notebook order. + +Each edit must match the notebook exactly once, so a change to the notebook +that touches an edited line stops the build rather than going unnoticed. + + python tools/build_engine.py # write src/maplepy/_cells/ + python tools/build_engine.py --check # fail if they are out of date +""" + +import argparse +import hashlib +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +CELLS = ROOT / 'src' / 'maplepy' / '_cells' +MANIFEST = ROOT / 'src' / 'maplepy' / '_manifest.py' + +# One entry per notebook cell, in notebook order. +# name file stem, or None to leave the cell out (with `why`) +# role 'engine' (loads with the package), 'run' (an action, run on a +# folder), 'check' (run by maplepy.validate()), or 'split' (both +# engine and run) +# split for 'split', the text the run part starts with +# run for 'run' and 'split', the key the package runs it under +# flags for 'check', the pass/fail names the cell sets +# edits (old, new) pairs, each of which must match exactly once +MAPLEPY_PLAN = [ + dict(cell=0, name=None, why='markdown: title and references'), + dict(cell=1, name=None, why='markdown'), + dict(cell=2, name=None, why='a commented pip install; the package ' + 'declares its dependencies'), + dict(cell=3, name=None, why='prints the pymatgen version; ' + 'maplepy --version reports it'), + dict(cell=4, name='c04_constants_and_version', role='engine', + edits=[('DEFAULT_DATA_DIR = _default_data_dir()\n', + 'DEFAULT_DATA_DIR = _MAPLEPY_DATA_DIR' + ' # maplepy package: the bundled tables\n')]), + dict(cell=5, name=None, why='markdown'), + dict(cell=6, name='c06_core_functions', role='engine'), + dict(cell=7, name=None, why='markdown'), + dict(cell=8, name=None, why='markdown'), + dict(cell=9, name='c09_nacl', role='check'), + dict(cell=10, name='c10_nacl_checks', role='check', + flags=['pass_na', 'pass_cl', 'pass_mf', 'pass_sym']), + dict(cell=11, name=None, why='markdown'), + dict(cell=12, name='c12_tio2_structures', role='check'), + dict(cell=13, name='c13_tio2', role='check'), + dict(cell=14, name='c14_tio2_checks', role='check', + flags=['pass_r', 'pass_a', 'pass_diff']), + dict(cell=15, name=None, why='markdown'), + dict(cell=16, name='c16_batio3_structures', role='check'), + dict(cell=17, name='c17_batio3', role='check'), + dict(cell=18, name='c18_batio3_checks', role='check', + flags=['pass_add']), + dict(cell=19, name=None, why='markdown'), + dict(cell=20, name=None, why='a demonstration on the NaCl result; ' + 'the README shows the same call'), + dict(cell=21, name=None, why='markdown'), + dict(cell=22, name='c22_additivity_checker', role='engine'), + dict(cell=23, name='c23_batio3_additivity_example', role='check'), + dict(cell=24, name=None, why='markdown'), + dict(cell=25, name='c25_batch_processing', role='engine'), + dict(cell=26, name=None, why='markdown'), + dict(cell=27, name=None, why='Section 6, an application to the alkaline ' + 'earth oxides, is analysis rather than engine'), + dict(cell=28, name=None, why='Section 6, as above'), + dict(cell=29, name=None, why='Section 6, as above'), + dict(cell=30, name=None, why='markdown'), + dict(cell=31, name=None, why='the GUI: a Tk folder picker in front of ' + 'batch_maple(), which the package calls ' + 'directly with the folder passed in'), + dict(cell=32, name=None, why='markdown'), + dict(cell=33, name='c33_diagnostic_plots', role='run', run='plots'), + dict(cell=34, name=None, why='markdown: notes and limitations'), +] + +HOPPER_PLAN = [ + dict(cell=0, name=None, why='markdown: purpose'), + dict(cell=1, name=None, why='a commented pip install'), + dict(cell=2, name=None, why='markdown'), + dict(cell=3, name='c03_setup_and_version', role='engine'), + dict(cell=4, name='c04_load_maplepy_output', role='run', run='load', + edits=[('import tkinter as tk\nfrom tkinter import filedialog\n', + '# maplepy package: no folder dialog; the folder is passed ' + 'in\n'), + ('MAPLE_DIR_OVERRIDE = None ', + 'MAPLE_DIR_OVERRIDE = _HOPPER_RUN_DIRECTORY' + ' # maplepy package: the folder passed in\n# ')]), + dict(cell=5, name=None, why='markdown'), + dict(cell=6, name='c06_binary_reference_table', role='engine', + edits=[('BINARY_REFERENCE_PATH = None ', + 'BINARY_REFERENCE_PATH = _HOPPER_REFERENCE_PATH' + ' # maplepy package: the bundled table\n# ')]), + dict(cell=7, name=None, why='markdown'), + dict(cell=8, name='c08_decomposition', role='engine'), + dict(cell=9, name=None, why='markdown'), + dict(cell=10, name='c10_batch_additivity', role='split', run='batch', + split='# ── Run the batch'), + dict(cell=11, name=None, why='markdown'), + dict(cell=12, name='c12_classification', role='split', run='classify', + split='# ── Classify ─'), + dict(cell=13, name=None, why='markdown'), + dict(cell=14, name='c14_residual_histogram', role='split', + run='figure_residuals', split='# ── Plot ─'), + dict(cell=15, name='c15_madelung_factor_clustering', role='split', + run='figure_madelung', split='# ── Plot ─'), + dict(cell=16, name=None, why='markdown'), + dict(cell=17, name='c17_perovskites', role='run', run='perovskites'), + dict(cell=18, name=None, why='markdown'), + dict(cell=19, name='c19_pyrochlores', role='run', run='pyrochlores'), + dict(cell=20, name=None, why='markdown'), + dict(cell=21, name='c21_export', role='run', run='export'), + dict(cell=22, name=None, why='markdown: notes and limitations'), + dict(cell=23, name='c23_series_figures', role='split', + run='figures_series', split='# ── Generate Figures ─'), + dict(cell=24, name=None, why='empty'), +] + +NOTEBOOKS = { + 'maplepy': dict(notebook='MaplePy.ipynb', plan=MAPLEPY_PLAN, + version='MAPLEPY_VERSION'), + 'hopper': dict(notebook='Hopper.ipynb', plan=HOPPER_PLAN, + version='HOPPER_VERSION'), +} + +# The order the package runs each engine's actions in: the notebook's order, +# top to bottom. Hopper's figures run only when asked for. +PIPELINES = { + 'maplepy': [], + 'hopper': ['load', 'batch', 'classify', 'perovskites', 'pyrochlores', + 'export'], +} +FIGURES = { + 'maplepy': ['plots'], + 'hopper': ['figure_residuals', 'figure_madelung', 'figures_series'], +} + +HEADER = ('# Generated by tools/build_engine.py from {nb}, cell {cell}.\n' + '# Edit the notebook, not this file, then rebuild.\n' + '{note}\n') + + +def _apply(src, edits, where): + for old, new in edits or []: + n = src.count(old) + if n != 1: + raise SystemExit(f'{where}: edit expected once, found {n} times:\n' + f' {old!r}') + src = src.replace(old, new) + return src + + +def _version(cells, name, nbname): + for c in cells: + m = re.search(rf"^{name} = '([^']+)'", ''.join(c['source']), re.M) + if m: + return m.group(1) + raise SystemExit(f'{nbname}: no {name} found') + + +def build_one(key): + spec = NOTEBOOKS[key] + nbpath = ROOT / spec['notebook'] + nb = json.loads(nbpath.read_text(encoding='utf-8')) + cells, plan = nb['cells'], spec['plan'] + if len(cells) != len(plan): + raise SystemExit(f"{spec['notebook']} has {len(cells)} cells and the " + f"plan describes {len(plan)}. Update the plan.") + version = _version(cells, spec['version'], spec['notebook']) + files, engine, runs, checks, order = {}, [], {}, [], [] + for p, c in zip(plan, cells): + where = f"{spec['notebook']} cell {p['cell']}" + if p['name'] is None: + continue + if c['cell_type'] != 'code': + raise SystemExit(f'{where} is {c["cell_type"]}, expected code') + src = ''.join(c['source']) + first = src.splitlines()[0] if src.strip() else '' + if not first.startswith(('#', 'import', 'from', 'def', 'nacl', 'result', + 'maple', 'check')): + raise SystemExit(f'{where}: unexpected first line {first!r}; ' + f'has a cell moved?') + src = _apply(src, p.get('edits'), where) + role = p['role'] + hdr = dict(nb=spec['notebook'], cell=p['cell']) + if role == 'split': + k = src.count(p['split']) + if k != 1: + raise SystemExit(f'{where}: split point found {k} times') + i = src.index(p['split']) + head, tail = src[:i].rstrip() + '\n', src[i:] + ename, rname = 'e' + p['name'][1:], 'r' + p['name'][1:] + files[ename + '.py'] = HEADER.format( + note=f'# The action at the end of this cell is in {rname}.py.', + **hdr) + head + files[rname + '.py'] = HEADER.format( + note=f'# The action at the end of the cell; its definitions ' + f'are in {ename}.py.', **hdr) + tail + engine.append(ename + '.py') + runs[p['run']] = rname + '.py' + order += [ename + '.py', rname + '.py'] + else: + prefix = {'engine': 'e', 'run': 'r', 'check': 'k'}[role] + fname = prefix + p['name'][1:] + '.py' + files[fname] = HEADER.format(note='', **hdr) + src + order.append(fname) + if role == 'engine': + engine.append(fname) + elif role == 'run': + runs[p['run']] = fname + else: + checks.append((fname, p.get('flags', []))) + # Line endings normalised, so a Windows checkout (CRLF) hashes the same. + sha = hashlib.sha256(nbpath.read_bytes().replace(b'\r\n', b'\n')).hexdigest() + return files, dict(version=version, sha=sha, engine=engine, runs=runs, + checks=checks, order=order) + + +def build(): + files, parts = {}, {} + for key in NOTEBOOKS: + f, parts[key] = build_one(key) + files.update({f'{key}/{n}': s for n, s in f.items()}) + lines = ['"""Generated by tools/build_engine.py. Do not edit."""', ''] + for key in NOTEBOOKS: + p, K = parts[key], key.upper() + lines += [f'# {NOTEBOOKS[key]["notebook"]}', + f'{K}_VERSION = {p["version"]!r}', + f'{K}_NOTEBOOK_SHA256 = {p["sha"]!r}', + '', + '# Loaded, in this order, into one namespace when the engine ' + 'starts.', + f'{K}_ENGINE_CELLS = ['] + lines += [f' {n!r},' for n in p['engine']] + [']', ''] + lines += ['# The actions, by the name the package runs them under.', + f'{K}_RUN_CELLS = {{'] + lines += [f' {k!r}: {v!r},' for k, v in p['runs'].items()] + ['}', ''] + lines += [f'{K}_PIPELINE = {PIPELINES[key]!r}', + f'{K}_FIGURES = {FIGURES[key]!r}', '', + '# Run by maplepy.validate(), with the pass flags each sets.', + f'{K}_CHECK_CELLS = ['] + lines += [f' ({n!r}, {fl!r}),' for n, fl in p['checks']] + [']', ''] + lines += ['# Every packaged cell in notebook order.', + f'{K}_NOTEBOOK_ORDER = ['] + lines += [f' {n!r},' for n in p['order']] + [']', ''] + return files, '\n'.join(lines) + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument('--check', action='store_true', + help='exit 1 if src/maplepy/_cells/ is out of date') + a = ap.parse_args(argv) + files, manifest = build() + on_disk = {str(p.relative_to(CELLS)).replace('\\', '/') + for p in CELLS.glob('*/*.py')} + if a.check: + stale = [n for n, s in files.items() + if not (CELLS / n).exists() + or (CELLS / n).read_text(encoding='utf-8') != s] + extra = sorted(on_disk - set(files)) + if not MANIFEST.exists() or MANIFEST.read_text(encoding='utf-8') != manifest: + stale.append('_manifest.py') + if stale or extra: + print('src/maplepy/_cells/ is out of date with the notebooks:') + for n in stale: + print(f' changed {n}') + for n in extra: + print(f' extra {n}') + print('Run: python tools/build_engine.py') + return 1 + print(f'src/maplepy/_cells/ matches MaplePy.ipynb and Hopper.ipynb ' + f'({len(files)} cells).') + return 0 + for n in on_disk - set(files): + (CELLS / n).unlink() + for n, s in files.items(): + (CELLS / n).parent.mkdir(parents=True, exist_ok=True) + (CELLS / n).write_text(s, encoding='utf-8', newline='\n') + MANIFEST.write_text(manifest, encoding='utf-8', newline='\n') + print(f'Wrote {len(files)} cells to {CELLS.relative_to(ROOT)} ' + f'and {MANIFEST.relative_to(ROOT)}.') + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tools/equivalence.py b/tools/equivalence.py new file mode 100644 index 0000000..08d6cb2 --- /dev/null +++ b/tools/equivalence.py @@ -0,0 +1,140 @@ +"""Show that the package gives the notebooks' results on a folder of CIFs. + + python tools/equivalence.py my_cifs/ [--ox Ba=2,Ti=4,O=-2] [--keep DIR] + +Copies the folder twice. On one copy it runs MaplePy.ipynb and then +Hopper.ipynb headless, top to bottom, with two edits only: MAPLE_CIF_DIR and +MAPLE_DIR_OVERRIDE are set to the folders, so that no dialog opens. On the +other it runs `maplepy.run_folder()` and `maplepy.additivity()`. Then it +compares the MaplePy CSVs (results, summary, failures) and Hopper's +additivity_classified.csv cell by cell. One thing is normalised: the order +of the elements listed in an oxidation-state error, which comes from a set +and so differs from one Python process to the next. + +Where Tk is not installed (a headless Linux Python, for one), a stand-in +`tkinter` module is put in place before the notebooks run: with the folders +set, neither notebook calls it. + +Needs nbclient, nbformat and ipykernel (pip install nbclient ipykernel). +Exits 0 when everything matches. The CIFs are only read. +""" + +import argparse +import shutil +import sys +import tempfile +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +TK_STAND_IN = '''import sys, types +try: + import tkinter +except ImportError: # tools/equivalence.py: the folders are set, so the + _tk = types.ModuleType("tkinter") # dialogs are never called + _tk.filedialog = types.ModuleType("tkinter.filedialog") + sys.modules["tkinter"] = _tk + sys.modules["tkinter.filedialog"] = _tk.filedialog +''' + + +def _set(nb, old, new): + hits = [c for c in nb.cells if c.cell_type == 'code' and old in c.source] + assert len(hits) == 1, f'{old!r} found in {len(hits)} cells' + hits[0].source = hits[0].source.replace(old, new, 1) + + +def run_notebooks(cif_dir, work, ox): + import nbformat + from nbclient import NotebookClient + shutil.copytree(ROOT / 'data', work / 'data', dirs_exist_ok=True) + mp = nbformat.read(ROOT / 'MaplePy.ipynb', as_version=4) + _set(mp, 'MAPLE_CIF_DIR = None ', f'MAPLE_CIF_DIR = {str(cif_dir)!r} ') + if ox: + _set(mp, 'OXIDATION_STATES = {}\n', f'OXIDATION_STATES = {ox!r}\n') + mp.cells.insert(0, nbformat.v4.new_code_cell(TK_STAND_IN)) + NotebookClient(mp, timeout=None, kernel_name='python3', + resources={'metadata': {'path': str(work)}}).execute() + run = sorted(cif_dir.glob('outputs_*'))[-1] + hp = nbformat.read(ROOT / 'Hopper.ipynb', as_version=4) + _set(hp, 'MAPLE_DIR_OVERRIDE = None ', f'MAPLE_DIR_OVERRIDE = {str(run)!r} ') + hp.cells.insert(0, nbformat.v4.new_code_cell(TK_STAND_IN)) + NotebookClient(hp, timeout=None, kernel_name='python3', + resources={'metadata': {'path': str(work)}}).execute() + return run + + +def run_package(cif_dir, ox): + import maplepy + run = maplepy.run_folder(cif_dir, oxidation_states=ox) + maplepy.additivity(run) + return run + + +def _sorted_lists(col): + import re + return col.astype(str).map(lambda t: re.sub( + r"\[([^\]]*)\]", + lambda m: '[' + ', '.join(sorted(m.group(1).split(', '))) + ']', t)) + + +def compare(a, b): + import pandas as pd + bad = [] + for name in ('maple_results.csv', 'maple_summary.csv', 'maple_failed.csv', + 'additivity_classified.csv'): + fa, fb = a / name, b / name + if not fa.exists() and not fb.exists(): + continue + if fa.exists() != fb.exists(): + bad.append(f'{name}: written by only one of the two') + continue + da, db = pd.read_csv(fa), pd.read_csv(fb) + if name == 'maple_failed.csv': + # load_structure() lists the elements it could not assign from a + # set, whose order differs from one Python process to the next + da['error'], db['error'] = _sorted_lists(da['error']), \ + _sorted_lists(db['error']) + if list(da.columns) != list(db.columns) or da.shape != db.shape: + bad.append(f'{name}: columns or shape differ') + continue + diff = ~((da == db) | (da.isna() & db.isna())) + n = int(diff.values.sum()) + print(f' {name:28s} {da.shape[0]:5d} rows ' + f'{"identical" if not n else f"{n} cells differ"}') + if n: + bad.append(f'{name}: {n} cells differ') + return bad + + +def main(argv=None): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument('folder') + ap.add_argument('--ox', help='oxidation states for every CIF, e.g. ' + 'Ba=2,Ti=4,O=-2') + ap.add_argument('--keep', help='keep the two runs in this folder') + a = ap.parse_args(argv) + from maplepy.cli import _parse_ox + ox = _parse_ox(a.ox) if a.ox else None + src = Path(a.folder).resolve() + tmp = Path(a.keep) if a.keep else Path(tempfile.mkdtemp()) + nb_dir, pk_dir = tmp / 'notebook', tmp / 'package' + for d in (nb_dir, pk_dir): + d.mkdir(parents=True, exist_ok=True) + for f in src.glob('*.cif'): + shutil.copy2(f, d / f.name) + print(f'{len(list(src.glob("*.cif")))} CIFs from {src}') + print('running the notebooks ...') + ra = run_notebooks(nb_dir, tmp, ox) + print('running the package ...') + rb = run_package(pk_dir, ox) + bad = compare(ra, rb) + if not a.keep: + shutil.rmtree(tmp, ignore_errors=True) + print('The package matches the notebooks.' if not bad + else 'DIFFERENCES:\n ' + '\n '.join(bad)) + return 1 if bad else 0 + + +if __name__ == '__main__': + sys.exit(main())