    001    package calhoun.analysis.crf;
    002
    003    import java.util.List;
    004
    005    import calhoun.analysis.crf.io.TrainingSequence;
    006
    007    /** an interface to numerical solvers for optimizing the CRF objective function.  Conrad will call this when training the weights,
    008     * and this class is reponsible for evlauating the objective function iteratively and determining the weights.  Usually,
    009     * this class will just be a wrapper around some standard numerical solving package.
    010     * <p>
    011     * The optimizer is not required to find an optimal set of weights.  Although this is usually the goal and is usually feasible, the
    012     * interface only requires that a feature weight be assigned for each feature.  It is legal for the optimizer to return suboptimal weights.
    013     */
    014    public interface CRFTraining {
    015
    016            /** find the set of weights which maximizes the value of the objective function.  The {@link CRFObjectiveFunctionGradient} object will already
    017             * be configured witht eh appropriate training data, so it appears here as a pure function evaluation.
    018             *
    019             * @param fm            the model to train on.
    020             * @param data          the training data to use for training.
    021             * @return an array of doubles containing the optimal weights.
    022             */
    023            double[] optimize(ModelManager fm, List<? extends TrainingSequence<?>> data);
    024
    025            /** Sets the starting weights for the optimization.
    026             * @param weights an array of weights to use as the starting point for the optimizer.  The optimzier is not required to use this as a starting point.*/
    027            void setStarts(double[] weights);
    028    }