### 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