Using the user-source keyword

Some of the programs of this package require user-provided source-code or library functions. This can, for instance, be a potential energy routine, a switching-function, etc. The keyword user-source in the RUN-SECTION of these programs allows importing user-provided source-code at run-time without altering the original source code. The keyword user-source is always used together with at least one other keyword (e.g., potential-routine or switch-function) which provides the name of an entity specified in the user-provided source-code. Typically this entity is a subroutine or some other callable object.

With user-source the path to (or the name of) a module containing user-provided routines is specified. The module must be importable into Python, i.e., it must either be a Python script (file extension .py), a compiled Python script (file extension .pyc) or a shared library (file extension .so). If the module is already in the systems $PYTHONPATH, the name of the module is sufficient.

The module must provide all user-defined routines required within the calling program. In many cases, those routines are written in Fortran or some other languages, probably not even by the user himself, but are provided by a third party. If the routine is written in Fortran we suggest using the f2py Fortran to Python interface generator available at the SciPy homepage. Another possibility could be writing a wrapper routine which can be imported into Python. A further possibility is also to start a background process (e.g. using the Python built-in subprocess module) and communicating with it through named pipes.

Simple example of a user-provided source file (Python): 

#!/usr/bin/env python
#
# my_pes.py 

import numpy

def potential(Q):
    """
    My PES routine: harmonic oscillator. 
    Q is a numpy array containing a coordinate vector.
    """

    return numpy.dot(Q,Q)/2