BornAgain ≻ 24 ≻ Documentation ≻ Reference ≻ Model modifiers ≻ Correlation profiles

Correlation profiles

Correlation profiles describe spatial disorder and finite correlation lengths in one- and two-dimensional particle structures. They are distinct from parameter distributions, which sample scalar model parameters such as a particle radius.

The same profile classes serve two related purposes.

Neighbor disorder

Paracrystals use a normalized direct-space probability density for the displacement of one particle relative to its expected position. BornAgain uses its Fourier transform $\widetilde p(q)$ in the interference function, with $\widetilde p(0)=1$.

Attach profiles to paracrystals with

paracrystal_1d.setProbabilityDistribution(profile_1d)
paracrystal_2d.setProbabilityDistributions(profile_2d_1, profile_2d_2)

The first form is also used by RadialParacrystal.

Correlation decay

Crystals use a direct-space function $h(r)$, normalized to $h(0)=1$, to describe the loss of positional correlation over distance. Its Fourier transform broadens the reciprocal-lattice peaks.

Attach profiles to crystals with

crystal_1d.setDecayFunction(profile_1d)
crystal_2d.setDecayFunction(profile_2d)

The available profile sets differ because not every direct-space shape has a decay transform implemented.

The formulas below show reciprocal-space shapes normalized to one at zero. For a decay function, BornAgain instead retains the dimensional Fourier normalization implied by $h(0)=1$.

One-dimensional profiles

One-dimensional profiles have a characteristic length omega, in nanometers:

ba.Profile1DCauchy(omega)
ba.Profile1DGauss(omega)
ba.Profile1DGate(omega)
ba.Profile1DTriangle(omega)
ba.Profile1DCosine(omega)
ba.Profile1DVoigt(omega, eta)

The Cauchy classes take their name from their reciprocal-space transforms; their direct-space shape is exponential.

For $u=q\omega$ and $\operatorname{sinc}(u)=\sin(u)/u$, the direct-space shapes, up to normalization, and transforms normalized at $q=0$ are:

  • Cauchy: $\exp(-|x|/\omega)$ and $1/(1+u^2)$;
  • Gauss: $\exp[-x^2/(2\omega^2)]$ and $\exp(-u^2/2)$;
  • gate: a constant for $|x|<\omega$ and $\operatorname{sinc}(u)$;
  • triangle: $1-|x|/\omega$ for $|x|<\omega$ and $\operatorname{sinc}^2(u/2)$;
  • cosine: $1+\cos(\pi x/\omega)$ for $|x|<\omega$ and $\operatorname{sinc}(u)/(1-u^2/\pi^2)$.

Profile1DVoigt is the linear pseudo-Voigt combination $\eta,G+(1-\eta),C$ of the Gaussian and Cauchy transforms: eta=0 gives Cauchy and eta=1 gives Gaussian.

Profile Paracrystal Crystal decay 3D scene
Profile1DCauchy yes yes yes
Profile1DGauss yes yes yes
Profile1DGate yes no yes
Profile1DTriangle yes yes yes
Profile1DCosine yes no yes
Profile1DVoigt yes yes no

A zero-width one-dimensional profile is the delta-distribution, or perfectly ordered, limit for paracrystal scattering. Crystal decay lengths must be positive. Use a positive width when generating explicit 3D scene positions.

Two-dimensional profiles

Two-dimensional profiles have principal-axis lengths omega_x and omega_y, in nanometers, and an orientation gamma, in radians:

ba.Profile2DCauchy(omega_x, omega_y, gamma)
ba.Profile2DGauss(omega_x, omega_y, gamma)
ba.Profile2DGate(omega_x, omega_y, gamma)
ba.Profile2DCone(omega_x, omega_y, gamma)
ba.Profile2DVoigt(omega_x, omega_y, gamma, eta)

The angle gamma rotates the profile principal axes relative to the first lattice vector. Both lengths must be positive. As in one dimension, the pseudo-Voigt parameter runs from Cauchy at eta=0 to Gaussian at eta=1.

In principal-axis coordinates, let $r^2=(x/\omega_x)^2+(y/\omega_y)^2$ and $Q^2=(q_x\omega_x)^2+(q_y\omega_y)^2$. The Cauchy, Gaussian, gate and cone direct-space shapes, up to normalization, are respectively $\exp(-r)$, $\exp(-r^2/2)$, a constant for $r<1$, and $1-r$ for $r<1$. Their transforms, normalized at $Q=0$, are $(1+Q^2)^{-3/2}$, $\exp(-Q^2/2)$, $2J_1(Q)/Q$, and a numerically evaluated cone transform. The pseudo-Voigt profile linearly combines the Cauchy and Gaussian transforms.

Profile Paracrystal Crystal decay 3D scene
Profile2DCauchy yes yes yes
Profile2DGauss yes yes yes
Profile2DGate yes no yes
Profile2DCone yes no yes
Profile2DVoigt yes yes no

The 3D-scene column concerns generation of representative particle positions; it does not limit scattering simulations.

Other distribution APIs

Correlation profiles are not interchangeable with detector resolution functions. Detector convolution integrates a resolution kernel over detector bins and therefore uses a separate API.