---

inputs.c

Go to the documentation of this file.

#include <vector>
#include <functional>
#include <string>
using std::string;
#include <time.h>

#include "inputs.h"
#include "ipc.h"
#include "cmdparam.h"
#include "kernelfactory.h"
#include "fixedwtregion.h"
#include "retina.h"
#include "pointermap.h"
#include "kernelwrapper.h"
#include "stringutils.h"
#include "worldviews.h"
#include "shuffledrand.h"
#include "valuegencontainer.h"
#include "generic_stdlib.h"
#include "matrix.h"
#include "tnt_gnuplot.h"
#include "robj.h"
#include "neuralregion.h"
#include "neuralregionmap.h"
#include "neuralregionmanager.h"
#include "mathconstants.h"


#ifdef EXPLICIT_INSTANTIATION_FOR_STATICS
template class Msg::LevelHandler<Msg::MessageLevel,Msg::NumMessageLevels>;
template class ShuffledRandom<double>;
template class ValueGenerator_Increment<double>;
template class ValueGenerator_Expression<double>;
template class ValueGenerator_Correlate<double,synchronized_distribution<Distributions::uniform>,true>;
template class ValueGenerator_Random<double,synchronized_distribution<Distributions::uniform> >;
template class ValueGenerator_Random<double,synchronized_distribution<Distributions::normal> >;
#endif 


/******************************************************************************/
/* NamedValueGenerators class                                                 */
/******************************************************************************/

class NamedValueGenerators : public ValueGenContainer {
public:
  virtual cmdstat create(StringArgs args);
};


cmdstat NamedValueGenerators::create(StringArgs args)
{
  DistributedValueGeneratorFactory<double> vgf;
  
  const string name         = args.next(string(""));
  ValueGenerator<>* valgen  = vgf.create(args.recursiveparser());
  const string helpstring   = args.next(string(""));

  
  if (blackboard.define_param(DECLARE_PARAM(PARAM_DOUBLE,name.c_str(),false,
                                            valgen->valueptr())) == 1) {
    if (helpstring != "") params_define_doc(name.c_str(),cmdparam_dupstr(helpstring.c_str()));
    push_back(valgen);
    ipc_notify(IPC_ONE,IPC_STD,"Defined ValueGenerator %s",name.c_str());
  }
  else {
    delete valgen;
    ipc_notify(IPC_ONE,IPC_STD,"Could not define ValueGenerator %s; perhaps already defined",name.c_str());
  }
  return CMD_NO_ERROR;
}



/******************************************************************************/
/* Eyes class                                                                 */
/******************************************************************************/


class Eyes : public Inputs {
public:
  Eyes() : last_object_drawn(&permanent_contents),
           neuralregions("Region",blackboard),
           default_region_command("define_region height=BaseN*area_scale width=BaseN*area_scale"),
           initialize_weights(true), size_scale_override(-1),
           input_define_convolution_in_use(false) {  }
  
  virtual ~Eyes() { }

  virtual void uninit();
  virtual void init();

  virtual void reset() {
    permanent_contents.reset();
    namedgenerators.reset();
  }
  virtual void reset(long int seed) {
    permanent_contents.reset(seed);
    namedgenerators.reset();
  }

  virtual bool next();

  virtual void activate(const WorldViews& views, const ParamMap& argparams) {
    activate(views,
             argparams.get_with_default("learning",False),
             argparams.get_with_default("settle",True),
             argparams.get_with_default("activate",True),
             argparams.get_with_default("verbose",False));
  }

  virtual void activate(bool learn, bool settle_, bool activatefn=true)
    {  activate(permanent_contents,learn,settle_,activatefn);  };

  virtual void activate(const WorldViews& views,bool learn, bool settle_, bool activatefn=true, bool verbose=false);

  virtual bool   is_active(int objnumber, int eye) const
    {  return last_object_drawn->is_active(objnumber,eye);  }
  virtual double angle_of_object(int objnumber, int eye) const
    {  return last_object_drawn->angle_of_object(objnumber,eye);  }
  virtual double angle_of_object_at_location(int i, int j, int eye) const
    {  return last_object_drawn->angle_of_object_at_location(i,j,eye);  }

private:
  static void message(Msg::MessageLevel m, const string& s)
    {  NeuralRegionMap::message(m,s);  }
  
  CMDOBJ_DECLARE(Eyes,define_region);
  CMDOBJ_DECLARE(Eyes,connect_region);

  bool   has_default_region() {  return default_region!="";  }
  string ensure_default_region();

  void update_default_values();
  void register_params_and_commands( void );
  void select_worldview(const WorldViews& views);

  void define_input_pathway(const string& region_downstream, const string& eyename,
                            StringArgs& arglist, const double size_scale, const int layers_pereye );
  cmdstat training(StringArgs& arglist, const ParamMap& argparams);
    
  CMDOBJ_DECLARE(Eyes,input_undefine);
  CMDOBJ_DECLARE(Eyes,input_define);
  CMDOBJ_DECLARE(Eyes,input_define_generator);
  CMDOBJ_DECLARE(Eyes,input_print);
  CMDOBJ_DECLARE(Eyes,input_reset);
  CMDOBJ_DECLARE(Eyes,input_clear);
  CMDOBJ_DECLARE(Eyes,input_draw);
  CMDOBJ_DECLARE(Eyes,input_present);
  CMDOBJ_DECLARE(Eyes,input_present_object);

  CMDOBJ_DECLARE(Eyes,input_define_convolution);

  CMDOBJ_DECLARE(Eyes,load_snapshot);

  CMDOBJ_DECLARE(Eyes,step);
  CMDOBJ_DECLARE(Eyes,testing);
  CMDOBJ_DECLARE(Eyes,training);
    
  CMDOBJ_DECLARE(Eyes,uninit_network);
  CMDOBJ_DECLARE(Eyes,init_network);

  
  SETFNOBJ_DECLARE2(Eyes,inputs_pereye_setfn2);
  SETFNOBJ_DECLARE2(Eyes,blur_type_setfn2);
  SETFNOBJ_DECLARE2(Eyes,double_blur_setfn2);
  SETFNOBJ_DECLARE2(Eyes,exc_rad_setfn2);
  
  /* Obsolete */
  SETFNOBJ_DECLARE2(Eyes,distribution_setfn2);

  NamedValueGenerators namedgenerators;

  const WorldViews* last_object_drawn;
  WorldViews permanent_contents;
  WorldViews temporary_contents;

  typedef Retina        retina_type;
  
  typedef NeuralRegionMap neuralregions_type;
  neuralregions_type      neuralregions;
  
  KernelFactory kernel_factory;

  string default_region;
  
  string default_region_command;
  
  bool   initialize_weights;
  
  string default_input_target;
  
  static int    current_object_angle;
  static double world_size_scale;

  static Tristate progress_reports;
  static int    progress_report_interval;
  static int    startt;

  double size_scale_override;
  
  bool input_define_convolution_in_use;

  HooklistNum before_input;               
//HooklistNum after_presentation;         /**< Hook set for hooklists_run_list() */
  HooklistNum after_learning;             
  void advance_iteration_counter(int old_t, int new_t);
};



/* Static variables in Eyes */
int    Eyes::current_object_angle=0;
double Eyes::world_size_scale=1.0;

Tristate Eyes::progress_reports=Uninitialized;
int      Eyes::progress_report_interval=10;
int      Eyes::startt=0;

void Eyes::init()
{
  startt=0;

  /* Define toplevel area, if none already */
  ensure_default_region();
  
  /* Define inputs and optional convolution, if none already */
  if (!permanent_contents.has_been_defined())
    cmd_input_define_convolution();

  /* Define contents of each input area, if none already */
  if (permanent_contents.is_empty())
    permanent_contents.generate_default_contents();

  ipc_notify(IPC_ONE,IPC_SUMMARY,"Defined %d-connection network; %.1fMB%s total required for weight storage",
             int(neuralregions.size_unique_connections()),
             neuralregions.size_connection_bytes()/1024.0/1024.0,
             (NPEs>1 ? " on each PE" : ""));
}


string Eyes::ensure_default_region()
{
  if (default_region=="") cmddefs_exec_str(default_region_command);
  assert (default_region!="");
  return default_region;
}



void Eyes::uninit( void )
{
  cmddefs_declare_prereq_status( "init_network", CMD_NEVER_CALLED );
  iteration=0;
  presentation=0;

  permanent_contents.uninit();
  neuralregions.erase();
  default_region="";
  default_input_target="";
  ::network_initialized=false;
  startt=0;
  input_define_convolution_in_use=false;
  
  /* Clear out all training hooks defined */
  hooklists_empty_list(before_input);
//hooklists_empty_list(after_presentation);
  hooklists_empty_list(after_learning);
}



bool Eyes::next(void)
{
  /* Update parameters for this presentation */
  /* This barrier is superfluous (isn't it?) since the next() fns use
     the barrier-ed random distributions */
  ipc_barrier();
  bool status1 = namedgenerators.next();
  bool status2 = permanent_contents.next();
  return status1 && status2;
}



void Eyes::activate(const WorldViews& views,bool learn, bool settle_, bool activatefn, bool verbose)
{
  static int iteration_of_last_presentation=Uninitialized;
  if (iteration!=iteration_of_last_presentation) {
    iteration_of_last_presentation=iteration;
    presentation=0;
  }
  else
    presentation++;
  
  select_worldview(views);
  neuralregions.activate(learn,settle_,activatefn,verbose);
}


void Eyes::select_worldview(const WorldViews& views)
{
  for (WorldViews::const_iterator eye=views.begin(); eye!= views.end(); eye++) {
    retina_type* retina = dynamic_cast<retina_type*>(neuralregions.getptr((*eye)->get_name())->region());
    if (retina)
      retina->set_input(*eye);
  }
  
  /* Update globals for use in e.g. filename format strings */
  last_object_drawn = &views;
  current_object_angle = (int)floor(RADIANS_TO_DEGREES(CONSTRAIN_ANGLE(angle_of_object(0,0)))+0.5);
}


void Eyes::define_input_pathway(const string& region_downstream, const string& eyename,
                                StringArgs& arglist, const double size_scale, const int layers_pereye )
{
  const string eyenum = String::numeric_extension<string>(eyename);
    
  /* Save the user's default_region, to be restored before we finish */
  string default_reg    = default_region;
  
  /* True if input region has already been defined. */
  bool retina_defined = false;

  /* True if we will be defining ganglia layers between the input region and the
     target */
  const bool has_ganglia = (layers_pereye>0);

  
  /* Add each pathway to this input layer */
  for (int layer=0; layer<std::max(1,layers_pereye); layer++) {
    double sscale=size_scale;
      
    /* These are used for the first region defined, whatever it is */
    string target         = region_downstream;
    string connectionspec = "Blur_CircularRandom ::Region::"+default_region+"::rf_radius"; // Should honor various parameters instead

    /* Insert new Ganglia layer, if not connecting directly */
    if (has_ganglia) {
      const string convolvenum  = eyenum + String::stringrep(layer);
      const string convolvename = "Ganglia" + convolvenum;
      size_scale_override=sscale;
      const string ssoverride = String::stringrep(size_scale_override,String::StreamFormat(-1,'0',16,false));
      const string command = string("connect_region")
        + " name=Afferent" + convolvenum
        + " target="       + target
        + " source="       + convolvename
        // This copy of the size_scale is usually ignored, but it's
        // helpful if user is seeing the command execute:
        + " size_scale="   + ssoverride 
        + " sourcespec='type=Convolution'"
        + " " + connectionspec;
      cmddefs_exec_str(command);
      size_scale_override=-1;
      
      target=convolvename;
      sscale=1.0;
      connectionspec=arglist.stringrep();
    }

    /* Connect ganglia layer to retina layer, creating or overwriting it if need be */
    size_scale_override=(has_ganglia? world_size_scale : 1.0)*sscale;
    const string ssoverride = String::stringrep(size_scale_override,String::StreamFormat(-1,'0',16,false));
    const string command = string("connect_region")
      + " name=Afferent" + eyenum
      + " target="       + target
      + " source="       + eyename
      + (retina_defined? "" : " sourcespec='type=Retina" +
         string(!has_ganglia ? "" : " size_scale=" + ssoverride) + "'")
      + " " + connectionspec;
    cmddefs_exec_str(command);
    size_scale_override=-1;
    retina_defined=true;
  }
  
  /* Restore the value of default_region; we assume that none of the
     automatically-constructed ones defined here are of enough
     interest to be worthy of being the default.  Uses the public set
     command so that user can see that it has been changed when trying
     to recreate this process by hand, but sets the value first so
     that messages will not be printed unless requested. */
  default_region=default_reg;
  cmddefs_exec_str("set default_region=" + default_reg);
}



#define CMDARGP_DOC "Default value for the corresponding parameter for commands."
#define CMDARGP(name,initial_value,options,doc) PARAM_A(blackboard.lookup_map("::cmd"),name,initial_value,options,doc);



void  Eyes::register_params_and_commands( void )
{
  /* Define hook sets for cmd_training */
  before_input       = hooklists_define_list("before_input",   "iteration");
//after_presentation = hooklists_define_list("after_presentation", "iteration");
  after_learning     = hooklists_define_list("after_learning", "iteration");


  PARAM_A(blackboard,"display",0,.add_lower_bound(0),
          "Plot network activation, etc. every (display)th training or testing\n"
          "iteration.  If display==0, never do it; if display==1, do it every\n"
          "iteration, if display==2, do it every other iteration, etc.");

  PARAM_A(blackboard,"learning",True,.add_lower_bound(False),
          "Whether learning (as controlled by the various alpha_ parameters)\n"
          "is enabled.");

  PARAM_A(blackboard.lookup_map("::cmd"),"activate",True,.add_lower_bound(False),
          "Whether to pass a neuron's initial response through an activation function.\n"
          "Usually true, but this can be set to False for some commands to examine the\n"
          "initial response, or for commands like measure_stimulus_map which can work\n"
          "better with the smooth, continuous initial response than with the more patchy\n"
          "activated response.\n");
  
  PARAM_A(blackboard.lookup_map("::cmd"),"settle",True,.add_lower_bound(False),
          "Whether settling (as controlled by the tsettle parameter) is enabled or\n"
          "disabled.");
  
  PARAM_A(blackboard,"tend",50000,.add_lower_bound(0),
          "Upper bound for training iterations.");


  CMDOBJ_DOC(step,"init_network",this,0,"%s [<named_arguments>]* [<training_iterations>]",
          "Supported <named_arguments> include: <display>,<learning>,<settle>,<activate>.\n\n"

          "Same as training except that it interprets the parameter as a value relative\n"
          "relative to the current iteration (1 by default), rather than an\n"
          "absolute iteration number, and defaults to display==1. Example: \"step\"\n"
          "just trains for one iteration and calls plot.  Typically used at the\n"
          "command prompt for debugging or exploration, rather than in a command file.");
  blackboard.lookup_map("::cmd::step") /* Default arguments, overriding globals */
    .set_local("display",1);
  
  CMDOBJ_DOC(testing,"init_network",this,0,"%s [<named_arguments>]* [<tend>]",
          "Supported <named_arguments> include: <display>,<learning>,<settle>,<activate>.\n\n"
             
          "Same as training except that learning defaults to False.  The iteration counter\n"
          "is still advanced.");
  blackboard.lookup_map("::cmd::testing") /* Default arguments, overriding globals */
    .set_local("learning",False);
  
  CMDOBJ_DOC(training,"init_network",this,0,"%s [<named_arguments>]* [<tend>]",
          "Supported <named_arguments> include: <display>,<learning>,<settle>,<activate>.\n\n"

          "Trains the network for the current iteration, then repeats training until\n"
          "the iteration counter 'iteration' has reached the <tend>.  Sometimes it is\n"
          "appropriate to supply a specific tend iteration (e.g. `training 1000' trains\n"
          "until iteration 1000); other times it's more useful to supply an offset\n"
          "relative to the current iteration (e.g. `training iteration+1000' trains for\n"
          "1000 iterations more).  After training, the global parameter 'iteration' is\n"
          "equal to the specified tend.");

  CMDOBJ_DOC(uninit_network,NULL,this,0,"%s",
          "Marks network uninitialized so that network architecture parameters\n"
          "can be changed.  All weight values and training iteration hook\n"
          "definitions will be lost, and the iteration counter will be reset to\n"
          "zero.  However, other parameters keep their existing values, which can\n"
          "have surprising consequences.  When in doubt, it may be safest to quit\n"
          "the program and restart if changing the underlying architecture.");
  
  CMDOBJ_DOC(init_network,"uninit_network",this,0,"%s [<named_arguments>]*",
          "Supported <named_arguments> include:\n"
          "<initialize>,<essential_training_hooks_only>.\n\n"

          "Initializes network with the current parameters, suitable for\n"
          "beginning training anew.  A command file <filebase>.<iteration>.params\n"
          "is created with the current values of parameters, suitable for\n"
          "recreating the starting state later.  A single cycle of testing\n"
          "is done, iterating t to 1, in order to verify that everything is\n"
          "working properly.  This command is a prerequisite for most other\n"
          "commands, and will be called automatically the first time one of\n"
          "those commands is executed.");
  

  
  PARAM_I(PARAM_3BOOL,  progress_reports,False,True,
          "Whether or not to print messages during very long computations; defaults to\n"  
          "True for interactive sessions and False otherwise.");
  params_define_default_expr("progress_reports","interactive");
  
  PARAM_L(PARAM_INT,   progress_report_interval,0,
          "The minimum number of seconds between messages printed during very long\n"  
          "computations, such as training.  Only used if progress_reports is True.");
  
  PARAM_L(PARAM_INT,   startt,0,
          "Starting iteration to be used the next time training or testing begins.\n"  
          "This should not ordinarily be changed, but it can be used for debugging.");
  
  PARAM_A(blackboard,"essential_training_hooks_only",False,.add_lower_bound(False).add_upper_bound(True),
          "If this is true, inessential hooks such as plotting and analysis will be\n"
          "ignored during training and initialization.  (Whether or not a given command\n"
          "is ignored depends upon whether it was defined as a `catchup' command or not;\n"
          "see cmdparam.c.)  This defaults to true for an interactive session to\n"
          "facilitate exploration using a saved batch session; this avoids having too\n"
          "many images displayed automatically.");
  params_define_default_expr("essential_training_hooks_only","interactive");
  
  PARAM_A(blackboard,"rf_radius",6.0,.add_lower_bound(0.0),
          "Default radius (centered about the neuron) of an afferent receptive field.\n"  
          "Must not be larger than half the width of the input region (usually RN/2).\n\n"

          "For square radii, the floating-point value of the radius is rounded to the\n"
          "nearest integer.  For circular radii, the digits after the decimal point\n"
          "determine the shape of the blocky circular outline.  For small values of the\n"
          "radius you may want to set the decimal value precisely to achieve the most\n"
          "circular-looking outline; generally .5 works well.");
  
  PARAM_A(blackboard,"inh_rad",9.0,.add_lower_bound(0.0),
          "Default connection radius for lateral inhibitory weights.  See rf_radius\n"
          "for more information about using floating-point values.");
  
  PARAM_A(blackboard,"exc_rad",4.0,.add_lower_bound(0.0),
          "Default connection radius for lateral excitatory weights.  When the global\n"  
          "value of this parameter is changed after a LISSOM map has been defined, each\n"  
          "such map is converted into one with the smaller excitatory radius.  To change\n"  
          "only a particular map, change that region's value of this parameter instead.\n"  
          "See rf_radius for more information about using floating-point values.");



  /* Register default values for command arguments.  Eventually should
  probably add more documentation than this */
  CMDARGP("name",              string(""),  , CMDARGP_DOC);
  CMDARGP("objtype",           string(""),  , CMDARGP_DOC);
  CMDARGP("plotgroup",         string(""),  , CMDARGP_DOC);
  CMDARGP("parent",            string(""),  , CMDARGP_DOC);
  CMDARGP("child",             string(""),  , CMDARGP_DOC);
  CMDARGP("source",            string(""),  , CMDARGP_DOC);
  CMDARGP("target",            string(""),  , CMDARGP_DOC);
  CMDARGP("region",            string(""),  , CMDARGP_DOC);
  CMDARGP("type",              string(""),  , CMDARGP_DOC);
  CMDARGP("filename",          string(""),  , CMDARGP_DOC);

  CMDARGP("height",            1,.add_lower_bound(1), CMDARGP_DOC);
  CMDARGP("width",             1,.add_lower_bound(1), CMDARGP_DOC);

  CMDARGP("save_matrices",     False,       .add_lower_bound(False).add_upper_bound(True),
          "When using a plot routine, whether to save the matrices as ASCII in addition\n"
          "to any other plot format generated.");
  
  CMDARGP("gnuplot_plots",     False,       .add_lower_bound(False).add_upper_bound(True),
          "When using a plot routine, whether to generate gnuplot PostScript plots\n"
          "and save them to disk.");
  
  CMDARGP("ppm_plots",         True,        .add_lower_bound(False).add_upper_bound(True),
          "When using a plot routine, whether to generate .ppm bitmap images and\n"
          "save them to disk.");
  
  CMDARGP("weight_situate",    True,        .add_lower_bound(False).add_upper_bound(True),
          "Whether to situate weight plots in their location on the network.  If\n"
          "false, weights are shown in their own coordinate systems instead, which\n"
          "gives less information but requires less plot area.");

  CMDARGP("weight_bare",       False,       .add_lower_bound(False).add_upper_bound(True),
          "If true, suppresses extraneous details from weight plots, such as borders\n"
          "outlines, etc., without having to turn off the various other parameters.");

  CMDARGP("weight_fill_background",False,   .add_lower_bound(False).add_upper_bound(True),
          "If true, weight plots fill in all area not containing weights with the\n"
          "ppm_page color so that the weight outlines are visible.  At present,\n"
          "killed connections are not filled in with the background color, instead\n"
          "appearing as zero-strength connections, but at some point making\n"
          "them into the background color may be implemented.");

  /* Register parameters in subobjects */ 
  WorldViews::register_params_and_commands();
  kernel_factory.register_params_and_commands();
  neuralregions.register_params_and_commands();

  /*
    Strange but (currently) legal: Changes the setfn for a few
    parameters we do not own so that we will know when they change and
    can update our own structures; this should be ok as long as no one
    else has installed a special setfn for them (which should probably
    be checked).
  */
  SETFNOBJ_DEFINE2(this,inputs_pereye,inputs_pereye_setfn2);
  SETFNOBJ_DEFINE2(this,distribution,distribution_setfn2);
  SETFNOBJ_DEFINE2(this,blur_radius,double_blur_setfn2);
  SETFNOBJ_DEFINE2(this,blur_type,blur_type_setfn2);
  SETFNOBJ_DEFINE2(this,blur_radius_surround_multiplier,double_blur_setfn2);
  SETFNOBJ_DEFINE2(this,blur_range_multiplier,double_blur_setfn2);
  SETFNOBJ_DEFINE2(this,blur_scale,double_blur_setfn2);
  SETFNOBJ_DEFINE2(this,exc_rad,exc_rad_setfn2);
  
  CMDOBJ_DEFINE_CATCHUP(this,0,define_region,
          "%s [<named_arguments>]* [<name> [<named_region_arguments>*]]",

          "Supported <named_arguments> include: <name>,<type>,<initialize>,\n"
          "<height>,<width>,<xoffset>,<yoffset>.\n\n"

          "Supported <type>s include: LISSOM (default), Convolution, Retina\n"
          "(At present only LISSOM accepts any <named_region_arguments>.)\n\n"

          "Define a new neural region with the given <name>, which defaults to\n"
          "'Primary'.  After definition, the value of default_region is set to\n"
          "this <name>, e.g. for plot_unit and plot_unit_range.  (Often this\n"
          "command will only need to be called explicitly once, for a top-level\n"
          "region, and then the rest of the input pathway can be constructed to\n"
          "match it by connect_region using default_region.)\n\n"

          "After the default_region is set, the command (if any) specified in\n"
          "'Region::.defaults::<type>::default_command' is executed.");
  blackboard.lookup_map("::cmd::define_region") /* Default arguments, overriding globals */
    .set_local("type",string("LISSOM"))
    .set_local("name",string("Primary"));
  PARAM_A(blackboard.lookup_map("::Region"),"num_aff_inputs",1,.add_lower_bound(0)
          .add_default_expr("num_eyes*(layers_pereye>?1)"),
          "Parameter for a LISSOM map specifying the number of afferent inputs that\n"
          "you will eventually connect.  Most region types do not need this information,\n"
          "since it is implicit in the calls to connect_region, but LISSOM maps currently\n"
          "must know num_aff_inputs when they are created because they initialize all\n"
          "weights at that time.  Warnings will be generated if the number of actual\n"
          "calls to connect_region before the first iteration does not match this\n"
          "parameter's value.\n");
  
  PARAM_A(blackboard.lookup_map("::cmd"),"initialize",True,.add_lower_bound(False),  
          "Whether to initialize the internal state of a region or a set of connections\n"
          "when creating it.  Not usually changed to false by users, but some commands\n"
          "(e.g. load_snapshot) specify false because they will be initializing the\n"
          "objects themselves.");
  PARAM_A(blackboard.lookup_map("::cmd::define_region"),"xoffset",0.5,,
          "When creating a new region, where to place the horizontal (x) axis of the\n"
          "coordinate system origin.  At present many region types ignore this parameter\n"
          "and always place the origin at (0.5,0.5).");
  PARAM_A(blackboard.lookup_map("::cmd::define_region"),"yoffset",0.5,,
          "When creating a new region, where to place the vertical (y) axis of the\n"
          "coordinate system origin.  At present many region types ignore this parameter\n"
          "and instead always place the origin at (0.5,0.5).");
  
  CMDOBJ_DEFINE_CATCHUP(this,0,connect_region,
          "%s [<named_arguments>]* [<connection_arguments>*]",

          "Supported <named_arguments> include: <name>,<target>,<source>,<sourcespec>,\n"
          "<size_scale>.\n\n"

          "Define a new set of connections from the neural region <target> to the\n"
          "region <source>.  The <connection_arguments> are as for\n"
          "input_define_convolution, which see.  (Exception: named arguments cannot\n"
          "be used in the <connection_arguments>, because they will be processed in\n"
          "this command instead, and will thus have no effect.)\n\n"

          "The connection <name> defaults to 'Afferent'.  All connections to a given\n"
          "<target> MUST have a unique <name>.  In addition, it is usually a good idea\n"
          "to keep all connection <names> for a given <source> unique, since e.g. plotting\n"
          "parameters are stored with the <source> and not the target.\n\n"
                        
          "If a <sourcespec> is given, the <source> region will be created\n"
          "(or recreated) with a size that provides full connectivity (by default)\n"
          "for the target region with this size, connection radius, etc.");
  blackboard.lookup_map("::cmd::connect_region") /* Default arguments, overriding globals */
    .set_local("name",string("Afferent"));
  PARAM_A(blackboard.lookup_map("::cmd::connect_region"),"sourcespec",string(),,
          "If this argument is non-empty (even a quoted space will do), a new source\n"
          "region will be created (and will replace any old one by that name, if present.)\n"
          "Default sizes for the source are computed from the <target>, <size_scale>, and\n"
          "<connection_arguments>, and these values are combined with the value of this\n"
          "parameter and then passed to the define_region command to define the region.");


  CMDOBJ_DEFINE_CATCHUP(this,0,input_define,
          "%s [<name> [<parent> [<objtype> [<input_object_arguments>*]]]]",
          
          "Define a new persistent input object with the given <name>.\n\n"

          "The <parent> may be the name of one input region, e.g. EyeX, where\n"
          "X is a numeric digit representing a single eye, \"\", \'\', or 'All'\n"
          "for all input regions, or the name of a previously defined\n"
          "Input_Composite object. (To keep yourself from getting confused about\n"
          "which regions are included in `all input regions', you should probably\n"
          "not change num_eyes after you call this command.)\n\n"

          "The <objtype> may be any of the following (prefixed with `Input_'):\n\n"
          
          "  Composite,UniformRandomNoise,Gaussian,CircularGaussian,\n"
          "  SineGrating,Gabor,PGM,Clone,Rectangle\n"
          "  FuzzyLine,FuzzyDisc,FuzzyRing\n\n"
          
          "See the documentation for the corresponding constants for more\n"
          "information on that particular object type.\n\n"
          
          "The remaining parameters are determined by the <objtype>.  They\n"
          "can generally be specified either by position, i.e. by listing\n"
          "them in order, or by name, e.g. by specifying xsigma=5.  All\n"
          "named arguments must follow any positional arguments.\n\n"

          "Most or all floating-point parameters may be a ValueGenerator, i.e.\n"
          "any <valuegenerator> accepted by the input_define_generator command.\n"
          "If the object is being defined in more than one input region, the\n"
          "specified <valuegenerator>s apply only to the first region.  Objects\n"
          "in the remaining regions are created with references to the\n"
          "corresponding parameters in the first, so that e.g. random values are\n"
          "fully correlated between the input regions.\n\n"
          
          "If you wish to introduce some degree of uncorrelation between\n"
          "objects defined in more than one region, you may substitute for any\n"
          "ValueGenerator parameter the extended syntax:\n\n"

          "  \"Uncorrelate <uncorrelation-ratio> <lower-bound> <upper-bound> <valuegenerator>\"\n\n"

          "This will add or subtract a random value to the value generated\n"
          "in the first region, scaled by the difference between the bounds times\n"
          "the uncorrelation-ratio, and cropped by the bounds.  For instance,\n\n"
          
          "  \"Uncorrelate &uncorrelation 0 RN  Random RN/2 RN/2\"\n\n"

          "when uncorrelation=1.0 will create a random number generator\n"
          "in the range 0..RN in the first region, and will effectively\n"
          "uncorrelate the value entirely within that range in all the\n"
          "other input regions.  (This is the default for <cx> and <cy>\n"
          "parameters, except that uncorrelation is not necessarily 1.0.)\n\n"

          "Since ValueGenerators and input objects are extremely flexible, be\n"
          "sure to look at images of the inputs for a number of sample iterations\n"
          "so that you can verify that the inputs are being generated as you expect.\n"
          "You can also look at the logfile (when input_log is true) to verify\n"
          "the average and range for some of the generated values.");
 
  CMDOBJ_DEFINE_CATCHUP(this,2,input_define_generator,
          "%s <name> <valuegenerator> [<helpstring>]",

          "Define a new ValueGenerator whose value is updated before every input\n"
          "presentation.  A ValueGenerator is like a generalization of a parameter\n"
          "of type PARAM_DOUBLE which supports automatic updating from e.g. a\n"
          "random distribution.  This command allows you to define a named\n"
          "ValueGenerator which can be referred to when later defining input\n"
          "objects; this enables you to e.g. define a single random number\n"
          "which controls multiple objects in unison.  The value also\n"
          "becomes a parameter, so it will henceforth show up in documentation,\n"
          "online help, etc., and can be set or queried like any parameter.\n\n"
          
          "Possible values for a <valuegenerator>:\n\n"
          
          "  <expr>               A floating-point expression.  (Ex: 2*PI)\n\n"
          
          "  &<param>             A reference to a parameter.  (Ex: &xsigma)\n"
          "                       Future changes to the parameter will be\n"
          "                       reflected in the ValueGenerator, so this\n"
          "                       form provides a means for controlling a\n"
          "                       ValueGenerator after creation and linking\n"
          "                       multiple ValueGenerators together.  This form\n"
          "                       is also accepted for the numeric arguments of\n"
          "                       all the other ValueGenerators defined below.\n\n"

          "  \"Random <m> <r>\"     A random number from the uniform distribution\n"
          "                       centered at mean <m> and extending radius <r>\n"
          "                       in either direction (inclusively on the lower\n"
          "                       side, exclusively on the higher).\n"
          "                       (Ex: \"Random PI/2 PI/2\" or \"Random &mean &radius\"\n\n"

          "  \"Normal <m> <r>\"     A random number from the normal distribution\n"
          "                       centered at mean <m> with sigma (approx. half-width at\n"
          "                       half-height) <r>.\n"
          "                       (Ex: \"Normal PI/2 PI/2\" or \"Normal &mean &radius\")\n\n"

          "  \"Increment <s> <i>\"  Starts at value <s>; before each presentation, it\n"
          "                       is incremented by <i> (which may be negative or\n"
          "                       non-integer).  Note that increment occurs *before*\n"
          "                       each presentation, so decrement the starting\n"
          "                       value if needed.\n"
          "                       (Ex: \"Increment -1 1\" to count from 0 by 1)\n\n"

          "  \"Correlate <m> <u> <lb> <ub> \"     Generate a value correlated with\n"
          "                       the given master variable <m> within a correlation\n"
          "                       constant of <u>.  Optionally crops to the given\n"
          "                       range [<lb>..<ub>].  This description may be\n"
          "                       seriously incomplete, so study the code a bit first.\n\n"

          "  \"Expression <e>\"     Before each presentation, the given expression <e>\n"
          "                       is evaluated to get a value.\n"
          "                       (Ex: \"Expression theta+PI/2\" to get the current\n"
          "                       value of theta, plus PI/2, each time)\n\n"

          "Single or double quotes are required for any form that has an embedded space,\n"
          "and are optional for the others.\n\n"
          
          "Calling this command multiple times for the same name is not an error,\n"
          "but subsequent calls are ignored.");

  CMDOBJ_DEFINE_CATCHUP(this,0,input_define_convolution,
          "%s [<named_arguments>]* [<parent> [<blur_type> [<blur_type_arguments>*]]]",

          "Supported <named_arguments> include: <default_afferent_size_scale>,\n"
          "<num_eyes>,<layers_pereye>.\n\n"

          "Defines a convolution kernel for the given input region(s) (specified as\n"
          "in input_define) to perform input blurring, smoothing, edge detection or\n"
          "(in general) convolution.  This command is called automatically at network\n"
          "initialization and when any of the parameters blur_type, blur_radius,\n"
          "blur_scale, or blur_range_multiplier are changed.  It can also be called\n"
          "explicitly for more precise control.  Note that this command clears the\n"
          "the current activity values of the input regions, since some may be\n"
          "regenerated, so e.g. activity plots will show blank values until new\n"
          "activity is computed.\n\n"

          "See the documentation for each type for more information.  Convolution\n"
          "radii should be specified in terms of the retinal output; any scaling\n"
          "with respect to world_size_scale is handled automatically.  Available\n"
          "types include the following (prefixed with 'Blur_'):\n"
          "  CircularAverage,SquareAverage,Gaussian,DoG,LoG,GoD,DoGGoD");
  PARAM_A(blackboard,"default_afferent_size_scale",0.0,,
          "Default size ratio between a target region and a region connected to\n"
          "an input.  This is the ratio between the areas mapped directly between\n"
          "the regions.  For any given region, such an area can be less than the\n"
          "full area because other regions may be expanded to provide full receptive\n"
          "fields for this region.  At present, see retina_edge_buffer for more\n"
          "details, although that parameter is likely to be replaced with one\n"
          "that does not depend on connection radii.");
  params_define_default_expr("default_afferent_size_scale","BaseN/BaseRN");
  

  CMDOBJ_DOC(input_draw,"init_network",this,0,
          "%s [<named_arguments>]* [<parent> [<objtype> [<input_object_arguments>*]]]",
          "Supported <named_arguments> include: <name>.\n\n"

          "Same as input_define, but adds the unnamed object to a collection of\n"
          "temporary objects (e.g. for testing) to be presented using input_present.\n\n"

          "The arguments are like those in input_define. If no arguments are supplied,\n"
          "the object specified by parameter input_default_object is created in all\n"
          "input regions, with default arguments.\n\n"
          
          "The input_clear command can be called before this command to ensure\n"
          "that the object list is empty.  This command may be called multiple times\n"
          "to define more than one object, either in the same or different input regions.\n"
          " The object is not seen by the network until input_present is called.\n\n"

          "Objects created by this command are named 'input_draw' by default, but\n"
          "another can be supplied, e.g. if you are constructing composite objects.");

  CMDOBJ_DOC(input_clear,"init_network",this,0,"%s [<named_arguments>]* [<parent>]",
          "Supported <named_arguments> include: <name>,<parent>.\n\n"

          "Clears the specifed temporary objects (all objects, by default) defined\n"
          "for the given parent (all input regions, by default) in preparation for\n"
          "e.g. input_draw.");

  CMDOBJ_DOC(input_present,"init_network",this,0,"%s [<named_arguments>]*",
          "Supported <named_arguments> include: <display>,<learning>,<settle>,<activate>,<reset>.\n\n"

          "If <reset> is False (the default), presents the temporary objects currently\n"
          "defined by input_draw and activates the network, without advancing the\n"
          "iteration counter.  By default, learning is disabled for this test pattern,\n"
          "but it can be enabled by setting <learning> to True.  By default,\n"
          "pictures are saved using plot when the command completes; <display> can be\n"
          "set to zero to prevent this or to some integer higher than one to display only\n"
          "every <display>th presentation.  Unless <settle> is set to False, the network\n"
          "is allowed to settle after the initial activity calculation (for region types\n"
          "for which settling is defined).  Unless <activate> is False, the activation of\n"
          "each neuron is computed from using its activation function; if it's True then\n"
          "only the initial response is used.\n\n"
             
          "If <reset> is True, then this command restores the permanent contents of the\n"
          "eye and presents that instead of the temporary patterns defined with input_draw.");
  blackboard.lookup_map("::cmd::input_present") /* Default arguments, overriding globals */
    .set_local("learning",False)
    .set_local("display",1);

  CMDOBJ_DOC(input_present_object,"init_network",this,0,
          "%s [<named_arguments>] [<parent> [<objtype> [<input_object_arguments>*]]]",
          "Supported <named_arguments> include: <name>,<display>,<learning>,<settle>,\n"
          "<activate>.\n\n"
             
          "Convenience macro for looking at the response to a single object.\n"
          "Calls input_clear, then passes all the arguments to input_draw and\n"
          "then input_present.  (input_present ignores the <input_object_arguments>,\n"
          "if any).");

  CMDOBJ_DOC(input_print,NULL,this,0,"%s [<name> [<parent>]]",
          "Print a textual representation of the specified input object in the specified\n"
          "parent.  Parent defaults to all inputs, and name defaults to all persistent\n"
          "objects.");

  CMDOBJ_DEFINE_CATCHUP(this,0,input_reset,
          "%s [input_seed]",
          "Reset all persistent retinal objects and the input random number generator to\n"
          "their starting states.  For instance, if any Increment ValueGenerators have\n"
          "been defined (see input_define_generator), their values will be reset to the\n"
          "start value supplied initially.\n\n"

          "The random number generator is reset to the specified seed (or the value of\n"
          "input_seed if none is given), so the same series of pseudo-random numbers will\n"
          "be seen as the last time this command was called.  This means that the\n"
          "same sequence of input values will be generated unless other input settings\n"
          "have changed, which makes it possible to independently test the effect of\n"
          "unrelated changes such as to the network architecture.\n\n"

          "This command is called automatically by init_network, so (in general) changes\n"
          "in architecture parameters or the number of PEs should not usually affect the\n"
          "input sequence generated.  (Known exception: when Input_UniformRandom inputs\n"
          "are used, each processor computes the values independently instead of copying\n"
          "from a single master PE, so in that case the sequence will differ when the\n"
          "number of PEs changes.)");

  CMDOBJ_DEFINE_CATCHUP(this,0,input_undefine,"%s [<name> [<parent>]]",
          "Remove specified input object from specified parent.  Parent defaults to\n"
          "all input regions, and name defaults to all persistent objects.");

  CMDOBJ_DOC(load_snapshot,NULL,this,0,"%s [<named_arguments>]* [<tend> [<filename>]]",
          "Supported <named_arguments> include: <tend>,<filename>,<verbose>,\n"
          "<regions>,<plastic>,<internal>.\n\n"

          "Load weight files saved earlier at the specified iteration <tend>, in order to\n"
          "test it or continue training.  If no filename is specified, one is constructed\n"
          "as for save_snapshot at the specified iteration.  The load will fail if the\n"
          "architecture parameters do not match the current values.\n\n"

          "Specific regions can be given in the regions parameter, in which case only\n"
          "those regions are restored.  If using this option, you should ensure that\n"
          "the network has first been initialized (via init_network, called\n"
          "automatically by most commands), since otherwise regions whose state\n"
          "is not restored will have undefined (uninitialized) weight values.");
  blackboard.lookup_map("::cmd::load_snapshot")
    .set_local("essential_training_hooks_only",True)
    .set_local("plastic",True);

  PARAM_A(blackboard.lookup_map("::Region"),"activity_threshold",-1.0,,
          "Threshold below which activation is set to zero, usually to save computation\n"
          "time.  For an input region, judicious use of this parameter can reduce the\n"
          "amount of computation performed in later recurrent regions, since those often\n"
          "compute final activations only when a neuron has some initial activation.\n"
          "The values should be set high enough so that activations below it would rarely\n"
          "exceed the thresholds of subsequent states.  For a recurrent region, an\n"
          "activation reaching this lower value is eliminated from future calculations,\n"
          "with similar results.  Ignored if < 0.0.\n");
  PARAM_A(blackboard.lookup_map("::Region"),"activity_lbound",2.0,,
          "Activations below this value are set to it, e.g. to prevent overwhelming later\n"
          "regions.  Ignored if > 1.0 (negative values are allowed).\n");
  PARAM_A(blackboard.lookup_map("::Region"),"activity_ubound",-1.0,,
          "Activations above this value are set to it, e.g. to prevent overwhelming later\n"
          "regions.  Ignored if < 0.0.\n");
  
  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"current_object_angle",true,&current_object_angle));  
  params_define_doc("current_object_angle",
         "Read-only parameter which reports the top-level (nominal) angle of the object\n"
          "last drawn on an input surface, in degrees.  This can be useful for\n"
          "constructing filenames for a series of images differing primarily by their\n"
          "orientations.  The value is only guaranteed to be current during a call\n"
          "to the plot command.\n\n"

          "Obviously, one might also wish to include positions, disparities, etc., in\n"
          "filenames, but rather than adding new parameters for each such possibility,\n"
          "the command language should probably be extended to be able to access all\n"
          "such quantities directly.  Such support has not yet been provided because\n"
          "the command language is not yet sufficient to convert the angle in radians\n"
          "to a clean integer value in degrees.");
  SETFN_DEFINE2(current_object_angle,read_only_param_setfn2);
 
  PARAM_LL(PARAM_DOUBLE,world_size_scale,&world_size_scale,0,
          "Scale of world model relative to the size of the retinal ganglia.  Only\n"
          "used when layers_pereye>0.  In such cases, it can be useful for the world\n"
          "to have a higher resolution than the network input in order to avoid aliasing\n"
          "effects for operations like rotation of image input.");
  SETFNOBJ_DEFINE2(this,world_size_scale,double_blur_setfn2);

  PARAM_NN(PARAM_STRING,default_region,&default_region,
          "The name of a region to use as the default for commands expecting\n"
          "a single region, like plot_unit, plot_unit_range, and define_region.\n"
          "This default is used as the <region> for such commands when no non-empty\n"
          "<region> is specified in their arguments.  Also used as the default\n"
          "<target> for commands expecting <source> and <target> regions, such as\n"
          "connect_region.  Every time define_region is called, it changes the\n"
          "value of this parameter to be the <name> of the newly-defined region.");

  PARAM_NN(PARAM_STRING,default_region_command,&default_region_command,
          "Command that will be used to construct a default region, if not has yet\n"
          "been defined when init_network is called.  Usually this will be\n"
          "one or more define_region calls with options.");

  PARAM_A(blackboard.lookup_map("::Region"),"default_command",string(""),,
          "Default command to be executed after a region of this type is created.");


  
  /*       Region-type-specific defaults      */
  
  BlackboardType* typedefaults = blackboard.lookup_map("::Region").new_child(".defaults",true);
  
  /* Automatically define the lateral weights for LISSOM maps.  The
     weight specifications here should also take the various
     parameters like preset_lat_wts into account, or provide
     alternatives to them. */
  (* typedefaults->new_child("LISSOM",true))
    .set_local("default_command",
               string("exec 'connect_region name=LateralExcitatory target=${default_region} source=${default_region}"
                      "        size_scale=1.0 Blur_CircularRandom ::Region::${default_region}::exc_rad' "
                      "     'connect_region name=LateralInhibitory target=${default_region} source=${default_region}"
                      "        size_scale=1.0 Blur_CircularRandom ::Region::${default_region}::inh_rad' "))
    .set_local("activity_threshold",1.0E-09);
  
  (* typedefaults->new_child("Retina",true))
    .set_local("activity_threshold",1.0/(Math::e*Math::e));
  
  (* typedefaults->new_child("Convolution",true))
    .set_local("activity_threshold",1.0/(Math::e*Math::e));
}



void Eyes::advance_iteration_counter(int old_t, int new_t)
{
  int i;
  for (i=old_t; i<new_t; i++) {
    hooklists_run_list(before_input,i,True);
//  hooklists_run_list(after_presentation,i,True);
    hooklists_run_list(after_learning,i,True);
  }
}



/******************************************************************************/
/* Commands                                                                   */
/******************************************************************************/


template <class InContainer, class OutContainer>
class ParameterizedThreshold : public SequenceTransform::OneD<InContainer,OutContainer> {
public:
  typedef typename InContainer::value_type value_type;

  ParameterizedThreshold(const ParamMap& params_) : params(params_) { }
  
  virtual void operator() (const InContainer& in, OutContainer& out) const {
    const double threshold        = params.get_with_default("activity_threshold", -1.0);
    const double low_bound        = params.get_with_default("activity_lbound",     2.0);
    const double upp_bound        = params.get_with_default("activity_ubound",    -1.0);
    
    if (threshold>=0.0) Generic::lower_threshold(MSEQ(in),MBEGIN(out),threshold,0.0);
    if (low_bound<=1.0) Generic::lower_threshold(MSEQ(in),MBEGIN(out),low_bound,low_bound);
    if (upp_bound>=0.0) Generic::upper_threshold(MSEQ(in),MBEGIN(out),upp_bound,upp_bound);
  }

private:
  const ParamMap& params;
};


cmdstat Eyes::cmd_define_region( CMD_ARGS )
{
  CMD_ARG_PARAMS(define_region);
  
  if (!has_default_region()) update_default_values();

  const string name             = arglist.next(argparams.get_with_default("name",string("")));
  const string type             = argparams.get_with_default("type",string(""));
  const int    height           = argparams.get_with_default("height",1);
  const int    width            = argparams.get_with_default("width",1);
  const double xoffset          = argparams.get_with_default("xoffset",0.5);
  const double yoffset          = argparams.get_with_default("yoffset",0.5);
  typedef ParameterizedThreshold<NeuralRegion::ActivityMatrix,NeuralRegion::ActivityMatrix> ThresholdActfn;
    
  const NeuralRegion::Dimensions dims =
    NeuralRegion::Dimensions(height,width,xoffset,yoffset);

  
  if (name=="") {
    message(Msg::Error,"A <name> is required; no region defined");
    return CMD_PARAMETER_ERROR;
  }

  /* Use remaining arguments to set region-specific parameters */
  BlackboardType&  region_params = blackboard.lookup_map("::Region");
  BlackboardType*  new_params    = &(region_params.lookup_map(name,false));
  if (new_params==&region_params) /* If no parameters yet defined, make a new set */
    new_params = region_params.new_child(name,true);
  new_params->merge(blackboard.lookup_map("::Region::.defaults::"+type),false);
  new_params->set_local("type",type)
    .set_local("height",height).set_local("width", width)
    .set_local("xoffset",xoffset).set_local("yoffset",yoffset);
  cmdparams_set(*new_params,arglist,true,false,false);
  

  if (type=="LISSOM") 
    /* Note that this call depends on the value of the member variable initialize_weights */
    neuralregions.new_manager(*LissomMap_create(name,dims,initialize_weights,new_params),
                              new_params);
#if 0
  else if (type=="OBJ-LISSOM") 
    /* Note that this call depends on the value of the member variable initialize_weights */
    neuralregions.new_manager(*ObjLissomMap_create(name,dims,initialize_weights,new_params),
                              new_params);
#endif
  else if (type=="Retina") {
    const double size_scale = argparams.get_with_default("size_scale",1.0);
    neuralregions.new_manager(*new retina_type(name,dims,new ThresholdActfn(*new_params),
                                               size_scale),
                              new_params);
    /* The nominal_width is not the same as the actual width, because
       ganglion-centered coordinates are used.  That way coordinates
       will be the same regardless of whether a Convolution layer
       (ganglion) is used or not.

       This code should probably be replaced with something making
       fewer assumptions about the network configuration, i.e.,
       assuming that the following formulas will always be correct.
       Meanwhile, the nominal_width and height should only be used in
       other parts of the code for constructing defaults, because in
       some configurations it will not be meaningful.
    */
    const double nominal_width  = (dims.width +2*(dims.xoffset-0.5))/world_size_scale;
    const double nominal_height = (dims.height+2*(dims.yoffset-0.5))/world_size_scale;
    permanent_contents.define(name,nominal_height,nominal_width);
    temporary_contents.define(name,nominal_height,nominal_width);
  }
  else if (type=="Convolution")
    neuralregions.new_manager(*new FixedWtRegion(name,dims,new ThresholdActfn(*new_params)),
                              new_params);
  else {
    message(Msg::Error,"Unknown <type>: "+type+"; no region defined");
    return CMD_PARAMETER_ERROR;
  }

  /* Set this region as the new default and call any default_command needed */
  default_region = name;
  const string default_command=new_params->get_with_default("default_command",string());
  if (!default_command.empty()) cmddefs_exec_str(default_command);

  
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}


std::ostream& operator<<(std::ostream &s, const NeuralRegion::Dimensions& d)
{
  s << "height="   << d.height
    << " width="   << d.width
    << " xoffset=" << d.xoffset
    << " yoffset=" << d.yoffset;
  return s;
}


// Needs to be extended to connect a NeuralRegion with a RetinalObject (i.e. a WorldView);
// right now that connection is implicit and very shaky.
cmdstat Eyes::cmd_connect_region( CMD_ARGS )
{
  CMD_ARG_PARAMS(connect_region);

  if (!has_default_region()) update_default_values();

  const string default_name     = "Afferent";
  const string specified_name   = argparams.get_with_default("name",string(""));
  const string name             = (specified_name!=""? specified_name : default_name);
  
  const string specified_target = argparams.get_with_default("target",string(""));
  const string targetstr        = (specified_target!=""? specified_target : default_region);
  NeuralRegionManager* target   = neuralregions.getptr(targetstr);
  
  const string sourcestr        = argparams.get_with_default("source",string(""));
  NeuralRegionManager* source   = neuralregions.getptr(sourcestr);

  const string sourcespec       = argparams.get_with_default("sourcespec",string(""));
  const double size_scale       = (size_scale_override>=0? size_scale_override :
                                   argparams.get_with_default("size_scale",1.0));

  const int    connectionnum    = String::numeric_extension<int>(targetstr);
  
  if (!target) {
    ipc_notify(IPC_ONE,IPC_ERROR, "Could not locate <target> region %s; no connection defined",targetstr.c_str());
    return CMD_PARAMETER_ERROR;
  }
  else if (!target->internalregion()) {
    ipc_notify(IPC_ONE,IPC_ERROR, "The <target> region %s cannot accept incoming connections",targetstr.c_str());
    return CMD_PARAMETER_ERROR;
  }

  /* Creates each set of initial weights */
  KernelFactoryWrapper kfw(kernel_factory,arglist,connectionnum);

  /* Abort if connection matrix is empty */
  if (!mat::size(kfw(size_scale))) {
    message(Msg::Error,"Empty connection matrix; no connection defined");
    return CMD_PARAMETER_ERROR;
  }
    
  /* Create source region */
  if (sourcespec!="") {
    const NeuralRegion::Dimensions dims = target->internalregion()->input_dimensions(kfw,size_scale);
    const string command = "define_region name="+sourcestr+" "+String::stringrep(dims)+" "+sourcespec;
    cmddefs_exec_str(command);
    source = neuralregions.getptr(sourcestr);
  }
  
  if (!source) {
    ipc_notify(IPC_ONE,IPC_ERROR, "The <source> region %s does not exist; no connection defined",sourcestr.c_str());
    return CMD_PARAMETER_ERROR;
  }

  /* Create this set of connections */
  target->add_input(name,*source,kfw,size_scale);
  
  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_uninit_network( CMD_UNUSED_ARGS )
{  uninit();  return CMD_NO_ERROR;  }


void Eyes::update_default_values()
{
  int oldval=cmdparam_changes_verbose;
  cmdparam_changes_verbose=False;
  params_update_all_default_values();
  cmdparam_changes_verbose=oldval;
}



cmdstat Eyes::cmd_init_network( CMD_ARGS )
{
  CMD_ARG_PARAMS(init_network);
  cmdparam_changes_verbose = False;

  /* Since this command can be called automatically in different contexts,
     ensure that we always use the root set of parameters */
  cmddefs_exec_str("select_param_set ::");
  
  /* Sets member variable for use in define_region */
  initialize_weights = argparams.get_with_default("initialize",True);

  /* Reset master defaults for parameters and variables */
  iteration=0;

  update_default_values();
  
  /* Check parameters against compilation limits, etc. */
  if (params_check_all() != 0) {
    const Tristate interactive = blackboard.get_with_default("interactive",True);
    if (interactive) {
      ipc_notify(IPC_ONE,IPC_WARNING, "init_network failed due to parameter problem; fix message(s) above and try again");
      return CMD_PARAMETER_ERROR;
    }
    else
      ipc_exit(IPC_EXIT_PARAM_VALUE_ERROR, "Parameter problem (see message(s) above)");
  }

  /* Exercise random number generator differently on each PE to help
     ensure that noise is uncorrelated */
  shuffled_rand_reset();
  for(int i=0; i < 500+MyPE; i++)
    ShuffledRandom<double>::plain_rand();

  init();

  /* Declare initialization officially complete */
  ::network_initialized = True;
  cmddefs_declare_prereq_status( "init_network", CMD_NO_ERROR );
 
  /* Iteration 0 is used to make sure everything is initialized properly */
  argparams.set_local("tend",0).set_local("learning",False);
  training(arglist,argparams);

  /* Erase effect of running the test iteration */
  reset();
  
  /* One PE prints out final values of starting params, for reference */
  if (AMPARENTPE) cmddefs_exec_str("save_params");
  ipc_notify(IPC_ONE,IPC_STD, "Current parameters saved to .params file; future changes will be reported");
  /* Now that a listing is on file, report changes to params */
  cmdparam_changes_verbose = True; 

  cmddefs_exec_str("select_param_set");
  
  return CMD_NO_ERROR;
}



#define PROGRESS_REPORT_NEEDED(last_msg_time)                                  \
(progress_reports && (time(NULL)-(last_msg_time) >= progress_report_interval))



cmdstat Eyes::cmd_training( CMD_ARGS )
{
  CMD_ARG_PARAMS(training);
  return training(arglist,argparams);
}

cmdstat Eyes::training(StringArgs& arglist, const ParamMap& argparams)
{
  const bool incremental = (arglist.top(string(""))[0] == '+');
  const int  tend        = arglist.next(argparams.get_with_default("tend",1))
                           + (incremental? iteration : 0);
  const bool learning    = argparams.get_with_default("learning",True);
  const int  display     = argparams.get_with_default("display",1);
  const bool ess_h_only  = argparams.get_with_default("essential_training_hooks_only",False);
                           
  time_t last_msg_time = time(NULL);
  
  if (tend-startt>1) {
    if (learning)
      ipc_notify(IPC_ONE,IPC_STD,"Training until iteration %d", tend);
    else if (iteration!=0) /* Zeroth iteration is for housekeeping */
      ipc_notify(IPC_ONE,IPC_STD,"Testing until iteration %d", tend);
  }

  /* Main iteration loop */
  for(iteration=startt; iteration <= tend; iteration++) {
    ipc_barrier(); 

    if (PROGRESS_REPORT_NEEDED(last_msg_time)) {
      last_msg_time = time(NULL);
      ipc_notify(IPC_ONE,IPC_STD,"%s has reached iteration %06d, %.24s",
                 (learning ? "Training" : "Testing"),iteration,ctime(&last_msg_time));
    }

    /* Run any hooks needed before input is presented. */
    hooklists_run_list(before_input,iteration,ess_h_only);
    

    next();
#ifdef PRINT_TIME_PER_ITERATION
    clock_t time_before_iteration = clock();
#endif
    
    activate(permanent_contents,argparams);
    
#ifdef PRINT_TIME_PER_ITERATION
    ipc_log(IPC_ONE,"Iteration %06d took %04d milliseconds",
            iteration,(int)((clock()-time_before_iteration)*1000.0/CLOCKS_PER_SEC));
#endif
 
    hooklists_run_list(after_learning,iteration,ess_h_only);
    if (display && iteration%display==0)
      cmddefs_exec_str("plot");
  }
  startt = iteration; /* Set the startt to the last iteration. */
  iteration--; /* Make the declared iteration be the one last finished */

  CMD_ARG_ASSERT_EMPTY;  

  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_testing( CMD_ARGS )
{
  CMD_ARG_PARAMS(testing);
  return training(arglist,argparams);
}



cmdstat Eyes::cmd_step( CMD_ARGS )
{
  /* Converts specified increment into a tend specification for cmd_training */
  CMD_ARG_PARAMS(step);
  argparams.set_local("tend", iteration+arglist.next(1));
  return training(arglist,argparams);
}



cmdstat Eyes::cmd_input_define_generator( CMD_ARGS )
{
  CMD_ARG_LIST;
  // Should pass arglist by reference all the way down, to detect unused args
  return namedgenerators.create(arglist);
}


cmdstat Eyes::cmd_input_define_convolution( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_define_convolution);

  if (default_input_target=="")
    default_input_target=ensure_default_region();

  const string parent     = arglist.next(argparams.get_with_default("parent",string("")));
  const double size_scale = argparams.get_with_default("default_afferent_size_scale",1.0);
  const int    number     = argparams.get_with_default("num_eyes",1);
  const int    numlayers  = argparams.get_with_default("layers_pereye",1);

  if (parent!="" && parent!="All")
    define_input_pathway( default_input_target, parent, arglist, size_scale, numlayers );
  else for (int e=0; e<number; e++)
    define_input_pathway( default_input_target, "Eye"+String::stringrep(e), arglist, size_scale, numlayers );

  input_define_convolution_in_use=true;
  
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_clear( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_clear);
  const string parent = arglist.next(argparams.get_with_default("parent",string("")));
  const string name   = argparams.get_with_default("name",string(""));
  temporary_contents.remove_object(parent,name);
  ipc_notify(IPC_ONE,IPC_VERBOSE,"Cleared temporary objects");
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_draw( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_draw);
  const string spec_name = argparams.get_with_default("name",string(""));
  const string name      = (spec_name != "") ? spec_name : "input_draw";
  
  // Should pass arglist by reference all the way down, to detect unused args
  if (temporary_contents.create_object(arglist,name,permanent_contents, false) != 0) {
    ipc_notify(IPC_ONE,IPC_ERROR,"Could not draw input object");
    return CMD_PARAMETER_ERROR;
  }

  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_define( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_define);

  if (!permanent_contents.has_been_defined())
    cmd_input_define_convolution();
  
  const string name = arglist.next(argparams.get_with_default("name",string("")));
  
  if (permanent_contents.create_object(arglist,name,permanent_contents) != 0)
    ipc_notify(IPC_ONE,IPC_ERROR,"Could not define input object");
  
  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_present( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_present);
  const int  plot   = argparams.get_with_default("display",1);
  const bool reset  = argparams.get_with_default("reset",False);

  if (reset) {
    Eyes::activate(permanent_contents,argparams);
    ipc_notify(IPC_ONE,IPC_VERBOSE,"Reset contents of retina");
  }
  else {
    Eyes::activate(temporary_contents,argparams);
    if (plot && presentation%plot==0) cmddefs_exec_str("plot");
    ipc_notify(IPC_ONE,IPC_VERBOSE,"Presented currently-defined temp input");
  }
  
  // Currently ignores extra arguments, so same arguments
  // can be passed to both input_draw and input_present
  //   CMD_ARG_ASSERT_EMPTY;

  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_present_object( CMD_ARGS )
{
  cmdstat status=CMD_NO_ERROR;

  cmd_input_clear();
  status = cmd_input_draw(CMD_CALL_ARGS);
  if (status >= 0) cmd_input_present(CMD_CALL_ARGS); // Hack?  (Arguments are shared with two commands)

  return status;
}



cmdstat Eyes::cmd_input_print( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_print);

  const string name   = arglist.next(argparams.get_with_default("name",string("")));  
  const string parent = arglist.next(argparams.get_with_default("parent",string("")));  

  /* This may not stay here, but is useful for now */
  if (name == "" && parent == "")
    for (neuralregions_type::const_iterator e=neuralregions.begin(); e!=neuralregions.end(); e++) {
      const string ename = (*e).first;
      ipc_notify(IPC_ONE,IPC_REQUESTED,ename.c_str());
    }

  permanent_contents.print_object(parent,name);
  temporary_contents.print_object(parent,name);
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_reset( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_reset);
  const int seed = arglist.next(argparams.get_with_default("input_seed",0));
  Eyes::reset(seed);
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}



cmdstat Eyes::cmd_input_undefine( CMD_ARGS )
{
  CMD_ARG_PARAMS(input_undefine);
  const string name   = arglist.next(argparams.get_with_default("name",string("")));  
  const string parent = arglist.next(argparams.get_with_default("parent",string("")));
  
  permanent_contents.remove_object(parent,name);
  CMD_ARG_ASSERT_EMPTY;
  return CMD_NO_ERROR;
}


cmdstat Eyes::cmd_load_snapshot( CMD_ARGS )
{  
  CMD_ARG_PARAMS(load_snapshot);
  const int    load_snap = arglist.next(argparams.get_with_default("tend",0));
  const string filename  = arglist.next(argparams.get_with_default("filename",string()));
  const bool   verbose   = arglist.next(argparams.get_with_default("verbose",True));

  const int    oldipcverbosity = ipc_msg_level;
  const int    newipcverbosity = IPC_SUMMARY;
  const bool   setverbosity    = (!verbose && (ipc_msg_level > newipcverbosity));

  if (setverbosity)
    ipc_msg_level = newipcverbosity;

  /* Call init_network with non-essential hooks disabled and weight init skipped */
  if (!has_default_region())
    cmddefs_exec_str("init_network essential_training_hooks_only=True initialize=False");
  
  /* Make sure parameters have advanced to this iteration */
  ipc_notify(IPC_ONE,IPC_STD,"Advancing to iteration %d", load_snap);
  advance_iteration_counter(iteration,load_snap);
  iteration=load_snap;
  startt=iteration;
  if (!AMPARENTPE) ipc_get(&iteration, IPC_INT, 1, PARENTPE);
  
  /* Ask each region to restore its enduring state */
  bool restored = neuralregions.restore_state(argparams,load_snap,filename);

  if (restored) {
    /* Recreate the dynamic state (activation levels, etc.) */
    hooklists_run_list(before_input,load_snap,True);
    next(); /* Is this call necessary and/or desirable? */
  
    /* Recreate the last input */
    activate(permanent_contents,argparams);
  }
  
  ipc_barrier();  /* Synchronize all PEs */

  if (restored) {
    iteration=load_snap;
    ipc_notify(IPC_ONE,IPC_STD,"Changing iteration to %d",iteration);
    startt=iteration+1;
    
    hooklists_run_list(after_learning,load_snap,True);
  }

  if (setverbosity)
    ipc_msg_level=oldipcverbosity;
  
  return (restored? CMD_NO_ERROR : CMD_FILE_ERROR);
}


/******************************************************************************/
/* Parameter changing functions                                               */
/******************************************************************************/


cmdstat Eyes::distribution_setfn2(const string&, Typeless&, const Typeless& requested)
{
  int  dist = (int)requested.numericvalue();
  bool changed=false;

  cmdstat status = WorldViews::set_distribution(dist,changed);

  /*
    If objects have already been defined, overwrite them now, otherwise delay
    object creation until runtime to ensure that all relevant parameters
    have been defined.
  */
  if (changed && !permanent_contents.is_empty()) {
    message(Msg::Notify,"Regenerating input contents");
    permanent_contents.remove_object();
    permanent_contents.generate_default_contents();
  }
  
  return status;
}



cmdstat Eyes::blur_type_setfn2(const string& name, Typeless& existing, const Typeless& requested)
{
  const bool differs = (existing != requested);
  int newvalue = (int)requested.numericvalue();
  
  if (newvalue<0 || newvalue>kernel_factory.max_blur_type) {
    ipc_notify(IPC_ONE,IPC_WARNING,"No %s of %d is defined",name.c_str(),newvalue);
    return CMD_PARAMETER_ERROR;
  }

  existing.set(requested);
  if (input_define_convolution_in_use &&
      permanent_contents.has_been_defined() && differs) {
    message(Msg::Notify,"Regenerating input pathways");
    cmd_input_define_convolution();
  }
  
  return CMD_NO_ERROR;
}



cmdstat Eyes::double_blur_setfn2(const string&, Typeless& existing, const Typeless& requested)
{
  const bool differs = (existing != requested);
  existing.set(requested);
  if (input_define_convolution_in_use &&
      permanent_contents.has_been_defined() && differs) {
    message(Msg::Notify,"Regenerating input pathways");
    cmd_input_define_convolution();
  }

  return CMD_NO_ERROR;
}



cmdstat Eyes::inputs_pereye_setfn2(const string&, Typeless& existing, const Typeless& requested)
{
  const bool differs = (existing != requested);
  existing.set(requested);

  if (permanent_contents.has_been_defined() && differs) {
    message(Msg::Notify,"Regenerating input contents");
    permanent_contents.remove_object();
    permanent_contents.generate_default_contents();
  }

  return CMD_NO_ERROR;
}


cmdstat Eyes::exc_rad_setfn2(const string&, Typeless& existing, const Typeless& requested)
{
  const CmdParamStringParser sp(blackboard);
  if (::network_initialized)
    blackboard.set_matching(sp,"::Region::*::exc_rad", requested.stringrep(),true,true,true);
  existing.set(requested);
  return CMD_NO_ERROR;
}



/******************************************************************************/
/* Global points of entry                                                     */
/******************************************************************************/

Inputs& Inputs::global_entry()
{
  static Eyes eyes;
  return eyes;
}

---