-------------------------------------------------
�Installing PkFit and Filing on UNIX or OpenVMS
-------------------------------------------------
Contents
--------
�Installing PkFit and Filing on an OpenVMS workstation
�Installing PkFit and Filing on a UNIX workstation
�Main features of the Graphic User Interface
�Basic use of Filing
�Basic use of PkFit
�Adding user functions
�New or undocumented features
�
Installing PkFit and Filing on an OpenVMS workstation
---------------------------------------------
1-Download the PGPLOT library
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)
�GRPCKG.OLB
�GRPSHR.EXE (PGPLOT library)
�GRPSHR.OLB
�PGDISP.EXE (required by /XDISP driver)
�PGXWIN_SERVER.EXE (required by /XWIN and /XSERV driver)
�RGB.TXT (color name base)
2-Download the archive-file
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
3-Expand and decode the archive-file.
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. "
www.digital.com/info/vms-freeware.html" for executable files or "
ftp.wku.edu/vms/freeware" for source 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 [.PKFIT] into the current directory.
Thus, make sure that the current directory is the appropriate one.
4-Define and set the following logical variables:
�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.
5-Creating the executable files
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.
�
Installing PkFit and Filing on a UNIX workstation
-------------------------------------------------
1-Downloading the PGPLOT library
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)
2-Downloading a TAS-prog archive file
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
3-Decode and expand the archive
This requires the widely distributed gunzip and tar utilities. Decode
and expand the archive to a new subdirectory pkfit, using the following
lines. Note that the archive-file name must be replaced by the correct
ones.
gunzip TAS-prog_HP-UNIX.tar.gz
tar xvf TAS-prog_HP-UNIX.tar.gz
4-Define and set the following environment variables:
�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.
5-Configuring the command file "createtasprog".
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"
6-Creating the executable files
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.
�
Main features of the Graphic User Interface
-------------------------------------------
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.
1-Graphic device type
When launched, PkFit and Filing ask for the type of the terminal you are
using. We list below some typical answers:
�a carriage return�the terminal is the default device defined by
environment variable PGPLOT_DEV
�/XSERVE� an X terminal
�/tk� a Tektronix 4100 terminal
�?� to get the list of supported terminals.�
2-Menus
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.
3- Dialogues
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 framed. 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.
�
Basic use of Filing
-------------------
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.
�
Basic use of PkFit
------------------
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.
7.1.Set the number of peaks (dialogue "Number of peaks")
7.2.Center the cursors in the peak and then click to initialize the peak
parameters
7.3.Set the peak types (dialogue "Non fitting peak parameters")
7.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 dat file which was
processed followed by the final values of the fit parameters.
Note that PkFit accepts data files with 1 to 500 points.
Adding user functions
---------------------
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.
Syntax
A user-defined peak function for PkFit:
�must take only one argument: a structure "MyStruct" declared as below.
�must have its name typed in UPPER CASE (at least for the 68k resource
code).
The FORTRAN structure containing the function parameters must be
declared as follows:
Structure /TypeMyStruct/
��Character UserFuncName*12
��Integer NUSE,IN(N_Max_Data)
��real YTMP(N_Max_Data),XIN(N_Max_Data),A_BoseCorr(N_Max_Data)
��real Hight,CENT,WID,AREA
End Structure �
where the following are input parameters:
MyStruct.NUSE Number of points used
�MyStruct.IN� Index array of points�used
MyStruct.XIN A vector of N_Max_Data abscissa values.
MyStruct.Cent The peak position.
MyStruct.Width �FWHM of the peak.
MyStruct.Area� Peak area.
MyStruct.A_BoseCorr�A vector of N_Max_Data values of the "En*Bose-factor"
correction at the abscissa XIN.
�
and the following are output parameters:
MyStruct.UserFuncNameName (up to 12 characters) of the user function.
MyStruct.Height� Peak height
MyStruct.YTMP A vector of N_Max_Data values of the user function
at the abscissa XIN.
PkFit uses the MyStruct.UserFuncName 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]..).
MyStruct.Height must be a constant multiplyed by the ratio MyStruct.Area
/MyStruct.Width. If not, PkFit will compute wrong peak heights.
Building again the PkFit executable file
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.
******************************************************************************
* Subroutine� * before� * after *
******************************************************************************
*SearchUserFunc* N_UserFunc=2� * N_UserFunc=3 *
******************************************************************************
* UserFunc� *If (i_UserFunc.eq.1) Then *If (i_UserFunc.eq.1) Then *
*� * �Call USERFUNC(MaStruct) �� * Call USERFUNC(MaStruct) *
* *Else If (i_UserFunc.eq.2) Then*Else If (i_UserFunc.eq.2) Then*
*� * �Call USERFUN2(MaStruct) �� * �Call USERFUN2(MaStruct) *
* *End If *Else If (i_UserFunc.eq.3) Then*
* * *��Call USERFUN3(MaStruct) *
* * *End If *
******************************************************************************
To build again the PkFit executable file, use the command file
updatepkfit, which is part of the TAS-src package.
------------------------------------------------------------------------
New or undocumented features
----------------------------
1.- Reading files in free format (PkFit and Filing)
�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.
2.- Q scan and four-dimensional convolution (PkFit)
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.
3.- Linear constraint (PkFit)
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.
4.- Monochromator and analyzer curvatures (PkFit)
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 smple 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.
Simply click the corresponding button in the dialogue "Set focusing
parameters" (menu "ResCal", item "Set resol. param.").
5.- Instrument-configuration parameters (PkFit)
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 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
Last update February 1997
------------------------------------------------------------------------
