-------------------------------------------------------------------------
PHYS210: OCTAVE PROGRAMMING  

I. Introduction to Octave Programming

   o Overview
   o Scripts and simple functions
      o How octave finds function defintions
   o Control structures
   o Exercises
-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
1) OVERVIEW (very similar to that for Maple, so go back and review those
   notes as necessary)
-----------------------------------------------------------------------------

- RECALL: We are viewing octave and Matlab as synonymous

- Will also abbreviate octave as O often below

- ADVANCED TOPICS will be marked with (**).  Some will be addressed in 
  future labs/lectures, for others you will have to consult online references
  for help  as needed

- Getting interactive help in octave

>> help <topic>

- Example

>> help linspace

- Principal unit of O usage: O statements

   - Assignment statements

      >> a = 2
      >> vr = [1, 2, 3, 4]
      >> vc = [5; 6; 7; 8]
      >> M =  [cos(Pi) sin(Pi); -sin(Pi) cos(Pi)]

   - Other examples

      >> linspace(0.0,100.0,101)
      >> diag(M)
                .
                .
                .

-----------------------------------------------------------------------------
1.1) PRINCIPAL MODES OF OCTAVE PROGRAMMING
-----------------------------------------------------------------------------
  
  i) O scripts (programs)
      - arbitrary sequence of O statements, including assignment stmnts
        control structures, etc.

  ii) O functions
      - analogous to Maple procedure

- IMPORTANT: octave source code (scripts/programs/functions) MUST 
  ALWAYS be prepared in text files having an extension, ".m", e.g.

  myscript.m
  somefcn.m

- Then provided that either

   i) O is running in the directory containing the .m file
   ii) .m file is in O's PATH 

   can execute statements in script, or execute specific function call
   simply by typing the prefix/stem of the .m file, i.e. the part 
   of the file name before the '.m'

   >> myscript
   >> somefcn(arg1,arg2)    (Assumes somefcn takes 2 arguments)

- We will return to this point below 

- For time being will assume that i) is the case, and will return to 
  path settings later

- CRUCIAL!!

  Each script (program) or function that can be invoked from the 
  O command line, or in a script, or in another function, etc.  
  must be defined in a separate file

- Recommended coding procedure
   - By all means experiment with O interactively, BUT

      - Prepare all scripts/functions in text files using your text editor

      - Keep editor window OPEN while you test your scripts/fcns, so that 
        you can quickly make changes as needed, and reexecute without 
        stopping/starting the editor

   - IMPORTANT:  For functions, ALWAYS code a testing script at the 
     same time or better, before, you code the function!
     - e.g. for somefcn(arg1,arg2), code script file 

       tsomefcn.m
          somefcn(targ1,targ2)
          somefcn(targ3,targ4)
                  .
                  .
                  .
 
-----------------------------------------------------------------------------
1.2) OCTAVE PROGRAMMING PARADIGMS 
-----------------------------------------------------------------------------

- As with Maple, octave has support for both

   - FUNCTIONAL programmming 
   - PROCEDURAL (IMPERATIVE) programmming 

   - FUNCTIONAL programming

     - e.g. Rich set of constructors/operators for array creation/manipulation

   - PROCEDURAL programming

      - Data & Algorithms

      - Data
        - Arrays (general dimension)

      - Algorithms
         - Function definitions
         - Control structures 

-----------------------------------------------------------------------------
EXAMPLE:  Writing and executing a simple octave script
-----------------------------------------------------------------------------

- Open a terminal and change the working directory to ~/octave (if 
  you didn't make ~/octave previously, make it now)

- Start octave from the command line

% octave

- Open your text editor and create the file ~/octave/myscript1.m with 
  contents as follows

# This is a simple octave script file
a = 10
b = [1 2 3 4]
c = 1:2:9
d = [1 4 9 16]'
e = sind(30)
f = [1 2 3; 4 5 6]
g = eye(2)

- Save the file, then in octave type

>> myscript1

- You should see the following output

   a =  10
   b =

      1   2   3   4

   c =

      1   3   5   7   9

   d =

       1
       4
       9
      16

   e =  0.50000
   f =

      1   2   3
      4   5   6

   g =

   Diagonal Matrix

      1   0
      0   1

- Now modify myscript1.m by adding semi-colons to the end of lines 1, 3, 5
  and 7 as follows

# This is a simple octave script file
a = 10;
b = [1 2 3 4]
c = 1:2:9;
d = [1 4 9 16]'
e = sind(30);
f = [1 2 3; 4 5 6]
g = eye(2);

- Be sure to resave myscript1.m, then reexecute the script

>> myscript1

- This time the output is 

   b =

      1   2   3   4

   d =

       1
       4
       9
      16

   f =

      1   2   3
      4   5   6

- So by putting a ';' at the end of the command we suppress output 
  from the command when the script is executed

-----------------------------------------------------------------------------
IMPORTANT!! 
-----------------------------------------------------------------------------

- Before moving on to programming per se, we should observe the 
  following

- These notes have been written to ensure maximum 
  portability/compatibility between octave and Matlab

- There are syntactic differences between the two that you may 
  encounter when looking, for example, at on-line documentation for 
  either of the languages

- One example is that Matlab uses 'end' to end many programming 
  constructs (function definitions, if-then-else statements,
  loops, etc.).  Octave also supports this syntax, but also 
  has reserved words (such as endfunction, endif, ...) to improve
  code readibility.  

- Again, however, we will stick to the simple Matlab form to keep
  our code as portable as possible.

-----------------------------------------------------------------------------
2) DEFINING A OCTAVE FUNCTION
-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
2.1) FUNCTION DEFINITION: GENERAL FORMS
-----------------------------------------------------------------------------

- NOTE: An octave function can return 0, 1, 2 ... values (as many 
  values as you want), and each value can be a scalar, vector, 
  array, ...

- Adopt usual "meta" notation; <ss> denotes arbitrary seqence of 
  O statements/commands.  Generally will have one statement per 
  line, but can have more using either ',' or ';' to separate 
  statements (';' suppresses output)

  <inarg> = "input argument" (formal argument)

  <rval> = "return value" 

- 0 return values

   function <name>(<inarg1>, <inarg2>, ..., <inargm>)
      <ss>
   end

- 1 return value

   function <rval> = <name>(<inarg1>, <inarg2>, ..., <inargm>)
      <ss>
   end

- 2 return values

   function [ <rval1> <rval2> ] = <name>(<inarg1>, <inarg2>, ..., <inargm>)
      <ss>
   end

- n return values

   function [ <rval1> <rval2> ... <rvaln> ] = 
      <name>(<inarg1>, <inarg2>, ..., <inargm>)
      <ss>
   end

- NOTES:
 
  - For all of the above forms, there can be 0 or more input arguments,
    <inarg_i>

  - Both the inarg's and rval's must be valid octave variable names

  - Don't need commas between rval's but can include them if you wish

  - DO need commas between inarg's 

  - All rval's must be assigned a value before the end of the 
    function (implicit return) or a return statement is executed
    (explicit return) - THIS IS HOW THE FUNCTION RETURNS VALUES

  - If there are mutiple rvals, then to "capture" all of them upon
    return from the function, the function invocation must be on the 
    RHS of an assignment statement with a row vector of names on the 
    LHS, e.g.
       
      [rval1 rval2] = fcn2(in1, in2)

    otherwise, only the FIRST rval is returned
 
  - Will usually want to end each statement in <ss> (i.e. in the 
    body of the function) with ';' so that output doesn't appear on 
    standard out (terminal) as function executes

-----------------------------------------------------------------------------
EXAMPLES:  Simple octave functions
-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
EXAMPLE 1: myadd
-----------------------------------------------------------------------------

- myadd takes two scalar inargs, sc1 and sc2, and 
  returns one scalar rval with the value sc1 + sc2

- Create the file ~/octave/myadd.m that contains the following 3 lines

function res = myadd(sc1, sc2)
   res = sc1 + sc2;
end

- Be sure to end each line in the function definition with a ';' to 
  suppress the output that normally would be generated

- Also note the use of indentation to emphasize which statements are 
  contained within the body of the function

- Ensure that octave is (still) running in the directory ~/octave

- In octave, type

>> myadd(2,3)

- and you should see

   ans =  5

- NOTE: Observe how we assign the rval 'res' the value
  'sc1 + sc2', and since 'res' is defined to be the (single)
  inarg in the function header, this is the value that is returned
  from the function call

- We can assign myadd's return value to a variable as follows

>> val = myadd(3.0,pi)

   val =  6.1416

-----------------------------------------------------------------------------
IMPORTANT: When defining octave functions one MUST

   1) Define only ONE function per source file (.m file)

   2) Ensure that the name of the function and the name of the 
      file match, e.g.

           myadd.m contains the definition of myadd
           foo.m containg the definition of foo
                            .
                            .
                            .

- If you do NOT follow this protocol---in particular if you 
  include more than one function definition per file---then
  octave will not be able to find all of the necessary functions, and 
  error messages will be issued.

- For example, let's assume that myadd.m contains an extra definition
  for a function mysub as follows

##############################
function res = myadd(sc1, sc2)
   res = sc1 + sc2;
end

function res = mysub(sc1, sc2)
   res = sc1 - sc2;
end
##############################

- Invoking myadd still works

>> myadd(3.0,pi)

ans =  6.1416

- But calling mysub doesn't

>> mysub

error: `mysub' undefined near line 6 column 1

- QUESTION: Where should the definition of mysub.m go?
-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
EXAMPLE 2: myaddsub 
-----------------------------------------------------------------------------

- myaddsub takes two scalar inargs, sc1 and sc2, and
  returns TWO scalar rvals with values, sc1 + sc2, sc1 - sc2

- Create the file ~/octave/myaddsub.m that contains the 4 lines

function [res1 res2] = myaddsub(sc1, sc2)
   res1 = sc1 + sc2;
   res2 = sc1 - sc2;
end

- IMPORTANT: Note the [] around the two return values, res1 and res2

- Now use the function in octave

- First try

>> myaddsub(2, 3)

   ans = 5

- Note how only a single value is returned 

- Now try 

>> [val1 val2] = myaddsub(2,3)

   val1 =  5
   val2 = -1

- and we see that TWO values are returned and assigned to the variables
  val1 and val2

- Again, in the definition of the function we MUST assign values to 
  the rvals in order for the function to return the desired results

-----------------------------------------------------------------------------
EXAMPLE 3: myvec
-----------------------------------------------------------------------------

- myvec takes one  integer inarg i1 and returns the TWO row vectors
  1:i1 and i1:-1:1  (i1 should be positive, but we won't test for 
  that)

- Create the file ~/octave/myvec.m containing 

function [vec1 vec2] = myvec(i1)
   vec1 = [1:i1];
   vec2 = [i1:-1:1];
end

- Now use the function, and be sure to use an assignment statement that 
  has a vector with two names on the left hand side to ensure that we 
  capture BOTH of the return values (each of which is a vector)

>> [v1 v2] = myvec(5)

- And the output should be 

v1 =

   1   2   3   4   5

v2 =

   5   4   3   2   1

EXAMPLE 4: 

- Here we see what again happens if we try to call a function that hasn't 
  been defined in the file <fcn>.m, where <fcn> is the name of the function

>> myvce(5)

error: `myvce' undefined near line 41 column 1

- (The reference to 'line 41' corresponds to the command number that 
  octave maintains, and that is included in the real octave prompt
  by default)

- In addition, note that octave can't even tell what sort of reference
  this is, since in addition to having the correct syntax for a function
  call, it has the proper syntax for an array reference (i.e. myvce could
  in principle be a vector)

2.2) DISPLAYING FUNCTION DEFINITIONS

- Use the octave command 'type' to display the definition of a function

>> type myadd

myadd is the user-defined function defined from: /home/phys210d/octave/myadd.m

function res = myadd(sc1, sc2)
   res = sc1 + sc2;
end


-----------------------------------------------------------------------------
3) OCTAVE CONTROL STRUCTURES
-----------------------------------------------------------------------------

NOTE: We can (and will below) use all of the control structures 
interactively, but they will, of course, be much more useful when 
used in scripts and functions

-----------------------------------------------------------------------------
3.1) Relational and Logical Operators
-----------------------------------------------------------------------------

- NOTE: In contrast to Maple which has a special Boolean type (true and false),
        octave follows the C-language approach of 

 i) Returning the integers 0 for false and 1 for true when 
    *evaulating* relational or logical expressions 

 ii) Treating the value 0 (integer OR floating point) as false, and any 
    non-zero value as true in contexts where relational/logical expressions
    are expected (e.g. if statements) --- i.e. although 0 is the unique 
    "false value", and although comparisons and logical operations will
    always return 0 or 1, there is no unique "true value"

- Among other things this means that 

 i) Results from relational and logical operations can be used 
    in arithmetic statements (which can be sometimes be useful, 
    but should be considered (**))

 ii) *Arbitrary* statements that return a scalar value can be used where 
    relational/logical expressions are expected (**)

-----------------------------------------------------------------------------
3.1.1) O defines the following relational operators
-----------------------------------------------------------------------------

    Operator         Definition

      <               Less than
      >              Greater than
     <=             Less than or equal
     >=            Greater than or equal
     ==                 Equal
     ~=                Not equal 

- Note the use of tilde ~= for not equal, versus <> in Maple and != in C/C++

- These work in the usual fashion for scalars, but need to be careful
  when arrays are compared (**)

- Examples:

>> a = 1; b = 2; c = 3;

>> a < 3

  ans = 1

>> b > c

  ans = 0 

>> a == c

  ans = 0

>> b ~= c

  ans = 1

(**)

>> 32 * (a < 3) + 16 * (b == c) + 8 * (a == a)

  ans = 40

-----------------------------------------------------------------------------
3.1.2) O defines the following logical operators
-----------------------------------------------------------------------------

   Operator           Definition

     &                Logical AND
     |                Logical OR
     ~                Logical NOT

- Note that these are single character expressions, NOT 'and', 'or' and 
  'not' as in maple

- Examples

>> a = 1; b = 2; c = 3; 
 
>> (a < b) & (b < c)

  ans = 1

>> (a == 2) | (a == 3) 

  ans = 0

>> ~(a < b)

  ans = 0

(**) 

>> ~30

  ans = 0

>> ~~30

  ans = 1


- NOTES: 
  - There *is* a precedence order for all of the arithmetic and 
    logical operators, but, as was the case for Maple, it is best to 
    simply use parentheses to ensure you get the order you want

  - McCarthy evaluation rules DO NOT apply in octave

    >> (1 > 2) & myadd(2,3)

    ans = 0

    but myadd DOES get executed

-----------------------------------------------------------------------------
3.2) SELECTION: THE if-elseif-else-end STATEMENT
-----------------------------------------------------------------------------

- DEFNS:

   <Bexpr> = Boolean expression (should be a scalar), also known 
             as conditional expresssion <condexpr>
   <ss>    = Statement sequence

GENERAL FORM

   if <Bexpr>
      <ss>
   elseif <Bexpr>
      <ss>
   elseif <Bexpr>
      <ss>
       .
       .
       .
   else 
      <ss>
   end

- NOTES:

   - DON'T USE 'then' after the 'if' --- will work in octave, but NOT
     in Matlab

   - USE elseif NOT elif (as in Maple)

   - can have arbitrary number of elseif clauses (0 or more)

   - else clause is optional

   - if statement is terminated with end (O uses end to end pretty much 
     everything)

Examples:

- Simplest form

>> a = 2; b = 3;

>> if a < b
      a + b
   end

ans =  5
    
- Next simplest form

>> a = 2; b = 3;

>> if a == b
      a + b
   else
      a - b
   end

ans = -1

- Form using 'elseif'

>> aa = 2;

>> if aa == 1 
      10
   elseif aa == 2
      20
   else
      30
   end

ans = 20

- NOTE: O also has a 'case' statement (**)

-----------------------------------------------------------------------------
3.3) ITERATION (REPETITION / LOOPS)
-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
3.3.1) for-end LOOP
-----------------------------------------------------------------------------

GENERAL FORM 1

- DEFNS:

   <lvar>   = loop variable
   <flvar>  = first value of <lvar>
   <slvar>  = lvar increment  (step)
   <llvar>  = last value of <lvar>

   for <lvar> = <flvar> : <slvar> : <llvar>
      <ss>
   end

or 

   for <lvar> = <flvar> : <llvar>
      <ss>
   end

- <slvar> defaults to 1 in the second case

- As the loop executes, <lvar> takes on the values 

     <flvar>, <flvar> + <slvar>, <flvar> + 2 * <slvar>,  ...

  and where the last value of <lvar> is always <= <llvar>

- <flvar>, <slvar>, <llvar> don't have to be integers, but usually  
  will want them to be to avoid possible problems with roundoff errors


GENERAL FORM 2

- DEFN:

   <vlvar> = row vector of values

   for <lvar> = <vlvar>
      <ss>
   end

- In this case, as the loop executes, <lvar> takes on the values of 
  the elements of <vlvar> in turn

Examples (first form):

>> for k = 1 : 3
      k
   end

      k =  1
      k =  2
      k =  3

>> for k = 4 : -1 : 2
      k
   end

      k =  4
      k =  3
      k =  2

>> for k = 1 : 4 : 3
      k
   end

      k =  1


>> for k = 2 : 2
      k
   end

      k =  2


>> for k = 2 : 1
      k
   end

NO OUTPUT

Example (second form):

>> for k = [1 7 13]
      k
   end

      k =  1
      k =  7
      k =  13

IMPORTANT!!

 - DO NOT modify loop variable within loop, you CAN do it without
   generating a syntax or run-time error, but results are unlikely
   to be what you expect/want.  BE VERY CAREFUL ABOUT THIS POINT!

-----------------------------------------------------------------------------
3.3.2) while-end LOOP (**)
-----------------------------------------------------------------------------

- DEFNS:

   <Bexpr>    = Boolean / conditional expression
   <ss>       = statement sequence

- General form 

   while <Bexpr>
      <ss>
   end

- NOTE: 

- The while loop executes until <Bexpr> evaluates to 0 (false).  If 
  <Bexpr> is 0 upon initial entry to the loop, the body of 
  the loop does NOT execute.

  In other words, as long as <Bexpr> is true, the looping will 
  continue

- It is up to you to do something within the loop so that, eventually, 
  <Bexpr> evaluates to 0 (false), or your program will be stuck
  in the proverbial "infinite loop"

- Example:

>> q = 1
   while q <= 16
      q = 2 * q
   end

      q =  2
      q =  4
      q =  8
      q =  16
      q =  32


- NOTE:

  - All of the above loops can be nested, i.e. we can have loops within 
    loops

- Example:

>> for ii = 1 : 2
      for jj = 3 : -1 : 1
         [ii jj]
      end
   end

ans =

   1   3

ans =

   1   2

ans =

   1   1

ans =

   2   3

ans =

   2   2

ans =

   2   1

- Note that the inner loop (loop variable jj) executes "most rapidly";
  for each iteration through the outer loop, ii = 1 , 2 in 
  succession, the inner loop executes, jj = 3, 2, 1 in succession

-----------------------------------------------------------------------------
3.3.3) THE break STATEMENT (**)
-----------------------------------------------------------------------------

- break causes an immediate exit from the (innermost) loop where it is 
  executed

- Example (contrived!):

>> q = 1 
   while q <= 16
      q = 2 * q
      if q > 3
         break
      end
   end

   q =  2
   q =  4

- NOTE:

- If break occurs outside a loop in a script or function it terminates
  the execution of the file

-----------------------------------------------------------------------------
3.3.4) THE continue STATEMENT (**)
-----------------------------------------------------------------------------

- continue is used within a loop to "short circuit" the execution of the 
  loop body, and proceed to the next iteration 

- Example: (the O rem command is equivalent to mod in Maple,
            so rem(n,2) = 0 or 1 for n even or odd, respectively)

>> for ii = 1:5
      jj = ii
      if rem(ii,2) == 0
         continue
      end
      jj = -ii
   end

   jj =  1
   jj = -1
   jj =  2
   jj =  3
   jj = -3
   jj =  4
   jj =  5
   jj = -5

-----------------------------------------------------------------------------
EXERCISES: IMPLEMENT FUNCTIONS AS FOLLOWS
-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
PRELIMINARIES
-----------------------------------------------------------------------------

- Be sure to define each function in a SEPARATE file 
  ~/octave/<function>.m, and ensure that your octave session is 
  running in ~/octave, or octave won't know what to do when you 
  try to use the function

- Your final forms of the definitions should have semi-colons 
  at the end of every statement to suppress the output from their 
  execution when the function is called 

- HOWEVER, you may find it useful to omit the semi-colons until 
  you have your functions debugged since this provides an easy 
  way to see exactly what is being computed as the function
  executes

- Whenever you make changes to any '.m' file, be sure to save it,
  but note that you don't have to "reload" or "re-read" anything 
  in the octave session (as you need to do in maple); you simply 
  type the name of the function/script and the updated definition
  will be used.

-----------------------------------------------------------------------------
EXERCISES PER SE
-----------------------------------------------------------------------------

1) myadd3 

- myadd3 takes 3 inargs (input args), x, y and z and returns 
  their sum (one value)

-----------------------------------------------------------------------------
2) myop4
-----------------------------------------------------------------------------

- myop4 takes 4 inargs (you choose the names!) and returns their 
  sum and product (two values)

-----------------------------------------------------------------------------
3) myifC 
-----------------------------------------------------------------------------

- myifC takes 3 inargs and returns the largest of them (you wrote 
  this function in maple!)

- Remember that octave IS case sensitive, so be careful naming the
  file that contains this function definition

-----------------------------------------------------------------------------
4) myiffor 
-----------------------------------------------------------------------------

- myiffor takes 3 inargs, j1, j2, j3, all of them integers and retuns 
  one value 

   - If j1 is positive, it returns a ROW VECTOR of length j2, each 
     of whose elements is j3

   - If j1 is negative it returns a COLUMN VECTOR of length l2, each
     of whose elements is j3

  -  If j1 is 0 it returns 0

- No error testing is required

-----------------------------------------------------------------------------
4) TESTING
-----------------------------------------------------------------------------

- Test your work by creating another octave source file (script)
  ~/octave/tfcns1.m that contains appropriate calls to all four functions

- Note that a script can call any number of functions; octave will
  look for the definitions as needed (i.e. you only need to write
  ONE testing script, and you should add to it as you code each
  function.

- Again, until a function is debugged you may find it useful NOT 
  to end the statements in the function body with a semi-colon, 
  so that you see an "execution trace"---however, the final versions
  of the functions SHOULD include the semi-colons.
 
- The statements in the testing script should NOT end with a semi-colon

- You can execute the script via

>> tfcns1

- If this doesn't work, then you either haven't created tfcns1.m in 
  the correct directory (~/octave), or octave isn't running in that 
  directory

- You can include descriptive output in your script using the 
  disp function that we will discuss further in using the disp function 
  that we will discuss in more detail later
  
- Specifically, add lines such as ...

disp('Testing myadd3')

disp('Testing myop4')

- ... etc. before the calls to the corresponding functions (note 
  that the arguments to disp here are strings, so be careful to 
  use matching single quotes)

-------------------------------------------------------------------------
PHYS210 OCTAVE PROGRAMMING  

II. Octave Programming Continued (and other octave features)

   o Octave path
   o Octave core files
   o Displaying/outputing quantities in octave
   o Inputing quantities in octave
   o Simple 2D plotting with octave
-------------------------------------------------------------------------

-------------------------------------------------------------------------
SAMPLE SOLUTIONS TO LAST DAYS' EXERCISES ARE IN 

   ~phys210/octave/exercise-solns
-------------------------------------------------------------------------

-------------------------------------------------------------------------
- while loop, break, continue statements, go back in notes
-------------------------------------------------------------------------

-------------------------------------------------------------------------
1) Octave path 
-------------------------------------------------------------------------

- Similarly to the bash's path, octave maintains a list of directories
  in which to look for .m files that correspond to a script or 
  function that you want to execute

- You can display the current path using

>> path

Octave's search path contains the following directories:

.
/usr/lib/octave/3.2.4/site/oct/i586-mandriva-linux-gnu
/usr/lib/octave/site/oct/api-v37/i586-mandriva-linux-gnu
/usr/lib/octave/site/oct/i586-mandriva-linux-gnu
/usr/share/octave/3.2.4/site/m
              .
              .
              .

- Note that . (dot)---which you may (should!) recall means the current 
  (working) directory---is in the path by default. 

  This is why octave finds script/function definitions if the 
  corresponding .m files are in the directory in which the octave 
  session is executing (as we have done thus far).

- We can add directories (components) to the path using the 
  addpath function

- For example, open a terminal window and ensure that the working
  directory is your home 

% cd 

- Now start up octave

% octave

- And try to execute one of the simple functions that we have 
  programmed

>> myadd(2,3)

error: `myadd' undefined near line 1 column 1

- We get the error message since there is no file myadd.m containing
  a definition for the function myadd in any of the directories 
  specified in the path

- So let's add ~/octave to the path

>> addpath('~/octave')

- Note that we need to enclose the directory name in (forward) quotes

- Now try myadd again

>> myadd(2,3)

ans = 5

- Since you may (eventually) have octave source files in various 
  directories and/or run octave in directories that don't contain
  all of the needed source files, it can become very inconvenient to 
  have to explicitly use addpath every time you start octave

- Naturally, there is a solution to this problem, and again it is 
  similar to what is done for the shell (bash)

- Analogously to ~/.bashrc, you can create a file ~/.octaverc
  that contains (arbitrary) octave commands that are executed every 
  time you start an octave session

- Let's create ~/.octaverc by copying the corresponding file from
  phys210's account (note that the second argument to the cp command
  is . (dot))

% cd
% cp ~phys210/.octaverc .

- Examine its contents

% cat .octaverc

   addpath('~/octave');
   addpath('/home/phys210/octave');
   addpath('/home/phys210/octave/hw3');
   addpath('/home/phys210/octave/hw4');

- So now, whenever octave starts up, the directories specified in 
  the addpath commands will be added to the path

- Let's test this --- first exit your current octave session

>> exit

- Be sure that you're in your home directory

% cd

- Start up octave again

% octave

  and call myadd

>> myadd(2,3)

ans =  5


- So now, for example, when you define a new script/function in 
  ~/octave, you can use it any octave session, no matter what the 
  working directory is

- NOTE: You can add other octave commands to ~/.octaverc as you
  wish; we will see an example below

- Here's another example of invoking a function which is in your 
  octave path 

>> greetings

Greetings, user phys210d!

- Again, you can see the definition of greetings using the type command

>> type greetings

greetings is the user-defined function defined from: 
   /home/phys210/octave/greetings.m

function [] = greetings()
   fprintf('Greetings, user %s!\n',getenv('LOGNAME'));
end

- Note that the definition is in /home/phys210/octave, and that that 
  directory is in your octave path by virtue of the line

   addpath('/home/phys210/octave');

  in your ~/.octaverc

- Finally, and again in complete analogy with the PATH setting in bash,
  if there is more than one file <something>.m defining the function
  <something> in the list or directories stored in octave's path,
  then the first one encountered as the directories are scanned is 
  the one that is executed 

-----------------------------------------------------------------------------
2) Octave "core files"
-----------------------------------------------------------------------------

- From time to time octave may terminate abnormally, particularly if 
  you use Ctrl-C to interrupt a calculation that is taking an
  inordinately long time.

- In such instances, octave may 'dump core'---i.e. write a memory 
  image to a file that, in principle, can later be loaded into 
  octave to resume the computation.  However, you will never 
  want to use this resume feature (which is really strictly 
  for the benefit of octave developers), and the file that is 
  produced (which always has the name octave-core) can be quite 
  large.  Thus, if you notice an 'octave-core' file while working 
  with octave, it is best to remove it.

- Also, there is an octave function, octave_core_file_limit,
  which can be used to control the size of the core file.  Recommended
  practice, then (unless you really think you can make use of the 
  restore feature), is to add the following line to your 
  ~/.octaverc

octave_core_file_limit(1.0e-10);

- This will limit the size of octave-core to a few bytes.
  Note that octave_core_file_limit(0) doesn't do what you 
  might expect, and in fact generates an error message.

- Once you've added that line, start a new octave session and 
  ensure that you don't see any error messages --- if you do, 
  then you've made one or more typo and, of course, you should fix
  it/them --- ask for help as necessary

- Lines added to ~/.octaverc should normally end with a semi-colon,
  so that output generated from their exectution does not appear 
  when octave starts up

-------------------------------------------------------------------------
3) Displaying/outputing quantities in octave
-------------------------------------------------------------------------

-----------------------------------------------------------------------------
3.1) more 
-----------------------------------------------------------------------------

     Enables/disables output paging  (use of 'more' when output exceeds
     a terminal's worth)

- Turn paging off

>> more off

- Turn page on 

>> more on

- Try the following

>> more off
>> eye(100)

>> more on 
>> eye(100)

-----------------------------------------------------------------------------
3.2) disp 
-----------------------------------------------------------------------------

- Simple output, with no user control over appearance.
  Form of output essentially the same seen with interactive
  definition/use of vbls/expresssions, except with out the 
  '<whatever> ='

- Syntax 

  disp(<expr>)

  where <expr> is a SINGLE octave expression, i.e. something 
  that can be assigned to a variable

- Example

>> a = [1:2:11]

a =

    1    3    5    7    9   11

>> disp(a)

    1    3    5    7    9   11

- Compare this with 'type a' (recall 'type' previously used to show defn
  of a function)

>> type a

a is a variable
    1    3    5    7    9   11

- disp(<expr>) is the form to use when you only want to see the 
  value(s) associated with an expression, unadorned with additional
  information (including the name of the variable)

-----------------------------------------------------------------------------
XXX: CONTINUING ... START UP octave IN YOUR ~/octave DIRECTORY AS USUAL
-----------------------------------------------------------------------------
% cd ~/octave
% octave

-----------------------------------------------------------------------------
3.3) fprintf 
-----------------------------------------------------------------------------

- With this function, the user has control over the output format, 
  and more than one quantity can be output with a single function call

  Syntax 

  fprintf(<template>, <expr>, <expr>, <expr> ...)

  where 
     <template> is a string that provides information about the 
     number of additional arguments (<expr>'s) that will be output,
     but also their type (integer, float, string) and how they 
     should be output 

- Basic usage is best illustrated through some examples (be careful
  with the quotes that delimit the templates), and note that I've added 
  some blank lines in the below for readability

>> fprintf('This is an integer: %d\n', 100)

This is an integer: 100

>> fprintf('First integer: %d  Second integer: %d\n', 100, 200)

First integer: 100  Second integer: 200
 
>> fprintf('This is a real value: %f\n', 31415.9)

This is a real value: 31415.900000

>> fprintf('This is a real value (exponential format): %e\n', 31415.9)

This is a real value (exponential format): 3.141590e+04

>> fprintf('Real value 1: %g  Real value 2: %g\n', 3.14, .00000000314)

Real value 1: 3.14  Real value 2: 3.14e-09

>> fprintf('The is a string in angle brackets <%s>\n', 'foo')

The is a string in angle brackets <foo>

- Observe how all the characters in the templates, except for

  %d
  %f
  %e
  %g
  %s 

  are simply written to the terminal

- %d, %f, %e, %g and %s are known as CONVERSION SPECIFICATIONS.

  When fprintf executes, it replaces each of the conversion 
  specifications with a new string.  Each of these strings is the 
  result of the conversion of the corresponding argument to 
  a string as follows:

  %d  ->   converts an integer value 
  %f  ->   converts a floating point value using usual floating 
           point representation
  %e  ->   converts a floating point value using exponential notation
  %g  ->   converts a floating point value using %f or %e, dependent
           on the magnitude to the value, to give the most readable 
           result
  %s   ->  converts a string (i.e. simply replaces %s with the string)

- Note that the type (integer, float, string) of each argument should 
  match the type of the corresponding conversion specification (it 
  is safe to use fprintf to convert an integer to a float string,
  but conversion of a float to an integer will cause truncation)

- IMPORTANT: The '\n' (backslash n) stands for new-line, and will 
  generate a new-line whenever it is encountered in the template.  
  You will usually want to include one of these at the end of each 
  template string

- This may all seem a little confusing, but, as usual, experience 
  will help

- You can use fprintf to output a quantity that has mulitple values,
  i.e. an array.  In this case, fprintf processes each value in 
  turn, recycling the template as necessary

- Examples

>> fprintf('4 values: %d %d %d %d\n', linspace(1, 16, 8));

4 values: 1 3 5 7
4 values: 9 11 13 16

>> fprintf('4 values: %d %d %d %d\n', linspace(1, 16, 7));

4 values: 1 3 6 8
4 values: 11 13 16 >>

- In this last example, since there were only 7 values to output, 
  fprintf did not encounter a new-line before the input values
  were exhausted, so there is no new-line before the prompt

-------------------------------------------------------------------------
3.3.1) Using fprintf to output to a file
-------------------------------------------------------------------------

- fprintf can also be used to output quantities to a file -- in fact 
  this is the most common usage for it

- We will illustrate this facility (which requires the use of two other
  built in functions, fopen and fclose) via the demo script 'tfprintf'

>> type fprintf

tfprintf is the user-defined function defined from: /home/phys210/octave/tfprint
f.m

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Illustrates use of fprintf to output data to a file.  
   %
   % Requires use of additional built in functions:
   %
   %    fopen:  Opens file 
   %    fclose: Closes file 
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % First, open 'tfprintf.dat' for writing.
   % 
   %    First (string) argument to fopen specifies name of file.
   %    Second (string) argument to fopen specifies type of access,
   %       'w' means write.
   %
   %    Return value is an integer 'file descriptor' that is then
   %    used in 'fprintf' calls.  If return value is < 0, then 
   %    open failed (as could happen, for example, if you were trying
   %    to open a file in a directory for which you do not have 
   %    write access.
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   fid = fopen('tfprintf.dat', 'w');

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Bail out if can't open file for write ...
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   if fid < 0 
      fprintf('Could not open ''tfprintf.dat'' for write.\n');
      return;
   end

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Now use fprintf to output integers from 1 to 10, their squares 
   % and cubes as three columns ...
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
   for i = 1 : 10
      fprintf(fid,"%d %d %d\n", i, i^2, i^3);
   end

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Close file ... until the file is closed, there is no guarantee
   % that what you think you've written to the file is actually 
   % there! 
   %
   % Note that  the file descriptor, NOT the file name is the argument
   % passed to fclose ...
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   fclose(fid);

- Execute the script ...

>> tfprintf

- ... which does its job silently

- Now open up another terminal window, change to your ~/octave directory
  look for the file 'tfprintf.dat', and examine its contents (if you 
  don't find the file in ~/octave, then you probably weren't running
  octave in that directory)

% cd ~/octave
% cat tfprintf.dat 

   1 1 1
   2 4 8
   3 9 27
   4 16 64
   5 25 125
   6 36 216
   7 49 343
   8 64 512
   9 81 729
   10 100 1000

- When doing your term projects, you may find it useful to use fprintf 
  for file output.  If you have problems using it that can't be resolved 
  using the available documentation, don't hesitate to ask for help!

-------------------------------------------------------------------------
4) Inputing quantities in octave
-------------------------------------------------------------------------

-------------------------------------------------------------------------
4.1) input
-------------------------------------------------------------------------

- When programming, may want user (typically you) to enter some input 
  interactively and have it assigned to variable

- Won't do this (much) in the lab exercises / homeworks, but you may 
  find it useful for your projects

- Syntax 

     <var> = input(<prompt string>)

- or 

     input(<prompt string>)

- In both cases script/function execution pauses until ENTER key
  is typed

- The input MUST be something that can be assigned to an octave 
  variable (for our purposes scalar, vector, array, string, or 
  nothing) or an error will be generated

- In the second case the input is simply "thrown away" but the form is 
  still useful to have execution suspended so that user can examine
  output etc. before the program/fcn continues see 
  ~phys210/octave/plotex.m for an example

- Examples

>> scalarin = input('Enter a single number: ')

Enter a single number: 5
scalarin =  5

>> vectorin = input('Enter a vector: ')

Enter a vector: [1 2 3 4]
vectorin =

   1   2   3   4

>> stringin = input('Enter a string: ')

Enter a string: 'foobar'
stringin = foobar

>> wrongin = input('Enter some invalid input: ')

Enter some invalid input: xyz
error: `xyz' undefined near line 16 column 1

- An example where the input value is not assigned to anything

>> for i = 1 : 5
   input('Enter anything to continue: ')
end
 
   Enter anything to continue: 
   ans = [](0x0)
   Enter anything to continue: 
   ans = [](0x0)
   Enter anything to continue: 
   ans = [](0x0)
   Enter anything to continue: 
   ans = [](0x0)
   Enter anything to continue: 
   ans = [](0x0)

- In the last example, it is a good idea to suppress the output of 
  the input function (this will also usually be the case when you are using
  input in your own functions or scripts), so we end the input call
  with a semi-colon

>> for i = 1 : 5
   input('Enter anything to continue: ');
end

   Enter anything to continue: 
   Enter anything to continue: 
   Enter anything to continue: 
   Enter anything to continue: 
   Enter anything to continue: 

-------------------------------------------------------------------------
4.2) fscanf
-------------------------------------------------------------------------

- fscanf is the input counterpart to fprintf ... we will illustrate its
  usage here via a script 'tfscanf' which inputs the values from 
  the file created by the script 'tfprintf' described above, nd then outputs 
  them to the terminal

>> type tfscanf

   tfscanf is the user-defined function defined from: /home/phys210/octave/tfscanf.m

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Illustrates use of fscanf to input data from a file.  
   %
   % Requires use of additional built in functions:
   %
   %    fopen:  Opens file 
   %    fclose: Closes file 
   %
   % Note that there are many different ways that fscanf can be called,
   % some of which allow data stored in a file in a particularly 
   % organized fashion (e.g. as columns) to be read with little coding 
   % effort.
   %
   % This script illustrates a general technique that can be used 
   % in cases where the data to be read is not necessarily structued
   % as an array (e.g.)
   % 
   % Refer to online documentation or seek help from the instructor
   % and/or TAs should you wish to read from files as part of your 
   % term project, and you are having difficulty doing so.
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % First, open 'tfprintf.dat' for reading.
   % 
   %    First (string) argument to fopen specifies name of file.
   %    Second (string) argument to fopen specifies type of access,
   %       'r' means read.
   %
   %    Return value is an integer 'file descriptor' that is then
   %    used in 'fprintf' calls.  If return value is < 0, then 
   %    open failed, as could happen, for example, if file does not 
   %    exist, or if you don't have permission to read the file.
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   fid = fopen('tfprintf.dat', 'r');

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Bail out if can't open file for write ...
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   if fid < 0 
      fprintf('Could not open ''tfprintf.dat'' for read.\n');
      return;
   end

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Use a while loop to read the data in the file row by row until
   % the input is exhausted ...
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
   notdone = 1;
   while notdone
      
       %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
       % Arguments to fscanf:
       %
       %    First: file descriptor
       %    Second: template string (specifies three integer values)
       %    Third: 'C' - denotes that fscanf is being used a la the 
       %      C programming language
       %
       % Return values
       % 
       %     val1, val2, val3:  Values read
       %     count: Number of values read: if < 3 then input is exhausted
       %        
       %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
      [val1, val2, val3, count] = fscanf(fid,'%d %d %d','C');
      if count < 3 
         notdone = 0;
      else
         fprintf('i=%d  i^2=%d  i^3=%d\n', val1, val2, val3);
      end
   end

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Close file ... 
   %
   % Note that  the file descriptor, NOT the file name is the argument
   % passed to fclose ...
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   fclose(fid);

- Run the script

>> tfscanf

   i=1  i^2=1  i^3=1
   i=2  i^2=4  i^3=8
   i=3  i^2=9  i^3=27
   i=4  i^2=16  i^3=64
   i=5  i^2=25  i^3=125
   i=6  i^2=36  i^3=216
   i=7  i^2=49  i^3=343
   i=8  i^2=64  i^3=512
   i=9  i^2=81  i^3=729
   i=10  i^2=100  i^3=1000

- The same comment applies here as for fprintf.  If you want/need to use 
  it, and run into problems that you can't solve easily using the available 
  documentation, ask for help!

-------------------------------------------------------------------------
5) Simple 2D plotting with octave
-------------------------------------------------------------------------

- Octave's plotting facilities use gnuplot, and allow you to make 
  2D plots in a straightforward manner

- This is accomplished using the 'plot' function/command

- The simplest usage is to create vectors of x and y values and 
  plot them against each other; here we make a plot of cos(x) vs 
  x for x = 0 .. 3 pi / 2, using 1000 values

>> x = linspace(0, 3*pi/2, 1000);
>> y = cos(x);
>> plot(x,y)

  ... and a simple plot should appear on the screen

- YOU CAN USE THIS TYPE OF CALL TO plot IN YOUR DEVELOPMENT OF THE 
  FUNCTIONS THAT YOU NEED TO WRITE FOR THE CURRENT HOMEWORK

- I have created a script, plotex, that demonstrates a few more features 
  of the plot command

>> First, diplay the contents of plotex

>> type plotex;

plotex is the user-defined function defined from: ...

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Simple examples of 2D plotting in octave.
   %
   % Use 'doc plot' for additional information.
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

   more off;

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   % Example 1:  Basic plot
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   fprintf('The following is a plot of\n\n');
   fprintf('   sin(x)*sin(3x) for 0 <= x <= 2 pi, and using\n\n');
   fprintf('   - 1000 points uniformly distributed in the interval\n');
   fprintf('   - default plotting style (line)\n');
   fprintf('   - default line color\n');
   fprintf('   - default annotations (no title, axes labels or legend)\n\n');

   % 'clf' clears the graphics window.
                             .
                             .
                             .

- Now, execute the script

>> plotex

- You should see output such as the following on your terminal, 
  and, as the script executes, you should also see various plots
  appearing in a separate plotting window labelled 'Figure 1'.
  If this doesn't work for you, ask for help.

      The following is a plot of

         sin(x)*sin(3x) for 0 <= x <= 2 pi, and using

         - 1000 points uniformly distributed in the interval
         - default plotting style (line)
         - default line color
         - default annotations (no title, axes labels or legend)

      Type 'Enter' to continue:
      The following is a plot of

         sin(x)*sin(3x) for 0 <= x <= 2 pi, using

         - 1000 points uniformly distributed in the interval
         - points plotting style, with small green circles for the points
         - a title and axes labels

      Type 'Enter' to continue:
      The following is a plot of

         sin(x)*sin(3x) AND cos(5x)*cos(2x) for 0 <= x <= 2 pi, using

         - 1000 points uniformly distributed in the interval
         - red +'s for the first data set, a cyan line for the second
         - a title, axes labels and legend
      Also, a hardcopy of the figure is saved as 'plot.ps'

- You should see 'plot.ps' (a Postscipt file) when you get a listing of 
  the directory in which octave is executing 

- Once you have finished with this demo, study the script file 

   /phys210/octave/plotex.m

  to see how the plots were generated. 

- You can use this file as a template to work from for exercises, 
  homework, term projects etc.

- Refer to 

   http://www.gnu.org/software/octave/doc/interpreter/Two_002dDimensional-Plots.html

   or google 'octave plotting' for additional information on this topic

-------------------------------------------------------------------------
6) Interfacing functions to octave's help command
-------------------------------------------------------------------------

- FIRST NOTE THE FOLLOWING IMPORTANT POINT:

   - You (and I!) should only use '%' as the comment character in 
     octave/MATLAB.  '#' will also work in octave BUT NOT IN MATLAB
     (bad insructor!)

- Leave as exercise for you to modify all of the code that you 
  have written, and be sure to use '%' in the future, including 
  your code for homeworks and projects

- In an octave session enter

>> type demohelp

   demohelp is the user-defined function defined from: /home/phys210/octave/demohelp.m

   function demohelp()
   % demohelp illustrates the mechanism for interfacing
   % an arbitrary function to the 'help' command in 
   % octave/MATLAB.
   %
   % Input arguments: None
   %
   % Return values: None
   %
   % Any text in contiguous comment lines following the 
   % function header will be displayed when 'help <function name>' 
   % is invoked.  
   %
   % The comment characters per se are stripped from the 
   % output.
   %
   % All 'demohelp' does is echo an empty line to the terminal.
   % 
      disp('');
      % The comment block above will be displayed when 
      % 'help demohelp' is entered, but this block will not.
   end

- Now type

>> help demohelp

   `demohelp' is a function from the file /home/phys210/octave/demohelp.m

    demohelp illustrates the mechanism for interfacing
    an arbitrary function to the 'help' command in 
    octave/MATLAB.

    Input arguments: None

    Return values: None

    Any text in contiguous comment lines following the 
    function header will be displayed when 'help <function name>' 
    is invoked.  

    The comment characters per se are stripped from the 
    output.

    All 'demohelp' does is echo an empty line to the terminal.
                             .
                             .
                             .


- Have modified some of the solutions to assigned exercises so 
  that they have help comment blocks

-------------------------------------------------------------------------
7) Cell arrays
-------------------------------------------------------------------------

- The individual elements of the arrays that we have used thus far 
  in octave/MATLAB must all be scalars (i.e. single numbers)

- There is another type of array, called a CELL ARRAY, whose elements 
  can be ARBITRARY octave quantities, including scalars, arrays 
  strings, or even other cell arrays (and each element can be can
  be a DIFFERENT type of object)

- Cell arrays are very handy for many programming tasks in octave,
  and you are encouraged to become familiar with their use  (for 
  example, the driver script 'tfdas.m' for the third homework uses them)

- Unlike regular arrays, cell arrays cannot be defined "on the fly";
  they must be created with some specified dimensions using the 
  built-in 'cell' function.  (However, once defined, additional values 
  will be added automatically when referenced as is the case for 
  normal arrays.)

>> help cell

   `cell' is a built-in function

    -- Built-in Function:  cell (X)
    -- Built-in Function:  cell (N, M)
        Create a new cell array object.  If invoked with a single scalar
        argument, `cell' returns a square cell array with the dimension
        specified.  If you supply two scalar arguments, `cell' takes them
        to be the number of rows and columns.  If given a vector with two
        elements, `cell' uses the values of the elements as the number of
        rows and columns, respectively.

- Let's create a cell array with dimensions 1 x 4 (i.e. a row vector 
  of cells, and then assign values to it

>> cc = cell(1,4)

   cc =

   {
     [1,1] = [](0x0)
     [1,2] = [](0x0)
     [1,3] = [](0x0)
     [1,4] = [](0x0)
   }

- The value [](0x0) is to be interpreted as "undefined"

- Now assign row vectors of varying lengths to the elements of cc
  
  IMPORTANT:  Cell arrays are indexed with { } (braces, curly brackets),
  both for assignment and retrieval of values.

>> cc{1} = 1:2

   cc =

   {
     [1,1] =

        1   2

     [1,2] = [](0x0)
     [1,3] = [](0x0)
     [1,4] = [](0x0)
   }

>> cc{2} = 1:4

   cc =

   {
     [1,1] =

        1   2

     [1,2] =

        1   2   3   4

     [1,3] = [](0x0)
     [1,4] = [](0x0)
   }

>> cc{3} = 1:6

   cc =

   {
     [1,1] =

        1   2

     [1,2] =

        1   2   3   4

     [1,3] =

        1   2   3   4   5   6

     [1,4] = [](0x0)
   }

>> cc{4} = 1:8

   cc =

   {
     [1,1] =

        1   2

     [1,2] =

        1   2   3   4

     [1,3] =

        1   2   3   4   5   6

     [1,4] =

        1   2   3   4   5   6   7   8

   }

- Now retrieve the contents of the 3rd cell

>> cc{3}

   ans =

      1   2   3   4   5   6

- Cell arrays can be multidimensional --- for example, as the help 
  message for cell states, if the function is called with a single 
  argument, N, a square N x N array of cells is created  ...

>> dd = cell(2)

   dd =

   {
     [1,1] = [](0x0)
     [2,1] = [](0x0)
     [1,2] = [](0x0)
     [2,2] = [](0x0)
   }

- ... and then elements are assigned/retrieved using the usual 
  syntax for multi-d arrays, but again using {} for indexing

>> dd{1,1} = 'a'; dd{1,2} = 1:5:2; dd{2,1} = eye(2); dd{2,2} = [1:4]';

- Display the contents of the entire cell array

>> dd

   dd =

   {
     [1,1] = a
     [2,1] =

   Diagonal Matrix

        1   0
        0   1

     [1,2] =  1
     [2,2] =

        1
        2
        3
        4

   }

- Display the contents of a specific element

>> dd{2,2}

ans =

   1
   2
   3
   4

- Again, note how we can "mix and match" various types of objects in
  the different cells 

-------------------------------------------------------------------------
EXERCISES (TWO HANDOUTS INCLUDING PROBLEMS FROM GILAT)
-------------------------------------------------------------------------

- Suggestions

   - Handout 1

      - Problems from Ch 1.10 are fairly trivial, so skip them
      - Do problems from Ch 2.11
      - Do problem 3c) --- sintaylor 

   - Handout 2

      - Do problems from Ch 3.9
      - Do part 2
      - If you have time, do part 3 (recommend that you do it at 
        some point)