#ifndef Energy_H
#define Energy_H

/* Last edited on DATE TIME by USER */

#include <Triangulation.h>
#include <r4.h>

/* A generic energy function. */

typedef r4_vec_t Gradient;   /* A vector of energy gradients per knot */

typedef struct EnergyRec_t *Energy_t;

typedef struct EnergyMethods_t 
  { void (*defTop)(Energy_t self, ElemTableRec_t *top);
     /* Attaches the energy evaluator {eval} (bellow) to some topological
        triangulation.Must be called at least once before {defVar} below. */

    void (*defVar}(Energy_t self, bool_vec_t *variable);
      /* Tells {eval} (below) which knots {v} should be considered
        variables ({variable[v]==TRUE}) or fixed parameters 
        ({variable[v]==FALSE}); see below.  

        Must be called at least once before the first use of {eval}.
        Since it may be an expensive operation, clients should
        avoid calling it if the variable knot set hasn't changed. */

    void (*eval)(Energy_t self, Coords_t *c, double *e, bool_t grad, Gradient *eDc);
      /* Returns in {*e} the energy of the attached triangulation when the knots
        have the coordinates {c}. 

        Also, if {grad} is TRUE, {eval} will store in {*eDc} the
        gradient of {e}, that is, the partial derivatives of {e}
        relative to each element of {c}.

        An {Energy.T} object is typically used inside optimization
        loops where only some knots are being adjusted, while the
        others are kept fixed.  In that context the
        absolute value of the energy is not important; only energy
        differences are important.

        Accordingly, the {eval} method is free to omit any terms of
        the energy formula that depend only on fixed knots.
        (However, the decision to omit a term must not depend on {c}.)

        The client should be aware that if knot {v} is fixed, the
        corresponding component of the gradient {eDc[v]} may not be
        set by {evalGrad}, and therefore should not be used. */

    char * (*name)(Energy_t self);
      /* Prints a description of the energy function. */
  } EnergyMethods_t;

typedef struct EnergyRec_t 
  { EnergyMethods_t *m; /* Methods vector. */
    char *typecode;     /* String that identifies the actual allocation type. */
  } EnergyRec_t;

#define Energy_TYPE "Energy."
  /* The {typecode} of an {Energy_t} object must begin with this. */

#endif