Clarify the ordering of modes
We should better document the ordering of modes in, say, kwant.wave_function
.
Right now it says: "The modes appear in the same order as incoming modes in kwant.physics.modes
". The latter says
"incoming modes having k sorted in descending order" but it's not very clear how k is defined nor what an "incoming" mode is (modes()
by itself does not know anything about a scattering region, so "incoming" is undefined).
The docstring of PropagatingModes
explains the same ordering but with different words. It avoids "incoming" and "outgoing" and uses instead "positive" and "negative", but without a definition. Also, it's confusing when it says "The modes with negative velocity are ordered from larger to lower momenta". What is meant is "from larger to lower absolute momenta".
We should review all these related docstrings and make sure that they are correct, consistent, and easy to understand. Adding a drawing would help to explain why for an attached lead "positive velocity" is equivalent to "outgoing". The drawing could be like this:
left lead SR right lead
/---------\ /---\ /---------\
...-3-2-1-0-X-X-X-0-1-2-3-...