DFXM-Topographic-Origins

Codebase for: "The topographic origin of chemomechanical failure in high-nickel cathodes revealed by operando dark-field X-ray microscopy"

🔬 Overview

This repository contains the analysis workflow used to deterministically map dislocation nucleation in single-crystal NMC 811. Developed at the BASE Laboratory (University of Greenwich) for data collected at ESRF Beamline ID03, these notebooks process 3D reciprocal space volumes to convert raw diffraction data into quantitative stress maps.

Key Capabilities:

• Kinematic Analysis: Visualisation of intragranular lattice rotation and mosaicity.
• Stress Quantification: Calculation of Geometrically Necessary Dislocation (GND) densities and local stress states (~100 MPa resolution).
• Statistical Validation: Spatial segmentation to isolate "high-strain tails" associated with surface defects.
• Numerical Modelling: Finite Element Analysis (FEA) to define geometric failure thresholds.

---

📓 Notebooks

The analysis is split into four modular notebooks, corresponding to Figures 2, 3, 4, and 5 of the manuscript.

1. 01_Lattice_Rotation_Analysis.ipynb (Figure 2)

Operando Tracking of Defect Nucleation. Visualises the internal lattice evolution of a single primary particle during the initial charge ($3.6$ V $\to$ $3.9$ V).

• Output: Mosaicity maps, Lattice Tilt ($\Delta \mu$) maps, and the defect line profile.
• Key Result: Identifies the discrete rotation step ($\Delta \mu \approx 0.049^{\circ}$) at the surface notch.

2. 02_Stress_and_Failure_Mechanics.ipynb (Figure 3)

The Physics of Failure. Maps the internal strain landscape at the moment of failure to test the geometric hypothesis.

• Output: GND Density maps, KAM maps, and the "Notch vs. Bulk" statistical distributions.
• Key Result: Calculates the local stress concentration and compares it against the yield strength of NMC 811 ($\approx 78$ MPa).

3. 03_Morphological_Control.ipynb (Figure 4)

The Control Experiment. Analysis of a spherical control particle cycled to high voltage ($4.4$ V).

• Output: Comparative histograms and strain maps.
• Key Result: Confirms that in the absence of surface grooves, the lattice remains elastic, proving failure is geometric rather than intrinsic.

4. 04_Finite_Element_Modelling.ipynb (Figure 5)

Theoretical Validation. Processes Finite Element Analysis (FEA) results to quantify the sensitivity of the particle to surface topography.

• Output: Von Mises stress maps and the Defect Tolerance Plot.
• Key Result: Establishes the "Design Rule" that surface roughness must be kept below $<125$ nm to inhibit plastic yielding.

---

🚀 Getting Started

Prerequisites

• Python 3.9+
• JupyterLab or Jupyter Notebook

Installation

# 1. Clone the repository
git clone [https://github.com/BASE-Laboratory/DFXM-Topographic-Origins.git](https://github.com/BASE-Laboratory/DFXM-Topographic-Origins.git)
cd DFXM-Topographic-Origins

# 2. Install dependencies
pip install -r requirements.txt

---

💾 Data Availability

Due to the size of the diffraction volumes, the raw HDF5 data is hosted externally on Zenodo.

Download Data from Zenodo (DOI: 10.5281/zenodo.18348960)

Directory Setup

1. Download the dataset from the link above.
2. Unzip the contents into the Post_processed_data folder in the root of this repository.
3. Ensure your file structure looks like this:

DFXM-Topographic-Origins/
├── 01_Lattice_Rotation_Analysis.ipynb
├── 02_Stress_and_Failure_Mechanics.ipynb
├── 03_Morphological_Control.ipynb
├── 04_Finite_Element_Modelling.ipynb
├── CITATION.cff
├── requirements.txt
└── Post_processed_data/
    ├── 3.9V_layer2_COM_mu.h5
    ├── 3.9V_layer2_mosaicity.h5
    ├── 4.4V_layer1_COM_mu.h5
    ├── shallow_crack.mat
    ├── medium_crack.mat
    ├── deep_crack.mat
    └── ...

---

📜 Citation

If you use this code or methodology in your research, please cite the associated paper:

The topographic origin of chemomechanical failure in high-nickel cathodes revealed by operando dark-field X-ray microscopy J. Le Houx, J. Mistry, Y. Li, L. Lesage, S. Staeck, R. Bird, D. Spencer-Jolly chemRxiv, 2026.

Alternatively, refer to the CITATION.cff file included in this repository.

---

⚖️ License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

BASE Laboratory | JamesLeHoux.com