Skip to content

About

Desktop application for whole-pattern fitting of powder diffraction data — Rietveld structural refinement, Le Bail and profile refinement (Qt6 GUI, CLI and Python library API).

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

XinRefinement logo

XinRefinement

Chinese (Simplified) · English

Open-source desktop software for whole-pattern fitting of powder diffraction data — Rietveld structural refinement, Le Bail extraction and profile fitting, with a pure-Python computation kernel, a Qt6 GUI, a CLI and a library API.

✅ v1.7.0 (2026-11-14). Rietveld / Le Bail / profile fitting; quantitative phase analysis with e.s.d.; TCH peak shapes, EWIMV or harmonic texture, Popa LB anisotropic size/strain, Brindley micro-absorption and Wyckoff-constrained atomic-coordinate refinement. v1.7.0 adds an opt-in amorphous hump component solved in the linear layer (zero extra nonlinear parameters), fixes two recipe-path switches (refine_asym, and the dead refine_eta slot on the anisotropy path), and keeps the disabled paths bit-for-bit identical to v1.6.4.

Benchmark: 7 real multi-phase patterns, mean Rwp 11.030% vs MAUD 11.203%, every sample within tolerance; 596 passed / 0 skipped tests. Negative experiments are documented alongside the wins, not hidden.

Download v1.7.0 · Changelog · Release notes · MAUD benchmark report · Audit backlog

What XinRefinement does

  • Whole-pattern fitting: Rietveld structural refinement, Le Bail and profile-only fitting on powder diffraction patterns.
  • Quantitative phase analysis: phase mass fractions and estimated standard deviations; text / JSON / HTML reports. The linear layer solves phase scales, background and amorphous-hump amplitude together; R-factors use experimental counting weights by default.
  • Crystal structure: unit-cell refinement, Wyckoff-constrained atomic coordinates (xyz), isotropic temperature factors (ΔB_iso) and site-occupancy handling; CIF input plus a bundled set of common structure CIFs.
  • Profile and microstructure: TCH pseudo-Voigt shapes (tan θ or 1/d width basis), EWIMV / harmonic preferred orientation, Popa LB anisotropic size–strain broadening, Brindley micro-absorption, crystallite size and microstrain.
  • Recipe workflow: staged refinement (zero → background → scale → cell → profile → xyz → micro → B) with a wall-clock budget and responsive cancellation; a single-pass solve is also available.
  • Three entry points: PySide6 / Qt6 GUI, command line, and a stable Python library API (xinrefinement.api.RefineRequest).
  • Project and family interoperability: self-contained .xinr projects, import of XinMatch .xinm phase-analysis results, and 2θ / Q pattern readers including .xy, .xye, .txt, .dat, .csv, .chi and .xrdml.

Design principles

  1. Kernel / GUI decoupled: everything in xinrefinement/core/ is pure computation (numpy arrays and dataclasses), unit-testable without a display; the GUI in xinrefinement/gui/ is a thin layer on top.
  2. Stable external contract: external callers use xinrefinement.api.refine(request); versioned request/response dataclasses with JSON-serialisable as_dict() output keep the engine free to evolve without breaking integrations.
  3. Numerically honest: a golden CLI Rwp (3.4074156640940005) guards the default path, and newly added switches are required to be bit-identical when disabled. Optimisation is checked against MAUD on measured patterns; changes that lower Rwp while drifting QPA are rejected as degenerate solutions.
  4. Verifiable in small steps: pytest acceptance tests accompany each change; GUI smoke tests, cancellation checks and regression fixtures run in the same suite.

Project layout

xinrefinement/
├── core/
│   ├── patterns.py          # pattern readers / 2θ-Q conversion
│   ├── io/                  # .xinm import and exporters
│   ├── profile/             # CIF parsing, peak shapes, Popa LB, naming
│   ├── refine/              # linear + nonlinear solvers, recipe, QPA, e.s.d., diagnostics
│   └── report.py            # report data model and rendering
├── api.py                   # public library API (RefineRequest / RefineResponse)
├── cli/                     # command-line entry point
├── gui/                     # PySide6 GUI (canvas, dialogs, project, workers)
├── data/                    # bundled CIFs and assets
├── registration.py          # licence registration (release build only)
└── build_variant.py         # release / internal build detection
tests/                       # pytest suite, fixtures and golden baseline
tools/                       # benchmark, diagnostics and build scripts
packaging/                   # PyInstaller spec + Inno Setup script
docs/                        # release notes, benchmark and audit reports

Getting started

# Python 3.10 is required
python -m venv .venv
.venv\Scripts\Activate.ps1

# install in editable mode with test dependencies
pip install -e ".[dev]"

# run the full test suite
pytest

Command line

# single-pass refinement
xinrefinement refine pattern.xy rutile.cif anatase.cif --anode Cu -o result.json

# staged recipe with quantitative report and parameter uncertainties
xinrefinement refine pattern.xy rutile.cif anatase.cif `
  --recipe --anode Cu --tmin 5 --tmax 120 --quant --esd --report reports

Run xinrefinement refine --help for all options, including --amorphous 22:9, --texture phase=0,0,1, --aniso-auto, --refine-xyz and --width-basis d.

Library API

from pathlib import Path
from xinrefinement import api

response = api.refine(api.RefineRequest(
    pattern=Path("pattern.xy"),
    cifs=(Path("rutile.cif"), Path("anatase.cif")),
    tmin=5.0,
    tmax=120.0,
))
print(response.rwp, response.as_dict()["phases"])

Run the working tree without building

run_dev.bat runs the current source in place — no PyInstaller build and no install step. With no arguments it opens the GUI; any other arguments are forwarded to the CLI:

run_dev.bat                                              :: GUI
run_dev.bat refine pat.xy phase.cif -o result.json        :: CLI refinement
run_dev.bat --version                                     :: print version

The interpreter is resolved in this order and echoed on startup: %XINREFINEMENT_DEV_PYTHON% → .venv\Scripts\python.exe → venv\Scripts\python.exe → D:\Project\XRD\python310\python.exe → python on PATH.

Builds & registration

Build Artifact Registration Right end of the status bar
Release build (release) XinRefinement-<v>-setup.exe, Windows x64 installer (zh/en/ja) Yes — checked on every launch Registered: <organization/department name> / Unregistered
Internal evaluation build (internal) XinRefinement-internal-<v>-portable.zip None internal evaluation version (bold red)

Current release: v1.7.0 — XinRefinement-1.7.0-setup.exe, SHA256 044641c5c0a48c307a7fe83dad52ff4459c990f0635d8f2a643846d06fdcb765. Only the installer is published; the portable evaluation build is for internal use. Per-version hashes and acceptance results live in CHANGELOG.md and docs/RELEASE-NOTES-1.7.0.md.

When the release build is unregistered, a prompt appears at launch:

This software is not registered — all rights reserved; commercial use is prohibited. For registration, please contact sshztx@outlook.com

Click OK to continue using the software (the prompt returns next launch), or Enter registration code to paste a code. Registration is also available at any time from Help → Enter registration code (&R)…. Codes are generated by the developer from the organisation/department name: PXRD1-XXXX-XXXX-… (Base32 payload UTF8(org name) + HMAC-SHA256[:8]), verified locally without network access or a machine ID; the same organisation can use its code on multiple machines. The production key is embedded in the release build, so codes issued for earlier releases remain valid.

License

This software is distributed under a dual license (Academic + Commercial). Academic research and education are free under the Academic License; commercial use requires a separate written Commercial License from the copyright holder.

About

Desktop application for whole-pattern fitting of powder diffraction data — Rietveld structural refinement, Le Bail and profile refinement (Qt6 GUI, CLI and Python library API).

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages