• What you need
• Installing the TAS software package on your Macintosh
• Basic use of Filing
• Basic use of PkFit
• Using resolution calculation
• Adding user functions
• Kaleidagraph script
• New or undocumented features

• A Macintosh with 128K ROM or more.
• At least 1.5 Mb of available RAM memory space for each application
• A hard disk drive (preferably) with at least 1.1 Mb of available space for each application.
• Hardware requirements depend on the program version:
  • PkFit68020 and Filing68020 require a Motorola 68020, 68030 or 68040 processor.
  • PkFit68020_FPU and Filing68020_FPU require a Motorola 68020, 68030 or 68040 processor plus a floating point unit (FPU), which considerably speeds up the calculations.
  • PkFitPPC and FilingPPC require a PowerPC processor.
• System 7.0 or higher.

Download the TAS software package most appropriate to your computer. It is available in the form of a self extracting archive-file compacted by StuffIt and binhexed with Fetch. First unbinhex the file and then double-click its icon to expand it. You will be asked to give the name of the folder in which the following files will be expanded:

• the Filing application
• the PkFit application
• the ResCal application (which is also contained in PkFit)
• the help file "pkf.help"
• the Kaleidagraph documents "PkFitPlotScript.plot" and "PkFitPlotScript"
• the directory "makePlug-ins" and "Plug-ins" where is an example of a PkFit user-function

A printed manual of Filing is not yet available, however, this should not be a problem since the use of Filing is largely intuitive. Please refer to the tutorial for a description of a standard use of the program 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 (menu "File", item "Open"). In the open-dialogue, select a file name and click the button "Add" for each file you want to open.
2. Click the button "Done" to exit the open-dialogue.
3. Optionally set the energy unit, the temperature, the normalization value (menu "Options" item "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 (menu "File", item "Open", use the file format "Resolution parameter file" in the open-dialogue)
6. Add or combine the contents of data files and plot the new data set (menu "Filing", item "Add files" or "Combine files")
7. Optionally plot all or some data files on the same graph (menu "Plot", item "Plot")
8. Print the current plot (menu "File", item "Print")
9. Save the current plot (menu "File", item "Save") to a PICT file
10. Save the new data set to a new disk file in the ILL data format. (menu "File", 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 manual, the tutorial and, when using the program. 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 (menu "File", item "Open")
3. Optionally set the energy unit and the normalization value and 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 (menu "File", item "Print")
11. Save the current data set (if changed) to a disk file (menu "File", item "Save")
12. Save the observed points, the fitted curve, the correction parameters and the values of the fitted parameters to a PICT file and/or to a log file (menu "File", 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 (menu "File", 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 and ResCal for the MacOS, 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 "Activate 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 "Activate resol. calc.")
3. Check the resolution parameters (menu "ResCal" item "Set resol. param.")
4. Check the focusing parameters (Popovici method only) by clicking the button "Focusing param" in the dialogue "Set resol. param." (menu "ResCal" item "Set resol. 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 "Ellipsoid in Cooper coor.").
7. View the resulting resolution function in the form of ellipsoid cuts and projections in the dispersion frames (menu "ResCal" item "Ellipsoid in disp. frame").
8. View the pseudo Bragg and Vanadium width at the current (Q,En) position (menu "ResCal" item "Bragg")..
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 "Read resol. param. file").
11. Save current resolution parameters to a file (menu "File" item "Save"). Check the box "Resol. param." in the save dialogue.

In PkFit, you can add your own peak-shape to the built-in list, by means of "standalone code",i.e. Plug-ins files. The latter is the code of a subroutine which can be dynamically linked at runtime. Of course the arguments of the subroutine must strictly conform to what is expected by the program. The "standalone code" must be compiled with the same options and linked with the same libraries than the main program. PkFit also assumes that the file containing the "standalone code" is placed in the subdirectory "Plug-ins" of the application folder.

Note that before using a subroutine in the form of a "standalone code" it is advisable to execute it in the usual manner from within a small test program since there is no easy way to debug a "standalone code".

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:

and the following are output parameters:

and the following are output parameters:

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.

Compiling and linking with MPW

The TAS-prog software package provides the code of a sample user-function and the make file to create the standalone code.These files are in the directory makePlug-ins:

    * UserFunc.f : the FORTRAN code of a sample user function which computes a "square Lorentz" peak function.
    * PkFitUserFunc68k.make: a make file to compile and link it as a "68k code resource" with MPW.
    * PkFitUserFuncPPC.make: a make file to compile and link it as a "PPC code fragment" with MPW.

The standalone code of a Square-lorentzian peak shape is in the directory Plug-ins:

    * PkFitUserFunc68k: a file which contains a "68k code resource" of ID 1001.
    * PkFitUserFuncPPC: a file which contains a "PPC code fragment".

To create your own 68k code resource with MPW:

   1. modify the FORTRAN code of the subroutine USERFUNC in the file UserFunc.f.
   2. increment the ID of the resource (for example ResID=1002) in the make file PkFitUserFunc68k.make.
   3. select the item "Set Directory..." from the menu "Directory" and select the folder makePlug-ins as the current directory.
   4. select the item "Build..." from the menu "Build" (keyboard shortcut command-B) and type PkFitUserFunc68k in the edit text "Program name?".
   5. The new code resource will be added to the file PkFitUserFunc68k in the directory Plug-ins.

To create your own PPC code fragment in MPW:

   1. duplicate the FORTRAN code of the subroutine USERFUNC in the file UserFunc.f.
   2. rename the subroutine, i.e. USERFUNC2 and modify its contents.
   3. duplicate the line -export USERFUNC in the link options of the make file PkFitUserFuncPPC.make and replace USERFUNC by the name of your subroutine (e.g. USERFUNC2).
   4. select the item "Set Directory..." from the menu "Directory" and select the folder makePlug-ins as the current directory.
   5. select the item "Build..." from the menu "Build" (keyboard shortcut command-B) and type PkFitUserFuncPPC in the edit text "Program name?".
   6. The new PPC code fragment will be added to the file PkFitUserFuncPPC in the directory Plug-ins.

Each time PkFit creates a log file, it also creates a file with extension ".KGScript" which contains a Kaleidagraph script. Running these scripts with Kaleidagraph 3.0 or higher, automatically plots the data and the fitted curves and thus helps you producing documents with publishing quality. Click here for an example.

Warning!!! Be sure that files "PkfitPlotScript.plot" and "PkfitPlotScript", given in the TAS software package, are present in your PkFit folder otherwise the program will not be able to run the scripts.

1. Launch Kaleidagraph.
2. Select the item "Formula entry" from the menu "Windows".
3. Click the button "Formula posted note" (bottom-left of the window "Formula entry").
4. Click the button "Open" in the dialogue "Formula Posted Note".
5. Select a script file created by PkFit (extension ".KGScript").
6. Click the button "OK" in the dialogue "Formula posted note".
7. Click the button "Run" of the dialogue "Formula entry".
8. And magically enough your plot is displayed in a Kaleidagraph window.

1.- The option fixed-scale (Filing)

When this option is selected, the plot scale is kept unchanged until the user change it manually in the corresponding dialog (menu "Plot", item "Plot scale").

Simply check the box "Fixed scale" in the dialog "General options" (menu "Options, item "General options").

2.- Shift of the X-plot scale (PkFit)

It is now possible to redefine the zero of the X values. For example, to fit the gain and loss contributions with an harmonic oscillator, the zero energy must be determined accurately.

The shift value, X-shift, of the X-plot scale can be edited in the dialog "Plot scale" (menu "Plot", item "Plot scale").