7. S(Q,E) modules
How to write own scattering modules for data fitting
version 4.8.1 and higher
7.1. Requirements
- A package with EXCI source files (download from
here)
This archive includes:
- source files of template modules (called
res_exci_name.f
) in./exci
- include files with common block declarations etc. in
./includes
- other source code to be linked with EXCI in
./src
- script
configure.EXCI
, which creates the makefile for easy compilation - the
./config
directory with configuration files containing settings and options for various types of UNIX/compiler systems.
- source files of template modules (called
- A fortran source code with an implementation of the user supplied S(Q,E) function. An existing source file from ./exci subdirectory should be taken as a template (see an example). Comments contained in this file provide a guide how to implement the model in a way compatible with RESTRAX.
- A fortran compiler. Options for Absoft Fortran for Linux, Digital Fortran (DEC Alpha) and GNU g77 are already available. The g77 should be available by default on Linux systems.
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):
- mangle names to lowercase (
-fcase-lower
) - append _ suffix (g77 default)
- no prefix for commons (g77 default)
- align data on 64-bit boundaries (
-malign-double
) - create position independent code (
-fPIC
) - and of course create a shared module (
-shared
)
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.