xrdkit 0.1.0__tar.gz → 0.2.0__tar.gz

{xrdkit-0.1.0 → xrdkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrdkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Reusable X-ray diffraction analysis toolkit for electroceramics research
 Keywords: x-ray diffraction,XRD,powder diffraction,Rietveld,Le Bail,GSAS-II,materials science,ceramics,crystallography
 Author: Amir Khesro
@@ -36,6 +36,13 @@ A reusable X-ray diffraction analysis toolkit for electroceramics research.
 analysing XRD patterns, so that the same analysis code can be reused across
 projects instead of being copied between one-off scripts.
 
+New here? [docs/USER_GUIDE.md](https://github.com/amirkhesro/xrdkit/blob/main/docs/USER_GUIDE.md) says what data you need, in
+what form, and how to get from a raw scan to each result.
+
+Starting from a machine with nothing installed?
+[docs/GETTING_STARTED.md](https://github.com/amirkhesro/xrdkit/blob/main/docs/GETTING_STARTED.md) sets up Python, xrdkit and
+the folder layout on Windows and macOS.
+
 ## Installation
 
 ```bash
@@ -43,7 +50,8 @@ pip install xrdkit
 ```
 
 Phase matching against the COD needs pymatgen, which comes with the `phases`
-extra:
+extra. It is what Section 6 of [docs/USER_GUIDE.md](https://github.com/amirkhesro/xrdkit/blob/main/docs/USER_GUIDE.md) uses
+to identify the phases in a pattern:
 
 ```bash
 pip install "xrdkit[phases]"
@@ -54,11 +62,46 @@ GSAS-II is optional and is needed only for the Rietveld driver in
 point `XRDKIT_GSAS2_PYTHON` and `XRDKIT_GSAS2_HOME` at it, or leave it at
 `~/gsas2main`. Every other module works without it.
 
+## Commands
+
+`xrdkit COMMAND --help` describes each command in full.
+
+| Command | What it does |
+| --- | --- |
+| `xrdkit init` | start a project: write `xrdkit.toml` and make its folders |
+| `xrdkit add-sample` | add a sample to `xrdkit.toml` |
+| `xrdkit check SCAN` | report the data quality of a scan, with a verdict per workflow |
+| `xrdkit plot SCAN` | plot one scan, list its peaks, and label them with hkl given a cell |
+| `xrdkit stack SCAN ...` | plot several scans stacked one above the other |
+| `xrdkit density` | theoretical density from a formula and a cell, and relative density |
+| `xrdkit instrument SCAN --cif CIF --cell ...` | instrument parameter file from a standard scan, refined in GSAS-II, with `--name` to record it in `xrdkit.toml` |
+| `xrdkit phases SCAN` | identify the phases against the COD: search by element set, fetch the CIFs, rank the candidates and say what is left over (needs the `phases` extra) |
+| `xrdkit lattice SCAN` | refine the cell of a scan, with its volume and density |
+| `xrdkit lebail SAMPLE` | Le Bail extraction of a sample in GSAS-II, for its cell, to `results/lebail/KEY` |
+| `xrdkit rietveld SAMPLE` | Rietveld refinement of a sample in GSAS-II from its Le Bail result, `--from` and `--through` the modes fixed_atoms, coordinates and occupancies, to `results/rietveld/KEY` |
+
+`lebail` and `rietveld` need GSAS-II (below) and a sample of the project file
+whose instrument gives an `instprm`.
+
+## Feedback and bug reports
+
+Bug reports and feature requests go through GitHub Issues, at
+<https://github.com/amirkhesro/xrdkit/issues>. Questions about method are
+welcome in the same place. Anyone without a GitHub account can send the same
+information by email to <am.khesro@gmail.com>.
+
+A useful report gives the xrdkit version (`python -c "import xrdkit; print(xrdkit.__version__)"`),
+the command you ran, the full error text, and a scan or a small sample file if
+it can be shared.
+
+Please do not attach measured data from unpublished work to a public issue:
+describe the pattern instead, or use a public standard such as LaB6.
+
 ## Data
 
-This repository contains **code only**. Raw and processed diffraction data
-(including `.xrdml` files) live in a separate data repository and are never
-committed here.
+xrdkit ships no data. Your scans, your CIFs and your `xrdkit.toml` live in a
+folder of your own, and the commands write their results and figures beside
+them, under `results/` in that folder.
 
 ## GSAS-II refinement
 
@@ -102,8 +145,9 @@ atoms as it left them, the coordinates it refined and held by site, its
 occupancy constraints, and a sanity check: negative Uiso, occupancies outside
 0 to 1 (and site totals above 1), and sites moved more than `max_shift`
 (fractional) from the reference. With `bonds`, `run_job` adds the final
-model's cation to anion distances (`xrdkit.structure.bond_lengths`, to oxygen
-up to 3 Å by default) to the result.
+model's cation to anion distances (`xrdkit.structure.bond_lengths`, to the
+anions given, the library default O when none are, up to 3 Å by default) to
+the result.
 
 ### What becomes of a stage that goes wrong
 
@@ -181,37 +225,44 @@ structure.
 | --- | --- |
 | `samples.<name>` | `id`, `scan`, `composition` (atoms per formula unit), `structure`, `start_cell` (`{file, model}` or `{a, c}`), `two_theta`, `background` (`{function, terms}`), `refine_microstrain`, `notes`; optionally `followed_reflections`, `trials` (`{runs = [{low, terms}], followed}`), `write_up` (text by mode and section), `unsettled` (the rule for each mode, over the top level one) |
 | `unsettled` | at the top level, the default rule for a stage of each mode that has not settled, `"accept"` (the pipeline's default) or `"reject"`, by the caller's own mode names; each sample carries it merged with its own as its `unsettled` |
-| `structures.<name>` | `cif`, `label`, `phase_name`, `space_group`, `formula_units`, `sites` (`{atoms = {label = element}, wyckoff, kind}`, kind A, B or O), `uiso_groups` (`{name, sites}`), `origin` (`{site, axis}`), `exchange` (`{elements, sites}`), `composition` (`{added = {element = host}}`); optionally `free_coordinates` (by Wyckoff position), `bond_limits` (`{kind = {min, max}}`) |
+| `structures.<name>` | `cif`, `label`, `phase_name`, `space_group`, `formula_units`, `sites` (`{atoms = {label = element}, wyckoff, kind}`, kind a short label such as A, B or O), `uiso_groups` (`{name, sites}`), `origin` (`{site, axis}`), `exchange` (`{elements, sites}`), `composition` (`{added = {element = host}}`); optionally `free_coordinates` (by Wyckoff position), `bond_limits` (`{kind = {min, max}}`) |
 
 From a structure table, `xrdkit.structure.site_setup` finds the sites among a
 phase's atoms as the driver reports them, checking that each site's atoms
 share one position, are of the elements given and have the multiplicity of
 its Wyckoff position, and that no atom is left over. It returns the sites by
 kind, the Uiso groups, the coordinates to refine on each site, the origin site
-and the exchange, in the forms the stage keys above take.
+and the exchange, in the forms the stage keys above take, with the anions and
+the bond limits of each kind: the library entry's when the structure names
+one (`anions`, and `[entry.bond_limits]`, `[min, max]` by kind, read with
+`xrdkit.library.bond_limits`), else O and 1.6 to 3.0 Å, under the structure's
+own `bond_limits`.
 `composition_edits` gives the atom edits that put a nominal composition on
 the sites by the table's rule: each element the CIF holds is scaled by one
 factor over its sites, which keeps its distribution, and each added element
 goes on its host's sites in proportion to the host's occupancy.
 `cell_contents` gives the atoms of each element per cell.
 
-For example, the sample pipeline of the XRD analysis repository reads every
-sample and structure setting from its `config/samples.toml` and runs Le Bail,
-fixed atoms, coordinates and occupancies in turn, each from the saved result
-of the one before:
+## A first run
 
-```
-python -B scripts/refine_sample.py 10                          # Le Bail only
-python -B scripts/refine_sample.py 10 --trials                 # Le Bail with the configured trial ranges and background terms
-python -B scripts/refine_sample.py 10 --through occupancies    # all four modes
-python -B scripts/refine_sample.py 10 --from coordinates       # one mode, from the saved fixed atoms result
-python -B scripts/refine_sample.py 10 --from coordinates --through occupancies
+These five commands run in an empty folder of your own, with the package
+installed and your own scan copied into it:
+
+```bash
+xrdkit init --name demo
+xrdkit add-sample data/raw/sample1.xrdml --structure ttb_p4bm
+xrdkit check sample1
+xrdkit lattice sample1
+xrdkit lebail sample1
 ```
 
-It passes each mode's `unsettled` rule and pass cap to its job, writes the
-mode's write up with `failure_markdown` and stops with a non-zero status
-where a mode cannot be finished, and writes `summary.md` beside the write
-ups with `summary_markdown` at the end of every run.
+`init` writes `xrdkit.toml` and makes its folders. `add-sample` appends a
+`[samples.sample1]` table naming the scan. `check` reports the data quality of
+the sample's scan with a verdict per workflow. `lattice` refines its cell,
+volume and density to `results/lattice/sample1`. `lebail` extracts the cell in
+GSAS-II to `results/lebail/sample1`. Fill in the instrument and structure
+tables that `init` leaves commented in `xrdkit.toml` before adding a sample;
+`check` and `lattice` also take a scan file in place of a sample key.
 
 ## Status
 
@@ -221,9 +272,9 @@ notice.
 ## Citing
 
 If xrdkit contributes to work you publish, please cite it. The metadata is in
-[CITATION.cff](CITATION.cff), which GitHub renders as a ready-made citation
+[CITATION.cff](https://github.com/amirkhesro/xrdkit/blob/main/CITATION.cff), which GitHub renders as a ready-made citation
 under **Cite this repository**.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/amirkhesro/xrdkit/blob/main/LICENSE).

{xrdkit-0.1.0 → xrdkit-0.2.0}/README.md

@@ -6,6 +6,13 @@ A reusable X-ray diffraction analysis toolkit for electroceramics research.
 analysing XRD patterns, so that the same analysis code can be reused across
 projects instead of being copied between one-off scripts.
 
+New here? [docs/USER_GUIDE.md](https://github.com/amirkhesro/xrdkit/blob/main/docs/USER_GUIDE.md) says what data you need, in
+what form, and how to get from a raw scan to each result.
+
+Starting from a machine with nothing installed?
+[docs/GETTING_STARTED.md](https://github.com/amirkhesro/xrdkit/blob/main/docs/GETTING_STARTED.md) sets up Python, xrdkit and
+the folder layout on Windows and macOS.
+
 ## Installation
 
 ```bash
@@ -13,7 +20,8 @@ pip install xrdkit
 ```
 
 Phase matching against the COD needs pymatgen, which comes with the `phases`
-extra:
+extra. It is what Section 6 of [docs/USER_GUIDE.md](https://github.com/amirkhesro/xrdkit/blob/main/docs/USER_GUIDE.md) uses
+to identify the phases in a pattern:
 
 ```bash
 pip install "xrdkit[phases]"
@@ -24,11 +32,46 @@ GSAS-II is optional and is needed only for the Rietveld driver in
 point `XRDKIT_GSAS2_PYTHON` and `XRDKIT_GSAS2_HOME` at it, or leave it at
 `~/gsas2main`. Every other module works without it.
 
+## Commands
+
+`xrdkit COMMAND --help` describes each command in full.
+
+| Command | What it does |
+| --- | --- |
+| `xrdkit init` | start a project: write `xrdkit.toml` and make its folders |
+| `xrdkit add-sample` | add a sample to `xrdkit.toml` |
+| `xrdkit check SCAN` | report the data quality of a scan, with a verdict per workflow |
+| `xrdkit plot SCAN` | plot one scan, list its peaks, and label them with hkl given a cell |
+| `xrdkit stack SCAN ...` | plot several scans stacked one above the other |
+| `xrdkit density` | theoretical density from a formula and a cell, and relative density |
+| `xrdkit instrument SCAN --cif CIF --cell ...` | instrument parameter file from a standard scan, refined in GSAS-II, with `--name` to record it in `xrdkit.toml` |
+| `xrdkit phases SCAN` | identify the phases against the COD: search by element set, fetch the CIFs, rank the candidates and say what is left over (needs the `phases` extra) |
+| `xrdkit lattice SCAN` | refine the cell of a scan, with its volume and density |
+| `xrdkit lebail SAMPLE` | Le Bail extraction of a sample in GSAS-II, for its cell, to `results/lebail/KEY` |
+| `xrdkit rietveld SAMPLE` | Rietveld refinement of a sample in GSAS-II from its Le Bail result, `--from` and `--through` the modes fixed_atoms, coordinates and occupancies, to `results/rietveld/KEY` |
+
+`lebail` and `rietveld` need GSAS-II (below) and a sample of the project file
+whose instrument gives an `instprm`.
+
+## Feedback and bug reports
+
+Bug reports and feature requests go through GitHub Issues, at
+<https://github.com/amirkhesro/xrdkit/issues>. Questions about method are
+welcome in the same place. Anyone without a GitHub account can send the same
+information by email to <am.khesro@gmail.com>.
+
+A useful report gives the xrdkit version (`python -c "import xrdkit; print(xrdkit.__version__)"`),
+the command you ran, the full error text, and a scan or a small sample file if
+it can be shared.
+
+Please do not attach measured data from unpublished work to a public issue:
+describe the pattern instead, or use a public standard such as LaB6.
+
 ## Data
 
-This repository contains **code only**. Raw and processed diffraction data
-(including `.xrdml` files) live in a separate data repository and are never
-committed here.
+xrdkit ships no data. Your scans, your CIFs and your `xrdkit.toml` live in a
+folder of your own, and the commands write their results and figures beside
+them, under `results/` in that folder.
 
 ## GSAS-II refinement
 
@@ -72,8 +115,9 @@ atoms as it left them, the coordinates it refined and held by site, its
 occupancy constraints, and a sanity check: negative Uiso, occupancies outside
 0 to 1 (and site totals above 1), and sites moved more than `max_shift`
 (fractional) from the reference. With `bonds`, `run_job` adds the final
-model's cation to anion distances (`xrdkit.structure.bond_lengths`, to oxygen
-up to 3 Å by default) to the result.
+model's cation to anion distances (`xrdkit.structure.bond_lengths`, to the
+anions given, the library default O when none are, up to 3 Å by default) to
+the result.
 
 ### What becomes of a stage that goes wrong
 
@@ -151,37 +195,44 @@ structure.
 | --- | --- |
 | `samples.<name>` | `id`, `scan`, `composition` (atoms per formula unit), `structure`, `start_cell` (`{file, model}` or `{a, c}`), `two_theta`, `background` (`{function, terms}`), `refine_microstrain`, `notes`; optionally `followed_reflections`, `trials` (`{runs = [{low, terms}], followed}`), `write_up` (text by mode and section), `unsettled` (the rule for each mode, over the top level one) |
 | `unsettled` | at the top level, the default rule for a stage of each mode that has not settled, `"accept"` (the pipeline's default) or `"reject"`, by the caller's own mode names; each sample carries it merged with its own as its `unsettled` |
-| `structures.<name>` | `cif`, `label`, `phase_name`, `space_group`, `formula_units`, `sites` (`{atoms = {label = element}, wyckoff, kind}`, kind A, B or O), `uiso_groups` (`{name, sites}`), `origin` (`{site, axis}`), `exchange` (`{elements, sites}`), `composition` (`{added = {element = host}}`); optionally `free_coordinates` (by Wyckoff position), `bond_limits` (`{kind = {min, max}}`) |
+| `structures.<name>` | `cif`, `label`, `phase_name`, `space_group`, `formula_units`, `sites` (`{atoms = {label = element}, wyckoff, kind}`, kind a short label such as A, B or O), `uiso_groups` (`{name, sites}`), `origin` (`{site, axis}`), `exchange` (`{elements, sites}`), `composition` (`{added = {element = host}}`); optionally `free_coordinates` (by Wyckoff position), `bond_limits` (`{kind = {min, max}}`) |
 
 From a structure table, `xrdkit.structure.site_setup` finds the sites among a
 phase's atoms as the driver reports them, checking that each site's atoms
 share one position, are of the elements given and have the multiplicity of
 its Wyckoff position, and that no atom is left over. It returns the sites by
 kind, the Uiso groups, the coordinates to refine on each site, the origin site
-and the exchange, in the forms the stage keys above take.
+and the exchange, in the forms the stage keys above take, with the anions and
+the bond limits of each kind: the library entry's when the structure names
+one (`anions`, and `[entry.bond_limits]`, `[min, max]` by kind, read with
+`xrdkit.library.bond_limits`), else O and 1.6 to 3.0 Å, under the structure's
+own `bond_limits`.
 `composition_edits` gives the atom edits that put a nominal composition on
 the sites by the table's rule: each element the CIF holds is scaled by one
 factor over its sites, which keeps its distribution, and each added element
 goes on its host's sites in proportion to the host's occupancy.
 `cell_contents` gives the atoms of each element per cell.
 
-For example, the sample pipeline of the XRD analysis repository reads every
-sample and structure setting from its `config/samples.toml` and runs Le Bail,
-fixed atoms, coordinates and occupancies in turn, each from the saved result
-of the one before:
+## A first run
 
-```
-python -B scripts/refine_sample.py 10                          # Le Bail only
-python -B scripts/refine_sample.py 10 --trials                 # Le Bail with the configured trial ranges and background terms
-python -B scripts/refine_sample.py 10 --through occupancies    # all four modes
-python -B scripts/refine_sample.py 10 --from coordinates       # one mode, from the saved fixed atoms result
-python -B scripts/refine_sample.py 10 --from coordinates --through occupancies
+These five commands run in an empty folder of your own, with the package
+installed and your own scan copied into it:
+
+```bash
+xrdkit init --name demo
+xrdkit add-sample data/raw/sample1.xrdml --structure ttb_p4bm
+xrdkit check sample1
+xrdkit lattice sample1
+xrdkit lebail sample1
 ```
 
-It passes each mode's `unsettled` rule and pass cap to its job, writes the
-mode's write up with `failure_markdown` and stops with a non-zero status
-where a mode cannot be finished, and writes `summary.md` beside the write
-ups with `summary_markdown` at the end of every run.
+`init` writes `xrdkit.toml` and makes its folders. `add-sample` appends a
+`[samples.sample1]` table naming the scan. `check` reports the data quality of
+the sample's scan with a verdict per workflow. `lattice` refines its cell,
+volume and density to `results/lattice/sample1`. `lebail` extracts the cell in
+GSAS-II to `results/lebail/sample1`. Fill in the instrument and structure
+tables that `init` leaves commented in `xrdkit.toml` before adding a sample;
+`check` and `lattice` also take a scan file in place of a sample key.
 
 ## Status
 
@@ -191,9 +242,9 @@ notice.
 ## Citing
 
 If xrdkit contributes to work you publish, please cite it. The metadata is in
-[CITATION.cff](CITATION.cff), which GitHub renders as a ready-made citation
+[CITATION.cff](https://github.com/amirkhesro/xrdkit/blob/main/CITATION.cff), which GitHub renders as a ready-made citation
 under **Cite this repository**.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/amirkhesro/xrdkit/blob/main/LICENSE).

{xrdkit-0.1.0 → xrdkit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xrdkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Reusable X-ray diffraction analysis toolkit for electroceramics research"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -44,6 +44,9 @@ Repository = "https://github.com/amirkhesro/xrdkit"
 Issues = "https://github.com/amirkhesro/xrdkit/issues"
 Changelog = "https://github.com/amirkhesro/xrdkit/blob/main/CHANGELOG.md"
 
+[project.scripts]
+xrdkit = "xrdkit.cli:main"
+
 [project.optional-dependencies]
 phases = ["pymatgen>=2026.5.4"]
 

{xrdkit-0.1.0 → xrdkit-0.2.0}/pyproject.toml.orig

@@ -1,58 +1,61 @@
-[project]
-name = "xrdkit"
-version = "0.1.0"
-description = "Reusable X-ray diffraction analysis toolkit for electroceramics research"
-readme = "README.md"
-requires-python = ">=3.11"
-license = "MIT"
-license-files = ["LICENSE"]
-authors = [
-    { name = "Amir Khesro", email = "am.khesro@gmail.com" }
-]
-keywords = [
-    "x-ray diffraction",
-    "XRD",
-    "powder diffraction",
-    "Rietveld",
-    "Le Bail",
-    "GSAS-II",
-    "materials science",
-    "ceramics",
-    "crystallography",
-]
-classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Intended Audience :: Science/Research",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Scientific/Engineering :: Physics",
-    "Topic :: Scientific/Engineering :: Chemistry",
-    "Typing :: Typed",
-]
-dependencies = [
-    "matplotlib>=3.11.1",
-    "numpy>=2.0.0",
-    "scipy>=1.13.0",
-]
-
-[project.urls]
-Homepage = "https://github.com/amirkhesro/xrdkit"
-Repository = "https://github.com/amirkhesro/xrdkit"
-Issues = "https://github.com/amirkhesro/xrdkit/issues"
-Changelog = "https://github.com/amirkhesro/xrdkit/blob/main/CHANGELOG.md"
-
-[project.optional-dependencies]
-phases = [
-    "pymatgen>=2026.5.4",
-]
-
-[build-system]
-requires = ["uv_build>=0.12.0,<0.13.0"]
-build-backend = "uv_build"
-
-[dependency-groups]
-dev = [
-    "pytest>=9.1.1",
-]
+[project]
+name = "xrdkit"
+version = "0.2.0"
+description = "Reusable X-ray diffraction analysis toolkit for electroceramics research"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Amir Khesro", email = "am.khesro@gmail.com" }
+]
+keywords = [
+    "x-ray diffraction",
+    "XRD",
+    "powder diffraction",
+    "Rietveld",
+    "Le Bail",
+    "GSAS-II",
+    "materials science",
+    "ceramics",
+    "crystallography",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Typing :: Typed",
+]
+dependencies = [
+    "matplotlib>=3.11.1",
+    "numpy>=2.0.0",
+    "scipy>=1.13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/amirkhesro/xrdkit"
+Repository = "https://github.com/amirkhesro/xrdkit"
+Issues = "https://github.com/amirkhesro/xrdkit/issues"
+Changelog = "https://github.com/amirkhesro/xrdkit/blob/main/CHANGELOG.md"
+
+[project.scripts]
+xrdkit = "xrdkit.cli:main"
+
+[project.optional-dependencies]
+phases = [
+    "pymatgen>=2026.5.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]