7. S(Q,E) modules

7.1. Requirements
7.2. Compiling
7.3. Implementation of S(Q,E)

How to write own scattering modules for data fitting

version 4.8.1 and higher

7.1. Requirements

Extract the package:

The following command will extract the archive into a new subdirectory called restrax-version-exci:

gunzip < restrax-version-exci.tar.gz | tar -xf -

Make it your current directory:

cd restrax-version-exci

7.2. Compiling

Copy your source file into the ./exci subdirectory and add its name (without .f extension) to the list in the script configure.EXCI. Comment out the others if you want to compile only your module:

EXCIFILES="   \
#         res_exci_osc   \
#         res_exci_osc1   \
#         res_exci_phon   \
#         res_exci_bcm   \
#         res_exci_incom    \
        res_exci_mymodule "

Decide which compiler to use and select the appropriate config.<sys> file from ./config, or create your own file with appropriate compiler options. The <sys> extension is used as an argument to the configure.EXCI script. For example, to create a makefile for g77, you have to call

configure.EXCI g77

The script creates a file ./exci/makefile. Compile the module by calling

make -f exci/makefile

Your module res_exci_mymodule.so is now created in the ./lib subdirectory and should be accessible from the normal RESTRAX installation (./lib overrides the default path to the generic modules).

Note: in the win32 version, res_exci_mymodule.dll is created in ./bin directory. Since the version 4.8.3, the distributions include makefile_exci.amk for Absoft Fortran 90 compiler and appropriate batch file for compilation, makeexci.bat.

Load the library from RESTRAX using the command EXCI and the library name (without extension) as an argument:

ResTrax> EXCI res_exci_mymodule

Note: The environment variable LD_LIBRARY_PATH can be modified in the start-up scripts of RESTRAX to define another search paths for the shared EXCI libraries.

Compiler options:

Consider following options in order to make a module compatible with RESTRAX (g77 equivalents are given in the brackets):

7.3. Implementation of S(Q,E)

Only main features are documented here, see comments in a template source file for details.

Interface

      SUBROUTINE EXCI(icom,q,omexc,sqom)
      integer*4 icom    
      real*8 q(4),omexc(6),sqom(6)

The subroutine should return the values of excitation energies, omexc(6) and structure factors, sqom(6) for a given Q and E, q(4). Use [meV] for energy and reciprocal lattice units [h,k,l] for Q.

Tasks

The parameter ICOM controls following tasks:

ICOM<-10 Model initialization, called only once when loaded at runtime; sets the model title, number of branches, default filename for model parameters, parameter names, etc.
ICOM=0 Model initialization called on initialization request (e.g. before each FIT command). Sets the initial values of model parameters (if not done once for all in the previous task), creates lookup tables when needed.
ICOM=-1 Only omexc(6) values are required (e.g. for plotting dispersion branches).
ICOM=-2 Only sqom(6) values are required (e.g. for mapping S(Q,E).
ICOM>0

In this part implement the algorithm representing the scattering function S(Q,E).

The value passed by ICOM corresponds to the index of the particular ray-tracing event being passed in q(4). This feature can be employed when implementing lookup tables. The (Q,E,probability) values for all events are accessible in EXCI via the common REAL*4 variables QOM(1:4,j), PQOM(j). Similarly, the common integer variable NDATQOM informs about the dataset index for which the actual event was simulated. This permits to define model parameters specific to given dataset (e.g. temperature or background)

The maximum number of fitted parameters is currently limitted to 64. The maximum number of model components (e.g. dispersion branches) is 6.