/* Data fitting and approximation by generic function spaces.
**
** Last edited on 2007-01-04 03:33:26 by stolfi
**
** Copyright © 2003 by Jorge Stolfi and Anamaria Gomide, the
** University of Campinas, Brazil. See the rights and conditions
** notice at the end of this file.
*/

#ifndef FBas_H
#define FBas_H

#include <bool.h>

#include <stdio.h>

/* BASES FOR FUNCTION SPACES */

/* An {FBas} object is a countable ordered basis {bas[0..]} of real
  functions defined over a certain {d}-dimensional domain. Usually one
  works with finite segments of such basis.  
  
  All 2-dimensional arrays below are stored by rows. */

#define OBJ void
  /* Actually, {FBas} or a subclass thereof. */
 
typedef double FBas_EvalMth(OBJ *bas, int index, int dp, double *p);
  /* A method that evaluates the basis element {bas[index]}
    at the point {p[0..dp-1]}. */

typedef double FBas_EnergyMth(OBJ *bas, int i, int j);
  /* A method that returns the entry {[i,j]} of the matrix that
    describes a quadratic "internal energy" functional associated
    with basis {bas}. */

typedef int FBas_RoundSizeMth(OBJ *bas, int n, bool_t up);
  /* A method that rounds the integer {n} to a suitable size {nb}
    such that the space generated by the sub-basis {bas[0..nb-1]} 
    is closed under isometric domain transformations. If {up = TRUE},
    returns the smallest such {nb} not less than {n}; else returns
    the largest such {nb} not exceeding {n}. */

typedef void FBas_WriteMth(OBJ *bas, FILE *wr);        
  /* A method that writes a description of {bas} to the 
    stream {wr}, so that it can be read back. */

typedef OBJ *FBas_CopyMth(OBJ *bas);
  /* A method that returns a clone {n} of {bas}, with the same
    concrete class.  Any storage owned by {n} is disjoint from
    that owned by {bas}, but is initialized with the same contents. */

typedef void FBas_FreeMth(OBJ *bas);
  /* A method that reclaims all storage owned by object {bas}. */

typedef struct FBas_Data
  {  } FBas_Data;            
  /* Data record of an {FBas} object,
    containing internal parameters of a basis (knots, etc.) */

typedef struct FBas_Mths  /* Methods of an {FBas} object. */
  { FBas_EvalMth *eval;         /* Evaluates a basis element. */
    FBas_EnergyMth *energy;     /* Computes the internal energy matrix. */
    FBas_RoundSizeMth *roundsz; /* Rounds off the basis size. */
    FBas_WriteMth *write;       /* Writes the basis to a stream. */
    FBas_CopyMth *copy;         /* Creates a clone of the object. */
    FBas_FreeMth *free;         /* Recycles the object's owned storage. */
  } FBas_Mths;

#define FBas_TypeId "FBas."

typedef struct FBas
  { char *type;        /* Identifier of concrete type. */
    FBas_Data *d;      /* Internal parameters. */
    FBas_Mths *m;      /* Methods. */
  } FBas;

FBas *FBas_Cast(OBJ *bas);
  /* If {bas} (according to {bas->type}) is a subclass of {FBas},
    returns {bas} cast to that type; otherwise returns NULL. */
  
void FBas_M_Write(FBas *bas, FILE *wr); 
  /* The default {write} method for a generic spherical function.
    Writes a standard {FBas} header line and the specific
    subclass ID, then calls the subclass-specific {write} method, and
    closes off with the generic {FBas} footer. */

FBas *FBas_Read(FILE *rd);  
  /* Reads a basis from {rd}. */
   
/* FITTING FUNCTIONS TO DATA */

void FBas_Fit
  ( int np,       /* Number of samples. */
    int dp,       /* Number of coordinates per sample. */
    double *P,    /* Sample positions. */ 
    int dv,       /* Number of data values per sample. */
    double *V,    /* Sample values. */  
    FBas *bas,    /* Basis to use. */  
    int nb,       /* How many elements of {bas} to use. */
    double *W     /* OUT: coefficients of fit. */
  );
  /* Computes a linear combination {f(p)} of the basis elements
    {bas[0..nb-1](p)} that best matches a given set of samples. The
    coordinates of sample {i} are {P[k,0..dp-1]} and the
    corresponding data values are {V[k,0..dv-1]}. The weights are
    returned in {W}, so {f(p)[r] = SUM_i W[i,r] * bas[i](p)} 
    for {r} in {0..dv-1}. */

/* DEBUGGING */

extern bool_t FBas_Debug; /* Set this to TRUE to turn on debugging */

#endif