PowderLine: a programmatic powder diffraction analysis application

PowderLine: a programmatic powder diffraction

arXiv:2608.17009v1 [cond-mat.mtrl-sci] 17 Aug 2026

analysis application Adam A. Corrao a

1

a

, Jennifer A. Perez b , John D. Langhout Thomas A. Caswell a , and Daniel Olds

b

, Megan M. Butala

b

,

a

National Synchrotron Light Source II, Brookhaven National Laboratory, Upton, NY 11973, USA b Materials Science and Engineering, University of Florida, Gainesville, FL 32611, USA

Introduction

Powder diffraction is a foundational materials characterization method that is used routinely in academic, government, and industrial settings across practically all fields, including energy storage, catalysis, pharmaceuticals, ceramics, semiconductors, polymers, mining, minerals, cultural heritage, and cosmetics (Kaduk et al., 2021). While it is often used as a material fingerprinting technique through phase identification and pattern matching tools, there is rich structural, chemical, and morphological information embedded in the positions, intensities, and shapes (i.e., profiles) of diffraction peaks. This includes the unit cell description and lattice parameters, atomic positions, site occupancies, chemical substitution and disorder, relative phase fractions, and microstructural details like crystallite size and shape, lattice microstrain, and stacking faults. Determining and quantifying the features present is the central goal of quantitative powder diffraction analysis. Extracting this quantitative information typically requires modeling the full diffraction pattern, most commonly through Rietveld refinement (Rietveld, 1969; Young, 1993). Whole-pattern fitting methods are mature and capable, but obtaining reliable results can require considerable expertise. A given fits refinement strategy is often informed by a mixture of experience, chemical intuition, and trial-and-error. Such approaches are a poor match for high-throughput experiments and autonomous self-driving laboratories, which can generate volumes of data at rates incompatible with conventional hand driven analysis approaches (Szymanski et al., 2023; Yotsumoto et al., 2024; Corrao et al., 2025). Machine learning (ML) and artificial intelligence (AI) have been applied to powder diffraction analysis with considerable success on specific tasks, including phase identification and classification (Maffettone et al., 2021; Szymanski et al., 2024; Ozaki et al., 2025), phase quantification and microstructure estimation from known structures and simulated patterns (Dong et al., 2021; Souesme et al., 2026), and crystal structure determination with generative models (Riesel et al., 2024; Li

1

et al., 2025; Li et al., 2026). However, these models are typically trained for narrow, well-defined tasks, and they do not yet generalize to the diversity of materials encountered in practice (Szymanski et al., 2021; Leeman et al., 2024; Rincón et al., 2025). For example, a measured pattern may correspond to a material that is not yet present in structural databases, distinct structures can produce closely similar patterns, and a single structure type can span a wide range of compositions and chemistries. Real samples add further complexity through the nearly unlimited space of secondary phases, phase mixtures, and intricate features such as chemical order/disorder and anisotropic peak broadening, all of which affect diffraction peak intensities, positions, and shapes (Yanxon et al., 2023; Yadav et al., 2026). These factors make it difficult to train a model that generalizes across phase spaces, crystal systems, and the diversity of features in diffraction data (Schuetzke et al., 2021). Traditional whole pattern fitting methods remain essential for reliable quantitative analysis, and automating such methods is what such emerging workflows require (Mun et al., 2026). Several programmatic and automated approaches to Rietveld refinement have been developed to address these needs. These include control-file driven programs (e.g., TOPAS, FullProf, and BGMN) (Coelho, 2018; Rodrı́guez-Carvajal, 1993; Doebelin & Kleeberg, 2015), scriptable interfaces to established refinement programs (e.g., GSAS-II) (Toby & Dreele, 2013; O’Donnell et al., 2018), automation layers that wrap these programs for batch and parallel processing (e.g., MILK and Spotlight) (Savage et al., 2023; Biwer et al., 2025), and pipelines that couple refinement to automated phase identification (e.g., DARA) (Fei et al., 2026). While these approaches effectively serve the workflows they were built for, they do not establish a generalized approach to how a refinement is specified and executed. To the best of our knowledge, no powder diffraction analysis software currently provides a single validated, machine-writable description of a refinement that can serve as common input for people and automated workflows alike. We developed PowderLine to close this gap and provide a composable, extensible, and scalable approach to powder diffraction analysis. PowderLine encapsulates a complete refinement into a single recipe written in JSON. PowderLine can validate the recipe against a versioned schema, execute it through supported software (currently supported includes GSAS-II and TOPAS), and return the refinement results as structured Python objects. This enables controlled and reproducible runs whether refinements are hand-executed by humans, run as part of an automated workflow, or orchestrated by AI agents. In this paper, we describe the design of PowderLine and its recipe schema, demonstrate its use for a multi-phase refinement on a disordered rocksalt cathode materials, and discuss how PowderLine enables future applications.

2

2

Architecture and design of PowderLine

2.1

Design philosophy and overview

PowderLine was developed around the core idea that a complete refinement should be fully encapsulated in a single declarative recipe that conforms to a versioned schema. The three main parts of a recipe are the diffraction data, the refinement model, and metadata (Figure 1). Metadata required by PowderLine are the specific schema and the schema version. Beyond these requirements, Powderline supports additional user-defined metadata that can be generated upstream of analysis such as refinement intent, sample provenance, measurement conditions, and the recipe generation method. The result is a metadata-rich dataset suitable for downstream statistical analysis and interpretation. By version controlling the schema, refinement models can evolve as new features are added to PowderLine. All schemas are fully documented and versioned, making PowderLine extensible and refinements reproducible. Powderline is an application that interfaces with and drives refinement engines, providing programmatic use of the existing capabilities in analysis software. It composes directly with the scientific Python ecosystem (e.g., NumPy, SciPy, pandas), keeps data flow in memory, and both ingests and returns structured data types. This makes PowderLine easy to integrate with databases, analysis dashboards, and AI agents. A single recipe fully specifies a refinement, and the same recipe produces the same result whether it is executed by a person, as part of a script, a workflow, or by an AI agent.

2.2

Recipe schema

A PowderLine recipe is a single JSON document with a hierarchical structure (see Figure 2). At the top level a schema name specifies the workflow (Rietveld refinement or single-peak fitting), a schema version ties the recipe to a validated schema, and a payload expresses the refinement relative to the schema and version. The payload organizes the refinement into named blocks that correspond to the familiar ingredients of a whole-pattern fit such as the phases and their parameterization, background model(s), and the refinement controls. The payload also includes components that are typically file-bound such as the diffraction data, instrument details (e.g., instrument profile function), and crystal structure info. Rather than a sequence of software-specific commands, the recipe is a structured description of the analysis. An excerpt from an example recipe for fitting diffraction data on a LaB6 standard reference material is shown in Figure 2, demonstrating how a real refinement is specified (left) and how this corresponds to the hierarchical schema (right). Refinable parameters are represented throughout the schema in a single standard form, the Pydantic RefinementParameterModel, which pairs a value with a refine flag and optional bounds. The bracketed [value, refine flag, ...] fields in Figure 2 show this in use for several parameters, such as the Gaussian instrumental broadening parameters (U, V, W), the LaB6 phase scale factor, 3

Figure 1: PowderLine workflow diagram that shows the encapsulation of a refinement within a JSON recipe. and boron’s non-special z atomic coordinate. This approach provides a consistent way to state which parameters are fixed and which are refined. Refine flags are set per parameter, and when needed PowderLine implements the constraint logic required to reflect that. For example, a user can simply specify the refinement of an individual lattice parameter (e.g., hold a, refine c for a tetragonal cell) or atomic coordinate directly.

2.3

Validation

PowderLine validates every recipe against its schema before a refinement runs, confirming that the fields required for the chosen workflow are present and that all fields in the recipe are well formed. For example, a Rietveld recipe must define at least one phase and the instrument profile function, while a single-peak fitting recipe must not contain phases. Individual values provided through the RefinementParameterModel are also checked against parameter-specific constraints that we impose, such as positive unit cell lengths and cell angles between 0 and 180 degrees. When a recipe violates one of these rules, validation fails before any computation and returns a specific message that identifies the offending field and the reason (e.g., size or strain broadening defined without specifying a model). To that end, every recipe must state the version it was written against: a recipe whose version PowderLine does not support is rejected outright. This ensures the intent of a recipe is unambiguous

4

Figure 2: Left: Example JSON recipe for fitting powder diffraction data collected on LaB6 (NIST SRM 660c, P m3̄m, a = 4.15682(6)) to determine the instrument profile contribution. Right: corresponding schema hierarchy that the example recipe follows. and reproducible as the schema evolves. Validation can also be done separately from a refinement run, allowing a recipe to be checked before it is submitted for computation. This is particularly useful when recipes are generated programmatically.

2.4

Execution modes

Once validated, a recipe is executed by constructing the refinement from the recipe’s contents. This involves a translation layer between the recipe and the specific refinement software’s requirements. The user prepares no separate input files and parses no output. When on-disk resources are required by the refinement program (e.g., project files for GSAS-II, input files for TOPAS), PowderLine manages temporary files and reads results back directly. The files can optionally be saved if a user wished to retrieve the refinement artifacts for inspection or debugging.

5

Two execution modes are currently available through PowderLine: a direct mode that loads the refinement software for each run, and a persistent server mode via FastAPI that keeps the refinement software alive across many refinements. Each recipe is self-contained, so refinements are independent of one another and can be run in parallel, which supports scalable, high-throughput analysis.

2.5

Outputs

A completed refinement returns its results as standard Python variables such as structured tables, scalars, and arrays. These results include the fit profile as well as all refined parameters with estimated standard deviations (ESDs). In this way, descriptors of a refinement are immediately available for further analysis and interpretation. This decoupling of analysis intent from the inner workings of the specific software means that the refinement package does not impose its unique file formats or input/output handling on the rest of the workflow. As a result, interactive sessions, scripts, and automated workflows can consume refinement results identically, removing the typical friction encountered when integrating analysis software.

3

Worked example: a disordered rocksalt cathode material

We demonstrate PowderLine for the analysis of synchrotron X-ray powder diffraction data from a disordered rocksalt (DRX) cathode material with a nominal composition of Li1.2 Mn0.4 Mg0.2 W0.2 O2 that was measured in a previous study (Langhout et al., 2026) on the Pair-Distribution Function (PDF, 28-ID-1) beamline at the National Synchrotron Light Source II (NSLS-II). The data was measured in a 1 mm Kapton® capillary under ambient conditions under typical beamline operation (λ = 0.1665 Å). The sample contains two crystalline phases, the DRX phase of interest (facecentered cubic, F m3̄m) and a secondary Li4 MgWO6 phase (monoclinic, C2/m) formed during solid-state synthesis. The complete two-phase refinement is expressed as a single recipe. This includes the measured data, the instrument profile function, a six-term Chebyshev background, each of the phases structural models, and the parameters to be refined. We chose to refine for each phase its scale factor, lattice parameters, and strain broadening, while the instrument parameters and the atomic structure (positions, occupancies, and displacement parameters) were fixed (full recipe provided in SI). The refinement was carried out with a single call to PowderLine, which validated the recipe, ran the refinement, and returned the results. The fit profile (see Figure 3) shows good agreement between the measured (black) and calculated (red) patterns with a reasonable background model (blue) and minimal difference (grey) across the full pattern, further supported by the weighted-profile R-factor (R wp ) of 8.46%. PowderLine returned the quantitative descriptors of the sample, including the lattice parameters and peak broadening terms with ESDs for each phase, along with the the refined scale factors which were

6

then used to calculate relative phase fractions (see Table 1). This demonstrates that a single recipe can drive a multi-phase refinement, with PowderLine returning structured outputs for direct use.

Figure 3: Fit quality from a 2-phase refinement on synchrotron X-ray powder diffraction data collected on a disordered rocksalt cathode material with a nominal composition of Li1.2 Mn0.4 Mg0.2 W0.2 O2 . Weighted profile R-factor (R wp ) = 8.46%.

Table 1: Refined structural and microstructural parameters with estimated standard deviations for the two crystalline phases fit in the synchrotron diffraction data on a disordered rocksalt cathode sample. Parameters extracted from a single two-phase Rietveld refinement executed with PowderLine. The weighted-profile R-factor for the refinement is Rwp = 8.46%. Parameter

Phase 1 (DRX)

Phase 2

Li1.2 Mn0.4 Mg0.2 W0.2 O2

Li4 MgWO6

Cubic (F m3̄m)

Monoclinic (C2/m)

a (Å)

4.1832(7)

5.1301(24)

b (Å)

—

8.7881(5)

c (Å)

—

5.1024(23)

β (◦ )

—

110.791(6)

Microstrain (%)

0.0133(4)

0.0110(1)

Phase fraction (wt.%)

32.0(7)

68.0(7)

7

4

Requirments and performance

4.1

Machine and software requirements

PowderLine runs on Linux and Windows, requires Python 3.10 or later, either a pinned build of GSAS-II or local TOPAS installation, and is installed as a reproducible software environment managed by Pixi (Fischer et al., 2025). PowderLine and its direct dependencies have a memory footprint of approximately 80 MB. The refinement engine and execution add additional overhead (e.g., loading the GSAS-II engine adds about 70 MB, and a complete refinement peaks near 240 MB).

4.2

Execution speed and server mode

Reusing a refinement program through the persistent server mode (Section 2.4) has been seen to provide a significant increase in calculation speed (e.g., up to a tenfold speedup for single-phase fit with 30 or less parameters), measured on a 16-core Xeon virtual machine with 23 GB of RAM. This speedup is largest for quick, simple refinements, where engine startup would otherwise dominate the total runtime, and it diminishes as the refinement itself becomes more expensive. Running the software as a long-lived service also allows refinement to be managed and scaled with standard process-orchestration tooling (e.g., Kubernetes). Each recipe is self-contained and returns its results in memory, so refinements remain independent of one another, and many patterns can be processed concurrently with throughput that scales with the number of available workers.

5

Conclusions and outlook

We developed PowderLine, a Python application that expresses a whole-pattern fit to powder diffraction data as a single declarative recipe, validates it against a versioned schema, and executes it through a refinement program to return structured results. The composability of PowderLine allows powder diffraction analysis to be done identically in varied environments, such as interactive work at a terminal, interactive notebooks, scripts, pipelines, and automated workflows. Through PowderLine’s API coding agents are able to interface with refinement engines, bespoke graphical user interfaces can be rapidly developed, and custom analysis pipelines can be created while reusing common infrastructure. At NSLS-II, we expect to use PowderLine extensively at Bluesky-enabled powder diffraction beamlines (Allan et al., 2019). For beamline operations PowderLine enables tools for automated instrument calibration and anomaly detection (e.g., instrument geometry has changed), as well as real-time data analysis via an API call. AI-driven workflows can thus be conditioned on reproducible diffraction results, and rich measurement metadata can be captured along with the sample provenance and analysis inputs/outputs. PowderLine can also be used as a simulation engine to generate training data for AI/ML models, and those models can then slot into full stack appli-

8

cations for automated analysis. PowderLine’s open development invites community-contributed extensions to both its capabilities and supported refinement software, as well as integration with data-acquisition systems.

Acknowledgements The authors thank Dr. Saul Lapidus and Dr. Zhuo Li for their valuable feedback.

Funding This research was supported by DOE/Basic Energy Sciences under the Genesis Mission BES AI Pathfinder Program, Integrated Scientific Agentic AI for Catalysis (ISAAC).This research used resources of the National Synchrotron Light Source II, a U.S. Department of Energy (DOE) Office of Science User Facility operated for the DOE Office of Science by Brookhaven National Laboratory under Contract No. DE-SC0012704. Conflicts of interest: The authors declare no conflicts of interest. Data availability: PowderLine is open-source software released under the BSD-3-Clause license, and its source code, documentation, and worked examples are available at https://github.com/NSLS2/PowderLine. Hosted documentation is available at https://powderline.readthedocs.io/. The repository is publicly available, and questions, bug reports, and contributions are handled through GitHub or by contacting the corresponding author.

References Allan, D., Caswell, T., Campbell, S. & Rakitin, M. (2019). Synchrotron Radiation News, 32(3), 19–22. https://doi.org/10.1080/08940886.2019.1608121 Biwer, C. M., Feng, Z., Finstad, D., McDonnell, M., Knezevic, M., McKerns, M., Savage, D. J. & Vogel, S. C. (2025). Scientific Reports, 15. Coelho, A. A. (2018). Journal of Applied Crystallography, 51, 210–218. https://scripts.iucr.org/cgi-bin/paper?S1600576718000183 Corrao, A. A., Maffettone, P. M., Ravel, B., Caswell, T. A., Campbell, S. I., Joress, H., Wilkins, S. & Olds, D. (2025). arXiv preprint arXiv:2509.22959. Doebelin, N. & Kleeberg, R. (2015). Journal of Applied Crystallography, 48, 1573–1580. Dong, H., Butler, K. T., Matras, D., Price, S. W. T., Odarchenko, Y., Khatry, R., Thompson, A., Middelkoop, V., Jacques, S. D. M., Beale, A. M. & Vamvakeros, A. (2021). npj Computational Materials, 7, 74. Fei, Y., McDermott, M. J., Rom, C. L., Wang, S. & Ceder, G. (2026). Chemistry of Materials, 38, 1364–1376. Fischer, T., Vollprecht, W., Zalmstra, B., Arts, R., de Jager, T., Fontan, A., Hines, A. D., Milford, M., Traversaro, S., Claes, D. & Raine, S., (2025). Pixi: Unified software development and distribution for robotics and ai. https://arxiv.org/abs/2511.04827 Kaduk, J. A., Billinge, S. J. L., Dinnebier, R. E., Henderson, N., Madsen, I., Černý, R., Leoni, M., Lutterotti, L., Thakral, S. & Chateigner, D. (2021). Nature Reviews Methods Primers, 1, 77. Langhout, J. D., Perez, J. A., Corrao, A. A., Israel, A., Jaquith, J., Kim, J., Rigdon, E., Schipf, K., Vlahos, N., Nino, J. C., Olds, D. P. & Butala, M. M., (2026). Chemical characteristics driving formability in li-excess disordered rocksalt cathodes. ChemRxiv preprint. 9

Leeman, J., Liu, Y., Stiles, J., Lee, S. B., Bhatt, P., Schoop, L. M. & Palgrave, R. G. (2024). PRX Energy, 3. Li, Q., Guo, M., Jiao, R., Gao, J., Xu, F., Xue, H., Zhang, W., Huang, W., Yan, J., Zhang, L., Wang, C., Yan, Z., Ke, G., E, W., Tang, Z., Jin, S. & Yao, L., (2026). Experimental powder x-ray diffraction crystal structure determination with realpxrd-solver. ArXiv:2603.00965; RealPXRD-Solver. https://arxiv.org/abs/2603.00965 Li, Q., Jiao, R., Wu, L., Zhu, T., Huang, W., Jin, S., Liu, Y., Weng, H. & Chen, X. (2025). Nature Communications, 16, 7428. Maffettone, P. M., Banko, L., Cui, P., Lysogorskiy, Y., Little, M. A., Olds, D., Ludwig, A. & Cooper, A. I. (2021). Nature Computational Science, 1, 290–297. Mun, S. J., Nam, Y. & Choi, S. (2026). Journal of Applied Crystallography, 59, 564–577. O’Donnell, J. H., Dreele, R. B. V., Chan, M. K. Y. & Toby, B. H. (2018). Journal of Applied Crystallography, 51, 1244–1250. Ozaki, H., Ishida, N. & Kiyobayashi, T. (2025). Journal of Applied Crystallography, 58, 718–730. Riesel, E. A., Mackey, T., Nilforoshan, H., Xu, M., Badding, C. K., Altman, A. B., Leskovec, J. & Freedman, D. E. (2024). Journal of the American Chemical Society, 146, 30340–30348. Rietveld, H. M. (1969). Journal of Applied Crystallography, 2, 65–71. https://scripts.iucr.org/cgi-bin/paper?S0021889869006558 Rincón, S., González, G., Macı́as, M. A. & Arbeláez, P. (2025). Scientific Data, 12. Rodrı́guez-Carvajal, J. (1993). Physica B: Condensed Matter, 192, 55–69. Savage, D. J., Lutterotti, L., Biwer, C. M., McKerns, M., Bolme, C., Knezevic, M. & Vogel, S. C. (2023). Journal of Applied Crystallography, 56, 1277–1286. Schuetzke, J., Benedix, A., Mikut, R. & Reischl, M. (2021). IUCrJ, 8, 408–420. Souesme, A., Guinebretière, R., Castelnau, O. & Boulle, A. (2026). Machine Learning: Science and Technology, 7, 025054. Szymanski, N. J., Bartel, C. J., Zeng, Y., Tu, Q. & Ceder, G. (2021). Chemistry of Materials, 33, 4204–4215. Szymanski, N. J., Fu, S., Persson, E. & Ceder, G. (2024). npj Computational Materials, 10, 45. Szymanski, N. J., Rendy, B., Fei, Y., Kumar, R. E., He, T., Milsted, D., McDermott, M. J., Gallant, M., Cubuk, E. D., Merchant, A., Kim, H., Jain, A., Bartel, C. J., Persson, K., Zeng, Y. & Ceder, G. (2023). Nature, 624, 86–91. Toby, B. H. & Dreele, R. B. V. (2013). Journal of Applied Crystallography, 46, 544–549. https://scripts.iucr.org/cgi-bin/paper?S0021889813003531 Yadav, L., Cheng, Y. & Doucet, M., (2026). Automated multiphase identification and refinement in powder diffraction using mismatch-tolerant machine learning. ArXiv:2605.12478. https://arxiv.org/abs/2605.12478 Yanxon, H., Weng, J., Parraga, H., Xu, W., Ruett, U. & Schwarz, N. (2023). Journal of Synchrotron Radiation, 30, 137–146. Yotsumoto, Y., Nakajima, Y., Takamoto, R., Takeichi, Y. & Ono, K. (2024). Digital Discovery, 3, 2523–2532. Young, R. A. (1993). The Rietveld Method. Oxford University Press.

10

Related documents

• Diagnosing and narrowing the simulation-to-real gap in powder X-ray diffraction with a wet-dry agentic loop#974557
• 3D electron diffraction for accurate structure analysis of nanoparticles#156208
• From molecules to solids with the DMol3 approach#6957
• Microstructure characterisation and reconstruction of intermetallic particles#365109
• A simple time coarse graining method for molecular dynamics simulations of liquids#624912