docs: US spelling, models refined against data, and review corrections by AdamCorrao · Pull Request #16 · NSLS2/PowderLine

Adam Corrao (AdamCorrao) · 2026-11-06T05:28:02Z

Documentation fixes ahead of moving the v0.2.0 tag.

Front page: "I analyze powder data". Models are refined against data; the same wording is fixed throughout.
US spelling throughout (behavior, catalog, license, modeled, -ize), including the schema descriptions and figure titles the generated pages come from. Recipe unit values such as micrometre are unchanged.
Corrections found in review: the DRX_33 examples that claimed convergence stop at their 5-cycle limit; EB-78's Uiso sign; EB-93 no longer rules out CrysFML's intensity model (its profile mismatch and intensity drift both act on Uiso and were not separated); the LaB6 offset from NIST (parallax, not the wavelength); GSAS-II U, V, W as a variance (8 ln 2 to FWHM²); the anisoADP Uij test; Li1 on 4h; March–Dollase A³; and others.
zero_shift is labeled degrees 2θ, not centidegrees: a 0.05 zero shift moves every LaB6 reflection by exactly +0.05°. Only the unit label changes; recipes and results are unaffected.
The NIST SRM 660c value is quoted as certified, 0.415 682 6 nm ± 0.000 008 nm (expanded uncertainty, k = 2). The comparison's σ (0.00004 Å) was already right; no number changes.

Checks: pixi run test (1848 passed, 23 skipped); GSAS-II schema, unit and zero tests; fields-, catalog- and figures-check; Sphinx -W with no warnings.

- Front page: "I analyze powder data"; models are refined against data, so the same wording fix is made wherever the docs said data, patterns or samples are refined. - US spelling throughout the docs, examples and the generated pages (behavior, catalog, license, modeled, -ize), including the schema descriptions and figure titles they are generated from. Recipe unit values such as `micrometre` are schema values and are unchanged. - One-line science fixes: Li1 is on 4h in C2/m; the March-Dollase correction is A^3; X, Y, Z are in centidegrees; a phase scale is not a mass fraction; Uij refer to a*, b*, c*; ADPs are mean-square displacements; "held" rather than "constrained" for fixed values; EB-75 separates the Lorentz and polarization factors. Assisted-by: claude-code:claude-opus-5-5

- Comparing engines fits the same data with different profile models, not the same model; models are refined against the data. - The three DRX_33 examples that claimed convergence stop at their 5-cycle limit (converged: false). - anisoADP: judge Uij by principal values; U13 is 0.34 Uiso for an isotropic atom in this cell. - EB-78: a refinement compensates the CrysFML drift by lowering Uiso. EB-93 and its copies trace CrysFML's low Uiso to its profile mismatch rather than to its intensity model. - LaB6 offset from the NIST cell: parallax not corrected in the 2D to 1D integration, not the wavelength. - GSAS-II U, V, W give the Gaussian variance; TOPAS and easydiffraction give FWHM^2 (8 ln 2 factor). - Simulation examples: the placeholder data are the measured pattern. - Missed spellings (artifacts, programs), wording nits. Assisted-by: claude-code:claude-opus-5-5

GSAS-II adds Zero to the peak position in degrees. A run of example_LaB6 with zero_shift 0.05 moves every reflection by exactly +0.05° 2θ. Only the unit metadata, the docs and two comments change; recipes and results are unaffected. Assisted-by: claude-code:claude-opus-5-5

The certificate gives 0.415 682 6 nm ± 0.000 008 nm (k = 2). Written as 4.156826(8) Å it read 10x too small. The comparison's sigma (0.00004 Å) was already right, so no number changes; the tables are regenerated with --no-run. Assisted-by: claude-code:claude-opus-5-5

- Quote the certificate as written, 0.415 682 6 nm ± 0.000 008 nm (expanded uncertainty, k = 2). In the docs a value in parentheses is the standard uncertainty, so 4.156826(80) Å read as twice the real s.u. (0.00004 Å, the sigma the comparison already uses). - EB-93 and its copies no longer rule out CrysFML's intensity model: EB-78's drift lowers a refined Uiso in the same direction as the measured 4 %. The profile mismatch and the drift both act on Uiso and were not separated. Assisted-by: claude-code:claude-opus-5-5

Copilot

🟡 Changes recommended

The comparison still categorically rules out an intensity contribution even though the CrysFML profile mismatch and intensity drift were not separated, leaving the paragraph internally inconsistent.

1 open issue

Qualify the claim that peak shape is the sole cause · New

What changed in this PR

This PR improves PowderLine’s documentation and scientific explanations ahead of v0.2.0, with matching updates to schema metadata and generated pages. Refinement calculations and recipe values remain unchanged.

Changes:

Standardizes US spelling and describes models as refined against data.
Corrects scientific explanations, example convergence claims, and the GSAS-II zero_shift unit label.
Refreshes generated field tables, catalog entries, figure titles, and NIST reference wording.

File	Description
`tests/data/ions/README.md`	Uses US spelling.
`src/powderline/gateways/topas/schema.py`	Updates polarization descriptions.
`src/powderline/gateways/gsasii/simulation_builder.py`	Corrects the zero-shift unit comment.
`src/powderline/gateways/gsasii/schema.py`	Labels zero shift in degrees 2θ.
`src/powderline/gateways/easydiffraction/schema.py`	Uses US spelling in a docstring.
`src/powderline/config_loader.py`	Corrects the zero-shift unit comment.
`scripts/gen_example_figures.py`	Generates titles using “gray.”
`scripts/gen_catalog.py`	Generates a US-spelled catalog heading.
`scripts/cross_engine_comparison.py`	Clarifies certified NIST uncertainty wording.
`README.md`	Uses US license spelling.
`examples/example_template/DESCRIPTION.md`	Distinguishes held from refined parameters.
`examples/example_LaB6/DESCRIPTION.md`	Clarifies embedded structure and held parameters.
`examples/example_LaB6_textured/DESCRIPTION.md`	Corrects March–Dollase and broadening descriptions.
`examples/example_LaB6_temperature_series/easydiffraction/README.md`	Uses US spelling.
`examples/example_LaB6_temperature_series/DESCRIPTION.md`	Clarifies sequential refinement and Uiso interpretation.
`examples/example_LaB6_simulation/DESCRIPTION.md`	Explains placeholder data in fit statistics.
`examples/example_DRX_33/DESCRIPTION.md`	Clarifies held atoms and parameter terminology.
`examples/example_DRX_33_strainonly/DESCRIPTION.md`	Corrects convergence and uncertainty descriptions.
`examples/example_DRX_33_simulation/DESCRIPTION.md`	Distinguishes phase scales from mass fractions.
`examples/example_DRX_33_atomrefine/DESCRIPTION.md`	Corrects convergence and Li1 site labeling.
`examples/example_DRX_33_anisoADP/DESCRIPTION.md`	Corrects convergence and displacement-tensor guidance.
`docs/reference/recipe-format.md`	Standardizes US spelling.
`docs/reference/outputs.md`	Renames the native-artifacts heading.
`docs/reference/known-issues.md`	Uses US spelling.
`docs/reference/index.md`	Updates behavior terminology.
`docs/reference/ids.md`	Updates the ID-index title.
`docs/reference/glossary.md`	Clarifies atomic displacement parameters.
`docs/index.md`	Updates reader-facing analysis terminology.
`docs/how-to/simulate.md`	Uses US spelling.
`docs/how-to/sequential-refinement.md`	Describes refining models against successive patterns.
`docs/how-to/run-topas.md`	Uses US license spelling.
`docs/how-to/refine-structure.md`	Describes the stationary correction at r = 1.
`docs/how-to/python-pipelines.md`	Standardizes metadata terminology.
`docs/how-to/index.md`	Clarifies sequential-refinement wording.
`docs/how-to/disorder.md`	Standardizes US spelling.
`docs/how-to/calibrate-instrument.md`	Clarifies parameter refinement and Gaussian-width units.
`docs/how-to/beamline-operation.md`	Uses US wording.
`docs/getting-started/your-own-data.md`	Uses analysis and model-refinement terminology.
`docs/getting-started/index.md`	Updates the tutorial link label.
`docs/getting-started/first-refinement.md`	Updates the next-step link label.
`docs/examples/index.md`	Clarifies calibration and sequential examples.
`docs/engines/topas.md`	Standardizes US spelling.
`docs/engines/index.md`	Updates fitting terminology and US spelling.
`docs/engines/gsasii.md`	Removes zero shift from centidegree quantities.
`docs/engines/easydiffraction.md`	Corrects the Uiso drift explanation.
`docs/development/policies.md`	Updates spelling and matching section links.
`docs/development/contributing.md`	Updates spelling and policy links.
`docs/development/architecture.md`	Standardizes US spelling.
`docs/development/adding-an-engine.md`	Updates spelling and a policy link.
`docs/conf.py`	Updates spelling in a comment only.
`docs/concepts/validation.md`	Standardizes US spelling.
`docs/concepts/results.md`	Uses US catalog spelling.
`docs/concepts/refinement-practice.md`	Clarifies noise, intensity, and model comparisons.
`docs/concepts/recipes.md`	Updates spelling and tutorial terminology.
`docs/concepts/how-powderline-works.md`	Updates catalog and fitting terminology.
`docs/concepts/comparing-engines.md`	Revises NIST, parallax, and Uiso explanations.
`docs/catalog/known_issues.yaml`	Standardizes catalog-source spelling.
`docs/catalog/engine_behaviour.yaml`	Corrects scientific explanations and spelling.
`docs/about/index.md`	Uses US license spelling.
`docs/_generated/known_issues.md`	Reflects catalog spelling changes.
`docs/_generated/ids.md`	Reflects the updated catalog heading.
`docs/_generated/fields_topas_spf.md`	Reflects polarization wording changes.
`docs/_generated/fields_topas_rietveld.md`	Reflects polarization wording changes.
`docs/_generated/fields_gsasii_spf.md`	Shows the corrected zero-shift unit.
`docs/_generated/fields_gsasii_rietveld.md`	Shows the corrected zero-shift unit.
`docs/_generated/fields_easydiffraction_rietveld.md`	Reflects schema-description spelling.
`docs/_generated/examples/example_LaB6.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_textured.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_textured_easydiffraction.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_temperature_series_easydiffraction.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_singlepeakfit.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_simulation.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_ionic.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_ionic_easydiffraction.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_LaB6_easydiffraction.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_DRX_33.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_DRX_33_strainonly.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_DRX_33_simulation.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_DRX_33_easydiffraction.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_DRX_33_atomrefine.svg`	Uses “gray” in the figure title.
`docs/_generated/examples/example_DRX_33_anisoADP.svg`	Uses “gray” in the figure title.
`docs/_generated/eb_topas.md`	Reflects catalog spelling changes.
`docs/_generated/eb_gsasii.md`	Reflects catalog spelling changes.
`docs/_generated/eb_easydiffraction.md`	Reflects polarization and Uiso corrections.
`docs/_generated/eb_all.md`	Reflects catalog spelling changes.
`docs/_generated/cross_engine_comparison.md`	Updates NIST wording and generation provenance.
`docs/_generated/cross_engine_comparison.json`	Updates reference text and generation metadata.
`CONTRIBUTING.md`	Uses US behavior spelling.
`CHANGELOG.md`	Standardizes US spelling.
`AGENTS.md`	Standardizes spelling in contributor guidance.

_{Review effort: Balanced}

CrysFML's remaining 4 % was not separated from its intensity drift (EB-78), so the comparison page and EB-93 no longer rule out an intensity contribution outright. CrysPy's shortfall is still fully explained by the profile. Assisted-by: claude-code:claude-opus-5-5

Copilot

🟢 Approval recommended

The supplied review reports no active issues with the documentation and unit-label updates.

No open issues 🎉

1 resolved since last review

Qualify the claim that peak shape is the sole cause

_{Review effort: Balanced}

Adam Corrao (AdamCorrao) added 5 commits November 5, 2026 22:31

Copilot AI balanced review requested due to automatic review settings November 6, 2026 05:28

Copilot started reviewing on behalf of Adam Corrao (AdamCorrao) November 6, 2026 05:28

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Comment thread docs/concepts/comparing-engines.md Resolved

Copilot AI balanced review requested due to automatic review settings November 6, 2026 05:45

Adam Corrao (AdamCorrao) merged commit e74d2f2 into NSLS2:main Nov 6, 2026
1 check was pending

Copilot started reviewing on behalf of Adam Corrao (AdamCorrao) November 6, 2026 05:45

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Navigation Menu

Repository navigation

docs: US spelling, models refined against data, and review corrections - #16

docs: US spelling, models refined against data, and review corrections#16
Adam Corrao (AdamCorrao) merged 6 commits into
NSLS2:mainfrom
AdamCorrao:docs/us-spelling-and-wording

Adam Corrao (AdamCorrao) commented Nov 6, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Adam Corrao (AdamCorrao) commented Nov 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Adam Corrao (AdamCorrao) commented Nov 6, 2026 •

edited

Loading