  ***************************************************************************
  * All the software  contained in this library  is protected by copyright. *
  * Permission  to use, copy, modify, and  distribute this software for any *
  * purpose without fee is hereby granted, provided that this entire notice *
  * is included  in all copies  of any software which is or includes a copy *
  * or modification  of this software  and in all copies  of the supporting *
  * documentation for such software.                                        *
  ***************************************************************************
  * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED *
  * WARRANTY. IN NO EVENT, NEITHER  THE AUTHORS, NOR THE PUBLISHER, NOR ANY *
  * MEMBER  OF THE EDITORIAL BOARD OF  THE JOURNAL  "NUMERICAL ALGORITHMS", *
  * NOR ITS EDITOR-IN-CHIEF, BE  LIABLE FOR ANY ERROR  IN THE SOFTWARE, ANY *
  * MISUSE  OF IT  OR ANY DAMAGE ARISING OUT OF ITS USE. THE ENTIRE RISK OF *
  * USING THE SOFTWARE LIES WITH THE PARTY DOING SO.                        *
  ***************************************************************************
  * ANY USE  OF THE SOFTWARE  CONSTITUTES  ACCEPTANCE  OF THE TERMS  OF THE *
  * ABOVE STATEMENT.                                                        *
  ***************************************************************************

   AUTHORS:

       Anna Concas, Caterina Fenu, and Giuseppe Rodriguez
       University of Cagliari, Italy
       Email: concas.anna@gmail.com, kate.fenu@gmail.com, rodriguez@unica.it

   REFERENCE:

       pqser: a Matlab package for spectral seriation
       NUMERICAL ALGORITHMS
       DOI: https://doi.org/10.1007/s11075-018-0510-6

   SOFTWARE REVISION DATE:

       V1.0, September 2017

   SOFTWARE LANGUAGE:

       MATLAB 9.2 (R2017a)
       Compatible with OCTAVE 4.0 except for the parallel implementation.


======================================================================
SOFTWARE
======================================================================

The pqser toolbox contains a Matlab implementation of a spectral
method by Atkins et al. to solve the seriation problem, based on the
use of the Fiedler vector of the Laplacian associated to the problem,
and which describes the results in terms of a particular data
structure called a PQ-tree.

The algorithm is optimized in terms of numerical efficiency and
includes Matlab routines for PQ-trees handling, as well as a simple
graphical interface to explore the results of the computation in case
a unique solution is not available.


======================================================================
HOW TO INSTALL
======================================================================

Please, follow the following steps:

- Extract the archive in the directory you prefer. This will create a
  directory called PQser that contains all the files of the toolbox.

- Start MATLAB.

- Add the directory containing the toolbox to Matlab search path, for
  instance by using the Matlab command addpath, or the "Set path"
  button in the Home tab.

In order to execute the function pspectrsort.m, the Parallel Computing
Toolbox must be present in the current Matlab installation.


======================================================================
PACKAGE
======================================================================

The main "PQser" directory contains the following Matlab functions.

Main functions
  spectrsort    - spectral sort for the seriation problem
  pspectrsort   - spectral sort for the seriation problem, parallel
                  version. The Parallel Computing Toolbox is required.
  testmatr      - test matrices for PQser.
  fiedvecs      - compute the Fiedler vectors and values of a
                  Laplacian.
  getconcomp    - determine the connected components of a graph.

PQ trees operations
  pqtree1perm   - extract an admissible permutation from a PQ tree.
  pqtreegetnode - extract a subtree from a PQ tree.
  pqtreenodes   - converts a PQ tree to "treeplot" format.
  pqtreeNperm   - number of admissible permutations in a PQ tree.
  pqtreeperms   - extract all admissible permutations from a PQ tree.
  pqtreeplot    - plot a PQ tree.
  pnode         - add a P node to a PQ tree.
  qnode         - add a Q node to a PQ tree.
  mnode         - add a M node to a PQ tree.
  lnode         - add a leaf node to a PQ tree.

Utilities
  distinct      - sort and level the elements of a vector.
  graphvisit    - visit a graph starting from root.
  lapl          - construct the graph Laplacian of a matrix.

The "demo" subdirectory contains the following Matlab scripts:
  tutorial.m    - illustrate the use of the toolbox.
  graf1.m       - reproduce the experiment in Figure 1 of the paper.
  graf2.m       - reproduce the experiment in Figure 2 of the paper.
  exper1.m      - reproduce the experiment in Figure 4 of the paper.
  exper2.m      - reproduce the experiment in Figure 5 of the paper.
  exper3.m      - reproduce the experiment in Figure 6 of the paper.
  mfiedval.m    - reproduce the experiment in Section 5 of the paper.
  startup.m     - sets the Matlab path for the demos.
  Bornholm.mat  - data file used by exper1.m.

