Custom constraints

This page describes how to extend the set of modules that implement constraints, cooling schemes, and permutation schemes for annealed surrogates. I have tried to keep everything as modular as possible with FORTRAN. Therefore, it seems extremely unlikely that, when you supply a new module for any one of the three tasks, you might want to change any of the others, or even the main module, randomize.f. Experts in simulated annealing are likely to know better cooling and permutation schemes than those available in this package. Experts, however, are likely to figure out how to provide these and I will therefore concentrate on the implementation of other cost functions.

If you want to supply any changed or new modules, here is the recommended sequence of actions.

Choose a new name for the module and place the source in the appropriate directory (cost, cool, or perm)
Add a line for the target all: to the Makefile in the directory randomize
Create the new executable by running make

For example, you could start from cost/auto.f by adding or deleting constraints and then name the source cost/mycost.f Then add the line

$(TEMPLATE) COST=mycost COOL=exp PERM=rand $(XFLAGS)

to Makefile and run make.

Cost function entry points

In order for the modularity to work, the subroutine calls must be kept identical through all constraint/cost function modules. This means that any additional information has to be exchanged and stored by means of common blocks. The blank common block
common nmax,cost,temp,cmin,rate,x
contains some useful items which are likely to be needed by the modules. These are the number nmax of data points, the current cost cost, the current temperature temp, the minimal cost cmin, the current rate of acceptance rate and the data set as a real array x. Note that x needs to be of fixed length syntactically, but since it is the last item of the common block, this is not essential as long as it is declared large enough to store nmax items.

The following entry points must be provided:

subroutine opts_cost(ncol)

Scans the command line for options specific to the cost function. Set ncol to the number of columns needed from the input file. On input, it is set to what is deduced from the -c and -m options.
Example: in cost/auto.f the number of desired lags is determined from the command line option -D and stored as an item in a common block to be available for the actual cost function. Similarly the option -W is scanned for the desired weighting.

subroutine what_cost()

Just prints a line saying which cost function is implemented.

subroutine usage_cost()

Prints that part of the usage message specific to the cost function, in particular maybe explaining the command line options.

subroutine cost_init()

Does all necessary initializations of the cost function. In particular, the goal value of some quantities, typically derived from the original time series, can be set.
Example: in cost/auto.f the number of lags is truncated to fit into the available space. Then the autocorrelation function of the data (x in the blank common block) is computed and stored as an array c0 in the common block /costcom/ for later use.

subroutine cost_transform(nmax,mcmax,nxdum,x)

Does any initial transformation on the data. The data length nmax, the number of columns mcmax, and the first dimension nxdum is provided in case that is needed. Finally, x is the data.
Example: in cost/auto.f the data is normalized to zero mean and unit variance, mean and variance are stored.

subroutine cost_inverse(nmax,mcmax,nxdum,x,y)

Inverts any initial transformation on the data. The data length nmax, the number of columns mcmax, and the first dimension nxdum is provided in case that is needed. Finally, x is the data and y a back transformed copy.
Example: in cost/auto.f the data is restored to its original mean and variance.

subroutine cost_full(iv)

Determines the value of the cost function given a configuration x. A nonzero value iv indicates that diagnostic output is desired.
Example: in cost/auto.f the autocorrelation function of the data is computed and averaged to yield the total cost, which is returned by the function.

subroutine cost_update(n1,n2,cmax,iaccept,iv)

Determines the value of the cost function when the data items n1 and n2 are exchanged. If the resulting cost is less than cmax, the change is accepted. In that case, iaccept is set to one. The new cost is stored in the blank common blok. On nonacceptance, its value is left unchanged. A nonzero value iv indicates that diagnostic output is desired.
Example: it is important to note that while the complete cost function requires O(nlag*nmax) computations, the interchange of two items can be monitored by O(nlag) computations. This is taken care of in cost/auto.f. Be absolutely sure that the update is done correctly for all possible cases! A mismatch between assumed cost and actual cost can lead to a desaster. Because of possible roundoff problems, the full computation is called for regularly by the cooling scheme.

constrained randomization * Table of Contents * TISEAN home