    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    }