nieminen/optiface/README.txt

An overall guide to the current F77 optimization interface
==========================================================

.. I shall leave this README along with the sources even though I have
   tried to include most of its contents (on 2007-01-17) to the
   developer documentation / report found among the writings of the
   project.

Just a couple of things you need to understand about my deranged
artifice here in order to perhaps maintain it, should somebody have
requested such a deed from you. "Top level" most visible to the
end-user is on the top of this text, and then we proceed closer to the
"low-level" Fortran 77 optimization codes downwards in the
text. Related concepts "on the same level" are shown indented before
the next level of things is presented. Sorry, but this text is not
very clearly written.

+---------------+
|Important files|, subject to changes more than others, are marked 
+---------------+
up with a nethackish square around their name.



Matlab interface for optimizers
  - is generated by a perl hack (was I to say "script") called genintf.pl
  - puts parameters into iparams and rparams, invisibly to the user
  - makes sure that parameter values are correct and consistent
  - calls the "mex level" and interprets return values
    (and, in order to call and interpret, must fully know the structure of
    iparams, rparams, iret, rret)

  genintf.pl
    - reads params.dat and produces the top-level matlab code
    - requires no changes unless you want to affect the user interface 
      characteristics

   +----------+
   |params.dat|
   +----------+
    - is where you describe the parameters of an optimization method
    - is where you describe the return values of an optimization method
    - THIS IS YOUR LINK between the F77 optimizers and your Matlab (or other)
      interface code.
    - needs direct synchronization with the "F77 optimization interface" level
      described below


Conveyor arrays and working space

  iparams, rparams
    - are arrays that convey all the knowledge of "how to optimize" further down the spiral...
    - have an internal, rather arbitrary, structure that is defined in params.dat

  iret, rret
    - are arrays for values that are either
      * return values from the optimization
      * not known beforehand (on the Matlab side of things), but required by optimization
      * copies of parameters, needed if their value can change during an optimization run

  iwork, rwork
    - are just working space for optimization


The mex interface in C
  - knows that iparams, rparams, iret, rret exist, and that the code on 
    "below levels" uses them for operation
  - reserves memory for iret, rret and working arrays
  - calls some canonical routines defined in the 'optiface' module
  - doesn't care in the least what the aforementioned routines actually do with 
    iparams, rparams, iret, rret, or what the conveyors contain in specific.
  - therefore, (I hope that) this is a rather unchanging mediator between the levels
    above and below; I expect little need of change in these codes.


F77 optimization interface
  - consists of abstraction subroutines and wrapper subroutines
  - when seen due, maps some things from iparams, rparams  to  iret, rret prior to 
    optimization
  - has to be manually synchronized with params.dat and current 
    implementations of the actual optimizers

  +----------+
  |mtdabstr.f|
  +----------+
    - needs to be updated along with params.dat when an optimizer interface changes

  +------------+
  |optwrapper.f| 
  +------------+
    - needs to be updated along with params.dat when an optimizer interface changes


F77 optimization codes
  - implemented by who-knows
  - with luck, also documented, so as to let you read the specs and create suitable 
    updates for params.dat, mtdabstr.f, and optwrapper.f