Requirements for binary code

This page describes the basic details of what is required of your code if you choose to write in a language that compiles to binary (such as C/C++/Fortran), and you wish to use that code with the CADI toolkit to perform optimisation or sensitivity analysis.

You must produce a compiled object file with entry points initialize_ forward_ and user_init_. In C and Fortran, the function signatures are as follows

C -- void initialize_(char* path, int* pathlenptr, int junk) FORTRAN -- subroutine initialize(path, pathlen) integer pathlen character path(pathlen)	This function is only required when the toolkit is run in distributed mode. For stand-alone mode, you must still have the function, but it can (and should) have an empty body. In distributed mode, this function is called by the toolkit before any of your other functions are called. The toolkit passes in an argument path that gives the absolute path to the diectory that holds your compiled object. If your code opens any files, you need to prepend this path argument to any files you open. You cannot use paths without this prefix (such as in open('datdir/datfile.dat')). You are required to prepend the path string to your paths because the toolkit sometimes has to relocate your code while distributing it. The initialize function is the way in which the toolkit tells your code where it has relocated the code to. For C code, the path string is guaranteed to be nul terminated. For Fortran code, the path string is guaranteed to have no trailing spaces/padding. For those coding in C, please note that for uninteresting technical reasons, their is an additional argument junk that you should just ignore.
C -- void user_init_(int* nd, float* ranges, float* scales) FORTRAN -- subroutine user_init(nd, ranges, scales) integer nd, real*4 ranges(*), real*4 scales(*)	The user_init function is called by the toolkit at the start of the optimisation in order to get information about the optimisation. Your implementation must set nd to the number of dimensions in the parameter space you wish to optimize. The array ranges must be initialized (by you) to hold the minimum and maximum values for each parameter, in ascending order (so the first element in the array is set to the minimum value of parameter 1, the second element to the maximum of parameter 1, the third to the minimum of parameter 2, and so on). The third argument scales can be ignored.
C -- void forward_(int* nd, float* model, float* mfit) FORTRAN -- subroutine forward(nd, model, mfit) integer nd, real*4 model(nd), real*4 mfit	This is where your code does the 'real' work in the optimisation. The toolkit will call this function multiple times, passing in different points in the parameter space you define in user_init, and this function must evaluate the misfit of each of these points. The value nd is passed in, and is the same value as set in your user_init function. model is an array of real numbers (of length nd) specifying a point in the parameter space. Your function must set the value of mfit to be the misfit value of model. This value should be non-negative (negative values will still work, but some of the graphs/plots produced by the toolkit will look funny. Lower misfit values indicate better models. If you are using some of the statistical routines in the toolkit (like the Markov Chain Monte Carlo sampler), this routine should return log(prior(model)*likelihood(data|model)), and, if the nd argument is negative, should return prior(model).

You can take your source code and produce a shared object with the following 2 steps

1. Compile all your source to object format: fc -c *.f
2. Create a shared object: ld -shared *.o -o nativeUser.so

If you have stuffed things up with linking somehow, you will get an unsatisfied link error printed to the terminal when you try and load your code in the toolkit. If you want to save yourself the trouble of starting up the toolkit and loading your code, you can check if your code has any link errors by ommitting the '-shared' option in the linking stage (i.e. by typing 'ld *.o -o linkTest.bin'). You will get a link error complaining about a missing/undefined MAIN method (this is normal, and OK), but you should not get any other link errors. If you do, you need to fix them first.

Finally, there are some restrictions to the files that your program may access while it is running. These restrictions are:

• Any files (data files, for example) that your program uses must reside in the same directory, or a sub-directory of the one in which your shared object is.
• In stand-alone mode, you must specify the absolute path to any input files. Relative paths never work. See here for an example. (Actually, you can either have the absolute path, or follow the scheme in the next step, for distributed mode -- both approaches will work in stand-alone mode.)
• [distributed mode only:] When you open any files in your code, you must prepend the path string (passed to your initialize function) to the path of the file that you want to open. Any files (data files, for example) that your program uses must also be accessible/readable by the user who is running the cadi server. Making it readable by everyone is one solution, if the data is not sensitive.