samer@0: /*
samer@0:  *	Copyright (c) 2002, Samer Abdallah, King's College London.
samer@0:  *	All rights reserved.
samer@0:  *
samer@0:  *	This software is provided AS iS and WITHOUT ANY WARRANTY;
samer@0:  *	without even the implied warranty of MERCHANTABILITY or
samer@0:  *	FITNESS FOR A PARTICULAR PURPOSE.
samer@0:  */
samer@0: 
samer@0: package samer.models;
samer@0: 
samer@0: import samer.core.*;
samer@0: import samer.maths.*;
samer@0: import samer.maths.opt.*;
samer@0: import samer.tools.*;
samer@0: 
samer@0: public interface Model
samer@0: {
samer@0: 	/** return size of vector this model expects */
samer@0: 	int getSize();
samer@0: 	
samer@0: 	/** model should begin observing this vector */
samer@0: 	void setInput(Vec x);
samer@0: 
samer@0: 	/** should infer values latent variables */
samer@0: 	void infer();
samer@0: 
samer@0: 	/**
samer@0: 		 contract is that getEnergy and getGradient
samer@0: 		must return correct values for current x after
samer@0: 		infer and compute has been called, but not necessarily
samer@0: 		before.
samer@0: 
samer@0: :q
samer@0: 
samer@0: 		This is to give model an opportunity to
samer@0: 		cache values of energy and gradient to avoid repeated
samer@0: 		computations.
samer@0: 	*/
samer@0: 	void compute();
samer@0: 
samer@0: 	/** return E = -log p(x) */
samer@0: 	double getEnergy();
samer@0: 
samer@0: 	/** return dE/dx */
samer@0: 	double [] getGradient();
samer@0: 
samer@0: 	public void dispose();
samer@0: 
samer@0: 	/** This presents a more functional interface to the model
samer@0: 	so that it can be driven by an optimiser. See classes
samer@0: 	Functionx and MinimiserBase in package samer.maths.opt. */
samer@0: 
samer@0: 	public Functionx functionx();
samer@0: 
samer@0: 	/** This represents a training algorithm for a Model
samer@0: 		Trainer is responsible for counting calls to accumulate()
samer@0: 		between flushes
samer@0: 	*/
samer@0: 
samer@0: 	public interface Trainer {
samer@0: 		/** collect statistics for parameter update */
samer@0: 		public void accumulate();
samer@0: 
samer@0: 		/** weighted accumulate */
samer@0: 		public void accumulate(double w);
samer@0: 
samer@0: 		/** use collected stats to update parameters and reset */
samer@0: 		public void flush();
samer@0: 
samer@0: 		/** Must be equivalent to reset(); accumulate(); flush();
samer@0: 			but can be optimised for non-batched training */
samer@0: 		public void oneshot();
samer@0: 
samer@0: 		/** reset accumulators without updating parameters */
samer@0: 		public void reset();
samer@0: 
samer@0: 		public void dispose();
samer@0: 	}
samer@0: }
samer@0: