  ***************************************************************************
  * 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.                                                        *
  ***************************************************************************

   AUTHOR:

       Yves Lucet
       Irving K. Barber School of Arts and Sciences
       University of British Columbia Okanagan, Canada
       yves.lucet@ubc.ca

   REFERENCE:

    -  Fast Moreau Envelope computation I: Numerical algorithms
       NUMERICAL ALGORITHMS, 43 (2006), 235-249

   SOFTWARE REVISION DATE:

       V1.0 november, 2006

   SOFTWARE LANGUAGE:

       Scilab 4.0


  ===================================
  Installation guide for CCA package
  ===================================

  CCA package is available from Netlib at
	www.netlib.org/numeralgo/na24

  This package can be used as a stand-alone package.  A user
  needs only standard Scilab, version 4.0 available from
  http://www.scilab.org. No additional toolboxes are
  needed. The package has been tested on Ms Windows XP and
  Linux Mandriva 2006.

  Quickstart guide:
  ================
  1. Follow the installation instructions for your OS below.
  2. The main functions are lft_llt, me_llt, and me_llt2d
     (see their help files). The demos illustrate their use.


  ============================================
  Step-by-step installation (Unix environment)
  ============================================

  1. Create a new folder (if it not exists) for installing
     the new Scilab packages.
     For instance a folder named 
         $HOME/.Scilab/toolbox 

  2. Download the gzipped tar archive 
	    na24.tgz
     in a directory of your choice.

  3. Open a terminal window and execute the commands
   	 cd $HOME/.Scilab/toolbox
	 tar zxvf na24.tgz
     which will create the directory 
	    CCA-1.0 
     containing the package. 

  4. Remove (if you want) the archive:
          rm na24.tgz

  5. Start the Scilab program.

  6. Case a.

     At the prompt, type 
         exec "<PATH>/loader.sce";
     where <PATH> stands for the complete path of the folder
     directory containing the present README.txt file.
     For instance
     exec /home/user_name/.Scilab/toolbox/CCA-1.0/loader.sce

     Case b.

     It is also possible (recommended) to provide an 
     automatic loading of the CCA package, help files and
     the demos, by inserting the following commands in the 
     startup file, before the launch of the Scilab program:

     // CCA-1.0 Path
     CCADIR="/home/user_name/.Scilab/toolbox/CCA-1.0";
     // load CCA toolbox
     exec (CCADIR+'/loader.sce',-1);

     The main startup file is named "scilab.star" and the user can
     find it into the directory Scilab 4.0 were the software has
     been installed. On some systems you may need administrator 
     privileges to edit scilab.star, so, alternatively, it is 
     possible to have an own startup file named ".scilab" in the 
     directory $HOME/.Scilab/scilab-4.0 automatically started at 
     Scilab launch.

     In both case a. or b., the CCA package is ready to be used.

  7. At the prompt, 

     - if you followed instructions 6.a, type
           exec <PATH>/tests/test.sci

     - if you followed instructions 6.b, type
           exec (CCADIR+'/tests/test.sci') 

     You should get a "All tests passed!" message. Check
     that the file <PATH>/tests/test.log is the same as
     <PATH>/tests/test_CCA.log (except possibly for the
     order of the tests which is OS dependent).

  8. You can now run some examples with 

        exec <PATH>/demos/demo.sci      (instructions 6.a)
     or
        exec (CCADIR+'/demos/demo.sci') (instructions 6.b)

     or from the "Demos" menu, select the "CCA demos" item. 


  ===============================================
  Step-by-step installation (Windows environment)
  ===============================================

  1. Create a new folder (if it not exists) for installing
     the new Scilab packages.
     For instance a folder named 
        My Documents\scilab\toolbox 

  2. Download the gzipped tar archive 
	    na24.tgz
     in a directory of your choice.

  3. Use your unarchiver to extract the files in the folder
     created in step 1. 
     There are several free archiver that handle .tgz files
     e.g. www.7-zip.org. 
     The extraction will create the folder
	    CCA-1.0 
     containing the whole package. 

  4. Remove (if you want) the archive na24.tgz

  5. Start the Scilab program.

  6. Case a.

     At the prompt, type 
     exec "<PATH>\loader.sce";
     where <PATH> stands for the complete path of the folder
     directory containing the present README.txt file.
     For instance
exec "C:\Documents and Settings\user\My Documents\scilab\toolbox\CCA-1.0\loader.sce"

     Case b.

     It is also possible (recommended) to provide an 
     automatic loading of the CCA package, help files and
     the demos, by inserting the following commands in the 
     startup file, before the launch of the Scilab program:

// CCA-1.0 Path
CCADIR="C:\Documents and Settings\user\My Documents\scilab\toolbox\CCA-1.0";
// load CCA toolbox
exec (CCADIR+'\loader.sce',-1);

     The main startup file is named "scilab.star" and the user can
     find it into the Scilab 4.0 folder (by default is
     "C:\Program Files\scilab-4.0"). On some systems you may 
     need administrator privileges to edit scilab.star, so, 
     alternatively, it is possible to have an own startup 
     file named "scilab.ini" in the directory where you are 
     working, automatically started at Scilab launch.
     If you start Scilab 4.0 by using the link in the Desktop,
     the file startup.ini must also be in the Desktop.

     In both case a. or b., the CCA package is ready to be used.

  7. At the prompt, 

     - if you followed instructions 6.a, type
           exec "<PATH>\tests\test.sci"; 

     - if you followed instructions 6.b, type
           exec (CCADIR+'\tests\test.sci'); 

     You should get a "All tests passed!" message. Check
     that the file <PATH>\tests\test.log is the same as
     <PATH>\tests\test_CCA.log (except possibly for the
     order of the tests which is OS dependent).

  8. You can now run some examples with 

        exec "<PATH>\demos\demo.sci"; (instructions 6.a)
     or
        exec (CCADIR+'\demos\demo.sci'); (instructions 6.b)

     or from the Demos menu (click the rightmost menu named
     ?, then select Scilab Demos and the CCA demos item).


Here are the main files provided by the package. 

======
<PATH>
======

builder.sce     Scilab script to re-generate all the html 
		help files using the xml source files in
		<PATH>/man/. The help files are then loaded
		with loader.sce. Only run builder.sce if you
		modify the xml files and want to update the
		html help files (the html help files are
		loaded with loader.sce). Otherwise, just use
		the included help files.
contents.htm	help file
index.htm	help file
loader.sce	Scilab script to load demos, library, and 
		help files.
README.txt	The present file
sciman.hhc	help file
sciman.hhk	help file
sciman.hhp	help file

lft.sci	Discrete Legendre transform functions and 
		internal functions. It contains all the
		functions to compute the discrete Legendre
		transform and associated functions. The main
		function is lft_llt. One may want to use the
		bb function to compute the lower convex
		envelope of a set of points in the plane
		using the Beneath-Beyond algorithm.  The
		function lft_direct is provided for
		comparison only.  The remaining functions
		(lft_direct_d, fusion, fusionsci) are
		internal and should not be called directly.

me.sci	Discrete Moreau envelope functions. The main 
		functions are me_llt and me_pe for nonconvex
		univariate functions, me_nep for convex
		univariate functions. For bivariate
		functions, use me_llt2d and me_pe2d for
		nonconvex data, and me_nep2d for convex
		data. The functions me_brute2d, me_direct,
		me_direct2d are provided for comparison
		only.  The function me_pe2d_d is an internal
		function and should not be used directly.

For more details on the Scilab functions defined in the 
files "lft.sci" and "me.sci", refer to the Scilab online help 
(item CCA toolbox).

============================
Unit Tests: in <PATH>/tests/
============================

test.sci	Scilab script that runs all unit tests in 
		the current folder (files test_*.sci) and
		record the results in test.log

test_*.sci	Unit test files that validate the algorithms
		and provide numerous examples of their
		use. Test files included are
		test_bb.sci: Unit tests and examples for the
			bb function.
		test_fusion.sci: Unit tests for the internal 
			functions fusion and fusionsci.
		test_llt.sci: Unit tests and examples for 
			the functions lft_llt, lft_llt_d,
			lft_direct, and lft_direct_d.
		test_me_llt.sci: Unit tests and examples for
			the functions me_llt, me_llt2d,
			me_direct, and me_direct2d:
			computation of the discrete Moreau
			envelope using the LLT algorithm.
		test_me_nep.sci: Unit tests and examples for
			the functions me_nep, me_nep2d, and
			me_direct: computation of the
			discrete Moreau envelope using the
			NEP algorithm.
		test_me_pe.sci: Unit tests and examples for 
			the functions me_pe, me_pe2d:
			computation of the discrete Moreau
			envelope using the PE algorithm.

                Each of the unit test files can be called 
                independently by giving the command 
                  exec "<PATH>/tests/name_of_test.sci"; 
                or
                  exec (CCADIR+'/tests/name_of_test.sci'); 

test.log	Results of the tests obtained after running 
		test.sci (note that the order of the tests
		is OS dependent). Look at this file if any
		test fails.

test_CCA.log	Results of the tests you should obtain, 
		provided for comparison with test.log.


=======================
Demos: in <PATH>/demos/
=======================

demo.sci	Scilab script calling all the demonstration 
		files and displaying the corresponding
		graphs.

Here is the detail of the demos provided in the Demos menu.
Alternatively the CCA demo menu can be launched directly by
running the command 
    exec "<PATH>/demos/demo.sci";
or
    exec (CCADIR+'/demos/demo.sci'); 

Each of the following demo file can also be called 
independently by giving the command 
    exec "<PATH>/demos/name_of_demo.sci"; 
or
    exec (CCADIR+'/demos/name_of_demo.sci'); 

1. time_me.sci
Compare 4 algorithms to compute the Moreau envelope. Each
algorithm is timed on the computation of the Moreau envelope
of the function f(x)=x^2 on the grid N={1,2,3,...,n} for
increasing values of n=100, 200, 300, ..., 3000. The 4
algorithms compared are LLT, PE, NEP, and direct.The results
show that the NEP algorithm is the fastest but requires
additional structure like convexity, followed by the llt
algorithm, the PE algorithm, and the direct algorithm. (The
later is provided for comparison only.)
Functions demoed: me_llt, me_pe_d, me_nep, me_direct

2. abs.sci
Computes the Moreau envelope and the proximal mapping of the
absolute value function on the interval [-1,1]. It
illustrates the smoothing property of the Moreau envelope at
the origin.
Function demoed: me_direct

3. sqr.sci
Computes the Moreau envelope and the proximal mapping of the
smooth convex function f(x)=x^2 on the interval
[-15,15]. The resulting envelope approximates the function
from below, and its proximal mapping is clearly monotone.
Function demoed: me_direct

4. nonconvexabs.sci
Computes the Moreau envelope of the nonsmooth nonconvex
function f(x)=||x|-1| on the interval [-2.5,2.5]. The Moreau
envelope does not smooth kinks arising from local maxima,
only those arising from minima.  The proximal mapping is
monotone with a jump at the origin as it is a
nondifferentiable point.
Function demoed: me_direct

5. nonconvexsqr.sci
Computes the Moreau envelope and the proximal mapping of the
smooth nonconvex function f(x)=(x^2-1)^2 on the interval
[-1.5,1.5]. The Moreau envelope introduces a kink at the
origin (local maximum).  The proximal mapping is monotone
with a jump at the origin as it is a nondifferentiable point
of the Moreau envelope.
Function demoed: me_direct

6.bb.sci
Computes the lower convex envelope of the smooth nonconvex
function f(x)=(x^2-1)^2 on the interval [-2,2]. The envelope
retains the vertices on the convex hull and discards the
vertices in the open interval ]-1,1[ corresponding to the
concave part of f.
Function demoed: bb

7. lft_direct.sci
Illustrate the convergence of the Legendre-Fenchel conjugate
of the absolute value function when the size of the
intervals is increased.  The conjugate is computed on
intervals [-2,2], [-4,4], [-8,8], and [-160,160]. It is
converging to the indicator function of the interval [-1,1]
Function demoed: lft_direct

8. time_lft.sci
Compare 3 algorithms to compute the Legendre-Fenchel
conjugate.  Each algorithm is timed on the computation of
conjugate of the absolute value function on the grid
N={1,2,3,...,n} for increasing values of n=100, 300, 500,
..., 4000. The 3 algorithms compared are lft_direct, lft_llt
using fusion, and lft_llt using fusionsci. For the values of
n considered, the llt algorithm with the option fusionsci is
the fastest mostly due to its compiled instructions. The llt
algorithm with the fusion option comes next although it has
a better complexity since it uses Scilab interpreted
commands.
Functions demoed: lft_direct, lft_llt

==========================
Help files: in <PATH>/man/
==========================
All *.xml files contain the help file in xml format. All the
corresponding *.htm file and the file whatis.htm are
generated by the script <PATH>/builder.sce.

========
Credits:
========
All the codes and the article were written by Yves Lucet
except for some code contributed by two students during
their summer research assistantship in 2005: Andrew Tonner
and Jeff Dicker.
