########
lib_qmat
########

*****************************
Quick start on datastructures
*****************************

This library uses three special datastructures to store the 
information on finite dimensional basis sets (``q_set``), linear operators (``q_mat``),
and sets of linear operators acting on the same space (``q_mats``).

For example, a ladder operator acting on a space spanned
by three vibrational basis functions :math:`s_1 = \{|v=0\rangle, |v=1\rangle, |v=2\rangle\}`
given by

.. math::

    \hat{A} = \sum_{v=0}^1 |v+1\rangle\; \sqrt{v+1}\;|v\rangle

would be defined by

.. code-block:: Scilab

    lib_load lib_qmat

    s1  = q_set([0; 1; 2], 'v')
    //  s1 = (OBJECT tlist) with fields:
    // 
    //    v
    //    _
    // 1: 0
    // 2: 1
    // 3: 2

    Ad  = q_mat([  0     0 0
                   1     0 0
                 sqrt(2) 0 0], s1)

    //  Ad = (OBJECT tlist) with fields:
    //
    //  |v(3)>A(3;3)<v(3)|

    // the values of the quantum numbers are stored in the field "q":

    disp(s1.q)
    // 0.
    // 1.
    // 2.

    // The names of the quantum number(s) are stored in the field "qnames"
    disp(s1.qnames)
    // "v"

    // The matrix is stored in the field A
    disp(Ad.A)
    // 0.          0.   0.
    // 1.          0.   0.
    // 1.4142136   0.   0.

    // The basis set on which Ad is acting is in the field "s1"

    disp(Ad.s1)  // (this is the set "s1" defined above

    // The codomain is in the field "s2", by default it is the same as "s1"

    Ad.s2==s1
    // ans =
    //  T

The sets ``==`` (is-equal) operator is defined for ``q_set`` datastructures
by operator overloading (see Scilab ``help overloading)``). It returns
true (``T``) when the names and the values of the quantum numbers are the same,
so the equivalent statement without using overloading would be::

    and(Ad.s2.names== Ad.s1.names & Ad.s2.q == Ad.s2.q)
    // ans =
    //  T

Many operators, like multiplication ``*`` and addition ``+`` are defined for for
these datastructures, see below.

**********************************************
Overview: data structures
**********************************************


**********************************************
q_set: defining quantum numbers and basis sets
**********************************************

.. function:: [s1, prow, pcol] = q_set(q, qnames)

   Define a basis set by specifying the names of the quantum numbers
   (``qnames``) and the values of the quantum numbers (``q``)

Example

.. code-block:: Scilab

   lib_load lib_qmat

   qnames = ['j' 'm']
   q      = [0  0
             1 -1
             1  0
             1  1]
   s1     = q_set(q, qnames)

Defines the basis set:

.. math::

    s_1  = \{ |j_i m_i\rangle, i=1,2,3,4 \}
         = \{ |0,0\rangle, |1,-0\rangle, |1,0\rangle, |1,1\rangle \}

**Input arguments**

   :q: 
       A Scilab ::math::`m \times n` matrix. Each row defines a basis function,
       each column a quantum number. The names of the quantum numbers are
       given by ``qnames``, with column ``j`` of ``q`` corresponding to ``qnames(j)``.

       If there is only one output argument (``s1``), the quantum numbers in ``q``
       must be sorted lexicographically. If there are at least two output arguments,
       the matrix ``q`` will be sorted if necessary.

   :qnames: 
       A character string with quantum numbers.

**Output arguments**

   :prow:
       If the rows or the matrix ``q`` are sorted lexicographically, ``prow`` will
       be an empty matrix. If not, ``prow`` will be a permutation, such that
       ``q(prow, :)`` is sorted lexicographically. If the rows of ``q`` are
       not properly sorted and there is only one output argument, an
       error is returned.

   :pcol:
       The first time a quantum number is used, it is added to a list
       of quantum numbers that is stored in a global character string
       (see ``qs_names``).  This defines the order of quantum numbers.
       If the quantum numbers in ``qnames`` are sorted, ``pcol`` will
       be an empty matrix. If not, ``pcol`` will be a permutation, such
       that ``qnames(pcol)`` will be sorted.

.. function:: [s3, irow] = qs_extract(i, j, raw, s1)

   This function is called when indexing a ``q_set``. When
   ``raw=%t`` it returns ``s1.q(i, j)`` and when ``raw=%f``
   it returns ``q_set`` ``s3``, where the names are ``s1.qnames(j)``.
   The index ``j`` can also be a character string with the names of
   the quantum numbers to be selected.

   The index ``i`` can also be a ``q_set``. In this case elements
   of ``s1`` will be selected where the quantum number names that
   occur in both ``i`` and ``s1`` have the same values. In this
   case the default value is ``raw=%f``, i.e., a ``q_set`` is returned.

   The index ``j`` can also be a ``q_set``, but in that case ``i``
   must be a colon. We have ``s1(s2) == s1(s2, :) == s1(:, s2)``.

   When ``raw=%t`` or when all columns are selected, ``irow`` will be
   the index of selected elements ``s1.q(irow,j)``. This is useful
   when ``i`` or ``j`` is a ``q_set``. When ``raw=%f`` and not
   all columns are selected, the index ``irow`` would not
   necessarily be unique, so an error message is given.

Example::

   q = [1 1
        1 2
        2 1
        2 2
        2 3]

   s1 = q_set(q, ['i' 'j'])

   [q2, irow] = s1(1:2:$, 'j', %t)
   // This will call
   // [q2, irow] = qs_extract(1:2:$, 'j', %t, s1)
   //
   // It returns:

   q2   = [1
           1
           3]
   irow = 1:2:$

The ``raw`` flag may be skipped, its default value depends on the type of ``j``.
When argument ``j`` is a ``constants``, a ``boolean``, or a ``string``, the
default is, ``raw = %t``.