🚀 go-pugleaf

Checksum: 2231066675 (verify with brik -cv)
Submitted-by: Salvatore A. Colomba <flynn@sabrina.dei.unipd.it>
Posting-number: Volume 7, Issue 36
Archive-name: smhl.sac/part01

BEGIN_DOC smhl1_1.doc
                         Symbolic Matrix Handling Library
                             Version 1.1  16 Nov 1992
                                 BETA TEST RELEASE
                                        by
                               Salvatore A. Colomba


       0 - Warnings

       This is a  BETA TEST  RELEASE. This means  that I've not  tried it in
     real operative situations;  I've just tested the  routines. If some bug
     is still present,  any report will be  very appreciated and immediately
     followed by a fixed release.


       1 - Introduction

       This is version  1.1 of  SMHL, an update  to version 1.0.  I've fixed
     some bugs, speeded  up most of the routines  (with a look to symmat_cf;
     thanks to  Carlos  Ferraro for  a  couple of  good ideas),  added some;
     moreover, most of the routines aren't  anymore hidden, in order to make
     it easier to develop more optimized SMHL-based programs.

       SMHL is a collection  of routines to handle  symbolic matrices almost
     exactly as they were numerical ones. Almost every standard command that
     usually operates on  either algebraics or matrices  is extended to deal
     with the new matrix type, and  a TRUE linear system solver is provided.
     SMHL has  been developed  in User RPL,  so it's  not very fast,  but it
     still should be useful for many purposes...

       SMHL is a Cardware: if you like it, I would be very happy if you send
     me  a   picture  card  of  your   country...  Thanks!!!  Non-commercial
     distribution of SMHL  with this document (unchanged)  is encouraged. My
     address is:

                               Salvatore A. Colomba
                                C.so del Popolo 14
                                35100 Padova Italy

       Comments, suggestions, bug  reports, NeXT computers  welcome... My e-
     mail address is the following:

                            Flynn@sabrina.dei.unipd.it
                               (Flynn@147.162.2.106)

       NOTE: I take no responsibility for any  damage caused by any possible
     bug in  the SMHL  library. Although  in SMHL1.0  people all  around the
     world has discovered 'just' two bugs, version 1.1 is mostly re-written,
     so I can't  be sure that it's totally  bug-free... And, as someone once
     said: "There is always one more bug".


       2 - Installation

       Well I'm  sure  that all  you out  there  know the  way to  install a
     library, however here are the required steps:

          1)   UUdecode  or ASC-> SMHL and download it in your HP48 (or
               vice-versa).
          2)   Recall  it and store in your favorite port; if you don't
               have  enough  memory, disable  LAST_STACK  and LAST_ARG,
               recall  it on the stack, PURGE the original variable and
               then  press <port  number> STO;  by doing this  way, you
               avoid  to get  more than one  copy of SMHL  in memory at
               the same time.
          3)   Turn off and then on your calculator.
          4)   Now  SMHL  is  installed; enter  in  the SMHL  directory
               under  the LIBRARY menu and  press BlueShift-NXT (PREV);
               choose  KEYS  to remap  the new  functions in  your user
               keyboard  (DKEY  gets rid  of them),  and enter  in USER
               mode.


       3 - Conventions

       Symbolic matrices are delimited by the  {} characters, using the same
     convention as the numerical matrices, i.e.:

           [ 1 2 3 ]     <-->     { a b c }     -     Row vectors

          [[ 1 2 3 ]             {{ a b c }
           [ 4 5 6 ]     <-->     { d E f }     -     Matrices
           [ 7 8 9 ]]             { g h I }

       Note that symbols  'e' and  'i' represent two  constants, and without
     apostrophes they  are  'built-in commands',  and  HP48 DOESN'T  care to
     convert them in computation, so keep in mind:

                   -  You can't use them like any other symbol.
                   -  If  you meant to use  them for what they
                      are,    you   MUST   enclose   them   in
                      apostrophes to allow HP48 to handle them
                      correctly.

       Symbolic and numerical matrices  or arrays are fully interchangeable:
     where a  matrix  can stay,  there  a list  can do.  So, you  haven't to
     perform  boring conversions  before,  e.g., summing  two matrices,  one
     numerical and  the other symbolic;  result, in general,  is symbolic if
     one of  the arguments was  symbolic. However, you  cannot form matrices
     like:
                                    {[ 1 2 3 ]
                                     { 4 5 6 }
                                     { 7 8 9 }}

       The first row is not always accepted,  so don't use it; no checks are
     performed, so it's due to you to avoid such situations.


       4 - Notes

       From now  on, when I'll  say 'matrix',  I'll mean both  numerical and
     symbolic matrix or vector.

       I'm sorry, but my  routines don't have almost  any error managing and
     there isn't a true arguments checking;  I think it would have slow down
     calculations  too  much. Maybe  in  a  system-rpl  version  (or just  a
     compiled one)...  Anyway, the linear  system solver will tell  you if a
     set of linear equation has no solution and Det will refuse to work on a
     non-square matrix.  Note that  if arguments  aren't correct,  you won't
     always incur into  an error: sometimes you'll  simply get wrong or bad-
     formed results.

       Flag -28 is used to keep track  of an internal sort of 'sort by type'
     routine; if you ABSOLUTELY need that flag for any other program, unpack
     the SMHL  library, STOre in 'SWAPPED'  the flag number you  wish to use
     and pack  again the  library, or  e-mail me  the flag number  you would
     prefer and I'll send you a modified version.

       As far as regards  the keys, a user keymap  is provided to extend the
     arithmetic commands  to the new  matrix type,  so keep the  keyboard in
     USER mode; note that when you  are in algebraic mode, you don't need to
     exit USER mode;  everything that can be  put in an algebraic expression
     will be as the usual.


       5 - Basic commands

       Name     [Key]    What's more
       ---------------------------------------------------------------------
       Eval     [EVAL]   E-valuates each matrix element.
       ->q      [->Q]    Applies  ->Q  to  all the  elements;  if the  input
                         matrix  is a  numerical one, it's  obviously turned
                         into a symbolic one.
       ->Num    [->NUM]  Transforms  a  symbolic matrix  (or vector)  into a
                         numerical one.
       Sq       [x^2]    If  argument is an array,  it returns the square of
                         its  modulus, that  is, it performs a  Dot with the
                         array itself.
       \^|      [y^x]    Returns  the  n-th power  of  a matrix.  This is  a
                         highly   optimized   routine.  In   the   range  of
                         exponents  from  1 to  100,  the maximum  number of
                         multiplications   is   10,  corresponding   to  the
                         exponent   value  87...   Nice,  isn't  it?     The
                         exponent,  must be a _relative_  integer other than
                         zero.
       PInv     [INV] |\
       Inv      INV   |->PInv  is a Partial Inverse: the inverse is given in
                         terms  of a matrix in level 2, and a coefficient in
                         level  one;  to  get  the  inverse  matrix,  you'll
                         simply   have   to  divide   the  matrix   by  that
                         coefficient.   Useful  you  you   have  to  operate
                         further  on the  inverse. Inv,  on the  other hand,
                         gives  directly  the inverse  matrix. Note  that if
                         the  input matrix was a  numerical one, the outputs
                         of  PInv and Inv  will be the same,  i.e. you won't
                         get the determinant in level one.
       Div      [/]      Performs  linear  system solving;  see below  for a
                         more detailed description.
       Mul      [*]      If   arguments  are  two  vectors,  it  computes  a
                         symbolic Dot.

       Neg      [+/-]    |
       Sub      [-]      |
       Add      [+]      |
       Con      CON      |
       Trn      TRN      |
       Rdm      RDM      |----> Simply extended to handle symbolic matrices
       Det      DET      |
       Abs      ABS      |
       Arry->   ARRY->   |
       ->Arry   ->ARRY   |
       Size     SIZE     |

       VIEW     ...      Shows  the matrix in level  1 using the small font;
                         it'll  leave you  in scroll  mode, so that  you can
                         view  matrices larger than display.  I've written a
                         version  of this routine that shows the elements in
                         the  Equation Writer  format; nice,  but it  eats a
                         lot  of  memory... If  you are  one of  those lucky
                         people  with a  memory expansion,  feel free  to e-
                         mail me to obtain a modified SMHL.
       EXCT     ...      EXpands and CollecTs each single element.
       MAT->    ...      Given  a matrix  in level  1, it  will split  it in
                         rows and leave the  number of rows in level 1.
       ->MAT    ...      It's  quite the opposite than  MAT->; given, say, n
                         arrays  and the number n in level 1, it returns the
                         formed matrix. Note that:
                                1: Arrays MUST all be  of the same kind, you
                                   can't mix symbolic and numerical ones.
                                2: They  MUST   have  the  same   number  of
                                   elements.
                         If  you  don't  follow these  simple rules,  you'll
                         surely  incur in  some error,  or get a  bad formed
                         matrix.
       Type     ...      Divides its input in five types:
                               0:  Numbers, complex
                               1:  Symbolic, expressions
                               2:  Numerical arrays (eventually complex)
                               3:  Symbolic arrays
                               4:  Numerical matrices (eventually complex)
                               5:  Symbolic matrices
       Apply    ...      Applies  program in level 1  to the SYMBOLIC matrix
                         or vector in level 2.
       M->L     ...      Turn a numerical matrix into a symbolic one.

       Note:   most of  the  above commands  can  be put  in algebraic  form
               (p.e.: 'Inv(X)'); this to give you maximum compatibility with
               the standard functions.


       6 - Symbolic linear system solving

       System solving  needs  the same  arguments than  the  built-in system
     solver; but it works with any possible matrix; when the solution is not
     unique, it  will  give the  GENERAL solution,  in terms  of independent
     variables xk (p.e.: x4,x5,x6,...). Let's see some example:

       _________________________
       | {HOME}                |
       |-----------------------|        The rank of this matrix is 2; it
       |2:            [ 0 0 0 ]|        means that the  solution will be
       |1: [[ 1 2 3 ]          |        a 1-dimension subspace.  In more
       |    [ 4 5 6 ]          |        mathematical terms, the solution
       |    [ 7 8 9 ]          |        will be  Ker(A),  where A is the
       |### ### ### ### ### ###|        matrix in level 1.
       `-----------------------'
       Pressing [/], after about 20 seconds, in level 1 you'll get:

                           { { x3 } { '2*-x3' } { x3 } }

       Trying to  multiply  the original  matrix for  this  solution, you'll
     always obtain a  three-elements null vector. The  same principle can be
     applied to  solve  liner systems  with  vector unknown  quantities; for
     example:

                             _________________________
                             | {HOME}                |
                             |-----------------------|
                             |2: [[ 1 2 3 ] [ 4 5 6..|
                             |1: [[ 1 2 3 ]          |
                             |    [ 4 5 6 ]          |
                             |    [ 7 8 9 ]          |
                             |### ### ### ### ### ###|
                             `-----------------------'

       Pressing [/], after about  20 seconds (SMHL1.0 took  30!), you'll get
     the solution of the following linear system:

                              x1+2*x2+3*x3 = ( 1,2,3 )
                            4*x1+5*x2+6*x3 = ( 4,5,6 )
                            7*x1+8*x2+9*x3 = ( 7,8,9 )

                                     that is:

                       x1= { 'x31+1'  'x32'     'x33-1'   }
                       x2= { '2*-x31' '2*x32+1' '2*-x33+2 }
                       x3= { 'x31'    'x32'     'x33'     }

       Call VIEW to see it better; note that the identity matrix is only one
     of the oo^3  possible matrices and corresponds  to x31=0, x32=0, x33=1.
     Nice, eh? Symbolic matrices are _obviously_ supported, but note that in
     this case  the  solutions found  won't _always_  be REALLY  general: my
     routines assume  that the coefficient  matrix rank doesn't  depend upon
     symbolic elements values; some other  times, you'll get a 'Incompatible
     system' error, although  system has some solution  if some condition is
     verified...
       Let's see some examples:

                                   / a 2 3 | 0 \
                                  (  4 5 6 | 0  )
                                   \ 7 8 9 | 0 /

       When you try  to solve  this system with  my package, you'll  get the
     null solution, although the number of  solution varies as a changes; if
     a!=1 the solution is actually the  null one, but if a=1 the rank of the
     coefficient  matrix becomes  2,  and  you'll have  oo^1 solutions.  The
     problem resides in the PIVOT routine itself: it's not so smart to avoid
     taking  symbolics  as special  elements;  I'm  sorry,  but I'll  hardly
     improve PIVOT in this direction, because  it would have to solve a sort
     of 'assignment problem', and I think it's not a practicable way in User
     RPL. Another example:

        / 1 2 3 | a \     PIVOT     / 1 0 -1 | 0               \
       (  4 5 6 | b  )  ---------> (  0 1  2 | 0                )
        \ 7 8 9 | c /               \ 0 0  0 | c-7*a-2*(b-4*a) /

       As you  can see,  this system  has no  solution for ALL  the possible
     values of  a,b,c, and solving  it by using  Div will lead  to an error,
     although the system with:
                                 c-7*a-2*(b-4*a)=0
       has the solutions:
                                 { x1 '-2*x1' x3 }


       7 - Program development oriented routines

       The following routines  constitute under certain points  of view, the
     very heart  of SMHL;  they are  very stupid  routines, in  general they
     DON'T make ANY  check on their arguments,  but intensive mail exchanges
     with some people has convinced me to make them visible.

       det     Computes a raw determinant on SYMBOLIC matrices only.
       Dot     Performs a dot between two vectors.
       MINOR   Given  a  matrix in  level  2 and  a list  containig  row and
               column, it returns the minor of the matrix.
       ->qu    It's equivalent to ->Q, but it's extended to unit objects.
       V\:-K   Divides a vector by a constant; result is ALWAYS a list.
       M\:-K   Same as above for matrices.
       SYS     Solves a linear system; same syntax as the built-in solver.
       K\*V    Multiplies a vector by a constant; result is ALWAYS a list.
       K\*M    Same as above for matrices.
       M\*M    Multiplies two SYMBOLIC matrices.
       V\+-V   Sums two vectors
       M\+-M   Sums two SYMBOLIC matrices.
       L->M    Turns a  symbolic matrix into  a numerical one;  note that if
               argument is  a symbolic  vector, it  turns it in  a numerical
               column vector.
       PIVOT   Pivotizes, as much as possible, a matrix.
       STICK   Given  a  known  terms  matrix  or  vector  in  level  2  and
               coefficent matrix in level  one, returns the complete matrix,
               that is, it puts them side to side.
       SPLIT   Is the inverse  operation. Note that if  a positive integer n
               is given, a matrix of n columns will be extracted.
       TSRT    Sorts by  Type two arguments  and returns a  two digit number
               whose first  digit is  the first  argument's Type  and second
               digit is the second one.
       SWAP?   Turns TSRTed objects in the right order.
       SWAP\?  Turns TSRTed objects in the inverse order.
       MULX    Equivalent to the HP's MULTI
       XMAKE   Given two positive integers m and  n, creates a mxn matrix in
               the form:
                                / x11 x12 ... x1n \
                                | x21 x22 ... x2n |
                                | ... ... ... ... |
                                \ xm1 xm2 ... xmn /

               Else, if m is 1, it will return a vectror in the form:
                                  ( x1 x2 .. xn )
       NULL    Returns a null  vector whose size is  given by the integer in
               level 1; if integer in level 2 is other than zero, a symbolic
               vector will be returned.

       VER     Call  it and follow the instructions, or a lighting will melt
               down your HP!!!  !8^) !8^) !8^)
       KEYS    Maps the new functions on the keyboard.
       DKEY    Restores the standard key definitions.

       Well, I think that's all folks. Hope  that your teacher allows you to
     bring your HP48 at the exam...

END_DOC