cafe - maintenance

           Describes how to support this environment

           cafe

      General:
      This environment is not intended to be a single monument but
      rather a collection of independent procedures which interact
      via a common interface.
      The interface will be a structure variable containing
      all "state" informations necessary for interchange and user
      manageability. This variable is further called the
      "environment" of the cafe system.
      Environment:
      This environment variable is represented as a pointer to a
      structure, which itself consists of other structures. Its name
      is "env". The structure will be defined with the procedure
      "cafeenv__define()". This is described in detail below.
      User Front-end:
      Main idea of a front-end is to keep the user away from
      syntactic/semantic obstacles when entering commands.
      This will be done with a main loop reading command lines,
      interpreting them and letting them execute via the IDL execute
      procedure.
      This allows to bypass the environment to the command
      procedure and to simplify the expressions. For example the user
      does not need to enter quotation marks for strings which
      clearly have string type. Also it is possible to support simple
      scripting.
      This will be done with a top loop procedure (cafe_execute).
      Groups/Subgroups:
      To allow fitting of several data sets two concepts are considered:
      1.) Similar data sets which are stored separately but are to be
          fit with the same model.
          These data are subsumed in several subgroups in a single
          group.
      2.) Data sets which are to be fit with different
          models/parameters are to be stored in disjunct groups.
      Summarizing:
      - a group contains similar data
      - each group contains one model+parameter.
      Fit Model:
      The fit model is represented by a function which has access to
      the environment. It fetches from the environment all valid
      (defined) data points and computes the model y values from
      given x values. Procedure name shall be "cafefitfun".
      For each group another function shall be  called which performs
      the actual model evaluation. This function is called
      "cafemodel".
      The model itself is a string consisting of an algebraic
      expression which joins predefined model components. Each
      component is another IDL function which knows which parameter
      it needs.
      This has the advantage that parameters easily could equipped
      with meaningful names, and the model components perform a sort
      of grouping of parameters. Also the user has not to manipulate
      x/y variables.
      The model string has to be parsed so parentheses are supported
      properly. While doing parsing the model components are endorsed
      with x values and parameters.

      Parameters shall be stored in the environment as a large 3-dim
      array reflecting their sorting into model components and groups
      (and of course - one model component could have more than one
      parameter).  The parameters are structures contains (according
      mpfit procedure requirements):
      - parameter name,
      - value,
      - error information,
      - free flag (if not the parameter is fixed while fitting)
      - tie expression (to link a parameter to another)
      - some other components reasonable for fitting.
      Selecting a parameter will be done with a special procedure
      (cafeparam).
      Driver Functions (Subtasks):
      Some commands have to perform tasks which may vary because the
      command interfaces to the world outside. To support easy
      maintenance and to keep the command procedure small the real
      task should be done with a driver function/procedure which does
      the hard interfacing/processing.
      If doing so the fit environment easily could be adapted to user
      needs which may change during time.
      Examples are the loading of data for different file types
      ("data"), the fit models mentioned above or plot styles for
      data ("plot"), model or residuals.
      There should be a common syntax how to access the subtasks and
      how to pass parameters to the subtask. This is closer described
      in the "syntax"-topic.
      Print/Read:
      The commands should not use the standard "print" or "read"
      procedures but instead special procedures which use the
      environment to report into log file also. (procedures
      "cafereport" and "caferead").

      The commands in CAFE are implemented as external IDL procedures
      which must follow some restrictions:
      1.) Each command must have the a first parameter "env", which is
          a pointer to a structure containing all environment
          information. If the procedure needs environment parameter
          itself it must allocate its environment in the structure
          definition in file  CAFEENV__DEFINE.PRO.
          If the structure allocates some external resources, it must
          add the necessary cleanup statements in file
          CAFEENV__CLEANUP.PRO.
      2.) If the procedure should be visible for the global help it
          must reside in the same directory where cafe.pro is loaded
          from.
      3.) The procedure must at least support the option parameters
          /help and /shorthelp. If the optional parameter /help is
          given  the procedure must print out a description, if
          /shorthelp is used the procedure must print out a single
          line containing the command name and a short description.
      4.) The procedure should have a header starting with ";+" and
          ending with ";-". This is used by the help command to
          extract a description text.
          This text must contain the name/purpose/category section
          (capitalized, with ":" appended). Reasonable is a
          syntax/input/output/sideeffect section. Desirable is a
          version string section (modification history).
      5.) Parameter syntax should follow the remarks mentioned under
          the "syntax"-topic.

      1.) All procedures/functions are located in files starting with
          "cafe". There should be no more than one function/procedure
          in a file.
      2.) The procedure defining a command "foo" must have the file name
          "cafe_foo.pro". Otherwise the command is not found by the
          execution unit and the internal help command.
      3.) If the procedure needs some auxiliary procedures/functions
          "bar" then these should be put into files named
          "cafefoobar.pro". There must be no underscore in the file
          name because otherwise the files are considered as valid
          command names by the help command.
      4.) If a procedure foo calls a subtasks ("driver procedure")
          bar these subtask file name should be
          "cafe_foo_bar.pro". In this case the help command reports
          the subtask information properly.

           $Id: cafe_maintenance.pro,v 1.7 2003/12/29 11:59:37 goehler Exp $

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]