1. Prepare the intensity data

To perform a polarization data reduction you must first have measured beam data under different polarization conditions:

pp spin up incident, spin up reflected
pm spin up incident, spin down measured
mp spin down incident, spin up measured
mm spin down incident, spin down measured

These data are passed into the correction using a PolarizedData container:

I = PolarizedData()
I.xlabel, P.xunits = 'Slit 1', 'mm'   # On TOF, maybe 'wavelength','nm'
I.ylabel, P.yunits = 'Intensity', 'counts'
I.pp.set(x=Spp, y=Ipp, variance=Ipp)
I.pm.set(x=Spm, y=Ipm, variance=Ipm)
I.mp.set(x=Smp, y=Imp, variance=Imp)
I.mm.set(x=Smm, y=Imm, variance=Imm)

The intensities given should be 1-dimensional. For 1D and 2D detectors, the integrated beam image should be used. Time-of-flight data will be organized by time channel while monochromatic data is organized by slit opening. Any ordering will do so long as the intensity is well behaved between points.

We will assume the correction is uniform across the detector since it is impractical to measure the efficiency as a function of position. In fact the slightly different path lengths for the various positions on the detector will lead to a decrease in efficiency as you move away from the center of the beam, and so it may have a subtle influence on off-specular polarized reflectometry.

The different cross sections must have corresponding ordinate axes. On TOF machines this will usually not be a problem since all time channels are measured simultaneously. On scanning instruments, there are a variety of factors which may result in points that don't correspond well, such as user error, or undersampling in the spin-flip cross sections.

Even if the data are already aligned across the four cross sections, it is still desirable to smooth the polarized data prior to estimating because the efficiency estimate is unstable.

Use alignment or smoothing corrections to make your data regular:

I.apply(align)    # use linear interpolation to regrid the data
I.apply(smooth)   # a weighted irregular Savitsky-Golay filter

2. Compute polarization efficiencies

The polarization efficiency correction is controlled by the PolarizationEfficiency class:

eff = PolarizationEfficiency(I)

Once the class is constructed and the resulting efficiency attributes are available:

eff.fp front polarizer efficiency
eff.ff front flipper efficiency
eff.rp rear polarizer efficiency
eff.rf rear flipper efficiency
eff.Ic overall beam intensity

The formalism from Majkrzak, et al. (see attached PDF) defines the following, which are attributes to the efficiency object:

eff.F = fp
eff.R = rp
eff.x = 1 - 2*ff
eff.y = 1 - 2*rf
eff.beta = Ic/2

There are a few attributes of the class that will change how the efficiencies are calculated:

eff.min_intensity = 1e-2
eff.min_efficiency = 0.7
eff.FRbalance = 0.5

FRbalance determines the relative front-back weighting of the polarization efficiency. From the data we can only estimate the product FR of the front and rear polarization efficiencies, and the user must decide how to distribute the remainder. The FRbalance should vary between 0 (front polarizer is 100% efficient) through 0.5 (distribute inefficiency equally) to 1 (rear polarizer is 100% efficient). The particular formula used is:

F = (F*R)^FRbalance
R = (F*R)/F

The min_intensity and min_efficiency numbers are used to bound the range of the correction. Normally you won't need to set them. These are class attributes, so you can set them globally in PolarizationEfficiency instead of eff, but still override them for particular instances by setting them in eff.

3. Apply the correction to the data

You must first prepare your data for the polarization correction by placing it in a PolarizedData container, and possibly subtracting the background measurements (the polarization correction is linear so it doesn't matter mathematically if background subtraction happens before or after the polarization correction, but the polarization correction is slow enough that it should probably only be done once).

Once again the measurements need to be aligned, but in this case smoothing should not be used. The data will need to be normalized to the same monitor as the intensity measurement before adding them to the container.

For scanning instruments, the data will need to retain the slit settings used for the measurement so that the correct intensity measurement can be used for the correction.

TODO: create a complete data reduction doc including footprint, etc. TODO: use array masks to identify interpolated data. TODO: incorporate time for He3 polarizer TODO: extend to 1D and 2D detectors TODO: cross check results against Asterix algorithm TODO: implement alignment and smoothing TODO: consider applying the efficiency correction to the theory rather than the data --- if the inversion is unstable, this may be more reliable. TODO: with both spin up and spin down neutrons in sample simultaneously in some proportion, do the cross sections need to be coherently to account for the theory?

[1] C.F. Majkrzak (1996). Physica B 221, 342-356.