Add preferred-orientation (March–Dollase) correction for textured powder samples

docs/dev/adrs/index.md

@@ -37,6 +37,7 @@ folders.
 | Experiment model     | Accepted   | Immutable Experiment Type                           | Makes experiment type axes creation-time state rather than mutable runtime state.                                          | [`immutable-experiment-type.md`](accepted/immutable-experiment-type.md)                     |
 | Experiment model     | Accepted   | Automatic Line-Segment Background Estimation        | Detects line-segment background control points from the measured pattern, peak-insensitive and editable.                   | [`background-auto-estimate.md`](accepted/background-auto-estimate.md)                       |
 | Experiment model     | Accepted   | Calculation Without Measured Data                   | Adds a writable `data_range` category so a structure-only experiment is calculable and plottable without loaded data.      | [`calculation-without-measured-data.md`](accepted/calculation-without-measured-data.md)     |
+| Experiment model     | Accepted   | Preferred-Orientation Category                      | Adds a per-phase March–Dollase preferred-orientation category for textured powder refinement on the CrysPy backend.        | [`preferred-orientation-category.md`](accepted/preferred-orientation-category.md)           |
 | Factories            | Accepted   | Factory Contracts and Metadata                      | Standardizes factory construction, metadata, compatibility, and registration behavior.                                     | [`factory-contracts.md`](accepted/factory-contracts.md)                                     |
 | Naming               | Accepted   | Factory Tag Naming                                  | Defines canonical factory tag style and standard abbreviations.                                                            | [`factory-tag-naming.md`](accepted/factory-tag-naming.md)                                   |
 | Persistence          | Accepted   | Free-Flag CIF Encoding                              | Encodes fit free/fixed state through CIF uncertainty syntax instead of a separate free list.                               | [`free-flag-cif-encoding.md`](accepted/free-flag-cif-encoding.md)                           |

docs/dev/package-structure/full.md

@@ -407,6 +407,13 @@
 │   │   │   │   │   └── 🏷️ class TotalGaussianDampedSinc
 │   │   │   │   └── 📄 total_mixins.py
 │   │   │   │       └── 🏷️ class TotalBroadeningMixin
+│   │   │   ├── 📁 pref_orient
+│   │   │   │   ├── 📄 __init__.py
+│   │   │   │   ├── 📄 default.py
+│   │   │   │   │   ├── 🏷️ class PrefOrient
+│   │   │   │   │   └── 🏷️ class PrefOrients
+│   │   │   │   └── 📄 factory.py
+│   │   │   │       └── 🏷️ class PrefOrientFactory
 │   │   │   ├── 📁 refln
 │   │   │   │   ├── 📄 __init__.py
 │   │   │   │   ├── 📄 bragg_pd.py

docs/dev/package-structure/short.md

@@ -193,6 +193,10 @@
 │   │   │   │   ├── 📄 tof_mixins.py
 │   │   │   │   ├── 📄 total.py
 │   │   │   │   └── 📄 total_mixins.py
+│   │   │   ├── 📁 pref_orient
+│   │   │   │   ├── 📄 __init__.py
+│   │   │   │   ├── 📄 default.py
+│   │   │   │   └── 📄 factory.py
 │   │   │   ├── 📁 refln
 │   │   │   │   ├── 📄 __init__.py
 │   │   │   │   ├── 📄 bragg_pd.py

docs/docs/user-guide/analysis-workflow/experiment.md

@@ -281,7 +281,28 @@ project.experiments['hrpt'].background.auto_estimate(n_points=10)
 project.experiments['hrpt'].linked_phases.create(id='lbco', scale=10.0)
 ```
 
-### 6. Measured Data Category { #measured-data-category }
+### 6. Preferred Orientation Category { #preferred-orientation-category }
+
+For textured powders, add a March–Dollase preferred-orientation
+correction per phase. Set the March coefficient `march_r` (1 = no
+texture, <1 platy/disk, >1 needle), the texture direction
+(`index_h`, `index_k`, `index_l`), and optionally the random untextured
+fraction `march_random_fract`:
+
+```python
+# Add a March–Dollase preferred-orientation correction for a phase
+project.experiments['hrpt'].preferred_orientation.create(
+    phase_id='lbco', march_r=1.2, index_h=0, index_k=0, index_l=1
+)
+```
+
+This is a constant-wavelength Bragg powder correction, available on the
+`cryspy` engine. The defaults (`march_r=1`, `march_random_fract=0`)
+apply no texture, so it has no effect until you set them. See the
+[preferred-orientation parameters](../parameters/pref_orient.md) for
+details.
+
+### 7. Measured Data Category { #measured-data-category }
 
 If you do not have a CIF file for your experiment, you can load measured
 data from a file in a supported format. The measured data will be

docs/docs/user-guide/parameters.md

@@ -176,6 +176,11 @@ EasyDiffraction.
     |                                                  | :material-format-superscript: [order][background]          | background.order                 |
     |                                                  | :material-arrow-collapse-up: [coef][background]            | background.coef                  |
     | :material-puzzle: [linked_phases][linked_phases] | :material-scale: [scale][linked_phases]                    | linked_phases['ID'].scale        |
+    | :material-compass-outline: [pref_orient][pref_orient] | :material-chart-bell-curve-cumulative: [march_r][pref_orient]    | preferred_orientation['ID'].march_r           |
+    |                                                  | :material-shuffle-variant: [march_random_fract][pref_orient]   | preferred_orientation['ID'].march_random_fract |
+    |                                                  | :material-axis-arrow: [index_h][pref_orient]               | preferred_orientation['ID'].index_h           |
+    |                                                  | :material-axis-arrow: [index_k][pref_orient]               | preferred_orientation['ID'].index_k           |
+    |                                                  | :material-axis-arrow: [index_l][pref_orient]               | preferred_orientation['ID'].index_l           |
 
 === "CIF name for serialization"
 
@@ -186,6 +191,11 @@ EasyDiffraction.
     |                                                  | :material-format-superscript: [order][background]          | \_pd_background.chebyshev_order        | [pdCIF][0]{:.label-cif} |
     |                                                  | :material-arrow-collapse-up: [coef][background]            | \_pd_background.chebyshev_coef         | [pdCIF][0]{:.label-cif} |
     | :material-puzzle: [linked_phases][linked_phases] | :material-scale: [scale][linked_phases]                    | \_pd_phase_block.scale                 | [pdCIF][0]{:.label-cif} |
+    | :material-compass-outline: [pref_orient][pref_orient] | :material-chart-bell-curve-cumulative: [march_r][pref_orient]    | \_pref_orient.march_r                  | [easydiffractionCIF][0]{:.label-cif} |
+    |                                                  | :material-shuffle-variant: [march_random_fract][pref_orient]   | \_pref_orient.march_random_fract       | [easydiffractionCIF][0]{:.label-cif} |
+    |                                                  | :material-axis-arrow: [index_h][pref_orient]               | \_pref_orient.index_h                  | [easydiffractionCIF][0]{:.label-cif} |
+    |                                                  | :material-axis-arrow: [index_k][pref_orient]               | \_pref_orient.index_k                  | [easydiffractionCIF][0]{:.label-cif} |
+    |                                                  | :material-axis-arrow: [index_l][pref_orient]               | \_pref_orient.index_l                  | [easydiffractionCIF][0]{:.label-cif} |
 
 [pd-neut-cwl][3]{:.label-experiment} [pd-xray][3]{:.label-experiment}
 
@@ -289,4 +299,5 @@ EasyDiffraction.
 [peak]: parameters/peak.md
 [background]: parameters/background.md
 [linked_phases]: parameters/linked_phases.md
+[pref_orient]: parameters/pref_orient.md
 <!-- prettier-ignore-end -->

docs/docs/user-guide/parameters/pref_orient.md

@@ -0,0 +1,55 @@
+[pdCIF][2]{:.label-cif}
+
+# \_pref_orient
+
+Per-phase **preferred-orientation** (texture) correction using the
+March–Dollase model. Powder samples whose crystallites pack with a
+preferred orientation (platy crystals lying flat, needles aligning) show
+Bragg intensities that deviate from the ideal random-powder average;
+this correction restores them.
+
+Each row corrects one linked phase along one crystallographic direction.
+The defaults (`march_r = 1`, `march_random_fract = 0`) are a
+mathematical no-op, so a freshly added row applies no texture until you
+change them. Supported on the **CrysPy** engine for constant-wavelength
+Bragg powder experiments.
+
+See the
+[IUCr powder dictionary](https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd)
+(`pd_pref_orient_March_Dollase`) for the standard data names.
+
+## \_pref_orient.phase_id
+
+Identifier of the linked phase corrected by this row.
+
+## \_pref_orient.march_r
+
+March coefficient `r`. `r = 1` means no preferred orientation; `r < 1`
+describes disk-/plate-like crystallites and `r > 1` needle-like ones.
+This is the standard IUCr/FullProf/GSAS coefficient (serialised as
+`_pd_pref_orient_March_Dollase.r`); the CrysPy backend stores its
+reciprocal internally.
+
+## \_pref_orient.index_h
+
+Texture-axis Miller index _h_.
+
+## \_pref_orient.index_k
+
+Texture-axis Miller index _k_.
+
+## \_pref_orient.index_l
+
+Texture-axis Miller index _l_.
+
+## \_pref_orient.march_random_fract
+
+Random (untextured) fraction of crystallites; `0` is pure March–Dollase.
+There is no IUCr standard name for this quantity, so it is serialised
+under the EasyDiffraction custom dictionary.
+
+<!-- prettier-ignore-start -->
+[0]: #
+[1]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_core
+[2]: https://www.iucr.org/resources/cif/dictionaries/browse/cif_pd
+<!-- prettier-ignore-end -->