XCTL

Behavioral specification (requirements) of
XCTL-Control program

Function: Manual Adjustment of Sample and Collimator

Document Version:

2.2 (July 4, 2001)

Author:

Klaus Bothe

English version:

Zoran Budimac (February 18, 2002)

Status:

Under way

Changes since ver. 1.1:

	new, extended structure of the document
	included results of reviews from Seminar 'Software repair' (winter-semester 2000/2001)

Document structure

0. Scope of the document
1. Overview
2. Functional description
    2.1 Drives for positioning of the sample
    2.2 Application scenario
    2.3 Motion of the single drive
    2.4 Measuring the half-width of reflection curve
3. Input data
4. Errors
5. Wishes for changes
6. Open questions, i.e. deficiencies of the document
7. Related documents
8. Changes in the document
9. Sources of the document
10. Glossary

0. Scope of the document

This document covers only the subject of topography. Generalization of the document to diffractometry/reflectometry and different work-places is not yet available.

To topography are specific especially the number and description of drives, as well as the 'quick choice of drives' (the field in the dialog-box). Furthermore, topography also needs values contained in ini-File that are specific to topography-device RTK4.

For more general view, see 2.3 and 2.4.

1. Overview

The task of the function Manual Adjustment of Sample and Collimator is to position a sample and a collimator in three-dimensional space for a special experiment (Topography) in Physics.

Kollimator = Collimator
Fotoplatte = Photo plate
Quelle = Source
Probe = Sample
Bild: ... = Figure: Double crystal topography.
a: usual double crystal configuration with asymmetric collimator
b: double crystal configuration with curved, asymmetric collimator, whose curvature corresponds to the curvature of probe

There are four different positioning drives for positioning of the sample by topography. They enable motion of the sample in different directions. In addition, there is another drive for curving of Collimator (for deflection of X-rays).

The good position (picture above, b) is reached step-by-step by setting manually the motion of each of the drives (using a dialog-box). The goodness of the current position is checked acoustically and/or optically (detector's signals) and by measuring the half-width of the reflection curve.

After execution of this function, the process of topography will be continued through separate dialog-boxes.

2. Functional description

Dialog-box:

Remarks on English version of dialog box:

"Special drives" -> better -> "Quick choice of drives"
"Omega" -> better -> "DF - Fine adjustment"
"Actual Drive" -> better -> "Current drive"
"Skip relative zero" -> better -> "Remove relative zero"

2.1 Drives for positioning of the sample

There are four different positioning drives for positioning of the sample by topography. They enable motion of the sample in different directions. Drives are the following:

DC (Diffraction angle, coarse - coarse adjustment of diffraction angle (angle of incidence)),

DF (Diffraction angle, fine - fine adjustment of diffraction angle),

AR (Azimuthal rotation) and

TL (Tilt, tipping, relative to the plane of incidence).

In addition, there is another drive for curving of Collimator (i.e., plates for deflection and dispersion of X-rays):

CC (Collimator curvature).

Probe = Sample
Probenhalter = Sample holder
Figure: Degrees of freedom of the sample holder drives

Using the dialog-box, one can chose one current drive of five mentioned drives (either by using the 'Quick choice of drives' or by selecting one from the combo-box 'Current drive'). All values shown in the dialog-box refer to the chosen (current) drive. Always only one drive can be controlled at every time through a dialog-box.

2.2 Application scenario

Drives are served independently of each other and can be simultaneously moved. Only drives DF and DC cannot be moved simultaneously, because they move in the same moving direction. Simultaneous move of two motors is solved in the following way: The actual drive will be set into motion. While it is still moving, other drive should be chosen and also set into motion.

If a drive is currently moving, other user inputs for that drive are ignored until the moving stops. In that case user will be notified with warning "Drive <Drive Name > in motion" (#Question: True in the present version?) (#Wish: better: forbid further user inputs to the same drive while drive is moving). User inputs to other drives are possible, as described in previous paragraph.

For every experiment, the sample is positioned by moving mentioned drives and by adjusting the curvature of Collimator. To do this, user will set the position of every drive to the wanted position (Target-position) using the dialog box Manual Adjustment. After chosen operation mode (see below), drives will move from their current position (Current-position) to the wanted position (Target-position). Target-positions depend on every sample and must be determined during the setting.

First, positions of drives DC and AR must be set. After that, positions of three other drives (DF, TL, CC) must be changed accordingly (alternatively) (therefore the "quick choice of drives" exist in dialog box.) This process is iterative and repeats usually 20 to 100 times, until the measured x-ray radiation reaches the maximal value as close as possible. This can be checked by measuring the half-width of the reflection curve (see 2.4 and in Glossary). Shorter the half-width, better position of the sample.

2.3 Motion of the single drive

The following statements hold for every drive:

a. Current position

Every drive is in its Current-position, that can be seen in a field of dialog box (Angle) as a numerical value, and as a position of button in a horizontal scrollbar. Current-position will be continuously changed by a moving drive. Graphical user-interface of the system ensures that numerical value and state of the scrollbar button are in accordance. All information (numerical values, scrollbar buttons) are with respect to relative zero (see b). (#Note: Does this make sense, i.e. is referring to absolute zero better?)

Note: The absolute-zero point of a drive will be determined by means of 'Reference Point Handling' dialog-box, before use of 'Manual adjustment'. This is equivalent to definition of absolute position as the origin of used coordinate system. The absolute-zero point lies somewhere between physically minimal and maximal position.

Exception: Text in a title row of dialog-box gives advice on the correctness of the shown Current-Position after initialization of the system (i.e., start of the program):

"Manual adjustment" means: shown Current-position is correct;

"Manual adjustment: no valid reference point" means: Shown current position [Angle] does not correspond to the real position, probably because program crashed previously (therefore position could not be remembered correctly).

b. Relative zero

All angle specification in the dialog-box is with respect to relative zero position. Initially the relative zero position is equivalent to absolute zero. However, any Current-position can be taken as relative zero position by pressing the button 'Set the relative zero' in the dialog box. By pressing the button 'Remove the relative zero position will be again set to absolute zero. New position can be set as relative zero by pressing 'Set the relative zero' button again in appropriate moment, without need to remove it first (by pressing 'Remove).

Example: The Current-position (currPos) is over absolute zero (absZero) and will be set to relative zero (relZero).

|----------------------|----------|--------------------------------|
minPos                 absZero	  currPos=relZero               maxPos

Note: Setting the relative zero has a consequence to entering the correct values to 'Angle' i.e. 'New angle'. When, for example, the relative zero is set to minimal angle, then only the positive angle positions can be entered. Relative zero cannot be set to a drive in motion.

By setting the relative zero, the scrollbar button will be positioned in the middle of the scrollbar. After skipping (i.e., forgetting, releasing) relative zero, absolute values will be shown in the dialog-box, and scrollbar button will be appropriately positioned.

c. Operation modes and start of motion

Direct motion: Target-position is entered in the edit-field New angle as an absolute value. After that, the drive move to the Target-position - the motion momentarily starts after pressing the Enter key. (#Note: ergonomically bad, because this is the only operation mode that is not explicitly mentioned in the dialog-box) (#Note by Budimac: however, this should be checked with the users - mentioning the operation mode in dialog-box is the one thing and forcing user to choose this operation mode first, is another - maybe unwanted)
Stepwise motion: The Target-position is entered relatively to the Current-position as a step-value in the edit-field 'D='. Motion will start after one of the keyboard cursor-keys (<- or -> ) is pressed; or one of the arrow-buttons on the scrollbar are clicked on. If the key -> has been pressed (or right scrollbar arrow-button clicked) (#Note: ergonomically problematic, because there is no 'Start' button) (#Note by Budimac: check with the users - maybe they do not want to have to press additional button for simple operation) drive will move to position Current-position + step-value. If the key <- has been pressed (or left scrollbar arrow-button clicked) drive will move to position Current-position - step-value.
Continuous motion: Drive will move continuously while cursor keys (<- or -> ) (or arrow-buttons on the scrollbar) are being pressed. The motion direction depends on pressed key (button). With pressed -> (i.e., right arrow-button of the scrollbar) an angle (= position) will get bigger, while with pressed <- (i.e., left arrow-button of the scrollbar) angle (position) will get smaller.

d. Motion speed

Direct motion

Continuous motion

with V = ... s-1

Stepwise motion

e. Reaction to invalid inputs

Drives must be protected by the software from invalid user inputs. (#Wish: Sensible, but still not implemented: user should be notified on invalid inputs by a warning tone).

Invalid target position: If in Direct motion-mode a Target-position is entered that is out of permitted range, then the position specification will be automatically corrected to minimal or maximal permitted position, depending on whether invalid input was below or above permitted range of values. In Continuous motion-mode the drive can move only inside the permitted range of values. Attempt to cross the boundaries of permitted range will result in stopping the drive.
Invalid speed: If in Direct motion-mode or in Continuous motion-mode an invalid speed is entered, then the speed will be adjusted by the software to maximal possible speed.
Invalid step value: If in Stepwise motion-mode the entered value for step-value is out of permitted range of values, the step-value will be automatically set to the minimal or to the maximal allowed value, depending on whether invalid input was below or above permitted range of values. If entered step value leads to position that is out of permitted range, then the step-value should be accordingly corrected

(#Wish: Automatic correction of invalid inputs should be verified (approved) by the user. #Note by Budimac: also check with users - maybe they don't want to press additional button)

f. Stopping drive motion

Direct motion: Only by exiting the dialog-box 'Manual adjustment' (#Note: ergonomically very bad)
Stepwise motion: Only by exiting the dialog-box 'Manual adjustment' (#Note: ergonomically very bad)
Continuous motion: by releasing cursor keys (or arrow-buttons)

This means that exiting the dialog-box always stops drives. Their position will be saved by the software. (#Note: this solution is ergonomically problematic. It would be better to show a message, if some drives are still moving: 'Some drives are in motion. Are you sure?') (#Note: there is a hardware command 'Abort motion' for stopping a drive. This command is internally used, also when exiting dialog-box)

2.4 Measuring the half-width of the reflection curve

After pressing a button 'Measure half-width' a half-width of the reflection curve will be measured. A message-box with result of measurement will appear after measurement is over.

3. Input data

3.1 Summary

Influencing the system behavior is possible through data from dialog-box and ini-Files.

By using dialog-box one can enter the data for drive motion:

	The choice of drive (DF, DC, TL, AR, CC),
	Operation mode (Direct motion, Stepwise motion, Continuous motion),
	Target-position (edit-field New Angle),
	Step-value (edit-field D=),
	Motion direction (initiated with cursor-keys <- or ->),
	Motion speed (edit-field with V = ... s-1),
	Setting or skipping (forgetting) the relative zero.

These data will be put by the system into the relationship with corresponding data from ini_File, which contains parameters for every drive. Every working place has a specific ini_File that relates to its own device.

3.2 Ini-File

'Verhaltensspezifikation: XCTL-Steuerprogramm, Teil: Motorsteuerungs-Komponente (motors.dll)'

'IX Entwicklerdokumente, Analyse und Definition, Motoren, Verhaltensspezifikation v. 0.7.3. - Daten'.

Values in ini_File are set by the user. The dialog-box 'Drive parameters' is used (for example) for this activity. To enter the settings, one should first delete the ini_File (before executing the program), after which a series of dialog-boxes will appear to enable input of parameters.

Note: Besides the possibility to set the values of ini-File through dialog-boxes, there is also possible to edit the ini-File directly, and that possibility is often used in every-day work. These uncontrolled changes are sources of critical errors in the system.

3.3 Permitted drive positions (absolute positions)

For drives DC, DF, and TL the Target-position is entered in arcseconds (1 grade = 3.600 arcseconds); for drive AR in grades, and for drive CC in micro-meters. The permitted ranges of values are given as constants in ini-File: AngleMin, AngleMax for every drive.

Values in ini_File do not necessary correspond to physically maximal positions! If the physically maximal position is exceeded in the ini_File, the program will 'catch' this situation. Besides these values, ini_File containes also two constants for resolution width: AngleWidth, PositionWidth. (#Question: One - which one - is influenced by the setting of scrollbar).

An example for constants AngleMin, AngleMax, AngleWidth in one specific ini-File is as follows:

	DC [-15.399,4 .. 15.815,6], Resolution 0,4 arcseconds,
	DF [-1.255,6 .. 1.255,6], Resolution 0,02 arcseconds,
	TL [-18.990,38 .. 16.211,30], Resolution 0,5 arcseconds,
	AR [-296,91 .. 296,04], Resolution 0,001 grades,
	CC [-1.063,8 .. 1.063,8], Resolution 0,12 micro-meters.

#Note: DC and TL in the example: range of values is not multiple of resolution (maximal position is not achievable)! (#Question: does this apply also for minimal step-value?)

Note:
Current-positions and Target-positions in edit-fields 'Angle' and 'New angle' will be taken as relative positions (with respect to relative zero). Therefore, setting the relative zero has a consequence to the range of values for angles.

Note:
User's specifications of angles are internally transformed into drive-steps of the drive. One drive-step is the minimal move that the drive can physically perform. For this reason, every input to angle value is rounded to the whole number of drive-steps (#Question: How rounded?). Minimal and maximal positions of a drive in the form of code-steps is given in the ini-File as constants: PositionMin, PositionMax.

3.4 Step-values

For the drives DF, DC, and TL the step-value is entered in arcseconds, for drive AR in grades, and for drive CC in micro-meters. The permitted range of values are given as constants in ini-File: MinimalWidth, MaximalWidth.

Example (in one specific ini-File)

	DC [4 .. 1000],
	DF [2 .. 800],
	TL [2 .. 10.000],
	AR [2 .. 800],
	CC [2 .. 500] .

3.5 Motion speed

For drives DF, DC, and TL the motion speed is entered in arcseconds/sec, for drive AR in grades/sec and for drive CC in micro-meters/sec. The permitted ranges of values are given as constants in ini-File: MaxVelocity for every drive.

Example (in one specific ini-File)

	DF [0 .. 8.000],
	DC [0 .. 8.000],
	TL [0 .. 8.000],
	AR [0 .. 8.000],
	CC [0 .. 1.000].

4. Errors

Look also for the '#Error' mark in this document.

1. In Continuous motion-mode initiated with cursor-keys the keyboard buffer gets overloaded.
Solution: Control the event of key-press (under Windows).
2. Handling of on-off switch of the device is not adequately supported by a software.

5. Wishes for changes

Look also for the '#Wish' mark in this document.

1. All drives should be simultaneously manipulated with,

2. Storing of states in ini-File:

Previous practice: edit ini-File to achieve personal settings based on previous test series. This practice is problematic and leads to errors that are very hard to find.

Suggestion: Settings of manual adjustments should be saved in other files. Thus, one could deal with different situations (test series).

Controlled settings of ini-File parameters should be implemented only in dialog with checking of logic consistencies of values, and with possibility to save them in a "private" ini-File (see above).

Attention: particular drive-specific parameters in ini-Files should be protected (from unnecessary changes during normal operations). Those parameters are the following: IOADDR, RamAddr, Torque, RemoveLimit, Koeff_1/2/3.

Therefore: split the ini-File into two files:
- protected data
- editable data

3. Motion speed V could consistently have the same influence to all three operation modes (and not only to two, as it is now).
(Remark: for step-value it suffices maximal motion speed - prediction of Mr. Pfeiffer)

4. The built-in dialog box is not ergonomically optimal for the aimed functionality.

5. Step-values (for target-position) in dialog box as input assistance (combo-box)?

6. Input for moving drives should not be ignored, but prevented (function of the user-interface)! (in the case of mistake: first stop moving drives)

7. Stopping the drive is now possible only by exiting the dialog-box. Additional button 'Stop' for stopping the current drive should be introduced instead.

8. Invalid inputs: produce warning tone and ask the user shall that input will be automatically replaced with boundary value.

6. Open questions, i.e. deficiencies in the document
(+ solved, - still open)

+ Can one in Direct motion-mode (Stepwise motion-mode) stop the moving drive (and how)? (solved: 2.3 f)
+ Does the horizontal scrollbar shows the relative or absolute zero? (2.3 a)
+ Can the relative zero be set for the moving drive (better not)? (2.3 b)
+ Exiting dialog box: what happens with moving drives (are they stopped or left to move further)? (2.3 f)
+ DC and TL: range values are not a multiple of resolution (i.e., the smallest possible step of motion). Therefore maximal position cannot be reached!
Answer: this can happen because user can freely edit the ini-File and set such values that maximal position cannot be reached in stepwise operation mode. In those cases, maximal position can be reached in direct operation mode.
+ Measure of step-value: drive-step? (no, see comments in ini-File)
+ Step-value for AR doesn't suit range for AR! (the same as in question 5)
- Motion speed of AR: measure in arcseconds/sec (not in grade/sec)? (it is in grade/sec, but in specific ini-File that was taken as an example, these values were not in accordance with other drives.) (#Note by Budimac: still not clear enough.)
- Minimal values for step-value resolution and for the speed (like for position)?
+ Correction of invalid inputs (for example: out of range or not appropriate for the resolution): to inform the user of changed values?
Answer: Angle values must not correspond to resolution (they will be rounded - how?)
- How long lasts the normal motion with respect to motion in exceptional case (is explicit stopping necessary?)
- 1 arcsecond = ?? drive-steps
It is drive specific
+ What happens with scrollbar after setting the relative zero.
- Information on ini_Files in this document still unsystematic
- 2.4: Measuring the half-width: description still too short and not clear
- Exactly how to round? (Part 3.3, note 3)
# From where the software gets the absolute zero? (#Note by Budimac: We have the answer for that question. See note in 2.3, a.)
- in 2.3e the document structure is bad; instead stressing operation modes, better: 1. target-position, 2. speed, 3. step-value.
+ 2.3d (relative zero) is to late: better after 2.3a (current position)
- #Note by Budimac: one introductory section is needed for an 'independent' reader. That section would put the whole document into a broader perspective, and answer the questions: what id topography, diffractometry, ...? How many devices are there? What is the difference between device and work-place? What is being measured (i.e., what is sample) - only in the glossary we can find out that we observe the crystal, and somewhere before that a crystal is mentioned in an 'unknown context')? What is RTK4? Whay do we need different ini-Files and how many devices are there and how they differ?...

7. Related documents

Requirements specification 'Automatic adjustment'
Behavioral specification (requirements) 'Drives'
Behavioral specification (requirements) 'Detectors'
Overview

8. Changes in the document
#Question: To continue to log changes in the document?

Version 1.1: Changes from Version 1.01:

- 2.2 extended
- 2.3 a, b, d extended
- 2.3 f new
- 3: b, c, d modified
- 4, 9, 10 new
- 5: questions solved and new added

9. Sources of the document

1. Behavioral specification for manual adjustment served as a first project document in project seminar 'Software repair' in winter semester 1998/99. The foundation was a talk given in Adlershof by Physicist Mr. Pfeiffer about manual adjustment. The resulting version was discussed and improved during the seminar.

2. Remarks, january 1999: U. Sacklowski, B. Wolf, Mr. Pfeiffer

3. That document was topic of the review during Software engineering lectures in summer semester 1999. It served as a document for an exercise executed in CTE for determination of test cases. CTE (software tool) and classification trees were previously introduced by Mr. J. Wegener from DeimlerChrysler.

4. Helpful suggestions, May 1999: J. Wegener (DeimlerChrysler)

5. Document version 1.01 (July 14, 1999) was translated to English by Zoran Budimac (Novi Sad)

6. Remarks: August 2000: S. Freund, D. Hepp

7. During project seminar 'Software repair for novices' in winter semester 2000/01, the document was reviewed again by small student groups. This resulted in fundamental revision of the document:

        1. addition of new topics: 7, 8, 9, 10.
        2. New title: instead of 'Requirements document' (used for development of new software), now: Behavioral specification' (used for description of existing software)
        3. Standardization of comments in text: #Question, #Error, #Wish.
        4. Another review took place during the course on Software Engineering in summer 2001. Many useful suggestions will be adopted (Kay Schuetzler)

10. Glossary

Angle measurement units
    Grade
    unit measure for angles. 1 grade is 90th part of the right angle.
    Angle minute, min
    60th part of one grade. Marked as '
    Angle second, sec
    60th part of one minute. Marked as ''
    Arcus, arc
    radian measure of an angle
    Arcsecond, arcsec
    in this project it has the same meaning as angle second. This is introduced to avoid confusion with time seconds.

Arcsecond -> angle measurement units

Azimuth rotation -> drive classes

Bragg-reflex
maximal constructive interference that is reflected by monochromatic x-rays to parallel net levels of single crystal. The following condition holds: 2dsin(theta) = n(lambda), where d is distance between parallel net levels, theta is the incidence angle between ray and net level, lambda is the wave length of x-ray and n is any natural number. More net levels at disposal for every crystal, more such reflexes. The crystal structure can be discovered from measured angles. This value helps in adjusting the sample.

Collimator -> drive classes
an optic plate cylinder that displays the radiation input in such a way, that the radiation measurement look infinite to the observer. The collimator crystal is here used to reflect different wave lengths in different directions, in that way enabling isolation of one defined wave length from primary continual x-ray spectrum. By proper combination of more such collimators, one is able to closer inspect the structure of analyzed crystal. Therefore, the effect of collimator is to broaden x-rays.

Continuous motion -> operation modes

Diffraction fine -> drive classes

Diffraction coarse -> drive classes

Direct motion -> operation modes

Drive -> drive classes

Drive classes
    AR, Azimuth rotation
    drive for turning the sample holder. (Used in topography. Referenced object: sample holder)
    CC, Collimator
    drive for bending of collimator
    DC, Diffraction angle coarse
    drive for coarse setting of diffraction angles. Diffraction angle lies in the plane: collimator-sample-reception medium. (Used in topography. Referenced object: sample holder)
    DF, Diffraction angle fine
    drive for fine setting of diffraction angles. Diffraction angle lies in the plane: collimator-sample-reception medium. (Used in topography. Referenced object: sample holder)
   TL, Tilt
    drive for tipping of sample holder. (Used in topography. Referenced object: sample holder)

Fine adjustment
terminating process of manual adjustment, where fine adjustments are done using Diffraction fine, Tilt, and Collimator

Grade -> angle measurement units

Half-width
Difference between x-coordinate values (in practice mostly angle or distance) in points left and right of y-coordinate maximum (usually intensity) where the measured value has half of its maximum. Occasionally, the factor 1/(square root of 2) is possible, instead of 1/2. This happens when measured value represent amplitude whose square is proportional to intensity.

Menge der reflektieren... = Volume of reflecting x-rays
Motor position = Drive position
Halbwertsbreite = Half-width

Operation modes
    Direct motion
    motion of the current drive with some speed from current position to given target position
    Continuous motion
    motion of the current drive with some speed as long as cursor keys <- and -> are pressed or left or right buttons on the scrollbar clicked on.
    Stepwise motion
    motion of the current drive with some step-value from current position. The motion starts when cursor keys <- and -> are pressed or left or right buttons on the scrollbar clicked on. The motion speed is maximal.

Peak
maximal intensity of tested radiation

Rocking curve
Intensity dispersion of tested radiation in one dimension. The half-width of this curve serves as a quality criterion for adjusting the sample

Sample holder
holder where the sample lies

Stepwise motion -> operation modes

Second, sec -> angle measurement units

Test sample
Crystal sample that will be a subject of a topographic measurement

Tilt -> drive classes

Minute, min -> angle measurement unit

	DC (Diffraction angle, coarse - coarse adjustment of diffraction angle (angle of incidence)),
	DF (Diffraction angle, fine - fine adjustment of diffraction angle),
	AR (Azimuthal rotation) and
	TL (Tilt, tipping, relative to the plane of incidence).