• 1. Installing PkFit and Filing on an OpenVMS workstation
• 1.1. Download the PGPLOT library
• 1.2. Download the archive-file
• 1.3. Expand and decode the archive-file.
• 1.4. Define and set the following logical variables
• 1.5. Creating the executable files
• 2. Installing PkFit and Filing on a UNIX workstation
• 2.1. Downloading the PGPLOT library
• 2.2. Downloading a TAS-prog archive file
• 2.3. Decode and expand the archive
• 2.4. Define and set the following environment variables:
• 2.5. Configuring the command file "createtasprog"
• 2.6. Creating the executable files
• 3. Main features of the Graphic User Interface
• 3.1. Graphic device type
• 3.2. Menus
• 3.3. Dialogues
• 4. Basic use of Filing
• 5. Basic use of PkFit
• 6. Using resolution calculation
• 7. Adding user functions
• 7.1. Syntax
• 7.2. Building again the PkFit executable file
• 8. New or undocumented features
• 8.1. Reading files in free format (PkFit and Filing)
• 8.2. Q scan and four-dimensional convolution (PkFit)
• 8.3. Linear constraint (PkFit)
• 8.4. Monochromator and analyzer curvatures (PkFit)
• 8.5. Instrument-configuration parameters (PkFit)

Download one of the two gzipped tar archive-files:

• TAS-prog_VMS_tar.gz which contains the applications from the ILL ftp server ftp.ill.fr/pub/tas/pkfit/appl/
• TAS-src_VMS_tar.gz which contains the FORTRAN sources from the ILL ftp server ftp.ill.fr/pub/tas/pkfit/src

E.g. use the sample FTP command lines:

cd pub/tas/pkfit/appl
binary
get TAS-prog_VMS_tar.gz

This requires the GUNZIP and VMSTAR utilities which are not part of the VMS system but can be easily found on the internet (e.g. "http://www.digital.com/info/vms-freeware.html" for executable files). Run those of the following lines appropriate to your computer. Note that the strings "disk" and [dir]" must be replaced by the correct ones.

    ! for Dec-alpha computer
    $ GUNZIP :== $disk:[dir]GUNZIP-AXP
    $ TAR    :== $disk:[dir]VMSTAR.ALPHA_EXE
     
    ! for VAX computer
    $ GUNZIP :== $disk:[dir]GUNZIP-VAX
    $ TAR    :== $disk:[dir]VMSTAR.EXE
     
    ! both Dec-alpha and VAX computer
    $ GUNZIP TAS-prog_VMS_tar.gz
    $ TAR/EXTRACT/VERBOSE TAS-prog_VMS_tar

This will create a subdirectory [.TAS-prog] or [.TAS-src] <code></code>into the current directory. Thus, make sure that the current directory is the appropriate one.

 PGPLOT_DIR      full pathname of the directory of the PGPLOT library files
 PGPLOT_FONT      full pathname of the name of the PGPLOT font file
 PGPLOT_DEV      name of the default graphic-device
 PGPLOT_XW_WIDTH      value of the ratio height/width of the PGPLOT window
 PGPLOT_ILL_PRINT_CMD      command for printing on the default printer

It is a good practice to do this by adding a set of command lines to your login.com file. This will automatically set the logical variables each time you log-in. The following is an example you must adapt to your specific case:

    # ----- used by the PGPLOT library
    $ DEFINE PGPLOT_DIR diskname:[directory.subdirectory1]
    $ DEFINE PGPLOT_ILL_PRINT_CMD "PRINT/QUEUE=my_Default_Printer_Name"
    $ DEFINE PGPLOT_XW_WIDTH 0.66
    $ DEFINE PGPLOT_DEV "/XSERVE"
    $ DEFINE PGPLOT_FONT PGPLOT_DIR:GRFONT.DAT

If you downloaded the application archive-file you are now able to run them. If not, just follow the instructions of the point 5 to compile and link the FORTRAN code.

First define the following temporary logical variables:

 PKFIT_DIR      full pathname of the directory of the source files
 OBJET_DIR      full pathname of the directory of the object files

Then execute the command file CREATETASPROG.COM to create the executable files PKFIT.EXE and FILING.EXE. E.g.:

    DEFINE PKFIT_DIR diskname:[directory.subdirectory1]
    DEFINE OBJET_DIR diskname:[directory.subdirectory2]
    @CREATETASPROG

Note that this command will delete all the object files at the end of the installation process.

If the PGPLOT library is not yet installed on your computer, download it from the PGPLOT ftp server astro.caltech.edu/pub/pgplot (131.215.240.1). Install it as explained in the file install.txt which comes together with the PGPLOT files. Check that you have at least the files:

     grfont.dat      (binary font file)
     libpgplot.a      (PGPLOT library)
     pgdisp      (required by /XDISP driver)
     pgxwin_server      (required by /XWIN and /XSERV driver)
     rgb.txt      (color name database)

Download one of the three gzipped tar archive-files:

• TAS-prog_HP-UNIX.tar.gz which contains the HP-UNIX executable files from the ILL ftp server ftp.ill.fr/pub/tas/pkfit/appl/
• TAS-prog_SGI.tar.gz  which contains the SGI executable files from the ILL ftp server ftp.ill.fr/pub/tas/pkfit/appl/
• TAS-src_UNIX.tar.gz which contains the FORTRAN source files from the ILL ftp server ftp.ill.fr/pub/tas/pkfit/src

E.g. use the sample FTP command lines:

cd pub/tas/pkfit/appl
binary
get TAS-prog_HP-UNIX.tar.gz

This requires the widely distributed gunzip and tar utilities. Decode and expand the archive to a new subdirectory TAS-prog or TAS-src, using the following lines. Note that the archive-file name must be replaced by the correct one.

    gunzip TAS-prog_HP-UNIX.tar.gz
    tar xvf TAS-prog_HP-UNIX.tar.gz

 PGPLOT_DIR      full pathname of the directory of the PGPLOT library files
 PGPLOT_FONT      full pathname of the name of the PGPLOT font file
 PGPLOT_DEV      name of the default graphic-device
 PGPLOT_XW_WIDTH      value of the ratio height/width of the PGPLOT window
 PGPLOT_ILL_PRINT_CMD      command for printing on the default printer

It is a good practice to do that by adding a set of command lines to your .login file. This will automatically set the logical variables each time you log-in. The following is an example you must adapt to your specific case:

    # ----- used by the PGPLOT library
    setenv PGPLOT_DIR /directory/subdirectory1
    setenv PGPLOT_FONT /directory/subdirectory1/grfont.dat
    setenv PGPLOT_DEV "/xserve"
    setenv PGPLOT_XW_WIDTH 0.66
    setenv PGPLOT_ILL_PRINT_CMD "lp -my_Default_Printer_Name"

If you downloaded one of the archive-file which contains the executable file, you are now able to run them. If not just follow the instructions of the points 5 and 6 to compile and link the FORTRAN code.

Before this file can be used, its contents must be adapted to your specific context. In fact, while the current operating-system (OS) is automatically recognized at run time, several environment variables must nevertheless be set by hand. Thus use a text editor to set the compiler and linker options and the library's access-pathname as explained below.

In the original file createtasprog, the six lines listed below define the computer configuration and must be adapted to your specific case. This set of lines is provided in three different versions:

    * the HP-UNIX version (OS name = "HP-UX") already set for the ILL computers,
    * the Silicon Graphic IRIX computer version (OS name = "IRIX*") already set for the ILL computers,
    * a "to be customized version". Replace the quoted strings with the appropriate option-list names or access pathnames as shown below:

 
    case '" ... your OS name ..."'
    setenv COMPILOPTION " ... your own compile options ..."
    setenv LINKOPTION " ... your own link options ..."
    setenv PGPLOT_Library " ... your own path name of the PGPLOT library ..."
    setenv X11_Library " ... your own path name of the X11 library ..."
    breaksw

If your compiler does not support the FORTRAN statements RECORD and STRUCTURE, set the environment variable OBJET_Pref as shown below. In other words, locate the string OBJECT_Pref in the file createtasprog. It will be found in two lines. Comment the first one (i.e. type a # in its first column) and uncomment the second one (i.e. delete the #) as shown below:

    # if FORTRAN supports the statements RECORD and STRUCTURE.
    # setenv OBJET_Pref "pkf_prefs.o pkfpg_pref.o"
    # if FORTRAN does not support the statements RECORD and STRUCTURE.
    setenv OBJET_Pref "pkfpg_nopref.o"

Execute the command file createtasprog (i.e. double click its icon) to create the executable files pkfit and filing:

    createtasprog

Note that this command will delete all the object files at the end of the installation process.

The graphic user interface of the VMS/UNIX version of PkFit and Filing is based on PGPLOT routines and thus cannot fully mimic the MacOS or the Motif interface. We give here a short description of its main features.

When launched, PkFit and Filing ask for the type of the terminal you are using. We list below some typical answers:

The menu bar is shown at the bottom of the PGPLOT graphic window. To select a menu, click on it. The item "Menu1" goes back to the main menu bar and when the menu bar is wider than the graphic window, the item "Next" displays the hidden items.

They can exhibit five kinds of items, the use of which is described below:

  - Static text. Display texts or comments on the dialogue window.   - Edit text. The active Edit text (only one at a time) accepts the text typed by the user and allows its editing.

• Click an Edit text to make it the active and selected one.
• Use the "<" and ">" keys to move the insertion point by one character to the left or to the right respectively. The selected character is highlighted. It is deleted when a key is typed or when the mouse is clicked.
• Use the Tab key to jump from one Edit text to the next one in the dialogue list. The new selected text becomes the active one.
• Use the delete key to erase the character left to the insertion point.
• Use the carriage-return key or the tab key to validate the change made in the active Edit text.
  

Note: The delete key must be assigned to a given key stroke (usually the backspace key). The item "General" of the menu "Preferences" makes it possible to perform a permanent assignment. The item "General" of the menu "Options" makes it possible to temporarily override the current assignment. This new assignment ends with the current session.   - Radio button. Of a series of radio buttons only one is selected at a time. The selected one is red. Click a radio button to select it while automatically deselecting the others.

  - List control Click the up or down arrow to scroll the item list.   - Button Click it to perform the associated action.

A printed manual for the UNIX/VMS versions of Filing is not yet available. Please refer to the tutorial for a description of a standard use and to the manual of PkFit for a description of the supported file formats. The following is a list of basic actions to handle TAS data files.

1. Open 1 to 7 data files (main menu, item "Open"). In the open-dialogue, select a directory and a file name and click the button "Open" for each file you want to open.
2. Click on the item "Menu1" to return to the main menu.
3. Optionally set the energy unit, the temperature, the normalization value (menu "Options", items "Energy unit", "Temperature" or "Monitor")
4. Optionally set the tolerance factors (menu "Options", item "Tolerances")
5. Optionally set or edit the resolution parameters (menu "Options", item "Set resol. param.") or input a new resolution parameter set from file (main menu, item "Open", file format "Resolution parameter file")
6. Add or combine the contents of the input files and plot the new data set (menu "Filing", item "Add" or "Combine")
7. Optionally plot all or some of the data files on the same graph (menu "Plot", item "Plot")
8. Print the current plot (main menu, item "Print")
9. Save the current plot (main menu, item "Save") to a PostScript file
10. Save the new data set to a new disk file at the ILL data format. (main menu, item "Save")

Note that Filing accepts data files with 1 to 500 points.

PkFit may be used in many distinct ways that will become apparent when reading the tutorial and, when using the program. A specific manual of PkFit for UNIX/VMS is not yet available. However, we encourage users to read the MacOS manual since the UNIX/VMS versions and the MacOS version are similar, except for the human interface.

As a quick start, we list here a set of basic actions which allows TAS data to be fitted.

1. Optionally set the preferences parameters (menu "Options")
2. Open a data file (main menu, item "Open")
3. Optionally set the energy unit and the normalization value; assign data columns to the plot axes (menu "Options")
4. Optionally add to the model a temperature factor, a kf or ki correction and/or an absorption correction (menu "Options")
5. Optionally choose a resolution calculation method, either Cooper-Nathans or Popovici (menu "ResCal", item "Activate Resol Calc")
6. Optionally set or edit the resolution parameters (menu "ResCal") or input a new resolution parameter set from a file
7. Initialize the fit parameters (menu "Fit", item "Init"). PkFit defines automatically the background and the peak width.
   1. Set the number of peaks (dialogue "Number of peaks")
   2. Center the cursors in the peak and then click to initialize the peak parameters
   3. Set the peak types (dialogue "Non fitting peak parameters")
   4. Optionally convolute peak shapes with the instrument resolution function (dialogue "Non fitting peak parameters")
8. Optionally add or remove constraints on the fit parameters (menu "Fit", item "Set fit param")
9. Perform the fit of the model (menu "Fit", item "Fit")
10. Print the observed points, the fitted curve and the values of the fit parameters (main menu, item "Print")
11. Save the current data set (if changed) to a disk file (main menu, item "Save")
12. Save the observed points, the fitted curve, the correction parameters and the values of the fitted parameters to a PostScript file and/or to a log file (main menu, item "Save")
13. To treat other data files repeat steps 1 to 12. However, for a series of similar spectra, repeating step 2 and 7-12 is generally enough.
14. Save a session file before quitting PkFit (main menu, item "Save"). Each line of the session file contains the name of a data file, which was processed, followed by the final values of the fit parameters.

Note that PkFit accepts data files with 1 to 500 points.

In PkFit, the resolution function can be calculated by means of two methods:

• the Cooper-Nathans method
• the Popovici method.

The Cooper-Nathans method, used in the old version of RESCAL for VAX computer, is a classical method based on rather simplifying assumptions, i.e. gaussian beams, angular collimations. The input parameters are taken either from the data files (TAS formats) or from a resolution parameter file. These parameters can be changed, listed, saved and printed via the appropriate menu items.

The Popovici method, used also in the program RESTRAX for UNIX and VMS workstations, is a more efficient method which permits to take into account focusing monochromators and analyzers as well as spatial beam collimations. The input parameters are taken from three sources:

• the RESCAL parameter set, used also in the Cooper-Nathans method, are taken either from the data files (TAS formats) or from a resolution parameter file.
• the focalization parameter set: the monochromator and analyzer curvatures, the sample diameter and height, must be given by the user. They can be edited in the "focalization parameter" dialogue.
• additional parameters describing the dimensions of the TAS elements and their distances, are taken either from the built-in parameter set of the ILL TAS-configuration or from a TAS configuration file.

Please refer to the tutorial for a description of a standard use of the resolution function and to the manuals of PkFit and RESTRAX for a detailed description. As a quick start, we list here a set of basic actions:

1. Choose the method to calculate the resolution calculation (menu "ResCal" item "Resol. Calc.").
2. Set the TAS configuration parameters (Popovici method only) either from the popup menu "built-in configuration parameters" of the ILL TAS or from the button "Read" to read them from a file (menu "ResCal" item "Resol. Calc.")
3. Check the resolution parameters (menu "ResCal" item "Param.")
4. Check the focusing parameters (Popovici method only) by clicking the button "Focusing param" in the dialogue "Set resol. param." (menu "ResCal" item "Param.").
5. View the resulting resolution function in the form of matrices (menu "ResCal" item "Matrix).
6. View the resulting resolution function in the form of ellipsoid cuts and projections in the Cooper-Nathans coordinates (menu "ResCal" item "Ell(CN)").
7. View the resulting resolution function in the form of ellipsoid cuts and projections in the dispersion frames (menu "ResCal" item "Ell(Disp)").
8. View the pseudo Bragg and Vanadium width at the current (Q,En) position (menu "ResCal" item "Width")..
9. Simulate a phonon profile by means of a Monte-Carlo integration technique (menu "ResCal" item "Phonon").
10. Read resolution parameters from a file (menu "ResCal" item "OpenResFile").
11. Save current resolution parameters to a file (menu "Save" item "ResFile").

In PkFit, you can add your own peak-shape to the built-in list in a very easy way. You have to modify only one file. However you will have to compile and link whole PkFit.

A user-defined peak function for PkFit is decared as a subroutine and must take exactly the argument list as shown below.

    USERFUNC1(YUser,Height,NUse,IN,XIN,A_BoseCorr,CENT,WID,
    1                    AREA,MyUserFuncName,N_Max_Data)


The arguments must be declared as follows:

Character MyUserFuncName*12
Integer N_Max_Data,NUSE,IN(N_Max_Data)
real YUser(N_Max_Data),XIN(N_Max_Data),A_BoseCorr(N_Max_Data)
real Height,CENT,WID,AREA
where the following are input parameters:

A vector of N_Max_Data values of the "En*Bose-factor" correction at the abscissa XIN.

NUSE	Number of points used
IN Index array of points  used
XIN	A vector of N_Max_Data abscissa values.
Cent	The peak position.
Width	FWHM of the peak.
Area	Peak area.
A_BoseCorr

and the following are output parameters:

MyUserFuncName      Name (up to 12 characters) of the user function.
Height                       Peak height
YUser                        A vector of N_Max_Data values of the user function at the abscissa XIN.

PkFit uses the MyUserFuncName in two distinct ways:

• The full name is appended to the popup menu in the dialogue "Non-fitting peak parameters"
• The first character is used as a marker of the top of the calculated peak in the graphic window. It is thus advisable to choose a name whose first character is not yet used (i.e., avoid using the following letters: I[ncoherent], G[aussian]., L[orentzian],.O[scillator], B[ragg], D[elta function]..).

Height must be a constant multiplyed by the ratio Area/Width. If not,  PkFit will compute wrong peak heights.

With the TAS-src package an example of the code of a user function is given in the file pkfituserfunc.f.

We assume here that you have already installed PkFit from the TAS-src package (either on OpenVMS or UNIX) as explained above, but without deleting all the object files. Therefore what you have to do is to modify the FORTRAN code of two subroutines and to add the subroutine of your function in the file pkfituserfunc.f:

• in subroutine SearchUserFunc increment the number of user functions N_UserFunc
• in subroutine UserFunc append a call to your subroutine as shwon in the table below. Of course di not forget to increment the test on the user-funciton index i_UserFunc by one.
• copy the code of an existing user-function subroutine, rename it, e.g. USERFUN3, and modify the code. Be sure to follow the syntax described above.

To build again the PkFit executable file, use the command file createpkfit, which is part of the TAS-src package.

• If a column-name line, containing the string "CNTS" (case insensitive) is found, the column assignment is performed automatically. The column named "CNTS" is associated with the Y plot-axis and the X plot-axis is associated with the first monotical data-column.
• otherwise a dialogue is shown which makes it possible:
  • to select manually the columns X, Y (and optionally DY ) columns.
  • to change the column names.

In the case of a Q scan, the four-dimensional convolution by means of the Monte-Carlo integration technique has been improved. A local dispersion-curve can be applied to a general Q scan [e.g. along (QH,QK)]. For a sinusoidal dispersion-curve, Q scans are not allowed since the dispersion-curve equation cannot be solved with respect to the energy.

Linear constraints can now be applied to fit parameters. In the fit-parameter field, simply replace the parameter value by a formula of the type p*Xn+q where p and q are real numbers, X is the fit-parameter name (e.g. H,W,C,A, or S) and n is the peak number. The fit will be performed with the constraint Xm=p*Xn+q, e.g. C1=-C2, A1=0.629*A2-10.

An option helps you to find optimum curvature values of both the monochromator and the analyzer. The monochromator is supposed to focus a parallel beam on the sample, while the analyzer curvatures are set to focus a point at the sample to a point at the detector. Usually these values are not far from the optimum values giving maximum intensities. This option is similar to the command "RO" in Restrax4.1 for Open-VMS/UNIX workstations (current Restrax version).

Simply click the corresponding button in the dialogue "Set focusing parameters" (menu "ResCal", item "Set resol. param.").

The calculation of the resolution function by means of the Popovici method requires extra parameters describing the instrument not available in the data files. A built-in table of the parameters of the ILL three-axis spectrometers has been implemented. A TAS configuration file is no longer necessary, but it can still be used to define either a non-standard configuration of ILL spectrometers or the configuration of a non-ILL spectrometer.

Select the item "Activate resol. calc." from the menu "ResCal". A dialogue is shown which allows you to choose the method to calculate the resolution function, either Cooper-Nathans or Popovici. In the latter case, choose the built-in configuration parameters (check box) and the ILL instrument (item list) or click the button "Read" to read the configuration parameters from a file.

Created by
Alain Bouvet and Alain Filhol