The sm_par Structure

The sm_par structure contains information stored in data file header. It holds some calibration and hardware information (which is less interesting to the end user), but also some scan information like pixel sizes, sample descriptions etc., which are interesting to the end user.

In the following, we describe all the elements in the structure.

strlen:

Maximum string length in characters for all entries in sm_par which are of string type (set to 128, probably won't ever change).

n_adc_channels:

Number of ADC (analog-to-digital-converter) channels (16 - 8 are currently used for the segmented silicon detector, 8 are not used routinely).

n_scaler_channels:

Number of scaler (counter) channels (2, for the proportional counter and the clock signal).

maxpointlist:

Maximum number of points in the pointlist. These are specific locations in the scan which can be labeled with a name (25). See Sec. 5.14.6.

filever:

Follows changes in the file format. When the file format is changed, the filever should be incremented. Currently, we are using filever 6. See Sec. 10.9.

fast_device, slow_device:

Code number for the fast and slow scan devices. See Table 1.2.

fast_device_name, slow_device_name:

String holding the name of the column and row devices, corresponding to the short name in Table 1.2.

detector:

Code (integer number) for the detector used. Currently 0 for the proportional counter, 1 for the silicon detector. -1 if no detector was inserted.

detector_name:

Name describing the detector used (COUNTER or SIDET).

fast_direction, slow_direction:

plus 1 if the corresponding device was scanned into the positive direction, and minus 1 if is was scanned in the negative direction (see Sec. 1.2 for the STXM 5 coordinate system). Except ZOSA, and ZSTG only for the CRYO microscope, all scan directions are negative (for real image scans, this is required so that the scan image looks like the real sample in the VLM, or as looked at in the upstream direction). If the monochromator (EV) was scanned, this entry is meaningless. Then, start_ev and stop_ev tell you the scan direction.

n_fast_pixels, n_slow_pixels:

Number of pixels in the horizontal and vertical scan directions.

n_data:

Number of measurements (recorded detector channels) for each pixel. See Sec. 9.1.

pixel_channel_names:

Array of strings describing the recorded data channels in the order as they are recorded in the data array. The string array has n_adc_channels + n_scaler_channels entries, but only the first n_data are filled and significant. All other entries must be empty strings!.

If silicon detector channels are recorded, they must be named SIDET01 etc. and must be the first channels in the list (adjacent to each other and in ascending order) to be recognized as silicon detector channels (to be calibrated and combined properly).

The clock and proportional counter channels must be named CLOCK and COUNTER to be recognized properly.

fast_pixel_um, slow_pixel_um:

Pixel (step) size in each direction.

dwell_msec:

Desired dwell time (which was chosen by the user). In scans with a piezo as fast axis, this will correspond to the actual dwell time (unless it's a completely weird number). When a stepper motor is used as fast axis, the actual dwell time will vary from pixel to pixel due to acceleration and deceleration of the stage. In that case, we record a clock signal for each pixel to determine the actual dwell time. Also see sm_par.clock_hertz.

bidirectional:

Flag (0 or 1) telling whether the scan was taken bidirectional.

[x,y,z]_use_laser_positions:

Flags (0 or 1) telling if the laser interferometer positions or the plain device positions were used for the scan.

shutopen:

Currently not used for anything.

tilt_degrees:

Tilt of sample for tomography. Not really used currently.

[x,y,z]_center_um:

Center position of image (interferometer position).

[x,y]_pzt_um, [x,y,z]_stg_um, [x,y,z]_det_um, z_osa_um:

Positions of all the stages. For the stages which were scanned, this is the center of the scan.

start_ev, stop_ev:

Energy at start and end of scan. The two are the same for images.

drift_d[x,y]_over_dz:

Misalignment of the Z stage relative to the beam direction.

zstg_follows_spectrum:

Flag (0 or 1) telling if the ZSTG was tracked during a point spectrum (to keep the sample in focus).

adc_voltsperbit, adc_voltoffsets:

ADC calibration. If you have the raw integer data (as unsigned integers!), you can calculate the voltage measured by the ADC as

$$\mbox{Volts} = \mbox{adc\_voltoffsets} + \mbox{adc\_voltsperbit} \times \mbox{Raw Integer}$$ (10.1)

Note that both these arrays have n_adc_channels elements, but only as many are significant as there were ADC channels recorded in that particular scan (starting from the zero element in the order the channels were recorded).

counts_divideby:

Integer factor describing the divideby setting for the proportional counter. When the actual number of counts is larger than can fit into a 16-bit unsigned integer number (65536), we apply a divide-by. When reading data back from a file, one must multiply by this number to obtain the true values (only for the proportional counter channel!).

clock_hertz:

In scans with a piezo as fast axis, the dwell time is rigidly fixed, so no clock signal will be recorded. Then, clock_hertz will hold the clock rate at which pixels are recorded (pixels per second), which is the inverse of the dwell time.

In scans where a stepping motor is the fast axis (due to acceleration and deceleration, the actual dwell time varies), we will record a clock signal as a separate detector channel, and clock_hertz will hold the clock rate (100 kHz or 20 MHz). dwell_msec in that case will hold the desired, but not the actual dwell time.

n_sidet_segments:

Number of segments on the silicon detector chip. Can be different from the number of segments which were actually recorded (but in most cases, if you record one, you want to record all).

sidet_crosstalk_matrix:

Crosstalk matrix for the segmented silicon detector. It has n_adc_channels $\times$ n_adc_channels entries, but only the first n_seg $\times$ n_seg are significant, where n_seg is the number of silicon detector channels which was recorded in this particular scan.

Example: To correct an $n$-element data vector from the crosstalk, you have to use the following IDL code (note the order of i and j):

        out = fltarr(n) ;; initialize
        FOR i=0, n-1 DO BEGIN
            FOR j=0, n-1 DO BEGIN
                out[i] = out[i] + c[j, i] * in[j]
            ENDFOR
        ENDFOR

where c is the $n \times n$ crosstalk matrix. The reason why i and j are interchanged as compared to what you are used to in math is that IDL is a row-major language, while in common math you treat matrices in column-major fashion. Read the IDL documentation for details.

If you want to correct only a 1-d data vector, you could more easily use the matrix multiplication operator, but if you want to correct a 3-d data array, you'll have to go with FOR loops.

sidet_u0_mvolts:

Voltage offset (extrapolated voltage for zero dwell time) for the silicon detector calibration. This is an array with n_adc_channels entries, but only the first n_seg are significant, see above. See Sec. 10.7 for details.

sidet_c_idark_mvolts_per_ms:

C $\times$ I_dark factor for the silicon detector calibration. Also an array as above.

sidet_mvolts_per_femtocoulomb:

Sidet amplifier output per input charge. Also an array as above.

sidet_ev_per_femtocoulomb:

(constant 22594.25) Number of eV required to create one fC of charge in silicon (corresponding to 3.62eV to create one electron-hole pair at room temperature). Introduced with file version 7, replaces sidet_photons_per_femtocoulomb. See Sec. 10.7.

sidet_photons_per_femtocoulomb:

Photon-charge conversion factor. See Sec. 10.7. Obsolete (but still in the file) as of file version 7, replaced with sidet_ev_per_femtocoulomb.

sidet_deadtime_ms:

Silicon detector dead time. See Sec. 10.7.

sidet_calibration_time:

String holding the time when the detector was last calibrated. Just informational.

sidet_chip_name:

Name of the detector chip.

sidet_chip_design:

String describing the silicon detector chip design. It should correspond to an accepted "configuration" in the IDL routine cvs/idl_local/sidet/det_segments.pro (currently: "8 segment original").

sidet_zmatch:

Silicon detector Z matching parameter, defined as the ratio of the size of the beam cone on the detector chip and the diameter of the quadrant segments. A value of 1.0 means that the beam cone exactly matches the quadrant segments. The value is important for quantitative reconstruction of phase.

disp_min, disp_max, disp_gamma:

Minimum, maximum and gamma values for the display at the time when the file was saved. The file will be restored just like that when you open it again.

disp_name:

Name of the display which was shown when the file was saved. See Sec. 9.3.

microscope:

String describing the microscope (see short name in Table 1.1).

systime:

String of the time of the scan.

scientist, sample, comments1, comments2:

Strings holding the name of the scientist(s), the sample and two arbitrary comments. Whatever the user entered before saving the scan.

original_filename:

Name under which the file was originally saved (preserved even if the file is renamed in the file manager). See Sec. 8.1.

temp1_celsius, temp2_celsius:

Temperature readings 1 and 2 (mainly for cryo, not currently used in the room temperature STXMs).

temp1_name, temp2_name:

Strings describing the temperature readings.

n_oneread_channels:

Number of channels which are read only once per scan. Not currently used.

oneread_data:

Array of data which is read only once per scan (at end of scan). Not currently used.

oneread_channel_names:

Array of names for the oneread channels. Not currently used, but if it was, it would be a n_adc_channels-element string array where only the first n_oneread_channels would be significant.

n_pointlist:

Number of valid entries in the pointlist (see Sec. 5.14.6). Actually, this parameter is not used because valid entries in the pointlist can be identified by non-zero coordinates or non-empty point_namestr entries and don't even have to be adjacent to each other.

point_namestr:

Array of strings holding the labels for the marked locations in the scan. It has n_pointlist entries.

point_xpos, point_ypos:

Arrays holding the X and Y positions of the marked locations in the scan. Each has n_pointlist entries.

ring_gev, ring_ma:

Storage ring parameters (read at beginning of scan).

undulator_gap_mm, undulator_period_mm:

Undulator settings.

ens_slit_um, exs_slit_um, exsy_slit_um, exsh_slit_um, exsyh_slit_um:

Width of entrance and exit slits. h stands for the high energy exit slits on the inboard branch.

exs_slits_used:

Flag telling which set of exit slits were used (only meaningful for inboard branch). 0: normal, 1: high energy slits.

sgm_zero_order_steps, sgm_steps_per_angstrom:

Monochromator calibration parameters. The x-ray wavelength can be calculated by

$$\lambda (\mbox{\AA}) = \frac{\mbox{SGM motor position in steps} - \mbox{zero-order steps}}{\mbox{steps per \AA}}$$ (10.2)

zp_d_um, zp_delta_nm, zp_stop_um, osa_d_um:

Zone plate and OSA parameters.

zp_name:

Name of the zone plate.