Mercurial > forge

changeset 11193:447c978c7b34 octave-forge

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Misc improvements to the documentation
author mmarzolla
date Tue, 30 Oct 2012 12:13:45 +0000
parents 175994a0a275
children 947f42078624
files main/queueing/ChangeLog main/queueing/NEWS main/queueing/devel/pmva.y main/queueing/doc/INSTALL main/queueing/doc/gettingstarted.txi main/queueing/doc/installation.txi main/queueing/doc/queueing.texi
diffstat 7 files changed, 303 insertions(+), 242 deletions(-) [+]
line wrap: on
line diff
--- a/main/queueing/ChangeLog	Tue Oct 30 01:21:56 2012 +0000
+++ b/main/queueing/ChangeLog	Tue Oct 30 12:13:45 2012 +0000
@@ -1,11 +1,11 @@
 2012-10-XX Moreno Marzolla <marzolla@cs.unibo.it>
 
-	* Version 1.2.0 released
+	* Version 2.0.0 released
 	* Restructured the documentation
 	* Reduced space requirement for qncsmva()
-	* New function naming scheme: qnXYAAA(), where X=c (closed) or o (open) and Y=s (single) or m (multi)
-	* New functions: qncmaba qncmnpop qncsbsb qncsgb qncspb qncmbsb qncmpopmix qncscmva qncsmvablo qnomaba qncmcb qncmva qncsconvld qncsmvald qnosaba qncmmva qncsaba qncsconv qncsmva qnosbsb
-	* Deprecated functions population_mix qnclosedab qnclosedbsb qnclosedgb, qnclosedmultimva qnclosedpb qnclosedsinglemvald qnclosedsinglemva qncmva qnconvolutionld qnconvolution qnjackson qnmvablo qnmvapop qnopenab qnopenbsb
+	* New function naming scheme; old function names are still available for compatibility with existing scripts, but will be removed in the future.
+	* New functions qncmaba, qncmbsb, qncmcb, qnomaba for computing performance bounds on multiclass networks
+	* New function qnom for analyzing open multiclass networks
 	* Fixed bugs in qncsconv, qncsconvld, qncmmva, qnopensingle, qnmix and qncscmva
 
 2012-09-08 Moreno Marzolla <marzolla@cs.unibo.it>
--- a/main/queueing/NEWS	Tue Oct 30 01:21:56 2012 +0000
+++ b/main/queueing/NEWS	Tue Oct 30 12:13:45 2012 +0000
@@ -1,28 +1,24 @@
-Summary of important user-visible changes for queueing-1.2.0
+Summary of important user-visible changes for queueing-2.0.0
 ------------------------------------------------------------------------------
 
-** queueing-1.2.0 includes bug fixes and new features
+** queueing-2.0.0 is a major update which includes bug fixes and new
+   features
 
 ** The documentation has been restructured, hopefully improving
    readability and overall organization
 
-** Asymptotic and balanced system bounds can now be computed also for
+** Asymptotic and balanced system bounds can be computed for
    multiclass networks
 
 ** New function qncmcb for computing Composite Bounds for multiclass
    networks
 
-** New functions qncmaba qncmnpop qncsbsb qncsgb qncspb qncmbsb
-   qncmpopmix qncscmva qncsmvablo qnomaba qncmcb qncmva qncsconvld
-   qncsmvald qnosaba qncmmva qncsaba qncsconv qncsmva qnosbsb
+** Adopted a new scheme for naming functions; old names are still
+   available for compatibility with existing scripts, but will be
+   removed in future releases.
 
-** Deprecated functions population_mix qnclosedab qnclosedbsb
-   qnclosedgb qnclosedmultimva qnclosedpb qnclosedsinglemvald
-   qnclosedsinglemva qncmva qnconvolutionld qnconvolution qnjackson
-   qnmvablo qnmvapop qnopenab qnopenbsb
-
-** Fixed bugs in various functions (qncscmva, qncsconv, qncsconvld,
-   qnopensingle, qnopenmulti and qncmmva)
+** Fixed bugs in qncscmva, qncsconv, qncsconvld, qnopensingle,
+   qnopenmulti and qncmmva
 
 
 Summary of important user-visible changes for queueing-1.1.1
--- a/main/queueing/devel/pmva.y	Tue Oct 30 01:21:56 2012 +0000
+++ b/main/queueing/devel/pmva.y	Tue Oct 30 12:13:45 2012 +0000
@@ -94,7 +94,7 @@
 
 class_list: /* empty */
 | TOK_ID		{ push_class($1); }
-| class_list ',' TOK_ID { push_class($3); }
+| TOK_OD ',' class_list { push_class($1); }
 ;
 
 server_list: /* empty */
--- a/main/queueing/doc/INSTALL	Tue Oct 30 01:21:56 2012 +0000
+++ b/main/queueing/doc/INSTALL	Tue Oct 30 12:13:45 2012 +0000
@@ -8,15 +8,15 @@
      Note: This file (`INSTALL') is automatically generated from
      `doc/installation.txi' in the `queueing' subversion sources.  Do
      not modify this document directly, as changes will be lost. Modify
-     the source `doc/installation.txi' instead.
+     `doc/installation.txi' instead.
 
-1 Installing the queueing toolbox
-*********************************
+1 Installation and Getting Started
+**********************************
 
 1.1 Installation through Octave package management system
 =========================================================
 
-The most recent version of `queueing' is 2.0.0 and can be downloaded
+The most recent version of `queueing' is 1.2.0 and can be downloaded
 from Octave-Forge
 
    `http://octave.sourceforge.net/queueing/'
@@ -48,7 +48,7 @@
      Octave-Forge; then, to install the package in the system-wide
      location issue this command at the Octave prompt:
 
-          octave:1> pkg install _queueing-2.0.0.tar.gz_
+          octave:1> pkg install _queueing-1.2.0.tar.gz_
 
      (you may need to start Octave as root in order to allow the
      installation to copy the files to the target locations). After
@@ -57,7 +57,7 @@
 
      If you do not have root access, you can do a local install using:
 
-          octave:1> pkg install -local queueing-2.0.0.tar.gz
+          octave:1> pkg install -local queueing-1.2.0.tar.gz
 
           Note: Octave version 3.2.3 as shipped with Ubuntu 10.04 LTS
           seems to ignore `-local' and always tries to install the
@@ -70,7 +70,7 @@
           octave:1>pkg list queueing
           Package Name  | Version | Installation directory
           --------------+---------+-----------------------
-              queueing  |   2.0.0 | /home/moreno/octave/queueing-2.0.0
+              queueing  |   1.2.0 | /home/moreno/octave/queueing-1.2.0
 
   4. Starting from version 1.1.1, `queueing' is no longer automatically
      loaded on Octave startup. To make the functions available for use,
@@ -94,8 +94,8 @@
 If you want to manually install `queueing' in a custom location, you
 can download the tarball and unpack it somewhere:
 
-     tar xvfz queueing-2.0.0.tar.gz
-     cd queueing-2.0.0/queueing/
+     tar xvfz queueing-1.2.0.tar.gz
+     cd queueing-1.2.0/queueing/
 
    Copy all `.m' files from the `inst/' directory to some target
 location. Then, start Octave with the `-p' option to add the target
@@ -117,29 +117,3 @@
 search path each time Octave is started, and you no longer need to
 specify the `-p' option on the command line.
 
-1.3 Using the queueing toolbox
-==============================
-
-You can use all functions by simply invoking their name with the
-appropriate parameters; the `queueing' package should display an error
-message in case of missing/wrong parameters. You can display the help
-text for any function using the `help' command. For example:
-
-     octave:2> help qncsmvablo
-
-   prints the documentation for the `qncsmvablo' function.  Additional
-information can be found in the `queueing' manual, which is available
-in PDF format in `doc/queueing.pdf' and in HTML format in
-`doc/queueing.html'.
-
-   Within GNU Octave, you can also run the test and demo blocks
-associated to the functions, using the `test' and `demo' commands
-respectively. To run all the tests of, say, the `qncsmvablo' function:
-
-     octave:3> test qncsmvablo
-     -| PASSES 5 out of 5 tests
-
-   To execute the demos of the `qnclosed' function, use the following:
-
-     octave:4> demo qnclosed
-
--- a/main/queueing/doc/gettingstarted.txi	Tue Oct 30 01:21:56 2012 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,158 +0,0 @@
-@c -*- texinfo -*-
-
-@c Copyright (C) 2012 Moreno Marzolla
-@c
-@c This file is part of the queueing toolbox, a Queueing Networks
-@c analysis package for GNU Octave.
-@c
-@c The queueing toolbox is free software; you can redistribute it
-@c and/or modify it under the terms of the GNU General Public License
-@c as published by the Free Software Foundation; either version 3 of
-@c the License, or (at your option) any later version.
-@c
-@c The queueing toolbox is distributed in the hope that it will be
-@c useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-@c of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-@c GNU General Public License for more details.
-@c
-@c You should have received a copy of the GNU General Public License
-@c along with the queueing toolbox; see the file COPYING.  If not, see
-@c <http://www.gnu.org/licenses/>.
-
-@node Getting Started
-@chapter Getting Started
-
-@menu
-* Naming Conventions::
-* Quickstart Guide::
-@end menu
-
-@node Naming Conventions
-@section Naming Conventions
-
-Most of the functions in the @code{queueing} package obey a common
-naming convention. Function names are made of several parts; the first
-part is a prefix which indicates the class of problems the function
-addresses:
-
-@table @asis
-@item @strong{ctmc-}
-Functions for continuous-time Markov chains
-
-@item @strong{dtmc-}
-Functions for discrete-time Markov chains
-
-@item @strong{qs-}
-Functions for analyzing queueing systems (individual service centers)
-
-@item @strong{qn-}
-Functions for analyzing queueing networks
-
-@end table
-
-Functions dealing with Markov chains start with either the @code{ctmc}
-or @code{dtmc} prefix; the prefix is optionally followed by an
-additional string which hints at what the function does:
-
-@table @asis
-@item @strong{-bd}
-Birth-Death process
-
-@item @strong{-mtta}
-Mean Time to Absorption
-
-@item @strong{-fpt}
-First Passage Times
-
-@item @strong{-exps}
-Expected Sojourn Times
-
-@item @strong{-taexps}
-Time-Averaged Expected Sojourn Times
-
-@end table
-
-For example, function @code{ctmcbd} returns the infinitesimal
-generator matrix for a continuous birth-death process, while
-@code{dtmcbd} returns the transition probability matrix for a discrete
-birth-death process. Note that there exist functions @code{ctmc} and
-@code{dtmc} (without any suffix) that compute steady-state and
-transient state occupancy probabilities for CTMCs and DTMCs,
-respectively. @xref{Markov Chains}.
-
-Functions whose name starts with @code{qs-} deal with single station
-queueing systems. The suffix describes the type of system, e.g.,
-@code{qsmm1} for @math{M/M/1}, @code{qnmmm} for @math{M/M/m} and so
-on. @xref{Single Station Queueing Systems}.
-
-Finally, functions whose name starts with @code{qn-} deal with
-queueing networks. The character that follows indicates whether the
-function handles open (@code{'o'}) or closed (@code{'c'}) networks,
-and whether there is a single customer class (@code{'s'}) or multiple
-classes (@code{'m'}). The string @code{mix} indicates that the
-function supports mixed networks with both open and closed customer
-classes.
-
-@table @asis
-@item @strong{-os-}
-Open, single-class network: open network with a single class of customers
-
-@item @strong{-om-}
-Open, multiclass network: open network with multiple job classes
-
-@item @strong{-cs-}
-Closed, single-class network
-
-@item @strong{-cm-}
-Closed, multiclass network
-
-@item @strong{-mix-}
-Mixed network with open and closed classes of customers
-
-@end table
-
-The last part of the function name indicates the algorithm implemented
-by the function. @xref{Queueing Networks}.
-
-@table @asis
-@item @strong{-aba}
-Asymptotic Bounds Analysis
-
-@item @strong{-bsb}
-Balanced System Bounds
-
-@item @strong{-gb}
-Geometric Bounds
-
-@item @strong{-pb}
-PB Bounds
-
-@item @strong{-cb}
-Composite Bounds (CB)
-
-@item @strong{-mva}
-Mean Value Analysis (MVA) algorithm
-
-@item @strong{-cmva}
-Conditional MVA
-
-@item @strong{-mvald}
-MVA with general load-dependent servers
-
-@item @strong{-mvaap}
-Approximate MVA
-
-@item @strong{-mvablo}
-MVABLO approximation for blocking queueing networks
-
-@item @strong{-conv}
-Convolution algorithm
-
-@item @strong{-convld}
-Convolution algorithm with general load-dependent servers
-
-@end table
-
-@node Quickstart Guide
-@section Quickstart Guide
-
--- a/main/queueing/doc/installation.txi	Tue Oct 30 01:21:56 2012 +0000
+++ b/main/queueing/doc/installation.txi	Tue Oct 30 12:13:45 2012 +0000
@@ -33,19 +33,20 @@
 This file (@file{INSTALL}) is automatically generated from
 @file{doc/installation.txi} in the @code{queueing} subversion sources.
 Do not modify this document directly, as changes will be lost. Modify
-the source @file{doc/installation.txi} instead.
+@file{doc/installation.txi} instead.
 @end quotation
 
 @end ifset
 
-@node Installation
-@chapter Installing the queueing toolbox
+@node Installation and Getting Started
+@chapter Installation and Getting Started
 
 @menu
 * Installation through Octave package management system::
 * Manual installation::
 * Development sources::
-* Using the queueing toolbox::
+* Naming Conventions::
+* Quickstart Guide::
 @end menu
 
 @c
@@ -193,9 +194,8 @@
 longer need to specify the @option{-p} option on the command line.
 
 @c
-@c
+@c The following will not appear in the INSTALL text file
 @c
-
 @ifclear INSTALLONLY
 
 @node Development sources
@@ -270,44 +270,295 @@
 
 @end table
 
-@end ifclear
+@node Naming Conventions
+@section Naming Conventions
+
+Most of the functions in the @code{queueing} package obey a common
+naming convention. Function names are made of several parts; the first
+part is a prefix which indicates the class of problems the function
+addresses:
+
+@table @asis
+@item @strong{ctmc-}
+Functions for continuous-time Markov chains
+
+@item @strong{dtmc-}
+Functions for discrete-time Markov chains
+
+@item @strong{qs-}
+Functions for analyzing queueing systems (individual service centers)
+
+@item @strong{qn-}
+Functions for analyzing queueing networks
+
+@end table
+
+Functions dealing with Markov chains start with either the @code{ctmc}
+or @code{dtmc} prefix; the prefix is optionally followed by an
+additional string which hints at what the function does:
+
+@table @asis
+@item @strong{-bd}
+Birth-Death process
+
+@item @strong{-mtta}
+Mean Time to Absorption
+
+@item @strong{-fpt}
+First Passage Times
+
+@item @strong{-exps}
+Expected Sojourn Times
+
+@item @strong{-taexps}
+Time-Averaged Expected Sojourn Times
+
+@end table
+
+For example, function @code{ctmcbd} returns the infinitesimal
+generator matrix for a continuous birth-death process, while
+@code{dtmcbd} returns the transition probability matrix for a discrete
+birth-death process. Note that there exist functions @code{ctmc} and
+@code{dtmc} (without any suffix) that compute steady-state and
+transient state occupancy probabilities for CTMCs and DTMCs,
+respectively. @xref{Markov Chains}.
+
+Functions whose name starts with @code{qs-} deal with single station
+queueing systems. The suffix describes the type of system, e.g.,
+@code{qsmm1} for @math{M/M/1}, @code{qnmmm} for @math{M/M/m} and so
+on. @xref{Single Station Queueing Systems}.
+
+Finally, functions whose name starts with @code{qn-} deal with
+queueing networks. The character that follows indicates whether the
+function handles open (@code{'o'}) or closed (@code{'c'}) networks,
+and whether there is a single customer class (@code{'s'}) or multiple
+classes (@code{'m'}). The string @code{mix} indicates that the
+function supports mixed networks with both open and closed customer
+classes.
+
+@table @asis
+@item @strong{-os-}
+Open, single-class network: open network with a single class of customers
+
+@item @strong{-om-}
+Open, multiclass network: open network with multiple job classes
+
+@item @strong{-cs-}
+Closed, single-class network
+
+@item @strong{-cm-}
+Closed, multiclass network
+
+@item @strong{-mix-}
+Mixed network with open and closed classes of customers
 
-@c
-@c
-@c
+@end table
+
+The last part of the function name indicates the algorithm implemented
+by the function. @xref{Queueing Networks}.
+
+@table @asis
+@item @strong{-aba}
+Asymptotic Bounds Analysis
+
+@item @strong{-bsb}
+Balanced System Bounds
+
+@item @strong{-gb}
+Geometric Bounds
+
+@item @strong{-pb}
+PB Bounds
+
+@item @strong{-cb}
+Composite Bounds (CB)
+
+@item @strong{-mva}
+Mean Value Analysis (MVA) algorithm
+
+@item @strong{-cmva}
+Conditional MVA
+
+@item @strong{-mvald}
+MVA with general load-dependent servers
+
+@item @strong{-mvaap}
+Approximate MVA
+
+@item @strong{-mvablo}
+MVABLO approximation for blocking queueing networks
+
+@item @strong{-conv}
+Convolution algorithm
+
+@item @strong{-convld}
+Convolution algorithm with general load-dependent servers
 
-@node Using the queueing toolbox
-@section Using the queueing toolbox
+@end table
+
+@cindex deprecated functions
+
+The current version (@value{VERSION}) of the @code{queueing} package
+still supports the old function names (although they are no longer
+documented and will disappear in future releases). However, calling
+one of the deprecated functions results in a warning message being
+displayed; the message appears only one time per session:
+
+@example
+@group
+octave:1> @kbd{qnclosedab(10,[1 2 3])}
+    @print{} warning: qnclosedab is deprecated. Please use qncsaba instead
+    @result{} ans =  0.16667
+@end group
+@end example
+
+Therefore, your legacy code should run unmodified with the current
+version of the @code{queueing} package. You can turn off all warning
+messages with the following command:
+
+@example
+@group
+octave:1> @kbd{warning ("off", "qn:deprecated-function");}
+@end group
+@end example
+
+However, it is recommended to update to the new API and not ignore the
+warnings above. To help you catch usages of deprecated functions, even
+with applications which produce a lot of console output, you can
+transform warnings into errors so that your application will stop
+immediately:
+
+@example
+@group
+octave:1> @kbd{warning ("error", "qn:deprecated-function");}
+@end group
+@end example
+
+@node Quickstart Guide
+@section Quickstart Guide
 
 You can use all functions by simply invoking their name with the
 appropriate parameters; the @code{queueing} package should display an
-error message in case of missing/wrong parameters. You can display the
-help text for any function using the @command{help} command. For
-example:
+error message in case of missing/wrong parameters. Extensive
+documentation is provided for each function, and can be displayed with
+the @command{help} command. For example:
 
 @example
 octave:2> @kbd{help qncsmvablo}
 @end example
 
-prints the documentation for the @command{qncsmvablo} function.
+@noindent prints the documentation for the @command{qncsmvablo} function.
 Additional information can be found in the @code{queueing} manual,
 which is available in PDF format in @file{doc/queueing.pdf} and in
 HTML format in @file{doc/queueing.html}.
 
-Within GNU Octave, you can also run the test and demo blocks
-associated to the functions, using the @command{test} and
-@command{demo} commands respectively. To run all the tests of, say,
-the @command{qncsmvablo} function:
-
-@example
-octave:3> @kbd{test qncsmvablo}
-@print{} PASSES 5 out of 5 tests
-@end example
-
-To execute the demos of the @command{qnclosed} function, use the
-following:
+Many functions have demo blocks containing code snippets which
+illustrate how that function can be used. For example, to execute the
+demos for the @command{qnclosed} function, use the @command{demo}
+command as follows:
 
 @example
 octave:4> @kbd{demo qnclosed}
 @end example
 
+Here we illustrate some basic usage of the @code{queueing} package by
+considering a few examples.
+
+@noindent @strong{Example 1}
+Compute the stationary state occupancy probabilities of a continuous-time
+Markov chain with infinitesimal generator matrix
+
+@iftex
+@tex
+$$
+{\bf Q} =
+\pmatrix{ -0.8 & 0.6  & 9,2 \cr
+           0.3 & -0.7 & 0.4 \cr
+           0.2 & 0.2  & -0.4 }
+$$
+@end tex
+@end iftex
+@ifnottex
+@example
+@group
+    / -0.8   0.6   0.2 \
+Q = |  0.3  -0.7   0.4 |
+    \  0.2   0.2  -0.4 /
+@end group
+@end example
+@end ifnottex
+
+@example
+@group
+Q = [ -0.8  0.6  0.2; \
+       0.3 -0.7  0.4; \
+       0.2  0.2 -0.4 ];
+q = ctmc(Q)
+    @result{} q = 0.23256   0.32558   0.44186
+@end group
+@end example
+
+@noindent @strong{€xample 2}
+Compute the transient state occupancy probability after @math{n=3}
+transitions of a three state discrete time birth-death process, with
+birth probabilities @math{\lambda_{01} = 0.3} and @math{\lambda_{12} =
+0.5} and death probabilities @math{\mu_{10} = 0.5} and @math{\mu_{21}
+= 0.7}, assuming that the system is initially in state zero (i.e., the
+initial state occupancy probabilities are @math{(1, 0, 0)}).
+
+@example
+@group
+n = 3;
+p0 = [1 0 0];
+P = dtmcbd( [0.3 0.5], [0.5 0.7] );
+p = dtmc(P,n,p0)
+    @result{} p = 0.55300   0.29700   0.15000
+@end group
+@end example
+
+@noindent @strong{Example 3}
+Compute server utilization, response time, mean number of requests and
+throughput of a closed queueing network with @math{N=4} requests and
+three @math{M/M/1}--FCFS queues with mean service times @math{{\bf S}
+= (1.0, 0.8, 1.4)} and average number of visits @math{{\bf V} = (1.0,
+0.8, 0.8)}
+
+@example
+@group
+S = [1.0 0.8 1.4];
+V = [1.0 0.8 0.8];
+N = 4;
+[U R Q X] = qncsmva(N, S, V)
+    @result{} 
+     U = 0.70064   0.44841   0.78471
+     R = 2.1030    1.2642    3.2433
+     Q = 1.47346   0.70862   1.81792
+     X = 0.70064   0.56051   0.56051
+@end group
+@end example
+
+@noindent @strong{Example 4}
+Compute server utilization, response time, mean number of requests and
+throughput of an open queueing network with three @math{M/M/1}--FCFS
+queues with mean service times @math{{\bf S} = (1.0, 0.8, 1.4)} and
+average number of visits @math{{\bf V} = (1.0, 0.8, 0.8)}. The overall
+arrival rate is @math{\lambda = 0.8} req/s
+
+@example
+@group
+S = [1.0 0.8 1.4];
+V = [1.0 0.8 0.8];
+lambda = 0.8;
+[U R Q X] = qnos(lambda, S, V)
+    @result{} 
+     U = 0.80000   0.51200   0.89600
+     R = 5.0000    1.6393   13.4615
+     Q = 4.0000    1.0492    8.6154
+     X = 0.80000   0.64000   0.64000
+@end group
+@end example
+
+@c
+@c 
+@c
+@end ifclear
--- a/main/queueing/doc/queueing.texi	Tue Oct 30 01:21:56 2012 +0000
+++ b/main/queueing/doc/queueing.texi	Tue Oct 30 12:13:45 2012 +0000
@@ -175,8 +175,7 @@
 
 @menu
 * Summary::
-* Installation::                Installation of the queueing toolbox.
-* Getting Started::             Start using the queueing toolbox.
+* Installation and Getting Started:: Installation of the queueing toolbox.
 * Markov Chains::               Functions for Markov Chains.
 * Single Station Queueing Systems:: Functions for single-station queueing systems.
 * Queueing Networks::           Functions for queueing networks.
@@ -191,7 +190,6 @@
 
 @include summary.texi
 @include installation.texi
-@include gettingstarted.texi
 @include markovchains.texi
 @include singlestation.texi
 @include queueingnetworks.texi