# Pattern and sample-physics composition
[`crate::engine`] and [`crate::workflows`] compose the lower-level profile and
crystallographic equations without changing their normalization.
## Multi-phase patterns
For phase `p`, reflection `h`, base integrated intensity `I_ph`, phase scale
`S_p`, sample intensity multiplier `M_ph`, normalized profile `P_ph(x)`, and
one supplied background array,
```text
Y_profile(x) = Σ_p Σ_h I_ph S_p M_ph P_ph(x)
Y_total(x) = Y_profile(x) + Y_background(x)
∂Y/∂S_p = Σ_h I_ph M_ph P_ph(x).
```
The background is added once after phase composition. Phase components are
diagnostics reconstructed from the same local support blocks. See
[`crate::engine::PreparedStructuralMultiphase`] and
[`crate::engine::StructuralMultiphaseResult`].
## Structural wavelength spectra
For source component `c`, normalized weight `w_c`, wavelength `λ_c`, and
reciprocal squared length `q_h²`,
```text
s_h = sqrt(q_h²)/2
θ_hc = asin[λ_c sqrt(q_h²)/2]
φ_hc = 2θ_hc + position corrections
```
Non-resonant X-ray and constant neutron structure factors depend on `s_h`, not
on `λ_c`; position, correction, widths, and compatible sample terms are
component-specific. Shared structural JVPs and VJPs sum component products.
See [`crate::engine::PreparedStructuralSpectrum`].
## Composable profile contributions
For each reflection, sample physics contributes additive Gaussian variance
`q_sample`, additive Lorentzian FWHM `l_sample`, and multiplicative intensity
factor `M`:
```text
q_total = q_instrument + q_sample
g_total = sqrt(8 ln(2)) sqrt(q_total)
l_total = l_instrument + l_sample
I_total = I_base M.
```
Gaussian variances add under convolution; Lorentzian FWHMs add linearly.
Multiple intensity providers compose with the product rule. The low-level
array boundary is [`crate::core::CwContributionsView`]; structural refinement
uses [`crate::workflows::RietveldSamplePhysicsModel`].
## Isotropic coherent-domain size
The Scherrer contribution is assigned to Lorentzian FWHM. For coherent-domain
size `D_nm`, shape factor `K`, wavelength `λ_A`, and `θ = φπ/360`,
```text
D_A = 10 D_nm
l_size = (180/π) K λ_A/[D_A cosθ]
∂l_size/∂D_nm = -l_size/D_nm
∂l_size/∂φ = l_size (π/360) tanθ.
```
`D_nm = infinity` is the exact disabled limit. The model denotes coherent
domain size, not necessarily particle or grain size.
## Isotropic RMS microstrain
For RMS strain `ε = std(δd/d)`, the Gaussian variance in degree² is
```text
q_strain = [(180/π) 2ε tanθ]²
C = [2(180/π)]²
∂q_strain/∂ε = 2C ε tan²θ
∂q_strain/∂φ = 2C ε² tanθ sec²θ (π/360).
```
The equivalent Gaussian FWHM is
`(180/π) 4 sqrt(2 ln(2)) ε tanθ`. Zero strain is the exact disabled limit.
## Isotropic Lorentzian microstrain
For the independent Lorentzian convention with dimensionless strain `η`,
```text
l_strain = (180/π) η tanθ
∂l_strain/∂η = (180/π) tanθ
∂l_strain/∂φ = 0.5 η sec²θ.
```
This parameter is named `isotropic_lorentzian_microstrain.fraction` and must
not be interpreted as the Gaussian RMS parameter above.
## March–Dollase preferred orientation
For preferred reciprocal direction `a`, reflection `h`, reciprocal metric
`G*`, and March ratio `r > 0`,
```text
M = A^(-3/2)
∂M/∂r = -(3/2) A^(-5/2) [2rc² - (1-c²)/r²].
```
`M` multiplies integrated intensity; `r=1` is random orientation. Structural
cell derivatives also differentiate the reciprocal-metric angle `c`.
## Derivative composition
Every built-in path follows ordinary product and chain rules. For one
reflection contribution `Y = I M p(x-φ,g,l)`, a parameter `u` contributes
```text
∂Y/∂u = (∂I/∂u) M p + I (∂M/∂u) p
+ I M[(∂p/∂φ)(∂φ/∂u)
+ (∂p/∂g)(∂g/∂u)
+ (∂p/∂l)(∂l/∂u)].
```
JVP implementations evaluate this expression for a supplied direction; VJP
implementations accumulate its transpose against sample adjoints. The adjoint
identity is
```text
u^T (Jv) = v^T (J^T u).
```
The identity is a tested contract across the structural calculation and
refinement layers.