Debye sums

Debye sums for a set of point scatterers.

Every kernel computes the same quantity:

\[ D(q) = \sum_j \sum_k w_j w_k \operatorname{sinc}(q r_{jk}), \qquad w_j = b_j - \rho v_j, \qquad \operatorname{sinc} x = \frac{\sin x}{x} \]

for scattering lengths \(b\) (Å), volumes \(v\) (ų) and a solvent SLD \(\rho\) (Å⁻²), at positions in Å. debye_pairs enumerates pairs and works for any point set. The spectrum builders first collect the pairs into a DistanceSpectrum, a list of distances with the weights b·b, b·v and v·v kept apart, so another solvent costs only the sinc sums:

• spectrum_lattice: the autocorrelation of weight grids, exact for points on a lattice and fast for large grids.
• spectrum_histogram: pairs counted by distance in bins of a given width, for any point set (coords2sans's pass).
• spectrum_radial: each point's distance from a centre, the squared orientation-averaged amplitude ⟨A⟩², exact only for spherically symmetric structures (SasView's is_avg).

DistanceSpectrum dataclass

The part of a Debye sum that does not depend on q or the solvent.

Attributes:

Name	Type	Description
r	ndarray	Distances, Å; only those with a non-zero component.
components	ndarray	(3, n): the summed pair weights \(bb\), \(bv\) and \(vv\) at each distance, so that \(D = \sum_r (bb - 2 \rho\, bv + \rho^2 vv) \operatorname{sinc}(q r)\). For a squared spectrum (2, n): \(b\) and \(v\) at each distance, so that \(D = \left(\sum_r (b - \rho v) \operatorname{sinc}(q r)\right)^2\).
squared	bool	Which of the two forms.

debye

debye(q, rho: float) -> np.ndarray

D(q) at a solvent SLD rho in Å⁻².

CalculationInterrupted

Bases: Exception

Raised when a progress callback asks a running calculation to stop.

debye_pairs

debye_pairs(q, xyz, w, *, block: int | None = None, progress: Callable[[float], bool | None] | None = None) -> np.ndarray

Exact Debye sum by enumerating the upper triangle of pairs.

Parameters:

Name	Type	Description	Default
q		Momentum transfers, 1/Å, any values >= 0.	required
xyz		Positions, shape (N, 3), Å.	required
w		Weights, shape (N,).	required
block	int | None	Rows per block. Defaults to a size that keeps each pair buffer near PAIR_BLOCK_ELEMENTS.	None
progress	Callable[[float], bool | None] | None	Called with the completed fraction after each block. A return value of True stops the sum with CalculationInterrupted.	None

spectrum_lattice

spectrum_lattice(grid_b, grid_v, step) -> DistanceSpectrum

The exact spectrum of weights on a rectangular lattice.

On a lattice every pair displacement is an integer vector \(\Delta\), so the pair weights are correlations of two grids, such as

\[ C_{bv}(\Delta) = \sum_x b(x)\, v(x + \Delta), \qquad D(q) = \sum_\Delta \left[C_{bb} - 2 \rho\, C_{bv} + \rho^2 C_{vv}\right](\Delta) \operatorname{sinc}(q |\Delta|) \]

Lags are grouped by the exact integer key \((|i|, |j|, |k|)\), so no floating-point rounding enters the grouping. A lag that some pair of occupied sites has gets \(C_{vv}\) of at least the smallest volume squared, far above the FFT noise of the empty lags, which are dropped.

Parameters:

Name	Type	Description	Default
grid_b		Scattering lengths on the grid, shape (nx, ny, nz); empty sites hold 0.	required
grid_v		Volumes on the same grid; positive at every occupied site.	required
step		Lattice steps along x, y and z, Å.	required

Raises:

Type	Description
ValueError	If no site has a positive volume, or a site with a scattering length has none.

spectrum_histogram

spectrum_histogram(xyz, b, v, bin_width: float, *, block: int | None = None, progress: Callable[[float], bool | None] | None = None) -> DistanceSpectrum

The spectrum of all pairs, counted by distance rounded to bin_width.

Squared distances come from a matrix product per block of rows; each distance is rounded to the nearest multiple of the bin, which moves a pair by at most bin/2, a phase error of at most q·bin/2. Only occupied bins are kept.

Parameters:

Name	Type	Description	Default
xyz		Positions, shape (N, 3), Å.	required
b		Scattering lengths, shape (N,).	required
v		Volumes, shape (N,).	required
bin_width	float	Bin width, Å.	required
block	int | None	Rows per block. Defaults to about HISTOGRAM_BLOCK_PAIRS pairs.	None
progress	Callable[[float], bool | None] | None	Called with the completed fraction after each block. A return value of True stops the pass with CalculationInterrupted.	None

spectrum_radial

spectrum_radial(xyz, b, v, centre) -> DistanceSpectrum

The squared spectrum ⟨A⟩²: each point's distance from centre, Å.

The orientation-averaged amplitude about the centre \(c\) is \(A(q) = \sum_j w_j \operatorname{sinc}(q |x_j - c|)\), and \(A(q)^2\) equals \(D(q)\) only for spherically symmetric structures.