---

globals.c

Go to the documentation of this file.

#include <string.h>
#include <math.h>

#include "ipc.h"
#include "cmdparam.h"
#include "globals.h"
#include "shuffledrand.h"


/* Public parameters */
string filebase="lissom";
int    iteration=0;
int    presentation=0;
  
/* Global variables */
int    MyPE=0;                          
int    network_initialized=False;       
int    NPEs=1;                          
/******************************************************************************/
/* Prototypes for private functions                                           */
/******************************************************************************/

CMD_DECLARE(save_params);

/* Wrappers for obsolete legacy functions; to be removed eventually */
CMD_DECLARE(plot_weights);
CMD_DECLARE(plot_activity);
CMD_DECLARE(plot_afferent_weight_map);
CMD_DECLARE(measure_od_pref);
CMD_DECLARE(measure_or_pref);
CMD_DECLARE(OD_features);
CMD_DECLARE(OR_features);
CMD_DECLARE(plot_od_pref);
CMD_DECLARE(plot_or_pref);


/******************************************************************************/
/* Initialization hook                                                        */
/******************************************************************************/

void  globals_init_hook( void )
{
  /* Initialize cached copy of PE number and number of PEs total */
  MyPE = ipc_my_process();    
  NPEs = ipc_num_processes(); 

  
  /* Commands */  
  CMD_DOC(save_params,NULL,0,"%s <filename>",
          "Save current values of parameters and currently-defined hooks in a format\n"
          "suitable for exec_file.");

  /* Global parameters defined in this file */  

  PARAM_N(PARAM_USTRING,filebase,
          "Basename to use for files to be created during this run.");
  
  PARAM_A(blackboard,"area_scale",1.0,.add_lower_bound(0.0),
          "Ratio between the canonical reference areas BaseN*BaseN and BaseRN*BaseRN\n"
          "and the actual area desired.  Used to smoothly scale the total cortical and\n"
          "input area simulated, as opposed to simulating at a finer or coarser level\n"
          "of detail (which may instead be obtained by varying BaseN and/or BaseRN).");
  SETFN_DEFINE2(area_scale,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"BaseN",36,.add_lower_bound(0),
          "The width and height of a canonical square reference area of a cortical region.\n"
          "Used to calculate parameters and default values which are independent of the\n"
          "actual total size of the cortex.");
  SETFN_DEFINE2(BaseN,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"N",36,.add_lower_bound(0), 
          "The (square) size of the cortical map, i.e. NxN.  This parameter is currently\n"
          "unused and may not always match the network(s) in use.");
  SETFN_DEFINE2(N,fixed_arch_param_setfn2);
  params_define_default_expr("N","BaseN*area_scale");
  
  CONST_I(NPEs,NPES,True,
          "The number of processing elements (PEs) assigned to this job.  This is\n"
          "determined by the compile-time constant NPES.  With more PEs, more\n"
          "memory and processing power are available, but because the LISSOM\n"
          "algorithm requires an enormous amount of interprocessor communication,\n"
          "the speedup is not linear in the number of processors.  In fact, with\n"
          "most ordinary communications methods such as Ethernet, going from\n"
          "NPEs=1 to NPEs=2 could actually slow down the computation.  Still,\n"
          "for large problems there is usually no other way to get all the memory\n"
          "and processing power needed.\n\n"

          "Note that when NPEs changes, the result changes as if a different random\n"
          "seed was chosen.  This occurs because each processor computes random numbers\n"
          "independently, and so a different sequence of random numbers is chosen than\n"
          "if a single processor had computed them all.  This could be alleviated by\n"
          "having a single processor compute all random numbers, but that (and the\n"
          "communication it would involve) would probably slow things down considerably.");

  PARAM_A(blackboard,"num_eyes",2,.add_lower_bound(0),
          "The default number of sheets of photoreceptors (eyes) to attach to the network.\n\n"

          "This parameter is ignored if you define your own input regions using\n"
          "define_region.  The number of eyes can be arbitrarily large, which may\n"
          "be interesting for studying experimental manipulations such as Reh &\n"
          "Constantine-Paton, J. Neurosci 5:5 1985, \"... Three-Eyed Rana pipiens\".");
  SETFN_DEFINE2(num_eyes,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"layers_pereye",0,.add_lower_bound(0),
          "The default number of retinal ganglion cell layers to attach to each eye.\n\n"

          "This parameter will often be 0, which means the input (photoreceptor) layer\n"
          "will be connected directly to the cortex.  In such cases one should ensure\n"
          "that the patterns drawn on the input layer are appropriate representations\n"
          "of the output of the LGN, e.g. that they have been blurred and are sparse.\n"
          "If layers_pereye is nonzero, that many ganglion cell layers will be created,\n"
          "each normally consisting of a homogenous group of cells, e.g. a set of\n"
          "OFF-center cells at a particular size.  You can use any number of such groups\n"
          "with different weight kernels.  See blur_type for more information.\n");
  SETFN_DEFINE2(layers_pereye,fixed_arch_param_setfn2);
  
  PARAM_L(PARAM_INT,   presentation,0,
          "Counter for inputs presented at a single training iteration t.  It will\n"
          "usually remain at zero, but if extra inputs are presented for testing or\n"
          "other purposes, this counter will advance each time.  The concatenation\n"
          "of t with this counter will then be sufficient to label that input\n"
          "presentation uniquely, e.g. for the purposes of creating a unique filename.");
  
  PARAM_A(blackboard,"BaseRN",36,.add_lower_bound(0),
          "The width and height of a canonical square reference area of an input region.\n"
          "Used to calculate parameters and default values which are independent of the\n"
          "actual total size of the input region.");
  SETFN_DEFINE2(BaseRN,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"RN",24,.add_lower_bound(0),
          "The size of the (square) input retina matrix, i.e. RNxRN."); 
  SETFN_DEFINE2(RN,fixed_arch_param_setfn2);
  params_define_default_expr("RN","BaseRN*area_scale+2*retina_edge_buffer");
  
  PARAM_NN(PARAM_INT,   seed, &(ShuffledRandom<double>::default_seed),
          "Seed for random number generator used to generate initial weights, etc.  See\n"
          "also inputs_seed if applicable.");
  SETFN_DEFINE2(seed,fixed_arch_param_setfn2);
  
  PARAM_L(PARAM_INT,   iteration,0,
          "The current training iteration.  Iteration 0 is used for init_network to\n"
          "make sure everything is initialized properly, without doing any learning.");
  /* Define "t" alias for "iteration" */
  blackboard.define_param(DECLARE_PARAM(PARAM_INT,"t",false,&iteration));
  params_add_lower_bound_int("t",0);
  params_define_doc("t","Alias for the `iteration' parameter.");
                                                      
  {
    static int i;
    static double f;
    
    PARAM_N(PARAM_INT,i,
            "Integer register predefined for convenience; suitable for use as\n"
            "e.g. a loop index.  Since many different user routines can use\n"
            "this parameter, don't expect its value to remain unchanged.");
    
    PARAM_N(PARAM_DOUBLE,f,
            "Floating-point register predefined for convenience; suitable for use\n"
            "as a temporary value e.g. in a loop.  Since many different user routines\n"
            "can use this parameter, don't expect its value to remain unchanged.");
  }


  /* Wrappers for obsolete legacy functions; to be removed eventually */
  CMD_DOC(plot_activity,"init_network",0,"%s [<filename>]",
          "Wrapper for legacy parameter file support: executes 'plot Activity'.");
  
  CMD_DOC(plot_weights,"init_network",0,"%s [<ui> <uj>]*",
          "Wrapper for legacy parameter file support: executes 'plot_unit' with the.\n"
          "argument order swapped to match changed conventions.");

  CMD_DOC(plot_afferent_weight_map,"init_network",0,"%s [<eye> [<filename>]]",
          "Wrapper for legacy parameter file support: executes 'plot_unit_range'.");

  CMD_DOC(measure_od_pref,"init_network",0, "%s [<low> [<high>]]",
          "Wrapper for legacy parameter file support: executes 'call measure_od_pref'\n"
          "and then 'plot OcularPreference'.");
  
  CMD_DOC(measure_or_pref,"init_network",0, "%s [<low> [<high> [<plot_filename>]]]",
          "Wrapper for legacy parameter file support: executes 'call measure_or_pref'\n"
          "and then 'plot OrientationPreference'.");

  CMD_DOC(OD_features,"init_network",0,"%s [<low> [<high> [<nexamples>]]]","Unimplemented.");
  
  CMD_DOC(OR_features,"init_network",0,"%s [<low> [<high> [<nexamples> [<calc_select>]]]]",
          "Unimplemented.");
  
  CMD_DOC(plot_od_pref,"init_network",0, "%s [<low> [<high> [<filename>]]]",
          "Wrapper for legacy parameter file support: executes 'call measure_or_pref'\n"
          "and then 'plot OrientationPreference'.");

  CMD_DOC(plot_or_pref,"init_network",0, "%s [<low> [<high> [<filename>] [<selectivity_only]]]",
          "Wrapper for legacy parameter file support: executes\n"
          "'plot OrientationPreference'.");
}


void kernel_init_hook( void )
{
  PARAM_A(blackboard,"circular_aff_wts",True,.add_lower_bound(False).add_upper_bound(True),
          "If this is true, all afferent weights outside a circular radius\n"
          "rf_radius will be killed before training begins.  Otherwise a\n"
          "square radius is used.");
  SETFN_DEFINE2(circular_aff_wts,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"circular_lat_wts",True,.add_lower_bound(False).add_upper_bound(True),
          "If this is true, all lateral weights outside a circular radius\n"
          "exc_rad or inh_rad (for the excitatory and inhibitory weights,\n"  
          "respectively) will be killed before training begins.  Otherwise\n"
          "a square radius is used.");
  SETFN_DEFINE2(circular_lat_wts,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"gammaaff",1.0,,
          "Scaling factor for the set of afferent connections.  For a LISSOM\n"
          "network (the only network supporting it as of this writing), this\n"
          "parameter makes the set overcomplete, but it can still be useful.\n"
          "If gammaaff is e.g. multiplied by a factor k, the result is the same\n"
          "as dividing all of gammaexc, gammainh, beta, and delta by that same\n"
          "factor k (assuming a linear sigmoidal function).");
  
  PARAM_A(blackboard,"gammasur",0.0,,
          "Scaling factor for the surround (actually the average afferent\n"
          "input).");
  
  PARAM_A(blackboard,"gammaexc",1.0,,
          "Scaling factor for excitatory lateral interactions.");
  
  PARAM_A(blackboard,"gammainh",1.0,,
          "Scaling factor for inhibitory lateral interactions.");
  
  PARAM_A(blackboard,"interactive",False,.add_lower_bound(False).add_upper_bound(True),
          "Whether this run is considered an interactive or a batch run;\n"  
          "affects certain behaviors such as how often progress messages\n"
          "are printed, what level of severity is required to exit the\n"  
          "program, whether to spawn viewers for images, etc.  The value\n"  
          "of this parameter is usually guessed appropriately, but if it is\n"  
          "not then the user can set it explicitly.");
  
  PARAM_A(blackboard,"normalize_aff",False,.add_lower_bound(False).add_upper_bound(True),
          "Whether or not to normalize afferent inputs.");
  /* it may be ok to change this parameter mid-stream */
  //SETFN_DEFINE2(normalize_aff,fixed_arch_param_setfn2); 

  PARAM_A(blackboard,"preset_lat_wts",True,.add_lower_bound(False).add_upper_bound(True),
          "Whether or not to preset the lateral weights.");
  SETFN_DEFINE2(preset_lat_wts,fixed_arch_param_setfn2);
  
  PARAM_A(blackboard,"retina_edge_buffer",0,.add_lower_bound(0),
          "Number of retinal units to leave on all sides when determining the center\n"
          "of the afferent receptive field of each neuron.  If it is zero, then the\n"
          "entire cortex is scaled to the entire retina, but then the neurons near\n"
          "the border will have only partial receptive fields.  An effectively\n"
          "infinite retina, where each neuron will have a complete receptive field,\n"
          "can be obtained by setting this parameter to rf_radius+randomness*RN/2.\n"
          "This maps the cortex to a smaller square region (width and length\n"
          "RN-2*retina_edge_buffer) in the center of the retina.  If you wish to\n"
          "keep the same cortical magnification factor as if there were no buffer,\n"
          "also increase RN by 2*retina_edge_buffer.");
  
  PARAM_A(blackboard,"running_remotely",False,.add_lower_bound(False).add_upper_bound(True),
          "Allows the user to declare that the program is being run in a remote shell,\n"  
          "which affects default values for whether image viewers are spawned, etc.");

  PARAM_A(blackboard,"spawn_viewer",Uninitialized,.add_lower_bound(Uninitialized).add_upper_bound(True),
          "Whether to spawn external programs to view images when they are\n"
          "created.  Uninitialized means to guess whether that's appropriate, based on\n"
          "the values of `interactive' and `running_remotely'.");

  PARAM_A(blackboard,"tsettle",10,.add_lower_bound(1),
          "Iterations for activity to settle at each input presentation.  The total\n"
          "duration of these is only the equivalent of a few seconds in real time,\n"
          "as opposed to the LISSOM training iterations, which total to the equivalent\n"
          "of days or weeks.  The first settling iteration (1) refers to the response\n"
          "to the input only (through the afferent weights);  subsequent settling\n"
          "iterations include the lateral weights."); 



  PARAM_A(blackboard,"alpha_exc",0.002,.add_lower_bound(0.0),
          "Learning rate for excitatory lateral connections.");
  
  PARAM_A(blackboard,"alpha_inh",0.0002,.add_lower_bound(0.0),
          "Learning rate for inhibitory lateral connections.");
  
  PARAM_A(blackboard,"alpha_input",0.0007,.add_lower_bound(0.0),
          "Learning rate for afferent connections.");

  PARAM_A(blackboard,"allow_negative_wts",False,.add_lower_bound(False).add_upper_bound(True),
          "Ordinarily, all live weights in LISSOM are positive, and dead weights are\n"
          "set to a small negative value to mark them as dead.  If this parameter is\n"
          "set to True, weights are allowed to become negative, but no weights\n"
          "are allowed to become dead.  At present, this option is experimental,\n"
          "and primarily for testing.");

  PARAM_A(blackboard,"beta",0.7,,
          "Upper threshold of sigmoid-like activation function.");

  PARAM_A(blackboard,"delta",0.1,,
          "Lower threshold of sigmoid-like activation function.");
  
  PARAM_A(blackboard,"dynamics",False,.add_lower_bound(False).add_upper_bound(True),
          "Whether to use continuous learning dynamics:\n"
          " False=discrete (learn after each presentation, i.e. when settling completes),\n"
          " True =continuous (learn after each settling step.\n"
          "(Should be called continuousdynamics for clarity; the name is a legacy.");
  
  PARAM_A(blackboard,"divide_input_sum",False,.add_lower_bound(False).add_upper_bound(True),
          "Whether to divide input_response values by the average of the input receptors;\n"
          "when true you will need a different gammaaff to compensate.");
  
  PARAM_A(blackboard,"divide_input_sum_offset",0.0,,
          "When divide_input_sum is True, constant to add to the input response before\n"
          "the division.  Should be non-zero, since if it is zero the response will be\n"
          "subject to the iceberg effect -- very low contrasts will be boosted to levels\n"
          "much higher than moderate contrasts, because the low contrast will activate\n"
          "only the center of the RF, and none of the surround.  (Another interpretation:\n"
          "the constant reduces divide-by-nearly-zero errors).");
  
  PARAM_A(blackboard,"divide_reference_sum",False,.add_lower_bound(False).add_upper_bound(True),
          "Same as divide_input_sum, except that instead of dividing by the average\n"
          "input value, divides by the dot product of the receptive field and the initial\n"
          "set of weights that would have been generated if preset_aff_wts were true.");
  
  PARAM_A(blackboard,"divide_input_sum_offset",0.0,,
          "When divide_input_sum is True, constant to add to the input response before\n"
          "the division.  Should be non-zero, since if it is zero the response will be\n"
          "subject to the iceberg effect -- very low contrasts will be boosted to levels\n"
          "much higher than moderate contrasts, because the low contrast will activate\n"
          "only the center of the RF, and none of the surround.");
  
  PARAM_A(blackboard,"divide_input_sum_scale",1.0,,
          "When divide_input_sum is True, constant by which to multiply the input\n"
          "response before the division.");

  PARAM_A(blackboard,"lateral_sign_type",Uninitialized,,
          "For long-range inhibitory connections, how the sign and magnitude of the\n"
          "gammainh are determined.  Options:\n"
          "  Uninitialized: gammainh is used as-is with a fixed negative sign.\n"
          "  False:         gammainh and lateral_sign_offset are scaled\n"
          "                 by the strength of the incoming inhibitory activations.\n"
          "  True:          gammainh and lateral_sign_offset are scaled\n"
          "                 by the strength of the current input response.");
  
  PARAM_A(blackboard,"lateral_sign_scale",0.0,,
          "Untested.  Scales LISSOM map long-range inhibition by the initial\n"
          "(afferent) response to the input or by the current sum of the inhibitory\n"
          "input.");
  
  PARAM_A(blackboard,"lateral_sign_offset",-1.0,,
          "Untested.  Offset added to the lateral_sign_scale term.");
  
  PARAM_A(blackboard,"exc_death",0.0,.add_lower_bound(0.0),
          "Maximum value of excitatory lateral connection weights to kill when pruning.");
  
  PARAM_A(blackboard,"inh_death",0.00001,.add_lower_bound(0.),
          "Maximum value of inhibitory lateral connection weights to kill when pruning.");
  
  PARAM_A(blackboard,"lat_exc_randomness",1.0,.add_lower_bound(0.0).add_upper_bound(1.0),
          "Randomness radius of lateral excitatory connections.");
  
  PARAM_A(blackboard,"lat_inh_randomness",1.0,.add_lower_bound(0.0).add_upper_bound(1.0),
          "Randomness radius of lateral inhibitory connections.");
  
  PARAM_A(blackboard,"force_matching_initial_weights",True,.add_lower_bound(False).add_upper_bound(True),
          "If true, initial weights are forced to match between different regions of the\n"
          "same size.  Useful for e.g. ocular dominance simulations, to ensure that the\n"
          "outcome does not require differences in starting values to develop differences\n"
          "in the final result through symmetry breaking.");
  SETFN_DEFINE2(force_matching_initial_weights,fixed_arch_param_setfn2);

  PARAM_A(blackboard,"noise",0.0,.add_lower_bound(0.0).add_upper_bound(1.0),
          "Intrinsic noise factor of the neuron.");
  
  PARAM_A(blackboard,"preset_aff_wts",True,.add_lower_bound(False).add_upper_bound(True),
          "Whether or not to use preset afferent weights."); 
  SETFN_DEFINE2(preset_aff_wts,fixed_arch_param_setfn2);

  PARAM_A(blackboard,"preset_sigma_aff",double(Uninitialized),.add_lower_bound(0.0),
          "Variance (sigma) of Gaussian to preset afferent weights.  It defaults to\n"
          "0.9*rf_radius, which makes it nearly fill up the available weight area.");
  params_define_default_expr("preset_sigma_aff","0.9*rf_radius");

  PARAM_A(blackboard,"preset_sigma_lat",double(Uninitialized),.add_lower_bound(double(Uninitialized)),
          "If this parameter is set, the default values for preset_sigma_exc and\n"
          "preset_sigma_inh are calculated from it as follows:\n\n"
          
          "   preset_sigma_exc = preset_sigma_lat\n"
          "   preset_sigma_inh = preset_sigma_lat*MIN(1,sqrt(inh_rad))\n\n"
          
          "This formula and the preset_sigma_lat parameter are used for backwards\n"
          "compatibility with old parameter files.  The normal default values for\n"
          "the two parameters listed are probably more appropriate, so it is better\n"
          "to avoid setting this parameter.");

  PARAM_A(blackboard,"preset_sigma_exc",double(Uninitialized),.add_lower_bound(double(Uninitialized)),
          "Variance (sigma) of Gaussian to preset lateral excitatory weights.  Unless\n"
          "preset_sigma_lat is set, it defaults to 0.9*exc_rad, which makes it nearly\n"
          "fill up the available weight area.");

  PARAM_A(blackboard,"preset_sigma_inh",double(Uninitialized),.add_lower_bound(double(Uninitialized)),
          "Variance (sigma) of Gaussian to preset lateral inhibitory weights.  Unless\n"
          "preset_sigma_lat is set, it defaults to 0.9*inh_rad, which makes it nearly\n"
          "fill up the available weight area.");

  PARAM_A(blackboard,"randomness",0.0,.add_lower_bound(0.0).add_upper_bound(1.0),
          "Amount of randomness of placement of receptive field centers for each neuron:\n"
          "0 = no randomness, 1 = offset by half of the width and height of the input\n"
          "region.  Large values of randomness are not likely to be useful, since they\n"
          "will result in many neurons having RFs cropped by the border of the input\n"
          "region.");
  
  PARAM_A(blackboard,"smooth_circular_outlines",False,.add_lower_bound(False).add_upper_bound(True),
          "If true, smooths the edges of circular sets of weights when they are\n"
          "initialized or when their size is changed.\n\n"

          "The outline of a weight radius (rf_radius, inh_rad, exc_rad, etc.) will\n"
          "inherently be jagged because of the underlying grid.  For small radii\n"
          "especially these jaggies can cause unwanted orientation artifacts, since\n"
          "some directions will have a slightly greater diameter than others.  To\n"
          "minimize this orientation bias in the initial weights, you can set this\n"
          "parameter to true.  The amount of smoothing can be controlled via\n"
          "smooth_circular_radius_trim.");

  PARAM_A(blackboard,"smooth_circular_radius_trim",-0.25,,
          "When smooth_circular_outlines is True, this quantity is added to the\n"
          "integer-truncated version of the appropriate radius (rf_radius,\n"
          "inh_rad, or exc_rad) to create a floating-point radius at which to\n"
          "start smoothing the outline.  The integer value of the radius plus\n"
          "this parameter should be less than the floating-point value\n"
          "of the radius; this parameter is often slightly negative.");


#ifdef OBJ_LISSOM  
  PARAM_A(blackboard,"l2_norm",False,.add_lower_bound(False).add_upper_bound(True),
          "Usually, afferent input is not normalized, and afferent weights are\n"
          "normalized with an L1 norm.  If this option is enabled, afferent\n"
          "inputs will be normalized with an L2 norm, and for train_obj_weights\n"
          "afferent weights will be normalized with an L2 norm.  The regular\n"
          "regular learning routines in modify_weights could also be extended\n"
          "to support an L2 norm, but meanwhile this option is only likely to\n"
          "be useful for OBJ-LISSOM.");

  PARAM_A(blackboard,"alpha_settle",0.001,.add_lower_bound(0.0),
          "Settling rate for map activity (use with OBJ-LISSOM).");
  
  PARAM_A(blackboard,"asymptotic_wts",False,.add_lower_bound(False).add_upper_bound(True),
          "Whether or not to use asymptotically positive weights (use with OBJ-LISSOM).");

  PARAM_A(blackboard,"crop_negative_wts",True,.add_lower_bound(False).add_upper_bound(True),
          "Whether to crop negative afferent weights or not (use with OBJ-LISSOM).");

  PARAM_A(blackboard,"obj_lateral_on",True,.add_lower_bound(False).add_upper_bound(True),
          "Whether or not to add lateral terms in OBJ-LISSOM activity update."); 
#endif /* OBJ_LISSOM */

}




/******************************************************************************/
/* LISSOM functions                                                           */
/******************************************************************************/

cmdstat cmd_save_params( CMD_ARGS )
{
  CMD_ARG_PARAMS(save_params);
  string dummy;
  const string default_filename = p.parse("${filebase}.${06iteration}.params",dummy);
  const string filename = arglist.next(default_filename);  
  return cmdparam_save_current_state(filename.c_str());
}


cmdstat fixed_arch_param_setfn2(const string& name, Typeless& existing, const Typeless& requested)
{
  if (!network_initialized)
    existing.set(requested);
  else  if (existing != requested) {
    ipc_notify(IPC_ONE,IPC_ERROR,"Can't change %s once the network has been initialized; call uninit_network first",
               name.c_str());
    return CMD_PARAMETER_ERROR;
  }
  
  return CMD_NO_ERROR;
}



cmdstat read_only_param_setfn2(const string& name, Typeless&, const Typeless&)
{
  ipc_notify(IPC_ONE,IPC_ERROR,"Read-only parameter; can't change %s",name.c_str());
  return CMD_PARAMETER_ERROR;
}



/******************************************************************************/
/* Wrappers for obsolete legacy functions; to be removed eventually           */
/******************************************************************************/

cmdstat cmd_plot_activity( CMD_ARGS )
{
  CMD_ARG_ASSERT_UNUSED;
  return cmddefs_exec_str("plot Activity");
}



cmdstat cmd_plot_afferent_weight_map( CMD_ARGS )
{
  CMD_ARG_ASSERT_UNUSED;
  return cmddefs_exec_str("plot_unit_range");
}



cmdstat cmd_plot_weights( CMD_ARGS )
{
  CMD_ARG_PARAMS(plot_weights);

  string command = "plot_unit";
  for (; (!arglist.empty()); ) {
    if (arglist.oneremaining()) {
      ipc_notify(IPC_ONE,IPC_ERROR,"Wrong number of arguments to plot_weights");
      return CMD_PARAMETER_ERROR;
    }

    // Swaps order to match reversed conventions used historically
    const string ui=arglist.next(string());
    const string uj=arglist.next(string());
    command += " " + uj + " " + ui; 
  }

  CMD_ARG_ASSERT_EMPTY;
  return cmddefs_exec_str(command.c_str());
}


cmdstat cmd_measure_od_pref( CMD_ARGS ) 
{
  CMD_ARG_ASSERT_UNUSED;
  return (cmddefs_exec_str("call measure_od_pref")<CMD_NO_ERROR ||
          cmddefs_exec_str("plot OcularPreference"));
}



cmdstat cmd_measure_or_pref( CMD_ARGS ) 
{
  CMD_ARG_ASSERT_UNUSED;
  return (cmddefs_exec_str("call measure_or_pref")<CMD_NO_ERROR ||
          cmddefs_exec_str("plot OrientationPreference"));
}



cmdstat cmd_plot_or_pref( CMD_ARGS )
{
  CMD_ARG_PARAMS(plot_or_pref);

  // Ignores all arguments except the filename
  arglist.next(string(""));
  arglist.next(string(""));

  const string filename   = arglist.next(string());
  const string name_fmt   = (filename==string() ? string("${filebase}.${06iteration}.or") :
                             (filename[0]=='.' && (filename.length()>1) && isalnum(filename[1])?
                              ("${filebase}" + filename) :
                              filename));
  const string command    = "plot filename_format=" + name_fmt + " OrientationPreference";
  
  CMD_ARG_ASSERT_EMPTY;
  return cmddefs_exec_str(command.c_str());
}



cmdstat cmd_plot_od_pref( CMD_ARGS )
{
  CMD_ARG_PARAMS(plot_od_pref);

  // Ignores first two arguments
  arglist.next(string(""));
  arglist.next(string(""));

  const string filename   = arglist.next(string());
  const string name_fmt   = (filename==string() ? string("${filebase}.${06iteration}.od") :
                             (filename[0]=='.' && (filename.length()>1) && isalnum(filename[1])?
                              ("${filebase}" + filename) :
                              filename));
  const string command    = "plot filename_format=" + name_fmt + " OcularPreference";
  CMD_ARG_ASSERT_EMPTY;
  return cmddefs_exec_str(command.c_str());
}



cmdstat cmd_OR_features( CMD_UNUSED_ARGS ) 
{
  ipc_notify(IPC_ONE,IPC_WARNING, "OR_features is not currently implemented; ignored");
  return CMD_MISC_ERROR;
}


cmdstat cmd_OD_features( CMD_UNUSED_ARGS )
{
  ipc_notify(IPC_ONE,IPC_WARNING, "OD_features is not currently implemented; ignored");
  return CMD_MISC_ERROR;
}

---