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    }