Connections
===========

Connections control the transfer of information between layers.

Making a created connection into a working connection requires 4 steps.
Autoconnect does all four of these.

1. Attach both ends to the relevant layers, i.e., `target attach conn` and 
`conn attach source`.

2. Identify the relevant conversion.  The automatic value for this is the
same as that given by the `find_conversion` command between the
representations of the two layers.  This conversion could be in either
direction.  Where both representations have a "natural" pattern that is a
localist\_pattern (e.g., keyed\_representation, or blocked\_representation with
keyed\_representation inner) the option for converting from source layer's
representation to the target layer's representations is explored first (and
the reverse second); for all other combinations, this preference is
reversed.  *I'm not sure why this is the case, but it helped with something
once upon a time.*

3. Subtype the connection.  The appropriate subtype is determined by (a)
the direction of the conversion, (b) the subtype of the conversion, (c)
the "natural" pattern of the source representation, and (d) the "natural"
pattern of the target representation.  Running the 
`list_conversion_connections`
method on any conversion will give the prevailing rules.

4. "Fill" the connection.  This refers to any set-up operation on the
connection from the conversion, such as filling the values of a matrix. 
This process may fail.  Upon failure, the autoconnect process would go back
to stage 2 and uses the reverse conversion (if that option has not already 
been tried).

Methods common to all connections
=================================


description
-----------

	some_conn description

The description of `some_conn` contains additional elements: `Source`
indicates the layer whose output is pulled.  `Target` indicates the layer
that pulls information through the connection, and has the sub-element
`port` for the input channel on the layer used.  `Autoconnect?` indicates
whether the connection will be automatically filled on a change in source
and target layers.  `Lag` describing the time differential between the output
of the source and the input of the target for any information.

lesion
------

	some_conn lesion

Insert a `lesioned_connection_impl` into the connection\_impl slot of 
`some_conn`
without destroying the existing connection\_impl facet (which now becomes the
responsiblity of the lesioned\_connection\_impl facet to manage; this is used
in its unlesion method).

autoconnect
-----------

	some_conn autoconnect src_layer tgt_layer port

Disable the autoconnect bit on `some_conn`; attach `some_conn` as a source
of `tgt_layer` on the port `port`; reenable the autoconnect bit on
`some_conn`; and attach `src_layer` as the source of `some_conn`, triggering
autoconnection.

	some_conn autoconnect src_layer tgt_layer

As above, but port 0 (usually net_input) is used, rather than `port`.

attach
------

	some_conn attach src_layer

Attach `src_layer` as the source of some_conn.

detach
------

	some_conn detach

Unset the source of `some_conn`

set_autoconnect
---------------

	some_conn set_autoconnect 0
	some_conn set_autoconnect 1

Indicate that the autoconnection mechanism should (1) or should not (0) be 
triggered when the source or target layer changes.

set_lag
-------

	some_conn set_lag nsteps

Set the amount of time between source and output of `some_conn` to be
`nsteps`.

source
------

	some_conn source

Return the source layer of `some_conn`.

get_labels
----------

	some_conn get_labels

List the dimension names of the representation of the target layer of `some_conn`.

conv_connect
------------

	some_conn conv_connect the_conv

Only effective if both a source and target layer are connected to
`some_conn`.  Select a connection\_impl for `some_conn` on the basis of the
representations at the source and target layer and format (fill) it using
`the_conv`; that is, use the manually selected `the_conv` instead of the
conversion from stage 2 above, and perform stages 3 and 4.  Turns off
autoconnection on further changes to source or target layer.

conv_fill
---------

	some_conn conv_fill the_conv

Only effective if both a source and target layer are connected to
`some_conn`, and a connection\_impl is already in place.  Format (fill) the
current connection\_impl of `some_conn` using `the_conv`.  That is, accept
the current subtype of connection instead of selected one automatically, as
use `the_conv` to perform stage 4 above.  Turns off autoconnection on
further changes to source or target layer.