External module function Icalc - used by mcphas, singleion

In order to run mcphas,singleion the following function has to be present in the module file *.so:

extern "C" void Icalc(Vector & I,double * T, Vector & Hxc, Vector & Hext,
                      double * gJ, Vector & MODPAR,
                      char ** sipffilename, double * lnZ,double * U,
                      ComplexMatrix & Icalc_parstorage);

Note for windows users with MINGW the declaration should be extern "C" __declspec(dllexport) void Icalc(...).

The meaning of the symbols is as follows:

  on input
    T           temperature[K]
    Hxc         vector of exchange field [meV] (n-dimensional, for a set of n operators I)
    Hext        external magnetic field [T] (3 components)
    gJ          Lande factor as read from sipf file
    MODPAR      Vector with Parameters  read from single ion property file
    sipffilename    file name of the single ion parameter file
    Icalc_parstorage parameter matrix (initialized by Icalc_parameter_storage_matrix_init)
                   it should/may contain any information, e.g. population numbers of the
                   states (imaginary part of row 0)
                   and eigenvalues (real part of row 0) with values set by the most recent call
                   for this ion (use of this matrix is optional, it is provided to save time by
                   storing here information instead of recalculating it for every call of Icalc)
  on output    
    I           thermal expectation value of operator <I> (n- dimensional with n>=1,
                may be an arbitrary set of operators,
    lnZ         natural logarithm of single ion partition function
    U           single ion magnetic energy [meV]
    Icalc_parstorage     parameter matrix matrix (optional)
                   it should/may contain any information for the next call of Icalc, e.g.
                   population numbers of the states (imaginary part of row 0)
                   and eigenvalues (real part of row 0) ...

The module function must perform the following tasks:

1. check if the dimensions of vectors ${\hat \mathbf I}$ and ${\mathbf H}$xc (taken by mcphas from the number of interaction constant columns in mcphas.j) and MODPAR (taken by mcphas from the number of params in the single ion property file) agree with the module specifications. Note a module may be designed to take different dimensions depending on the input files, however the dimensions of vectors ${\hat \mathbf I}$ and ${\mathbf H}$xc has to agree and must be within the range of dimensions which can be treated by the module. If the check fails the module function should exit the program with an appropriate error message
2. the module should calculate from external field $\mathbf H_{ext}$ at a given temperature the thermal expectation values of the operators $\langle\hat I_a\rangle, \langle\hat I_b\rangle,\langle\hat I_c\rangle etc$ and return them as a vector $\mathbf I$. Input file parameters params are supplied as a vector MODPAR and Lande factor as gJ and can be used for this purpose. The Hamiltonian is usually assumed to be of the general form $\hat H=\hat H_0- \hat \mathbf M \mathbf H_{ext} - \hat I_a {\rm Hxc}(1) - \hat I_b {\rm Hxc}(2) -\hat I_c {\rm Hxc}(3) -\hat I_d {\rm Hxc}(4) ...$.
3. the natural logarithm of the partition sum Z should be calculated and returned as lnZ, $Z=\sum_i e^{-\epsilon_i/kT}$
4. the magnetic energy U should be calculated and returned as U, $U=\sum_i p_i=\sum_i \epsilon_i e^{-\epsilon_i/kT}/Z$
5. if $T<0$ all quantities should be evaluated assuming that all Boltzmann probabilities $p_i$ are zero except for the state number $n=(-T)$, for which the probability $p_n=1$.

... as an example the anisotropic doublet function is given as a loadable module in the file ./examples/cecu2a/1ion_mod/kramer.c, in the same directory a Makefile is given in order to show how this loadable module is compiled (for details see appendix A).

Another more complicated example, the calculation of the magnetisation in a tetragonal quasi-quartet system is given in Appendix C.