home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / octa21eb.zip / octave / doc / octave.i08 < prev    next >
Encoding:
GNU Info File  |  1999-05-13  |  48.9 KB  |  1,587 lines
  1. This is Info file octave, produced by Makeinfo-1.64 from the input file
  2. octave.tex.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Octave: (octave).    Interactive language for numerical computations.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    Copyright (C) 1996, 1997 John W. Eaton.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided that
  16. the entire resulting derived work is distributed under the terms of a
  17. permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions.
  22.  
  23. 
  24. File: octave,  Node: Ordinary Differential Equations,  Next: Differential-Algebraic Equations,  Prev: Differential Equations,  Up: Differential Equations
  25.  
  26. Ordinary Differential Equations
  27. ===============================
  28.  
  29.    The function `lsode' can be used Solve ODEs of the form
  30.  
  31.      dx
  32.      -- = f (x, t)
  33.      dt
  34.  
  35. using Hindmarsh's ODE solver LSODE.
  36.  
  37.  - Loadable Function:  lsode (FCN, X0, T, T_CRIT)
  38.      Return a matrix of X as a function of T, given the initial state
  39.      of the system X0.  Each row in the result matrix corresponds to
  40.      one of the elements in the vector T.  The first element of T
  41.      corresponds to the initial state X0, so that the first row of the
  42.      output is X0.
  43.  
  44.      The first argument, FCN, is a string that names the function to
  45.      call to compute the vector of right hand sides for the set of
  46.      equations.  It must have the form
  47.  
  48.           XDOT = f (X, T)
  49.  
  50.      where XDOT and X are vectors and T is a scalar.
  51.  
  52.      The fourth argument is optional, and may be used to specify a set
  53.      of times that the ODE solver should not integrate past.  It is
  54.      useful for avoiding difficulties with singularities and points
  55.      where there is a discontinuity in the derivative.
  56.  
  57.    Here is an example of solving a set of three differential equations
  58. using `lsode'.  Given the function
  59.  
  60.      function xdot = f (x, t)
  61.      
  62.        xdot = zeros (3,1);
  63.      
  64.        xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \
  65.                  - 8.375e-06*x(1)^2);
  66.        xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27;
  67.        xdot(3) = 0.161*(x(1) - x(3));
  68.      
  69.      endfunction
  70.  
  71. and the initial condition `x0 = [ 4; 1.1; 4 ]', the set of equations
  72. can be integrated using the command
  73.  
  74.      t = linspace (0, 500, 1000);
  75.      
  76.      y = lsode ("f", x0, t);
  77.  
  78.    If you try this, you will see that the value of the result changes
  79. dramatically between T = 0 and 5, and again around T = 305.  A more
  80. efficient set of output points might be
  81.  
  82.      t = [0, logspace (-1, log10(303), 150), \
  83.              logspace (log10(304), log10(500), 150)];
  84.  
  85.  - Loadable Function:  lsode_options (OPT, VAL)
  86.      When called with two arguments, this function allows you set
  87.      options parameters for the function `lsode'.  Given one argument,
  88.      `lsode_options' returns the value of the corresponding option.  If
  89.      no arguments are supplied, the names of all the available options
  90.      and their current values are displayed.
  91.  
  92.    See Alan C. Hindmarsh, `ODEPACK, A Systematized Collection of ODE
  93. Solvers', in Scientific Computing, R. S. Stepleman, editor, (1983) for
  94. more information about the inner workings of `lsode'.
  95.  
  96. 
  97. File: octave,  Node: Differential-Algebraic Equations,  Prev: Ordinary Differential Equations,  Up: Differential Equations
  98.  
  99. Differential-Algebraic Equations
  100. ================================
  101.  
  102.    The function `dassl' can be used Solve DAEs of the form
  103.  
  104.      0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0
  105.  
  106. using Petzold's DAE solver DASSL.
  107.  
  108.  - Loadable Function: [X, XDOT] = dassl (FCN, X0, XDOT0, T, T_CRIT)
  109.      Return a matrix of states and their first derivatives with respect
  110.      to T.  Each row in the result matrices correspond to one of the
  111.      elements in the vector T.  The first element of T corresponds to
  112.      the initial state X0 and derivative XDOT0, so that the first row
  113.      of the output X is X0 and the first row of the output XDOT is
  114.      XDOT0.
  115.  
  116.      The first argument, FCN, is a string that names the function to
  117.      call to compute the vector of residuals for the set of equations.
  118.      It must have the form
  119.  
  120.           RES = f (X, XDOT, T)
  121.  
  122.      where X, XDOT, and RES are vectors, and T is a scalar.
  123.  
  124.      The second and third arguments to `dassl' specify the initial
  125.      condition of the states and their derivatives, and the fourth
  126.      argument specifies a vector of output times at which the solution
  127.      is desired, including the time corresponding to the initial
  128.      condition.
  129.  
  130.      The set of initial states and derivatives are not strictly
  131.      required to be consistent.  In practice, however, DASSL is not
  132.      very good at determining a consistent set for you, so it is best
  133.      if you ensure that the initial values result in the function
  134.      evaluating to zero.
  135.  
  136.      The fifth argument is optional, and may be used to specify a set of
  137.      times that the DAE solver should not integrate past.  It is useful
  138.      for avoiding difficulties with singularities and points where
  139.      there is a discontinuity in the derivative.
  140.  
  141.  - Loadable Function:  dassl_options (OPT, VAL)
  142.      When called with two arguments, this function allows you set
  143.      options parameters for the function `lsode'.  Given one argument,
  144.      `dassl_options' returns the value of the corresponding option.  If
  145.      no arguments are supplied, the names of all the available options
  146.      and their current values are displayed.
  147.  
  148.    See K. E. Brenan, et al., `Numerical Solution of Initial-Value
  149. Problems in Differential-Algebraic Equations', North-Holland (1989) for
  150. more information about the implementation of DASSL.
  151.  
  152. 
  153. File: octave,  Node: Optimization,  Next: Statistics,  Prev: Differential Equations,  Up: Top
  154.  
  155. Optimization
  156. ************
  157.  
  158. * Menu:
  159.  
  160. * Quadratic Programming::
  161. * Nonlinear Programming::
  162. * Linear Least Squares::
  163.  
  164. 
  165. File: octave,  Node: Quadratic Programming,  Next: Nonlinear Programming,  Prev: Optimization,  Up: Optimization
  166.  
  167. Quadratic Programming
  168. =====================
  169.  
  170. 
  171. File: octave,  Node: Nonlinear Programming,  Next: Linear Least Squares,  Prev: Quadratic Programming,  Up: Optimization
  172.  
  173. Nonlinear Programming
  174. =====================
  175.  
  176. 
  177. File: octave,  Node: Linear Least Squares,  Prev: Nonlinear Programming,  Up: Optimization
  178.  
  179. Linear Least Squares
  180. ====================
  181.  
  182.  - Function File: [BETA, V, R] = gls (Y, X, O)
  183.      Generalized least squares estimation for the multivariate model `Y
  184.      = X * B + E' with `mean (E) = 0' and `cov (vec (E)) = (S^2)*O',
  185.      where Y is a T by P matrix, X is a T by K matrix, B is a K by P
  186.      matrix, E is a T by P matrix, and O is a TP by TP matrix.
  187.  
  188.      Each row of Y and X is an observation and each column a variable.
  189.  
  190.      The return values BETA, V, and R are defined as follows.
  191.  
  192.     BETA
  193.           The GLS estimator for B.
  194.  
  195.     V
  196.           The GLS estimator for `S^2'.
  197.  
  198.     R
  199.           The matrix of GLS residuals, `R = Y - X * BETA'.
  200.  
  201.  - Function File: [BETA, SIGMA, R] = ols (Y, X)
  202.      Ordinary least squares estimation for the multivariate model `Y =
  203.      X*B + E' with `mean (E) = 0' and `cov (vec (E)) = kron (S, I)'.
  204.      where Y is a T by P matrix, X is a T by K matrix, B is a K by P
  205.      matrix, and E is a T by P matrix.
  206.  
  207.      Each row of Y and X is an observation and each column a variable.
  208.  
  209.      The return values BETA, SIGMA, and R are defined as follows.
  210.  
  211.     BETA
  212.           The OLS estimator for B, `BETA = pinv (X) * Y', where `pinv
  213.           (X)' denotes the pseudoinverse of X.
  214.  
  215.     SIGMA
  216.           The OLS estimator for the matrix S,
  217.  
  218.                SIGMA = (Y-X*BETA)' * (Y-X*BETA) / (T-rank(X))
  219.  
  220.     R
  221.           The matrix of OLS residuals, `R = Y - X * BETA'.
  222.  
  223. 
  224. File: octave,  Node: Statistics,  Next: Sets,  Prev: Optimization,  Up: Top
  225.  
  226. Statistics
  227. **********
  228.  
  229.    I hope that someday Octave will include more statistics functions.
  230. If you would like to help improve Octave in this area, please contact
  231. (bug-octave@bevo.che.wisc.edu).
  232.  
  233.  - Function File:  mean (X)
  234.      If X is a vector, compute the mean of the elements of X
  235.  
  236.           mean (x) = SUM_i x(i) / N
  237.      If X is a matrix, compute the mean for each column and return them
  238.      in a row vector.
  239.  
  240.  - Function File:  median (X)
  241.      If X is a vector, compute the median value of the elements of X.
  242.  
  243.                       x(ceil(N/2)),             N odd
  244.           median(x) =
  245.                       (x(N/2) + x((N/2)+1))/2,  N even
  246.      If X is a matrix, compute the median value for each column
  247.      and return them in a row vector.
  248.  
  249.  - Function File:  std (X)
  250.      If X is a vector, compute the standard deviation of the elements
  251.      of X.
  252.  
  253.           std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
  254.      If X is a matrix, compute the standard deviation for each
  255.      column and return them in a row vector.
  256.  
  257.  - Function File:  cov (X, Y)
  258.      If each row of X and Y is an observation and each column is a
  259.      variable, the (I,J)-th entry of `cov (X, Y)' is the covariance
  260.      between the I-th variable in X and the J-th variable in Y.  If
  261.      called with one argument, compute `cov (X, X)'.
  262.  
  263.  - Function File:  corrcoef (X, Y)
  264.      If each row of X and Y is an observation and each column is a
  265.      variable, the (I,J)-th entry of `corrcoef (X, Y)' is the
  266.      correlation between the I-th variable in X and the J-th variable
  267.      in Y.  If called with one argument, compute `corrcoef (X, X)'.
  268.  
  269.  - Function File:  kurtosis (X)
  270.      If X is a vector of length N, return the kurtosis
  271.  
  272.           kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3
  273.  
  274.      of X.  If X is a matrix, return the row vector containing the
  275.      kurtosis of each column.
  276.  
  277.  - Function File:  mahalanobis (X, Y)
  278.      Return the Mahalanobis' D-square distance between the multivariate
  279.      samples X and Y, which must have the same number of components
  280.      (columns), but may have a different number of observations (rows).
  281.  
  282.  - Function File:  skewness (X)
  283.      If X is a vector of length N, return the skewness
  284.  
  285.           skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)
  286.  
  287.      of X.  If X is a matrix, return the row vector containing the
  288.      skewness of each column.
  289.  
  290. 
  291. File: octave,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Statistics,  Up: Top
  292.  
  293. Sets
  294. ****
  295.  
  296.    Octave has a limited set of functions for managing sets of data,
  297. where a set is defined as a collection unique elements.
  298.  
  299.  - Function File:  create_set (X)
  300.      Return a row vector containing the unique values in X, sorted in
  301.      ascending order.  For example,
  302.  
  303.           create_set ([ 1, 2; 3, 4; 4, 2 ])
  304.                => [ 1, 2, 3, 4 ]
  305.  
  306.  - Function File:  union (X, Y)
  307.      Return the set of elements that are in either of the sets X and Y.
  308.      For example,
  309.  
  310.           union ([ 1, 2, 4 ], [ 2, 3, 5 ])
  311.                => [ 1, 2, 3, 4, 5 ]
  312.  
  313.  - Function File:  intersection (X, Y)
  314.      Return the set of elements that are in both sets X and Y.  For
  315.      example,
  316.  
  317.           intersection ([ 1, 2, 3 ], [ 2, 3, 5 ])
  318.                => [ 2, 3 ]
  319.  
  320.  - Function File:  complement (X, Y)
  321.      Return the elements of set Y that are not in set X.  For example,
  322.  
  323.           complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
  324.                => 5
  325.  
  326. 
  327. File: octave,  Node: Polynomial Manipulations,  Next: Control Theory,  Prev: Sets,  Up: Top
  328.  
  329. Polynomial Manipulations
  330. ************************
  331.  
  332.    In Octave, a polynomial is represented by its coefficients (arranged
  333. in descending order).  For example, a vector  C of length  N+1
  334. corresponds to the following polynomial of order  N
  335.  
  336.      p(x) = C(1) x^N + ... + C(N) x + C(N+1).
  337.  
  338.  - Function File:  compan (C)
  339.      Compute the companion matrix corresponding to polynomial
  340.      coefficient vector C.
  341.  
  342.      The companion matrix is
  343.  
  344.                _                                                        _
  345.               |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(N)/c(1)  -c(N+1)/c(1)  |
  346.               |       1            0      ...       0             0      |
  347.               |       0            1      ...       0             0      |
  348.           A = |       .            .   .            .             .      |
  349.               |       .            .       .        .             .      |
  350.               |       .            .           .    .             .      |
  351.               |_      0            0      ...       1             0     _|
  352.  
  353.      The eigenvalues of the companion matrix are equal to the roots of
  354.      the polynomial.
  355.  
  356.  - Function File:  conv (A, B)
  357.      Convolve two vectors.
  358.  
  359.      `y = conv (a, b)' returns a vector of length equal to `length (a)
  360.      + length (b) - 1'.  If A and B are polynomial coefficient vectors,
  361.      `conv' returns the coefficients of the product polynomial.
  362.  
  363.  - Function File:  deconv (Y, A)
  364.      Deconvolve two vectors.
  365.  
  366.      `[b, r] = deconv (y, a)' solves for B and R such that `y = conv
  367.      (a, b) + r'.
  368.  
  369.      If Y and A are polynomial coefficient vectors, B will contain the
  370.      coefficients of the polynomial quotient and R will be a remander
  371.      polynomial of lowest order.
  372.  
  373.  - Function File:  poly (A)
  374.      If A is a square N-by-N matrix, `poly (A)' is the row vector of
  375.      the coefficients of `det (z * eye (N) - a)', the characteristic
  376.      polynomial of A.  If X is a vector, `poly (X)' is a vector of
  377.      coefficients of the polynomial whose roots are the elements of X.
  378.  
  379.  - Function File:  polyderiv (C)
  380.      Return the coefficients of the derivative of the polynomial whose
  381.      coefficients are given by vector C.
  382.  
  383.  - Function File: [P, YF] = polyfit (X, Y, N)
  384.      Return the coefficients of a polynomial P(X) of degree N that
  385.      minimizes `sumsq (p(x(i)) - y(i))',  to best fit the data in the
  386.      least squares sense.
  387.  
  388.    If two output arguments are requested, the second contains the
  389. values of the polynomial for each value of X.
  390.  
  391.  - Function File:  polyinteg (C)
  392.      Return the coefficients of the integral of the polynomial whose
  393.      coefficients are represented by the vector C.
  394.  
  395.      The constant of integration is set to zero.
  396.  
  397.  - Function File:  polyreduce (C)
  398.      Reduces a polynomial coefficient vector to a minimum number of
  399.      terms by stripping off any leading zeros.
  400.  
  401.  - Function File:  polyval (C, X)
  402.      Evaluate a polynomial.
  403.  
  404.      `polyval (C, X)' will evaluate the polynomial at the specified
  405.      value of X.
  406.  
  407.      If X is a vector or matrix, the polynomial is evaluated at each of
  408.      the elements of X.
  409.  
  410.  - Function File:  polyvalm (C, X)
  411.      Evaluate a polynomial in the matrix sense.
  412.  
  413.      `polyvalm (C, X)' will evaluate the polynomial in the matrix
  414.      sense, i.e. matrix multiplication is used instead of element by
  415.      element multiplication as is used in polyval.
  416.  
  417.      The argument X must be a square matrix.
  418.  
  419.  - Function File:  residue (B, A, TOL)
  420.      If B and A are vectors of polynomial coefficients, then residue
  421.      calculates the partial fraction expansion corresponding to the
  422.      ratio of the two polynomials.
  423.  
  424.      The function `residue' returns R, P, K, and E, where the vector R
  425.      contains the residue terms, P contains the pole values, K contains
  426.      the coefficients of a direct polynomial term (if it exists) and E
  427.      is a vector containing the powers of the denominators in the
  428.      partial fraction terms.
  429.  
  430.      Assuming B and A represent polynomials  P (s) and Q(s)  we have:
  431.  
  432.            P(s)    M       r(m)         N
  433.            ---- = SUM -------------  + SUM k(i)*s^(N-i)
  434.            Q(s)   m=1 (s-p(m))^e(m)    i=1
  435.  
  436.      where M is the number of poles (the length of the R, P, and E
  437.      vectors) and N is the length of the K vector.
  438.  
  439.      The argument TOL is optional, and if not specified, a default
  440.      value of 0.001 is assumed.  The tolerance value is used to
  441.      determine whether poles with small imaginary components are
  442.      declared real.  It is also used to determine if two poles are
  443.      distinct.  If the ratio of the imaginary part of a pole to the
  444.      real part is less than TOL, the imaginary part is discarded.  If
  445.      two poles are farther apart than TOL they are distinct.  For
  446.      example,
  447.  
  448.            b = [1, 1, 1];
  449.            a = [1, -5, 8, -4];
  450.            [r, p, k, e] = residue (b, a);
  451.                => r = [-2, 7, 3]
  452.                => p = [2, 2, 1]
  453.                => k = [](0x0)
  454.                => e = [1, 2, 1]
  455.  
  456.      which implies the following partial fraction expansion
  457.  
  458.                   s^2 + s + 1       -2        7        3
  459.              ------------------- = ----- + ------- + -----
  460.              s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)
  461.  
  462.  - Function File:  roots (V)
  463.      For a vector V with N components, return the roots of the
  464.      polynomial
  465.  
  466.           v(1) * z^(N-1) + ... + v(N-1) * z + v(N).
  467.  
  468. 
  469. File: octave,  Node: Control Theory,  Next: Signal Processing,  Prev: Polynomial Manipulations,  Up: Top
  470.  
  471. Control Theory
  472. **************
  473.  
  474.    The Octave Control Systems Toolbox (OCST) was initially developed by
  475. Dr. A. Scottedward Hodel (a.s.hodel@eng.auburn.edu) with the assistance
  476. of his students
  477.    * R. Bruce Tenison (btenison@dibbs.net),
  478.  
  479.    * David C. Clem,
  480.  
  481.    * John E. Ingram (John.Ingram@sea.siemans.com), and
  482.  
  483.    * Kristi McGowan.  This development was supported in part by NASA's
  484. Marshall Space Flight Center as part of an in-house CACSD environment.
  485. Additional important contributions were made by Dr. Kai Mueller
  486. (mueller@ifr.ing.tu-bs.de) and Jose Daniel Munoz Frias (`place.m').
  487.  
  488.    An on-line menu-driven tutorial is available via *Note DEMOcontrol::;
  489. beginning OCST users should start with this program.
  490.  
  491. * Menu:
  492.  
  493. * OCST demonstration/tutorial:DEMOcontrol.
  494. * System Data Structure:sysstruct.
  495. * System Construction and Interface Functions:sysinterface.
  496. * System display functions:sysdisp.
  497. * Block Diagram Manipulations:blockdiag.
  498. * Numerical Functions:numerical.
  499. * System Analysis-Properties:sysprop.
  500. * System Analysis-Time Domain:systime.
  501. * System Analysis-Frequency Domain:sysfreq.
  502. * Controller Design:cacsd.
  503. * Miscellaneous Functions:misc.
  504.  
  505. 
  506. File: octave,  Node: DEMOcontrol,  Next: sysstruct,  Prev: Control Theory,  Up: Control Theory
  507.  
  508. OCST demo program
  509. =================
  510.  
  511.  - Function File :   DEMOcontrol
  512.      Octave Control Systems Toolbox demo/tutorial program.  The demo
  513.      allows the user to select among several categories of OCST
  514.      function:
  515.           octave:1> DEMOcontrol
  516.            O C T A V E    C O N T R O L   S Y S T E M S   T O O L B O X
  517.           Octave Controls System Toolbox Demo
  518.           
  519.             [ 1] System representation
  520.             [ 2] Block diagram manipulations
  521.             [ 3] Frequency response functions
  522.             [ 4] State space analysis functions
  523.             [ 5] Root locus functions
  524.             [ 6] LQG/H2/Hinfinity functions
  525.             [ 7] End
  526.      Command examples are interactively run for users to observe
  527.      the use of OCST functions.
  528.  
  529. 
  530. File: octave,  Node: sysstruct,  Next: sysinterface,  Prev: DEMOcontrol,  Up: Control Theory
  531.  
  532. System Data Structure
  533. =====================
  534.  
  535. * Menu:
  536.  
  537. * Demo program:sysrepdemo.
  538. * Variables common to all OCST system formats:sysstructvars.
  539. * tf format variables:sysstructtf.
  540. * zp format variables:sysstructzp.
  541. * ss format variables:sysstructss.
  542.    The OCST stores all dynamic systems in a single data structure
  543. format that can represent continuous systems, discrete-systems, and
  544. mixed (hybrid) systems in state-space form, and can also represent
  545. purely continuous/discrete systems in either transfer function or
  546. pole-zero form. In order to provide more flexibility in treatment of
  547. discrete/hybrid systems, the OCST also keeps a record of which system
  548. outputs are sampled.
  549.  
  550.    Octave structures are accessed with a syntax much like that used by
  551. the C programming language.  For consistency in use of the data
  552. structure used in the OCST, it is recommended that the system structure
  553. access m-files be used (*Note sysinterface::).  Some elements of the
  554. data structure are absent depending on the internal system
  555. representation(s) used.  More than one system representation can be
  556. used for SISO systems; the OCST m-files ensure that all representations
  557. used are consistent with one another.
  558.  
  559. 
  560. File: octave,  Node: sysrepdemo,  Next: sysstructvars,  Prev: sysstruct,  Up: sysstruct
  561.  
  562. System representation demo program
  563. ==================================
  564.  
  565.  - Function File :  sysrepdemo
  566.      Tutorial for the use of the system data structure functions.
  567.  
  568. 
  569. File: octave,  Node: sysstructvars,  Next: sysstructtf,  Prev: sysrepdemo,  Up: sysstruct
  570.  
  571. Variables common to all OCST system formats
  572. -------------------------------------------
  573.  
  574.    The data structure elements (and variable types) common to all
  575. system representations are listed below; examples of the initialization
  576. and use of the system data structures are given in subsequent sections
  577. and in the online demo `DEMOcontrol'.
  578. N,NZ
  579.      The respective number of continuous and discrete states in the
  580.      system (scalar)
  581.  
  582. INNAME, OUTNAME
  583.      list of name(s) of the system input, output signal(s). (list of
  584.      strings)
  585.  
  586. SYS
  587.      System status vector.  (vector)
  588.  
  589.      This vector indicates both what      representation was used to
  590.      initialize the  system data structure      (called the primary
  591.      system type) and which other representations      are currently
  592.      up-to-date with the primary system type (*Note sysupdate::).
  593.  
  594.     SYS(0)
  595.           primary system type
  596.  
  597.           =0 for tf form (initialized with `tf2sys' or `fir2sys')
  598.  
  599.           =1 for zp form (initialized with `zp2sys')
  600.  
  601.           =2 for ss form (initialized with `ss2sys')
  602.  
  603.     SYS(1:3)
  604.           boolean flags to indicate whether tf, zp, or ss, respectively,
  605.                  are "up to date" (whether it is safe to use the
  606.           variables           associated with these representations).
  607.           These flags are changed when calls are made to the
  608.           `sysupdate' command.
  609.  
  610. TSAM
  611.      Discrete time sampling period  (nonnegative scalar).   TSAM is set
  612.      to 0 for continuous time systems.
  613.  
  614. YD
  615.      Discrete-time output list (vector)
  616.  
  617.      indicates which outputs are discrete time (i.e.,     produced by
  618.      D/A converters) and which are continuous time.      yd(ii) = 0 if
  619.      output ii is continuous, = 1 if discrete.
  620.  
  621.    The remaining variables of the  system data structure are only
  622. present if the corresponding entry of the `sys' vector is true (=1).
  623.  
  624. 
  625. File: octave,  Node: sysstructtf,  Next: sysstructzp,  Prev: sysstructvars,  Up: sysstruct
  626.  
  627. `tf' format variables
  628. ---------------------
  629.  
  630. NUM
  631.      numerator coefficients   (vector)
  632.  
  633. DEN
  634.      denominator coefficients   (vector)
  635.  
  636. 
  637. File: octave,  Node: sysstructzp,  Next: sysstructss,  Prev: sysstructtf,  Up: sysstruct
  638.  
  639. `zp' format variables
  640. ---------------------
  641.  
  642. ZER
  643.      system zeros   (vector)
  644.  
  645. POL
  646.      system poles    (vector)
  647.  
  648. K
  649.      leading coefficient   (scalar)
  650.  
  651. 
  652. File: octave,  Node: sysstructss,  Prev: sysstructzp,  Up: sysstruct
  653.  
  654. `ss' format variables
  655. ---------------------
  656.  
  657. A,B,C,D
  658.      The usual state-space matrices. If a system has both
  659.      continuous and discrete states, they are sorted so that
  660.      continuous states come first, then discrete states
  661.  
  662.      *Note* some functions (e.g., `bode', `hinfsyn') will not accept
  663.      systems with both discrete and continuous states/outputs
  664.  
  665. STNAME
  666.      names of system states   (list of strings)
  667.  
  668. 
  669. File: octave,  Node: sysinterface,  Next: sysdisp,  Prev: sysstruct,  Up: Control Theory
  670.  
  671. System Construction and Interface Functions
  672. ===========================================
  673.  
  674.    Construction and manipulations of the OCST system data structure
  675. (*Note sysstruct::) requires attention to many details in order to
  676. ensure that data structure contents remain consistent.  Users are
  677. strongly encouraged to use the system interface functions in this
  678. section.  Functions for the formatted display in of system data
  679. structures are given in *Note sysdisp::.
  680.  
  681. * Menu:
  682.  
  683. * Finite impulse response system interface functions:fir2sys.
  684. * sys2fir::
  685. * State space system interface functions:ss2sys.
  686. * sys2ss::
  687. * Transfer function system interface functions:tf2sys.
  688. * sys2tf::
  689. * Zero-pole system interface functions:zp2sys.
  690. * sys2zp::
  691. * Data structure access functions:structaccess.
  692. * Data structure internal functions:structintern
  693.  
  694. 
  695. File: octave,  Node: fir2sys,  Next: sys2fir,  Prev: sysinterface,  Up: sysinterface
  696.  
  697. Finite impulse response system interface functions
  698. --------------------------------------------------
  699.  
  700.  - Function File :  SYS = fir2sys ( NUM{, TSAM, INNAME, OUTNAME } )
  701.      construct a system data structure from FIR description
  702.  
  703.      *Inputs:*
  704.     NUM
  705.           vector of coefficients `[c_0 c_1 ... c_n]' of the SISO FIR
  706.           transfer function
  707.  
  708.           C(z) = c0 + c1*z^{-1} + c2*z^{-2} + ... + znz^{-n}
  709.  
  710.     TSAM
  711.           sampling time (default: 1)
  712.  
  713.     INNAME
  714.           name of input signal;  may be a string or a list with a
  715.           single entry.
  716.  
  717.     OUTNAME
  718.           name of output signal; may be a string or a list with a
  719.           single entry.
  720.  
  721.      *Outputs*   SYS (system data structure)
  722.  
  723.      *Example*
  724.           octave:1> sys = fir2sys([1 -1 2 4],0.342,"A/D input","filter output");
  725.           octave:2> sysout(sys)
  726.           Input(s)
  727.                   1: A/D input
  728.           
  729.           Output(s):
  730.                   1: filter output (discrete)
  731.           
  732.           Sampling interval: 0.342
  733.           transfer function form:
  734.           1*z^3 - 1*z^2 + 2*z^1 + 4
  735.           -------------------------
  736.           1*z^3 + 0*z^2 + 0*z^1 + 0
  737.  
  738. 
  739. File: octave,  Node: sys2fir,  Next: ss2sys,  Prev: fir2sys,  Up: sysinterface
  740.  
  741.  - Function File : [C, TSAM, INPUT, OUTPUT] = sys2fir (SYS)
  742.      Extract FIR data from system data structure; see *Note fir2sys::
  743.      for parameter descriptions.
  744.  
  745.  
  746. 
  747. File: octave,  Node: ss2sys,  Next: sys2ss,  Prev: sys2fir,  Up: sysinterface
  748.  
  749. State space system interface functions
  750. --------------------------------------
  751.  
  752.  - Function File :  SYS = ss2sys (A,B,C{,D, TSAM, N, NZ, STNAME,
  753.           INNAME, OUTNAME, OUTLIST})
  754.      Create system structure from state-space data.   May be continous,
  755.      discrete, or mixed (sampeld-data)
  756.  
  757.      *Inputs*
  758.     A, B, C, D
  759.           usual state space matrices.
  760.  
  761.           default: D = zero matrix
  762.  
  763.     TSAM
  764.           sampling rate.  Default: `tsam = 0' (continuous system)
  765.  
  766.     N, NZ
  767.           number of continuous, discrete states in the system
  768.  
  769.           default:
  770.          TSAM = 0
  771.                `n = `rows'(A)', `nz = 0'
  772.  
  773.          TSAM > 0
  774.                ` n = 0',       `nz = `rows'(A)'
  775.  
  776.                see below for system partitioning
  777.  
  778.     STNAME
  779.           list of strings of state signal names
  780.  
  781.           default (STNAME=[] on input): `x_n' for continuous states,
  782.                           `xd_n' for discrete states
  783.  
  784.     INNAME
  785.           list of strings of input signal names
  786.  
  787.           default (INNAME = [] on input): `u_n'
  788.  
  789.     OUTNAME
  790.           list of strings of input signal names
  791.  
  792.           default (OUTNAME = [] on input): `y_n'
  793.  
  794.     OUTLIST
  795.           list of indices of outputs y that are sampled
  796.  
  797.           default:
  798.          TSAM = 0
  799.                `outlist = []'
  800.  
  801.          TSAM > 0
  802.                `outlist = 1:`rows'(C)'
  803.  
  804.           Unlike states, discrete/continous outputs may appear in any
  805.           order.
  806.  
  807.           *Note* `sys2ss' returns a vector YD where YD(OUTLIST) = 1;
  808.           all other entries of YD are 0.
  809.  
  810.      *Outputs* OUTSYS = system data structure
  811.  
  812.      *System partitioning*
  813.  
  814.      Suppose for simplicity that outlist specified   that the first
  815.      several outputs were continuous and the remaining outputs   were
  816.      discrete.  Then the system is partitioned as
  817.           x = [ xc ]  (n x 1)
  818.               [ xd ]  (nz x 1 discrete states)
  819.           a = [ acc acd ]  b = [ bc ]
  820.               [ adc add ]      [ bd ]
  821.           c = [ ccc ccd ]  d = [ dc ]
  822.               [ cdc cdd ]      [ dd ]
  823.           
  824.               (cdc = c(outlist,1:n), etc.)
  825.      with dynamic equations: `  d/dt xc(t)     = acc*xc(t)      +
  826.      acd*xd(k*tsam) + bc*u(t)'
  827.  
  828.      `  xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)'
  829.  
  830.      `  yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)'
  831.  
  832.      `  yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)'
  833.  
  834.      *Signal partitions*
  835.                   | continuous      | discrete               |
  836.           ----------------------------------------------------
  837.           states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
  838.           ----------------------------------------------------
  839.           outputs | outname(cout,:) | outname(outlist,:)     |
  840.           ----------------------------------------------------
  841.      where `cout' is the list of in 1:`rows'(P) that are not
  842.      contained in outlist. (Discrete/continuous outputs may be entered
  843.      in any order desired by the user.)
  844.  
  845.      *Example*
  846.           octave:1> a = [1 2 3; 4 5 6; 7 8 10];
  847.           octave:2> b = [0 0 ; 0 1 ; 1 0];
  848.           octave:3> c = eye(3);
  849.           octave:4> sys = ss2sys(a,b,c,[],0,3,0,list("volts","amps","joules"));
  850.           octave:5> sysout(sys);
  851.           Input(s)
  852.                   1: u_1
  853.                   2: u_2
  854.           
  855.           Output(s):
  856.                   1: y_1
  857.                   2: y_2
  858.                   3: y_3
  859.           
  860.           state-space form:
  861.           3 continuous states, 0 discrete states
  862.           State(s):
  863.                   1: volts
  864.                   2: amps
  865.                   3: joules
  866.           
  867.           A matrix: 3 x 3
  868.              1   2   3
  869.              4   5   6
  870.              7   8  10
  871.           B matrix: 3 x 2
  872.             0  0
  873.             0  1
  874.             1  0
  875.           C matrix: 3 x 3
  876.             1  0  0
  877.             0  1  0
  878.             0  0  1
  879.           D matrix: 3 x 3
  880.             0  0
  881.             0  0
  882.             0  0
  883.      Notice that the D matrix is constructed  by default to the correct
  884.      dimensions.  Default input and output signals names were assigned
  885.      since none were given.
  886.  
  887.  
  888. 
  889. File: octave,  Node: sys2ss,  Next: tf2sys,  Prev: ss2sys,  Up: sysinterface
  890.  
  891.  - Function File : [A,B,C,D,TSAM,N,NZ,STNAME,INNAME,OUTNAME,YD] =
  892.           sys2ss (SYS)
  893.      Extract state space representation from system data structure.
  894.  
  895.      *Inputs* SYS system data structure (*Note sysstruct::)
  896.  
  897.      *Outputs*
  898.     A,B,C,D
  899.           state space matrices for sys
  900.  
  901.     TSAM
  902.           sampling time of sys (0 if continuous)
  903.  
  904.     N, NZ
  905.           number of continuous, discrete states (discrete states come
  906.                  last in state vector X)
  907.  
  908.     STNAME, INNAME, OUTNAME
  909.           signal names (lists of strings);  names of states,
  910.           inputs, and outputs, respectively
  911.  
  912.     YD
  913.           binary vector; YD(II) is 1 if output Y(II)$  is discrete
  914.           (sampled); otherwise  YD(II) 0.
  915.  
  916.      *Example*
  917.           octave:1> sys=tf2sys([1 2],[3 4 5]);
  918.           octave:2> [a,b,c,d] = sys2ss(sys)
  919.           a =
  920.              0.00000   1.00000
  921.             -1.66667  -1.33333
  922.           b =
  923.             0
  924.             1
  925.           c = 0.66667  0.33333
  926.           d = 0
  927.  
  928. 
  929. File: octave,  Node: tf2sys,  Next: sys2tf,  Prev: sys2ss,  Up: sysinterface
  930.  
  931. Transfer function system interface functions
  932. --------------------------------------------
  933.  
  934.  - Function File :  SYS =  tf2sys( NUM, DEN {, TSAM, INNAME, OUTNAME })
  935.      build system data structure from transfer function format data
  936.  
  937.      *Inputs*
  938.     NUM, DEN
  939.           coefficients of numerator/denominator polynomials
  940.  
  941.     TSAM
  942.           sampling interval. default: 0 (continuous time)
  943.  
  944.     INNAME, OUTNAME
  945.           input/output signal names; may be a string or list with a
  946.           single string entry.
  947.  
  948.      *Outputs*  SYS = system data structure
  949.  
  950.      *Example*
  951.           octave:1> sys=tf2sys([2 1],[1 2 1],0.1);
  952.           octave:2> sysout(sys)
  953.           Input(s)
  954.                   1: u_1
  955.           Output(s):
  956.                   1: y_1 (discrete)
  957.           Sampling interval: 0.1
  958.           transfer function form:
  959.           2*z^1 + 1
  960.           -----------------
  961.           1*z^2 + 2*z^1 + 1
  962.  
  963. 
  964. File: octave,  Node: sys2tf,  Next: zp2sys,  Prev: tf2sys,  Up: sysinterface
  965.  
  966.  - Function File : [NUM,DEN,TSAM,INNAME,OUTNAME] = sys2tf (SYS)
  967.      Extract transfer function data from a system data structure
  968.  
  969.      See *Note tf2sys:: for parameter descriptions.
  970.  
  971.      *Example*
  972.           octave:1> sys=ss2sys([1 -2; -1.1,-2.1],[0;1],[1 1]);
  973.           octave:2> [num,den] = sys2tf(sys)
  974.           num = 1.0000  -3.0000
  975.           den = 1.0000   1.1000  -4.3000
  976.  
  977. 
  978. File: octave,  Node: zp2sys,  Next: sys2zp,  Prev: sys2tf,  Up: sysinterface
  979.  
  980. Zero-pole system interface functions
  981. ------------------------------------
  982.  
  983.  - Function File :  SYS = zp2sys (ZER,POL,K{,TSAM,INNAME,OUTNAME})
  984.      Create system data structure from zero-pole data
  985.  
  986.      *Inputs*
  987.     ZER
  988.           vector of system zeros
  989.  
  990.     POL
  991.           vector of system poles
  992.  
  993.     K
  994.           scalar leading coefficient
  995.  
  996.     TSAM
  997.           sampling period. default: 0 (continuous system)
  998.  
  999.     INNAME, OUTNAME
  1000.           input/output signal names (lists of strings)
  1001.  
  1002.      *Outputs*  sys: system data structure
  1003.  
  1004.      *Example*
  1005.           octave:1> sys=zp2sys([1 -1],[-2 -2 0],1);
  1006.           octave:2> sysout(sys)
  1007.           Input(s)
  1008.                   1: u_1
  1009.           Output(s):
  1010.                   1: y_1
  1011.           zero-pole form:
  1012.           1 (s - 1) (s + 1)
  1013.           -----------------
  1014.           s (s + 2) (s + 2)
  1015.  
  1016. 
  1017. File: octave,  Node: sys2zp,  Next: structaccess,  Prev: zp2sys,  Up: sysinterface
  1018.  
  1019.  - Function File : [ZER, POL, K, TSAM, INNAME, OUTNAME] = sys2zp (SYS)
  1020.      Extract zero/pole/leading coefficient information from a system
  1021.      data structure
  1022.  
  1023.      See *Note zp2sys:: for parameter descriptions.
  1024.  
  1025.      *Example*
  1026.           octave:1> sys=ss2sys([1 -2; -1.1,-2.1],[0;1],[1 1]);
  1027.           octave:2> [zer,pol,k] = sys2zp(sys)
  1028.           zer = 3.0000
  1029.           pol =
  1030.             -2.6953
  1031.              1.5953
  1032.           k = 1
  1033.  
  1034. 
  1035. File: octave,  Node: structaccess,  Next: structintern,  Prev: sys2zp,  Up: sysinterface
  1036.  
  1037. Data structure access functions
  1038. -------------------------------
  1039.  
  1040. * Menu:
  1041.  
  1042. * syschnames::
  1043. * syschtsam::
  1044. * sysdimensions::
  1045. * sysgetsignals::
  1046. * sysgettsam::
  1047. * sysgettype::
  1048. * syssetsignals::
  1049. * sysupdate::
  1050.  
  1051. 
  1052. File: octave,  Node: syschnames,  Next: syschtsam,  Prev: structaccess,  Up: structaccess
  1053.  
  1054.  - Function File : RETSYS = syschnames (SYS, OPT, LIST, NAMES)
  1055.      Superseded by `syssetsignals'
  1056.  
  1057.  
  1058. 
  1059. File: octave,  Node: syschtsam,  Next: sysdimensions,  Prev: syschnames,  Up: structaccess
  1060.  
  1061.  - Function File :  retsys = syschtsam ( sys,tsam )
  1062.      This function changes the sampling time (tsam) of the system.
  1063.      Exits with an error if sys is purely continuous time.
  1064.  
  1065. 
  1066. File: octave,  Node: sysdimensions,  Next: sysgetsignals,  Prev: syschtsam,  Up: structaccess
  1067.  
  1068.  - Function File :  [N, NZ, M, P,YD] = sysdimensions (SYS{, OPT})
  1069.      return the number of states, inputs, and/or outputs in the system
  1070.      SYS.
  1071.  
  1072.      *Inputs*
  1073.     SYS
  1074.           system data structure
  1075.  
  1076.     OPT
  1077.           String indicating which dimensions are desired.  Values:
  1078.          `"all"'
  1079.                (default) return all parameters as specified under
  1080.                Outputs below.
  1081.  
  1082.          `"cst"'
  1083.                return N= number of continuous states
  1084.  
  1085.          `"dst"'
  1086.                return N= number of discrete states
  1087.  
  1088.          `"in"'
  1089.                return N= number of inputs
  1090.  
  1091.          `"out"'
  1092.                return N= number of outputs
  1093.  
  1094.      *Outputs*
  1095.     N
  1096.           number of continuous states (or individual requested
  1097.           dimension as specified by OPT).
  1098.  
  1099.     NZ
  1100.           number of discrete states
  1101.  
  1102.     M
  1103.           number of system inputs
  1104.  
  1105.     P
  1106.           number of system outputs
  1107.  
  1108.     YD
  1109.           binary vector; YD(II) is nonzero if output II is discrete.
  1110.           `yd(ii) = 0' if output II is continous
  1111.  
  1112.  
  1113. 
  1114. File: octave,  Node: sysgetsignals,  Next: sysgettsam,  Prev: sysdimensions,  Up: structaccess
  1115.  
  1116.  - Function File : [STNAME, INNAME, OUTNAME, YD] = sysgetsignals (SYS)
  1117.  - Function File :  SIGLIST = sysgetsignals (SYS,SIGID)
  1118.  - Function File :  SIGNAME = sysgetsignals (SYS,SIGID,SIGNUM{, STRFLG})
  1119.      Get signal names from a system
  1120.  
  1121.      *Inputs*
  1122.     SYS
  1123.           system data structure for the state space system
  1124.  
  1125.     SIGID
  1126.           signal id.  String.  Must be one of
  1127.          `"in"'
  1128.                input signals
  1129.  
  1130.          `"out"'
  1131.                output signals
  1132.  
  1133.          `"st"'
  1134.                stage signals
  1135.  
  1136.          `"yd"'
  1137.                value of logical vector YD
  1138.  
  1139.     SIGNUM
  1140.           Index of signal (or indices of signals if signum is a vector)
  1141.  
  1142.     STRFLG
  1143.           flag to return a string instead of a list;  Values:
  1144.          `0'
  1145.                (default) return a list (even if signum is a scalar)
  1146.  
  1147.          `1'
  1148.                return a string.  Exits with an error if signum is not a
  1149.                scalar.
  1150.  
  1151.      *Outputs*
  1152.     *If SIGID is not specified
  1153.          STNAME, INNAME, OUTNAME
  1154.                signal names (lists of strings);  names of states,
  1155.                   inputs, and outputs, respectively
  1156.  
  1157.          YD
  1158.                binary vector; YD(II) is nonzero if output II is
  1159.                discrete.
  1160.  
  1161.     *If SIGID is specified but SIGNUM is not specified, then
  1162.          `sigid="in"'
  1163.                SIGLIST is set to the list of input names
  1164.  
  1165.          `sigid="out"'
  1166.                SIGLIST is set to the list of output names
  1167.  
  1168.          `sigid="st"'
  1169.                SIGLIST is set to the list of state names
  1170.  
  1171.                stage signals
  1172.  
  1173.          `sigid="yd"'
  1174.                SIGLIST is set to logical vector indicating discrete
  1175.                outputs; SIGLIST(II) = 0 indicates that output II is
  1176.                continuous (unsampled), otherwise it is discrete.
  1177.  
  1178.     *if the first three input arguments are specified, then SIGNAME is
  1179.           a list of the specified signal names (SIGID is `"in"',
  1180.           `"out"', or `"st"'), or else the logical flag indicating
  1181.           whether output(s) SIGNUM is(are) discrete (SIGVAL=1) or
  1182.           continuous (SIGVAL=0).
  1183.  
  1184.      *Examples* (From `sysrepdemo')
  1185.           octave> sys=ss2sys(rand(4),rand(4,2),rand(3,4));
  1186.           octave> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys) i  # get all signal names
  1187.           Ast =
  1188.           (
  1189.             [1] = x_1
  1190.             [2] = x_2
  1191.             [3] = x_3
  1192.             [4] = x_4
  1193.           )
  1194.           Ain =
  1195.           (
  1196.             [1] = u_1
  1197.             [2] = u_2
  1198.           )
  1199.           Aout =
  1200.           (
  1201.             [1] = y_1
  1202.             [2] = y_2
  1203.             [3] = y_3
  1204.           )
  1205.           Ayd =
  1206.           
  1207.             0  0  0
  1208.           octave> Ain = sysgetsignals(sys,"in")   # get only input signal names
  1209.           Ain =
  1210.           (
  1211.             [1] = u_1
  1212.             [2] = u_2
  1213.           )
  1214.           octave> Aout = sysgetsignals(sys,"out",2)   # get name of output 2 (in list)
  1215.           Aout =
  1216.           (
  1217.             [1] = y_2
  1218.           )
  1219.           octave> Aout = sysgetsignals(sys,"out",2,1)  # get name of output 2 (as string)
  1220.           Aout = y_2
  1221.  
  1222.  
  1223. 
  1224. File: octave,  Node: sysgettsam,  Next: sysgettype,  Prev: sysgetsignals,  Up: structaccess
  1225.  
  1226.  - Function File :  Tsam = sysgettsam ( sys )
  1227.      return the sampling time of the system
  1228.  
  1229. 
  1230. File: octave,  Node: sysgettype,  Next: syssetsignals,  Prev: sysgettsam,  Up: structaccess
  1231.  
  1232.  - Function File :  SYSTYPE = sysgettype ( SYS )
  1233.      return the initial system type of the system
  1234.  
  1235.      *Inputs*    SYS: system data structure
  1236.  
  1237.      *Outputs*    SYSTYPE: string indicating how the structure was
  1238.      initially             constructed:       values: `"ss"', `"zp"',
  1239.      or `"tf"'
  1240.  
  1241.      *Note* FIR initialized systems return `systype="tf"'.
  1242.  
  1243.  
  1244. 
  1245. File: octave,  Node: syssetsignals,  Next: sysupdate,  Prev: sysgettype,  Up: structaccess
  1246.  
  1247.  - Function File : RETSYS = syssetsignals (SYS, OPT, NAMES{, SIG_IDX})
  1248.      change the names of selected inputs, outputs and states.  *Inputs*
  1249.     SYS
  1250.           system data structure
  1251.  
  1252.     OPT
  1253.           change default name (output)
  1254.  
  1255.          `"out"'
  1256.                change selected output names
  1257.  
  1258.          `"in"'
  1259.                change selected input names
  1260.  
  1261.          `"st"'
  1262.                change selected state names
  1263.  
  1264.          `"yd"'
  1265.                change selected outputs from discrete to continuous or
  1266.                                from continuous to discrete.
  1267.  
  1268.     NAMES
  1269.          `opt = "out", "in", or "st"'
  1270.                string or string array containing desired signal names
  1271.                or values.
  1272.  
  1273.          `opt = "yd"'
  1274.                To desired output continuous/discrete flag.  Set name to
  1275.                0 for continuous, or 1 for discrete.
  1276.  
  1277.     LIST
  1278.           vector of indices of outputs, yd, inputs, or
  1279.           states whose respective names should be changed.
  1280.  
  1281.           Default: replace entire list of names/entire yd vector.
  1282.      *Outputs*     RETSYS=SYS with appropriate signal names changed
  1283.             (or yd values, where appropriate)
  1284.  
  1285.      *Example*
  1286.           octave:1> sys=ss2sys([1 2; 3 4],[5;6],[7 8]);
  1287.           octave:2> sys = syssetsignals(sys,"st",str2mat("Posx","Velx"));
  1288.           octave:3> sysout(sys)
  1289.           Input(s)
  1290.                   1: u_1
  1291.           Output(s):
  1292.                   1: y_1
  1293.           state-space form:
  1294.           2 continuous states, 0 discrete states
  1295.           State(s):
  1296.                   1: Posx
  1297.                   2: Velx
  1298.           A matrix: 2 x 2
  1299.             1  2
  1300.             3  4
  1301.           B matrix: 2 x 1
  1302.             5
  1303.             6
  1304.           C matrix: 1 x 2
  1305.             7  8
  1306.           D matrix: 1 x 1
  1307.           0
  1308.  
  1309.  
  1310. 
  1311. File: octave,  Node: sysupdate,  Prev: syssetsignals,  Up: structaccess
  1312.  
  1313.  - Function File :  SYS = sysupdate ( SYS, OPT )
  1314.      Update the internal representation of a system.
  1315.  
  1316.      *Inputs*
  1317.     SYS:
  1318.           system data structure
  1319.  
  1320.     OPT
  1321.           string:
  1322.          `"tf"'
  1323.                update transfer function form
  1324.  
  1325.          `"zp"'
  1326.                update zero-pole form
  1327.  
  1328.          `"ss"'
  1329.                update state space form
  1330.  
  1331.          `"all"'
  1332.                all of the above
  1333.  
  1334.      *Outputs* RETSYS: contains union of data in sys and requested data.
  1335.      If requested data in sys is already up to date then retsys=sys.
  1336.  
  1337.      Conversion to `tf' or `zp' exits with an error if the system is
  1338.      mixed continuous/digital.
  1339.  
  1340. 
  1341. File: octave,  Node: structintern,  Prev: structaccess,  Up: sysinterface
  1342.  
  1343. Data structure internal functions
  1344. ---------------------------------
  1345.  
  1346.  - Function File :   syschnamesl
  1347.      used internally in syschnames
  1348.  
  1349.  - Function File :  IONAME = sysdefioname (N,STR {,M})
  1350.      return default input or output names given N, STR, M.   N is the
  1351.      final value, STR is the string prefix, and M is start value
  1352.  
  1353.      used internally, minimal argument checking
  1354.  
  1355.      *Example* `ioname = sysdefioname(5,"u",3)' returns the list:
  1356.           ioname =
  1357.           (
  1358.             [1] = u_3
  1359.             [2] = u_4
  1360.             [3] = u_5
  1361.           )
  1362.  
  1363.  - Function File :  STNAME = sysdefstname (N, NZ)
  1364.      return default state names given N, NZ
  1365.  
  1366.      used internally, minimal argument checking
  1367.  
  1368.  - Function File :  VEC =  tf2sysl (VEC)
  1369.      used internally in *Note tf2sys::.   strip leading zero
  1370.      coefficients to get the true polynomial length
  1371.  
  1372. 
  1373. File: octave,  Node: sysdisp,  Next: blockdiag,  Prev: sysinterface,  Up: Control Theory
  1374.  
  1375. System display functions
  1376. ========================
  1377.  
  1378.  - Function File :   sysout ( SYS{, OPT})
  1379.      print out a system data structure in desired format
  1380.     SYS
  1381.           system data structure
  1382.  
  1383.     OPT
  1384.           Display option
  1385.          `[]'
  1386.                primary system form (default); see *Note sysgettype::.
  1387.  
  1388.          `"ss"'
  1389.                state space form
  1390.  
  1391.          `"tf"'
  1392.                transfer function form
  1393.  
  1394.          `"zp"'
  1395.                zero-pole form
  1396.  
  1397.          `"all"'
  1398.                all of the above
  1399.  
  1400.  - Function File :  Y = polyout ( C{, X})
  1401.      write formatted polynomial
  1402.              c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
  1403.       to string Y or to the screen (if Y is omitted)  X defaults to the
  1404.      string `"s"'
  1405.  
  1406.  - Function File :   tfout (NUM, DENOM{, X})
  1407.      print formatted transfer function `n(s)/d(s) ' to the screen  X
  1408.      defaults to the string `"s"'
  1409.  
  1410.  - Function File :   zpout (ZER, POL, K{, X})
  1411.      print formatted zero-pole form to the screen.  X defaults to the
  1412.      string `"s"'
  1413.  
  1414.  - Function File :   outlist (LMAT{, TABCHAR, YD, ILIST })
  1415.      Prints an enumerated list of strings.   internal use only; minimal
  1416.      argument checking performed
  1417.  
  1418.      *Inputs*
  1419.     LMAT
  1420.           list of strings
  1421.  
  1422.     TABCHAR
  1423.           tab character (default: none)
  1424.  
  1425.     YD
  1426.           indices of strings to append with the string "(discrete)"
  1427.                 (used by SYSOUT; minimal checking of this argument)
  1428.                  `yd = [] ' indicates all outputs are continuous
  1429.  
  1430.     ILIST
  1431.           index numbers to print with names.
  1432.  
  1433.           default: `1:rows(lmat)'
  1434.  
  1435.      *Outputs*    prints the list to the screen, numbering each string
  1436.      in order.
  1437.  
  1438.  
  1439. 
  1440. File: octave,  Node: blockdiag,  Next: numerical,  Prev: sysdisp,  Up: Control Theory
  1441.  
  1442. Block Diagram Manipulations
  1443. ===========================
  1444.  
  1445.    *Note systime::
  1446.  
  1447.    Unless otherwise noted, all parameters (input,output) are system
  1448. data structures.
  1449.  
  1450. * Menu:
  1451.  
  1452. * buildssic::
  1453. * jet707::
  1454. * ord2::
  1455. * parallel::
  1456. * sysadd::
  1457. * sysappend::
  1458. * sysconnect::
  1459. * syscont::
  1460. * syscont_disc::
  1461. * sysdisc::
  1462. * sysdup::
  1463. * sysgroup::
  1464. * sysgroupn::
  1465. * sysmult::
  1466. * sysprune::
  1467. * sysreorder::
  1468. * sysscale::
  1469. * syssub::
  1470.  
  1471.  - Function File :  outputs = bddemo ( inputs )
  1472.      Octave Controls toolbox demo: Block Diagram Manipulations demo
  1473.  
  1474. 
  1475. File: octave,  Node: buildssic,  Next: jet707,  Prev: blockdiag,  Up: blockdiag
  1476.  
  1477.  - Function File : [SYS] = buildssic(CLST, ULST, OLST, ILST, S1, S2,
  1478.           S3, S4, S5, S6, S7, S8)
  1479.      Contributed by Kai Mueller.
  1480.  
  1481.      Form an arbitrary complex (open or closed loop) system in
  1482.      state-space form from several systems. "`buildssic'" can  easily
  1483.      (despite it's cryptic syntax) integrate transfer functions  from a
  1484.      complex block diagram into a single system with one call.   This
  1485.      function is especially useful for building open loop
  1486.      interconnections for H_infinity and H2 designs or for closing
  1487.      loops with these controllers.
  1488.  
  1489.      Although this function is general purpose, the use of "`sysgroup'"
  1490.      "`sysmult'", "`sysconnect'" and the like is recommended for
  1491.      standard  operations since they can handle mixed discrete and
  1492.      continuous  systems and also the names of inputs, outputs, and
  1493.      states.
  1494.  
  1495.      The parameters consist of 4 lists that describe the connections
  1496.      outputs and inputs and up to 8 systems s1-s8.   Format of the
  1497.      lists:
  1498.     CLST
  1499.           connection list, describes the input signal of each system.
  1500.           The maximum number of rows of Clst is equal to the sum of all
  1501.           inputs of s1-s8.
  1502.  
  1503.           Example: `[1 2 -1; 2 1 0]' ==> new input 1 is old inpout 1 +
  1504.           output 2 - output 1, new input 2 is old input 2 + output 1.
  1505.           The order of rows is arbitrary.
  1506.  
  1507.     ULST
  1508.           if not empty the old inputs in vector Ulst will            be
  1509.           appended to the outputs. You need this if you            want
  1510.           to "pull out" the input of a system. Elements            are
  1511.           input numbers of s1-s8.
  1512.  
  1513.     OLST
  1514.           output list, specifiy the outputs of the resulting
  1515.           systems. Elements are output numbers of s1-s8.
  1516.           The numbers are alowed to be negative and may
  1517.           appear in any order. An empty matrix means            all
  1518.           outputs.
  1519.  
  1520.     ILST
  1521.           input list, specifiy the inputs of the resulting
  1522.           systems. Elements are input numbers of s1-s8.             The
  1523.           numbers are alowed to be negative and may            appear
  1524.           in any order. An empty matrix means            all inputs.
  1525.  
  1526.      Example:  Very simple closed loop system.
  1527.           w        e  +-----+   u  +-----+
  1528.            --->o--*-->|  K  |--*-->|  G  |--*---> y
  1529.                ^  |   +-----+  |   +-----+  |
  1530.              - |  |            |            |
  1531.                |  |            +----------------> u
  1532.                |  |                         |
  1533.                |  +-------------------------|---> e
  1534.                |                            |
  1535.                +----------------------------+
  1536.  
  1537.      The closed loop system GW can be optained by
  1538.           GW = buildssic([1 2; 2 -1], [2], [1 2 3], [2], G, K);
  1539.  
  1540.     CLST
  1541.           (1. row) connect input 1 (G) with output 2 (K).  (2. row)
  1542.           connect input 2 (K) with neg. output 1 (G).
  1543.  
  1544.     ULST
  1545.           append input of (2) K to the number of outputs.
  1546.  
  1547.     OLST
  1548.           Outputs are output of 1 (G), 2 (K) and appended output 3
  1549.           (from Ulst).
  1550.  
  1551.     ILST
  1552.           the only input is 2 (K).
  1553.  
  1554.      Here is a real example:
  1555.                                    +----+
  1556.               -------------------->| W1 |---> v1
  1557.           z   |                    +----+
  1558.           ----|-------------+                   || GW   ||     => min.
  1559.               |             |                        vz   infty
  1560.               |    +---+    v      +----+
  1561.               *--->| G |--->O--*-->| W2 |---> v2
  1562.               |    +---+       |   +----+
  1563.               |                |
  1564.               |                v
  1565.              u                  y
  1566.  
  1567.      The closed loop system GW from [z; u]' to [v1; v2; y]' can be
  1568.      obtained by (all SISO systems):
  1569.           GW = buildssic([1 4;2 4;3 1],[3],[2 3 5],[3 4],G,W1,W2,One);
  1570.      where "One" is a unity gain (auxillary) function with order 0.
  1571.      (e.g. `One = ugain(1);')
  1572.  
  1573. 
  1574. File: octave,  Node: jet707,  Next: ord2,  Prev: buildssic,  Up: blockdiag
  1575.  
  1576.  - Function File :  OUTSYS  = jet707 ( )
  1577.      Creates linearized state space model of a Boeing 707-321 aircraft
  1578.      at v=80m/s. (M = 0.26, Ga0 = -3 deg, alpha0 = 4 deg, kappa = 50
  1579.      deg)  System inputs:   (1) thrust   and (2) elevator angle  System
  1580.      outputs:  (1) airspeed and (2) pitch angle  Ref: R. Brockhaus:
  1581.      Flugregelung (Flight Control), Springer, 1994
  1582.  
  1583.      see also: ord2
  1584.  
  1585.      Contributed by Kai Mueller
  1586.  
  1587.