dlogger.h

a useful spiking neural networks simulator

/** 
 * @file  dlogger.h
 * @brief Activation logging class
 *
 * @author Makino, Takaki <[e-mail]>
 * @date 2003-05-01
 * @version $Id: dlogger.h,v 1.2 2003/05/08 07:24:56 t Exp $
 *
 *  Copyright (C) 2003 Makino, Takaki.  
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2, or (at your option)
 *  any later version.

 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  
 */


#ifndef __dlogger_h
#define __dlogger_h

#include "dneuron.h"
#include <mak/infinity.h>

namespace punnets_common {

/// \addtogroup Logging Logging (drawing a graph of neuron potentials)
/// @{

/** Activation logging class.
 *
 *  This class periodically probes the state (potential value) of neurons, 
 *  and produces a log file of the state changes.  
 *  To use logging, you need to do the followings:
 *    - Register the neurons to be logged by calling add method of the logger.
 *      If you want to plot several neurons separately, specify offsets to displace the graph vertically.
 *      Or you may specify the horizontal displacement by delay.  This is useful for analyzing
 *      events with temporal delays.
 *    - Schedule the logger to the scheduler by calling schedule method of the logger.
 *    - Create gnuplot definition file by calling gnuplot_def method of the logger.
 */
 
class tlogger : public taction
{
	mutable tqueue que;
	ntime_t step, from, until, delaymin, delaymax;
public:
	/// The option of the logging. You may log threshold, external inputs, and partitions.
	/// Multiple of them can be specified by logical or.
	enum logoption 
	{
		shownone = 0,	///< Nothing 
		showthr = 1,	///< Threshold
		showext = 2,	///< External inputs
		showpart = 4	///< Partitions
	};
private:
	/// A class to keep a list of logging neurons.
	struct neuentry
	{
		ntime_t delay;
		real lastthr;
		tneuron_base *neuron;
		logoption logopt;
		real offset;

		neuentry(tneuron_base *in, ntime_t idelay, bool ishowthr, bool ishowext=true, real ioffset=0.0) : 
			delay(idelay), lastthr(1), neuron(in), logopt((logoption)((ishowthr ? showthr : 0) | (ishowext ? showext : 0))), offset(ioffset) { }
		neuentry(tneuron_base *in, ntime_t idelay, logoption ilogopt = showthr, real ioffset=0.0) : 
			delay(idelay), lastthr(1), neuron(in), logopt(ilogopt), offset(ioffset) { }
	};

	std::vector< neuentry > neus;
	std::vector< std::pair<tsynapse_base *, ntime_t> > syns;
	std::ostream &out;

public:
	/// Constructs a logger with output stream iout, time step istep, and logging range between ifrom and iuntil.
	tlogger(std::ostream &iout, ntime_t istep, ntime_t ifrom = 0, ntime_t iuntil = mak::Infinity) : step(istep), from(ifrom), until(iuntil), delaymin(0.0), delaymax(0.0), out(iout) { }
	virtual ~tlogger() { }

	virtual const char *getClassName() const { return "tlogger"; }
	virtual tqueue *queue() const { return &que; }

	/// Add a neuron to be logged. Two boolean specifies logging options of thresholds and externals.
	void add(tneuron_base &p, ntime_t delay, bool ishowthr, bool ishowext=false, real offset = 0.0) 
		{ neus.push_back(neuentry(&p, delay, ishowthr, ishowext, offset)); if( delay < delaymin ) delaymin = delay; if( delay > delaymax ) delaymax = delay; }
	/// Add a neuron to be logged. logoption specifies logging options.
	void add(tneuron_base &p, ntime_t delay = 0.0, logoption logopt = showthr, real offset = 0.0) 
		{ neus.push_back(neuentry(&p, delay, logopt, offset)); if( delay < delaymin ) delaymin = delay; if( delay > delaymax ) delaymax = delay; }
	/// Add a synapse to be logged. 
	void add(tsynapse_base &p, ntime_t delay = 0.0) { syns.push_back(std::make_pair(&p, delay)); if( delay < delaymin ) delaymin = delay; if( delay > delaymax ) delaymax = delay; }

	/// When activated by scheduler, the logger logs the current status to the log file.
	virtual void activate(tscheduler &scheduler, ntime_t current_time);

	/// Schedule the logger itself to the specified scheduler.
	void schedule(tscheduler &scheduler) { 
		scheduler.scheduleEvent( from + delaymin, *this );
	}

	/// Generate a GNUPLOT definition file to the specified stream.
	/// file is a file name of the log file.
	void gnuplot_def(std::ostream &os, std::string file);
};

/// @}

} // namespace punnets_common

#endif