/home/doxygen/libascend/compiler/extfunc.h

Go to the documentation of this file.

/*
    ASCEND modelling environment
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly, Kirk Andre Abbott
    Copyright (C) 2006 Benjamin Allan
    Copyright (C) 2006 Carnegie Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//*
    by Kirk Andre Abbott and Ben Allan
    Created: July 4, 1994.
    Version: $Revision: 1.5 $
    Version control file: $RCSfile: extfunc.h,v $
    Date last modified: $Date: 1997/07/18 12:29:30 $
    Last modified by: $Author: mthomas $
*/

#ifndef ASC_EXTFUNC_H
#define ASC_EXTFUNC_H

#include <utilities/ascConfig.h>
#include "relation_util.h"

/*------------------------------------------------------------------------------
    type definitions and forward decls
*/

typedef int ExtEvalFunc(int *mode, int *m, int *n,
   double *x, double *u, double *f, double *g);

enum ExternalFuncType {
  efunc_ERR = 0, 
  efunc_BlackBox = 10, 
  efunc_GlassBox = 20, 
  efunc_Method = 30 
};

struct GlassBoxExternalFunc {
  ExtEvalFunc *initial;
  ExtEvalFunc **value; 
  ExtEvalFunc **deriv; 
  ExtEvalFunc **deriv2; 
  ExtEvalFunc *final; 
};


enum Calc_status {
  calc_converged,
  calc_diverged,
  calc_fp_error,
  calc_incorrect_args,
  calc_error,
  calc_all_ok
};

enum Request_type {
  bb_none,        
  bb_first_call,  
  bb_last_call,   
  bb_check_args,  
  bb_recalculate, 
  bb_func_eval,   
  bb_deriv_eval,  
  bb_hess_eval,   
  bb_single_step  
};

struct BBoxInterp {
  enum Calc_status status;

  void *user_data;

  enum Request_type task;
  /* if someone still needs a nodestamp, we could go back to
     defining one, but it should really be inside user_data as
     ascend doesn't need it. */

};

typedef int ExtBBoxInitFunc(struct BBoxInterp *interp
        , struct Instance *data
        , struct gl_list_t *arglist
);
typedef void ExtBBoxFinalFunc(struct BBoxInterp *interp);
typedef int ExtBBoxFunc(struct BBoxInterp *interp,
        int ninputs, int noutputs,
        double *inputs, double *outputs, double *jacobian);

struct BlackBoxExternalFunc {
  ExtBBoxInitFunc *initial; 
  ExtBBoxFunc *value; 
  ExtBBoxFunc *deriv; 
  ExtBBoxFunc *deriv2; 
  ExtBBoxFinalFunc *final; 
  double inputTolerance; 
};


typedef int ExtMethodRun(struct Instance *context, struct gl_list_t *args, void *user_data);

typedef int ExtMethodInit( struct Instance *context);

typedef int ExtMethodDestroyFn( void *user_data);


struct MethodExternalFunc {
  ExtMethodRun *run; 
  void *user_data; 
  ExtMethodDestroyFn *destroyfn;
};

struct ExternalFunc {
  enum ExternalFuncType etype;
  CONST char *name; 
  CONST char *help; 
  unsigned long n_inputs; 
  unsigned long n_outputs; 
  union {
    struct GlassBoxExternalFunc glass;
    struct BlackBoxExternalFunc black;
    struct MethodExternalFunc method;
  } u;
};

/*------------------------------------------------------------------------------
  REGISTRATION / LOOKUP FUNCTIONS
*/


extern void InitExternalFuncLibrary(void);
extern void DestroyExtFuncLibrary(void);
extern int AddExternalFunc(struct ExternalFunc *efunc, int force);
ASC_DLLSPEC struct ExternalFunc *LookupExtFunc(CONST char *funcname);
extern struct ExternalFunc *RemoveExternalFunc(char *name);
extern void DestroyExternalFunc(struct ExternalFunc *name);
extern void PrintExtFuncLibrary(FILE *f);
ASC_DLLSPEC char *WriteExtFuncLibraryString(void);
ASC_DLLSPEC void TraverseExtFuncLibrary(void (*)(void *,void *),void *secondparam);


ASC_DLLSPEC unsigned long NumberInputArgs(CONST struct ExternalFunc *efunc);

ASC_DLLSPEC unsigned long NumberOutputArgs(CONST struct ExternalFunc *efunc);


ASC_DLLSPEC CONST char*ExternalFuncName(CONST struct ExternalFunc *efunc);
/*------------------------------------------------------------------------------
  EXTERNAL METHOD STUFF
*/

ASC_DLLSPEC int CreateUserFunctionMethod(CONST char *name
        ,ExtMethodRun *run
        ,CONST long n_args
        ,CONST char *help
        ,void *user_data
        ,ExtMethodDestroyFn *destroyfn
);
extern ExtMethodRun *GetExtMethodRun(struct ExternalFunc *efunc);
extern void *GetExtMethodUserData(struct ExternalFunc *efunc);

/*------------------------------------------------------------------------------
  BLACK BOX STUFF
*/

extern ExtBBoxInitFunc *GetInitFunc(struct ExternalFunc *efunc);
extern ExtBBoxFunc *GetValueFunc(struct ExternalFunc *efunc);
extern ExtBBoxFunc *GetDerivFunc(struct ExternalFunc *efunc);
extern ExtBBoxFunc *GetDeriv2Func(struct ExternalFunc *efunc);
extern ExtBBoxFinalFunc *GetFinalFunc(struct ExternalFunc *efunc);
extern double GetValueFuncTolerance(struct ExternalFunc *efunc);


ASC_DLLSPEC int CreateUserFunctionBlackBox(CONST char *name,
        ExtBBoxInitFunc *init,
        ExtBBoxFunc *value,
        ExtBBoxFunc *deriv,
        ExtBBoxFunc *deriv2,
        ExtBBoxFinalFunc *final,
        CONST unsigned long n_inputs,
        CONST unsigned long n_outputs,
        CONST char *help,
        double inputTolerance
);
ASC_DLLSPEC int DefaultExtBBoxInitFunc(struct BBoxInterp *interp
        , struct Instance *data
        , struct gl_list_t *arglist
);
ASC_DLLSPEC int ErrorExtBBoxValueFunc(struct BBoxInterp *interp
        , int ninputs, int noutputs
        , double *inputs, double *outputs
        , double *jacobian
);
ASC_DLLSPEC int DefaultExtBBoxFuncDerivFD(struct BBoxInterp *interp
        , int ninputs, int noutputs
        , double *inputs, double *outputs
        , double *jacobian
);
ASC_DLLSPEC int DefaultExtBBoxFuncDeriv2FD(struct BBoxInterp *interp
        , int ninputs, int noutputs
        , double *inputs, double *outputs
        , double *jacobian
);
ASC_DLLSPEC void DefaultExtBBoxFinalFunc(struct BBoxInterp *interp);
/*-----------------------------------------------------------------------------
  GLASS BOX STUFF
*/

ASC_DLLSPEC int CreateUserFunctionGlassBox(CONST char *name,
        ExtEvalFunc *init,
        ExtEvalFunc **value,
        ExtEvalFunc **deriv,
        ExtEvalFunc **deriv2,
        ExtEvalFunc *final,
        CONST unsigned long n_inputs, CONST unsigned long n_outputs,
        CONST char *help
);
extern ExtEvalFunc *GetGlassBoxInit(struct ExternalFunc *efunc);
extern ExtEvalFunc **GetValueJumpTable(struct ExternalFunc *efunc);
extern ExtEvalFunc **GetDerivJumpTable(struct ExternalFunc *efunc);
extern ExtEvalFunc **GetDeriv2JumpTable(struct ExternalFunc *efunc);
extern ExtEvalFunc *GetGlassBoxFinal(struct ExternalFunc *efunc);

/* @} */

#endif /* ASC_EXTFUNC_H */

---