@c This file has been automatically generated from installation.txi
@c by proc.m. Do not edit this file, all changes will be lost

@c -*- texinfo -*-

@c Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014, 2016, 2018, 2024 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} source tree.  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::
* Testing and Demos::
* Naming Conventions::
* Quick start 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

@url{https://gnu-octave.github.io/packages/queueing/}

Additional information can be found at

@url{https://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} from Octave command prompt using this
command:

@example
octave:1> @kbd{pkg install pkg install "https://github.com/mmarzolla/queueing/releases/download/@value{VERSION}/queueing-@value{VERSION}.tar.gz"}
@end example

The command above will download and install the latest version of the
@code{queueing} package from the source repository, and install it on
your machine.

If you do not have root access, you can perform a local install with:

@example
octave:1> @kbd{pkg install -local "https://github.com/mmarzolla/queueing/releases/download/@value{VERSION}/queueing-@value{VERSION}.tar.gz"}
@end example

This will install @code{queueing} in your home directory, and the
package will be available to the current user only.

@item
Alternatively, you can first download the @code{queueing} tarball; 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 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

@item
Use the @kbd{pkg list} command at the Octave prompt to check that the
@code{queueing} package has been succesfully installed; you should see
something like:

@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 start. 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}/}
@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
Git repository at the URL:

@url{https://github.com/mmarzolla/queueing}

The source distribution contains additional development files that 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 the documentation.

The source distribution contains the following directories:

@table @file
@item doc/
Documentation sources. Most of the documentation is extracted from the
comment blocks of function files from the @file{inst/} directory.

@item inst/
This directory contains the @verb{|m|}-files which implement the
various algorithms provided by @code{queueing}. As a notational
convention, the names of functions for Queueing Networks begin with
the @samp{qn} prefix; the name of functions for Continuous-Time Markov
Chains (CTMCs) begin with the @samp{ctmc} prefix, and the names of
functions for Discrete-Time Markov Chains (DTMCs) begin with the
@samp{dtmc} prefix.

@item test/
This directory contains the scripts used to run all function tests.

@item devel/
This directory contains functions that 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 tests. 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 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
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 that 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 Testing and Demos
@section Testing and Demos

The @code{queueing} package makes extensive use of test and demo
blocks. These are GNU Octave features that allow tests and demos
to be embedded within the source code of m-files. Multiple test
blocks can be defined using the @samp{%!test} directive:

@example
@group
%!test
%! # test code
%!
%!test
%! # another test code
@end group
@end example

Test blocks rely on the @command{assert} built-in function to check
che correctness of computation, e.g., by comparing the results with
known ``good'' values or by cross-checking with other functions. The
tests for a given function can be manually executed with the
@command{test} command: for example, @code{test("qsmm1")} executes all
tests in the script file @file{qsmm1.m} and prints a diagnostic
message:

@example
@kbd{test("qsmm1");}
@print{} PASSES 3 out of 3 tests
@end example

A quick way to run all tests for all functions in the @code{queueing}
package is using the @command{runtests} built-in command at the GNU
Octave prompt, passing as parameter the full path where the @code{.m}
files are stored:

@example
@kbd{runtests("/path/to/queueing/inst");}
@print{} Processing files in /path/to/queueing/inst:
@print{}
@print{}  ctmc.m .............................................. PASS 9/9
@print{}  ctmcbd.m ............................................ PASS 1/1
@dots{}
@end example

A better way for Unix users is to use the @file{Makefile} provided in
the top-level directory of the development sources. As described in
@ref{Development sources}, the @file{Makefile} defines a target
@samp{check} that runs all tests over all functions in the
@file{inst/} directory. Simply run the

@example
@kbd{make check}
@end example

@noindent command from the Unix shell to run all tests.

The source files include small demos that show how the function
defined there can be used. Similarly to test blocks, demos are
embedded in the source files using the @samp{%!demo} directive. Demos
can be displayed and run using the @command{demo} built-in command
at the GNU Octave prompt:

@example
@kbd{demo("qsmm1");}

@verbatim
 ## Given a M/M/1 queue, compute the steady-state probability pk
 ## of having k requests in the systen.
 lambda = 0.2;
 mu = 0.25;
 k = 0:10;
 pk = qsmm1(lambda, mu, k);
 plot(k, pk, "-o", "linewidth", 2);
 xlabel("N. of requests (k)");
 ylabel("p_k");
 title(sprintf("M/M/1 system, \\lambda = %g, \\mu = %g", lambda, mu));
@end verbatim
@end example

@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 single-station 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

Some deprecated functions may be present in the @code{queueing}
package; generally, these are functions that have been renamed, and
the old name is kept for a while for backward compatibility.
Deprecated functions are not documented and will be removed in future
releases. Calling a deprecated functions displays a warning message
that appears only once per session. The warning message can be turned
off with the command:

@example
@group
octave:1> @kbd{warning ("off", "qn:deprecated-function");}
@end group
@end example

However, you are strongly recommended to update your code to the new
API. To help catching usages of deprecated functions, you can
transform warnings into errors so that your application stops
immediately:

@example
@group
octave:1> @kbd{warning ("error", "qn:deprecated-function");}
@end group
@end example

@node Quick start Guide
@section Quick start Guide

You can use all functions by simply invoking their name with the
appropriate parameters; an error is shown 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 shows the documentation for the @command{qncsmvablo} function.
Additional information can be found in the @code{queueing} manual,
that is available in PDF format in @file{doc/queueing.pdf} and in HTML
format in @file{doc/queueing.html}.

Ad sicussed above, many functions have demo blocks showing usage
examples. To execute the demos for the @command{qnclosed} function,
use the @command{demo} command:

@example
octave:4> @kbd{demo qnclosed}
@end example

We now illustrate a few examples of how the @code{queueing} package
can be used. More examples are provided in the manual.

@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{S
= [1.0, 0.8, 1.4]} and average number of visits @math{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{S = [1.0, 0.8, 1.4]} and
average number of visits @math{V = [1.0, 0.8, 0.8]}. The overall
arrival rate is @math{\lambda = 0.8} requests/second.

@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