For the midi matrix it's simple: the 'keyboards' lines are for note
on/off, and the 'division' lines are for swell and tremulant control.
Otherwise it's probably of little importance except when you want to
write your own definition file, or use one of the alternatives.

To understand the structure of Aeolus you need the following concepts:

- Ranks
- Divisions
- Keyboards

and

- (audio) Sections
- (midi) Channels
- (GUI) Groups

The first three map directly to real organs. Each rank belongs
to a division. There can be up to 32 ranks in a division, and
there can be up to 8 divisions. Tremulant and swell operate
on a division. A keyboard is a virtual 'manual' or 'pedal'.
The last three are required only beacuse Aeolus is a software
application.

to a division signal. Tremulant and swell are applied to this
mix. Although the implementation is a bit different, you can
imagine a division signal as a stereo signal that has a width
of about 90 degrees in the horizontal surround circle.

2. Each division belongs to an audio section. The division signals

for each audio section are added, and then the the set of controls
you find in the audio window - azimuth (surround panning), width,
volume, early reflections, and reverb send - are applied to this
mix. There can be up to 4 audio sections. In the default instrument,
each division has its own audio section.

3. The outputs of all audio sections plus the reverb output are mixed

to produce the final output signal. The only controls on this level
are the 'position' fader, and the master volume. Position is only
used for the stereo output, and it determines 'where you are' in
the surround scene, going from front over center to back.

For note on/off and effect control, the situation is different.

In the midi matrix each midi channel is mapped to one of the virtual
keyboards. This is a simple one-to-one relation.

The second mapping is from keyboards to divisions. In the default 'Aeolus'
instrument, there is a fixed link from each keyboard to a division, and
this enables the keyboards and the divisions to have the same names : P,
I, II and III. Additional keyboard to division links are enabled by the
couplers, in this case only 'upward'.

Now this second mapping can in fact be a bit more complicated.
First, the default keyboard to division links exist only because they
are specified in the definition file - they are not encoded into the
software structure as they were in 0.3.1. In the 'Aeolus2' instrument
definition for example, there is only one default coupler - from the
'Pedal' keyboard to the 'Pedal' division - and the three other divisions
can be coupled to any combination of keyboards. French romantic organs
(e.g. the one in the cathedral here in Antwerp) often permit this sort
of flexible coupling. Second, it is also possible to couple a rank
directly to a keyboard, bypassing the division grouping. Ranks used
in this way should be in a separate division that itself has no couplers.
This is the case in 'Aeolus1' where the three reed stops are in a fifth
division named 'IV', and can be used from both the I and the III keyboard.
These three stops are independent of division couplers: if you have for
example the Oboe on for keyboard III, and you engage the I+III coupler,
the Oboe will still not respond to keyboard I because it is not part of
division III. In this instrument the I and P divisions are also combined
into one audio section in order to give the extra 'reeds' division its
own one (so you can put it at the side or back).

Since it is now possible to have no fixed relation at all between
keyboards and divisions, it is necessary to route midi events for
each of them separately - hence the extra lines in the midi matrix.
You just can't see the need for this with the default instrument
because it has that fixed keyboard to division relationships.

This flexibility w.r.t. coupling also requires the concept of a
'group' for the GUI. Compare 'Aeolus' to 'Aeolus2'. In the first
we have the default keyboard to division mapping, and the groups
of buttons in the GUI represent both a keyboard and a division.
In this case the couplers are placed with their corresponding
keyboard, and this seems logical - 'I+III' means 'the ranks of
division III should also respond to keyboard I, as if these ranks
were added to division I. In 'Aeolus2' this is no longer possible
- the groups represent divisions only, and the couplers are now
placed with their division.

So it is necessary to control the visual grouping of buttons
independently from the division structure. A 'group' can in fact
be any set of up to 32 stops, couplers, or effects. If you want
to combine all 8' stops into a group that is perfectly possible
but of course quite silly. MIDI control of stops etc. if ever
implemented, will be in terms of these groups, not of divisions.