Routine Name:	fileconnect

Description:	Establishes synaptic connections and weights between groups
		of elements based on a file of weights. The routine
		sets up the connections by adding SPIKE messages between the 
		source and destination objects and then assigning a weight.


Usage:		fileconnect source_elements destination_elements \
			filename -wtscale w

		source_elements  A wildcarded list of elements which are the 
		        sources of the SPIKE messages.  These must be of
			class "spiking" and are usually spikegen or 
			randomspike objects.

		destination_elements  A wildcarded list of elements which are
		        the destinations of the SPIKE messages.  These must  
			be synchans or objects derived from synchan.

		filename	The name of an ascii file with weights
			(as floats) separated by whitespace. Separation
			can include spaces, line breaks etc.
			The file is expected to have  weights for all possible
			connections, i.e., :
				src_nelements * dest_nelements
			entries.
				The order of entries is source-first. For
			example, if the source_elements list has 9 entries
			and the dest_elements list has 16, then the
			first 9 entries will specify weights from each of
			the sources to the first destination. The next 9
			entries will be to the second destination, and so on.
				Weights less than or equal to zero will not
			form connections at all. 
 				Negative weights are often used to indicate
			inhibitory input, so the command provides a way
			around that: use a negative wtscale argument.
			If a file has +ve as well as -ve weights,
 			it would be read twice: first with the paths of
			excitatory receptor channels and a +ve wtscale,
			then with the paths of the inhibitory ones and a
			-ve wtscale.
			
		-wtscale w	-- This specifies a scale factor for all
			weights. As noted above, it can be negative to
			select for inhibitory (negative) weights.
		

Example:	
		int nx = 5
		int ny = 5
		int destx = 5
		int desty = 5
		
		include cellproto.g
		
		createmap /proto/cell /lgn {nx} {ny}
		createmap /proto/cell /v1 {destx} {desty}
		fileconnect /lgn/##[TYPE=spikegen] /v1/cell[]/glu \
			wts.file -wtscale 0.1
		fileconnect /lgn/##[TYPE=spikegen] /v1/cell[]/GABA \
			wts.file -wtscale -0.1
		
	wts.file would have 5x5x5x5 entries. A centre-surround
	pattern for the above example could start like this:

		10 -1 0 0 0 
		-1 -1 0 0 0 
		0 0 0 0 0 
		0 0 0 0 0 
		0 0 0 0 0 

		-1 10 -1 0 0 
		-1 -1 -1 0 0 
		0 0 0 0 0 
		0 0 0 0 0 
		0 0 0 0 0 

		0 -1 10 -1 0 
		0 -1 -1 -1 0 
		0 0 0 0 0 
		0 0 0 0 0 
		0 0 0 0 0 

		...
		

Notes:		The routine is somewhat inefficient for large input and
		output arrays with sparse connectivity, since it has to
		read Nsrc x Ndest entries. This is offset by the fact that
		the routine simultaneously creates synapses and sets their
		weights, thereby eliminating a scan for setting weights.
		The main use is for setting up large networks based on
		weight files generated by other programs.

See also:	planarconnect, planarweight, planardelay; chapter 18 of the 
		Book of GENESIS has a lengthy discussion on these and related 
		commands.  A detailed example of the use of fileconnect is
                given in Scripts/examples/fileconnect.
