001    /**
002     * 
003     */
004    package calhoun.analysis.crf;
005    
006    import java.util.List;
007    
008    import calhoun.analysis.crf.io.TrainingSequence;
009    
010    /** an interface to algorithms that compute an objective function and its gradient for CRFs.  The objective function is used
011     * to determine the optimal weights during the CRF training process.  Usually the objective function value and gradient
012     * will be computed many times for different values of feature weights during a training.  A numerical optimizer which implements
013     * the {@link CRFTraining} interface is responsible for choosing the weights and calling this class.
014     * 
015     *  Different implementations are avialable to handle the Markov and semi-Markov CRFs and to handle different speed/memory tradeoffs.
016     */
017    public interface CRFObjectiveFunctionGradient {
018    
019            /** sets the training data that will be used for evaluation of the objective function.  This function will be called before <code>apply</code>
020             * is called to set up the training data.  Since it is expected that <code>apply</code> will be called many times, this funtion is 
021             * the place to do one time setup and caching.
022             * 
023             * @param fm    the model to use.  Defines the hidden states, transitions, and features.
024             * @param data  the training sequences on which to calculate the objective function.
025             */
026            void setTrainingData(ModelManager fm, List<? extends TrainingSequence<?>> data);
027    
028            /** computes the objective function value and the gradient.  This function will be called for each iteration of the numerical solver during training.
029             * In each iteration it takes a new set of feature weights and computes a value for the objective function along with its gradient.
030             * 
031             * @param weights an array of feature weights to use.  The length will equal the number of features in the model, and the values will change 
032             * for each call to apply. 
033             * @param grad an array which must be filled with the gradient vector when the function returns.  For each feature index, the array should contain an
034             * entry with the partial derivative with respect to that feature.
035             * @return the value of the objective function.  This is what the numerical optimizer will attempt to maximize.
036             */
037            double apply(double[] weights, double[] grad);
038    
039            /** Frees resources allocated by setTrainingData */
040            void clean();
041    }