Mercurial > forge
view main/queueing/doc/installation.txi @ 12368:e2e72af49f3d octave-forge
Renaming "queueing toolbox" to "queueing package"
author | mmarzolla |
---|---|
date | Sat, 15 Feb 2014 13:38:14 +0000 |
parents | 2f0c66bf783d |
children |
line wrap: on
line source
@c -*- texinfo -*- @c Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014 Moreno Marzolla @c @c This file is part of the queueing package. @c @c The queueing package 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 package 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 package; see the file COPYING. If not, see @c <http://www.gnu.org/licenses/>. @ifset INSTALLONLY @include conf.texi This file documents the installation procedure of the Octave @code{queueing} package. @code{queueing} is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3 or later, as published by the Free Software Foundation. @quotation Note 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 @file{doc/installation.txi} instead. @end quotation @end ifset @node Installation and Getting Started @chapter Installation and Getting Started @menu * Installation through Octave package management system:: * Manual installation:: * Development sources:: * Naming Conventions:: * Quickstart Guide:: @end menu @c @c @c @node Installation through Octave package management system @section Installation through Octave package management system The most recent version of @code{queueing} is @value{VERSION} and can be downloaded from Octave-Forge @url{http://octave.sourceforge.net/queueing/} Additional information can be found at @url{http://www.moreno.marzolla.name/software/queueing/} To install @code{queueing}, follow these steps: @enumerate @item If you have a recent version of GNU Octave and a network connection, you can install @code{queueing} directly from Octave command prompt using this command: @example octave:1> @kbd{pkg install -forge queueing} @end example The command above will automaticall download and install the latest version of the queueing package from Octave Forge, and install it on your machine. If you do not have root access, you can do a local install using: @example octave:1> @kbd{pkg install -local -forge queueing} @end example This will install @code{queueing} within your home directory, and the package will be available to your user only. @item Alternatively, you can first download @code{queueing} from Octave-Forge; then, to install the package in the system-wide location issue this command at the Octave prompt: @example octave:1> @kbd{pkg install @emph{queueing-@value{VERSION}.tar.gz}} @end example @noindent (you may need to start Octave as root in order to allow the installation to copy the files to the target locations). After this, all functions will be readily available each time Octave starts, without the need to tweak the search path. If you do not have root access, you can do a local install using: @example octave:1> @kbd{pkg install -local queueing-@value{VERSION}.tar.gz} @end example @quotation Note Octave version 3.2.3 as shipped with Ubuntu 10.04 LTS seems to ignore @option{-local} and always tries to install the package on the system directory. @end quotation @item Verify that the package is indeed installed using the @kbd{pkg list} command at the Octave prompt; after succesfull installation you should see something like that: @example octave:1>@kbd{pkg list queueing} Package Name | Version | Installation directory --------------+---------+----------------------- queueing | @value{VERSION} | /home/moreno/octave/queueing-@value{VERSION} @end example @item Starting from version 1.1.1, @code{queueing} is no longer automatically loaded on Octave startup. To make the functions available for use, you need to issue the command @example octave:1>@kbd{pkg load queueing} @end example @noindent at the Octave prompt. To automatically load @code{queueing} each time Octave starts, you can add the command above to the startup script (usually, @file{~/.octaverc} on Unix systems). @item To completely remove @code{queueing} from your system, use the @kbd{pkg uninstall} command: @example octave:1> @kbd{pkg uninstall queueing} @end example @end enumerate @c @c @c @node Manual installation @section Manual installation If you want to manually install @code{queueing} in a custom location, you can download the tarball and unpack it somewhere: @example @kbd{tar xvfz queueing-@value{VERSION}.tar.gz} @kbd{cd queueing-@value{VERSION}/queueing/} @end example Copy all @code{.m} files from the @file{inst/} directory to some target location. Then, start Octave with the @option{-p} option to add the target location to the search path, so that Octave will find all @code{queueing} functions automatically: @example @kbd{octave -p @emph{/path/to/queueing}} @end example For example, if all @code{queueing} m-files are in @file{/usr/local/queueing}, you can start Octave as follows: @example @kbd{octave -p @emph{/usr/local/queueing}} @end example If you want, you can add the following line to @file{~/.octaverc}: @example @kbd{addpath("@emph{/path/to/queueing}");} @end example @noindent so that the path @file{/path/to/queueing} is automatically added to the search path each time Octave is started, and you no longer need to specify the @option{-p} option on the command line. @c @c The following will not appear in the INSTALL text file @c @ifclear INSTALLONLY @node Development sources @section Development sources The source code of the @code{queueing} package can be found in the Subversion repository at the URL: @url{http://octave.svn.sourceforge.net/viewvc/octave/trunk/octave-forge/main/queueing/} The source distribution contains additional development files which are not present in the installation tarball. This section briefly describes the content of the source tree. This is only relevant for developers who want to modify the code or documentation; normal users of the @code{queueing} package don't need The source distribution contains the following directories: @table @file @item doc/ Documentation source. Most of the documentation is extracted from the comment blocks of individual function files from the @file{inst/} directory. @item inst/ This directory contains the @verb{|m|}-files which implement the various Queueing Network algorithms provided by @code{queueing}. As a notational convention, the names of source files containing functions for Queueing Networks start with the @samp{qn} prefix; the name of source files containing functions for Continuous-Time Markov Chains (CTMSs) start with the @samp{ctmc} prefix, and the names of files containing functions for Discrete-Time Markov Chains (DTMCs) start with the @samp{dtmc} prefix. @item test/ This directory contains the test functions used to invoke all tests on all function files. @item devel/ This directory contains function files which are either not working properly, or need additional testing before they are moved to the @file{inst/} directory. @end table The @code{queueing} package ships with a Makefile which can be used to produce the documentation (in PDF and HTML format), and automatically execute all function tests. Specifically, the following targets are defined: @table @code @item all Running @samp{make} (or @samp{make all}) on the top-level directory builds the programs used to extract the documentation from the comments embedded in the @verb{|m|}-files, and then produce the documentation in PDF and HTML format (@file{doc/queueing.pdf} and @file{doc/queueing.html}, respectively). @item check Running @samp{make check} will execute all tests contained in the @verb{|m|}-files. If you modify the code of any function in the @file{inst/} directory, you should run the tests to ensure that no errors have been introduced. You are also encouraged to contribute new tests, especially for functions which are not adequately validated. @item clean @itemx distclean @itemx dist The @samp{make clean}, @samp{make distclean} and @samp{make dist} commands are used to clean up the source directory and prepare the distribution archive in compressed tar format. @end table @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 @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. 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 @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}. 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{Example 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