Previously these 2 steps were done in one pass. Now we separate them
out in order to facilitate augnmenting the verification to include
checking the number of orbitals (in future commits).

These will be needed later when verifying that constant values have
the correct shape.

It is only used in the tests anyway. This way we export less
API from the builder module.

add a test for invalid value functions

See merge request kwant/kwant!347

Previously we would use '*_term_parameters', as returned by
'_make_*_terms', however this was polluted with Exceptions.
Instead we modify '_make_*_terms' so that it does not return this
confusing object and use 'terms' directly, which are guaranteed
to either have a valid set of 'parameters' or 'None'.

Note that we only raise an error if 'params' is specified. This may
actually be incorrect; if we have a keyword-only parameter, for example
then the way in which we call the value function will always produce
an error, regardless of whether 'params' is specified or not.

implement vectorized value broadcasting

Closes #342

See merge request kwant/kwant!346

This is shorter but no less clear.

When a value function returns a single scalar or a matrix, we
reshape and repeat this value to obtain the required 3-axis array.

We want to enable: single scalars (norbs=1) or matrices (norbs>1),
functions returning single scalars or matrices, or functions returning
vectors of single scalars or matrices.

make system terms immutable

See merge request kwant/kwant!348

It is very easy to accidentally modify the subgraphs in place,
which should not be possible

Finalized Builders store negative term numbers associated with
edges in the graph whose reverse we must compute using
'hamiltonian_term'. If we are not careful people may use these
negative term numbers with 'hamiltonian_submatrix'.

vectorized operators

Closes #318

See merge request kwant/kwant!337

We get rid of '_is_herm_conj' in favour of '_is_hermitian', replace
'_check_ham' with '_check_hams' (which works on vectorized values)
and add '_check_onsites' (which also works on vectorized values).
Replace absolute value calculation with call to 'cabs' from 'complex.h'

This includes the following changes:

+ Group the elements of 'where' according to the term/site-families
  they belong to. This is pre-computed and stored in '_terms'.
  What specifically is stored depends on whether vectorization
  is enabled.
+ BlockSparseMatrix now takes its matrix elements as a sequence
  of pairs 'which, data', where 'which' indexes 'where'. This
  leverages the values stored in '_terms'.
+ Normalize 'onsite' to a function that takes 'site_range' (int)
  and 'site_offsets' (array of int). This facilitates vectorization
  when it is enabled. Previously 'onsite' was normalized to a
function
  taking 'site' (int), which was not vectorizable.
+ '_eval_onsite' is modified to compose components of '_terms' with
  'onsite'.
+ '_eval_hamiltonian' is modified to compose compoenents of '_terms'
  with 'hamiltonian_term' when vectorized, or 'hamiltonian' when
  not vectorized.

It is not clear how this will be implemented right now.

The next commit(s) will implement the necessary changes to the
operator module to make this test pass.

We will need this normalization in several places, and it is
more general than *just* Hamiltonian terms.

This is the canonical way of checking if a system exposes vectorization
capabilities.

One less import, and the explicit pattern match is not any less readable

The removed logic is an artifact from when vectorized and
unvectorized systems shared the same logic for 'hamiltonian_submatrix'.
This was accidentally left in when we reverted to the old logic
for unvectorized systems.

We forgot to add him when merging !333

Require that norbs are specified for abstract vectorized systems.
This was already a de-facto requirement for finalized Builders, and
it should be part of the abstract base class.

Closes #336

See merge request kwant/kwant!334

All site arrays must have 'norbs' set by definition.

The docstring erroneously stated that 'site_ranges' could be 'None',
however we want to restrict VectorizedSystems to contain only site
families that have 'norbs' specified. The docstring is now explicit
about that fact.

fix add_peierls_phase for system without leads

Closes #331

See merge request kwant/kwant!333