<?xml version='1.0' encoding='UTF-8'?>
<book version='5.0-subset Scilab' xml:lang='en_US'>
  <info xml:id='cca_(computational_convex_analysis)_manual'>
    <title>CCA (Computational Convex Analysis)</title>
  </info>

<part xml:id='section_7517a3f242e8fb4971fe2de3ca219c07'>
<title>CCA (Computational Convex Analysis)</title>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='_pl_fusion'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>_pl_fusion</refname><refpurpose>[Internal function] Merge 2 increasing sequences using classical programming; used to compute the Legendre-Fenchel conjugate.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>fH = _pl_fusion(C,S)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>C</term>
    
            <listitem>
       
               <para>Column vector. C(i) = (f(X(i+1) - f(X(i)) / (X(i+1) - X(i)) for some function f on a grid X.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>Column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>fH</term>
    
            <listitem>
       
               <para>Column vector. Index at which the slope S(i) support the epigraph.
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
      <itemizedlist>
     
         <listitem>
     
            <para>
	Calling _pl_fusion(C,S) gives the resulting indices fH(j) where the slope S(j) supports the epigraph
	of the underlying function f. All in all, it amounts to finding the first index i such that C(i-1) &lt;= S(j) &lt;= C(i).
     </para>
     
         </listitem>
     
         <listitem>
     
            <para>
	This function uses classical programming i.e. loops to guarantee a linear worst-case running time. 
	See <link linkend='_pl_fusionsci'>_pl_fusionsci</link> for a scilab specific implementation.
     </para>
     
         </listitem>
     
         <listitem>
	     
            <para>
		     This function is not intended to be used directly but to be called during the computation of the conjugate using the LLT algorithm by the function <link linkend='pl_lft_llt'>pl_lft_llt</link>.
	     </para>
     
         </listitem>
     
     
      </itemizedlist>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    C=(Y(2:size(Y,1))-Y(1:size(Y,1)-1))./(X(2:size(X,1))-X(1:size(X,1)-1));
    S=C-0.25*ones(size(C, 1));
    [fH]=_pl_fusion(C,S)
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='_pl_fusionsci'>_pl_fusionsci</link> 
      </member>
    
      <member> 
         <link linkend='pl_lft_llt'>pl_lft_llt</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='_pl_fusionsci'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>_pl_fusionsci</refname><refpurpose>[Internal function] Merge 2 increasing sequences using scilab syntax; used to compute the Legendre-Fenchel conjugate.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>fH = _pl_fusionsci(C,S)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>C</term>
    
            <listitem>
       
               <para>Column vector. C(i) = (f(X(i+1) - f(X(i)) / (X(i+1) - X(i)) for some function f on a grid X.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>Column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>fH</term>
    
            <listitem>
       
               <para>Column vector. Index at which the slope S(i) support the epigraph.
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
      <itemizedlist>
     
         <listitem>
     
            <para>
	Calling _pl_fusionsci(C,S) is equivalent to calling <link linkend='_pl_fusion'>_pl_fusion</link>(C,S). While the former uses scilab built-in functions to speed-up computation, contrary to the later it does not guarantee a linear worst-case running time. See <link linkend='_pl_fusion'>_pl_fusion</link> for more information.
     </para>
     
         </listitem>
     
         <listitem>
	     
            <para>
		     This function is not intended to be used directly but to be called during the computation of the conjugate using the LLT algorithm by the function <link linkend='pl_lft_llt'>pl_lft_llt</link>.
	     </para>
     
         </listitem>

     
      </itemizedlist>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    C=(Y(2:size(Y,1))-Y(1:size(Y,1)-1))./(X(2:size(X,1))-X(1:size(X,1)-1));
    S=C-0.25*ones(size(C, 1));
    [fH]=_pl_fusionsci(C,S)
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='_pl_fusion'>_pl_fusion</link> 
      </member>
    
      <member> 
         <link linkend='pl_lft_llt'>pl_lft_llt</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='_pl_kaFeasiblePoint'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>_pl_kaFeasiblePoint</refname>
    <refpurpose>Convex operators via optimization (OPT), Kernel average feasible point</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>y1 = _pl_kaFeasiblePoint(xstart, x, lambda1, lambda2, domf1, domf2, domg)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>xstart, x</term>
         <listitem>
           <para>real numbers.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda1, lambda2</term>
         <listitem>
           <para>real numbers satisfying lambda1+lambda2=1 and lambda1,lambda2&gt;=0.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf1, domf2, domg</term>
         <listitem>
           <para>Intervals of the form I=[lb,ub] storing sets of
           points where the respective functions are finite.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y1</term>
         <listitem>
           <para>Real number for which the function in the Description
           is finite (or %nan if such a number does not exist).</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes a feasible point, i.e. a point for which the function
       <programlisting>
    lambda1 f1(y1) + lambda2 f2(y2) + lambda1 lambda2 g(y1-y2)
</programlisting>
       is finite.
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
         <member>
           Bryan Gardiner, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='_plq_conv_on_interval'><info><pubdate>05-May-2008</pubdate></info><refnamediv><refname>_plq_conv_on_interval</refname><refpurpose>Piecewise linear quadratic (plq), two-piece convexity on interval</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqco = _plq_conv_on_interval(f1,f2,x1,x3,x5)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>f1</term>
			  
            <listitem>
				  
               <para>One row of a plq function, on the interval (x1,x3].
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>f2</term>
			  
            <listitem>
				  
               <para>The next row of the plq function, on the interval (x3,x5].
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>x1</term>
			  
            <listitem>
				  
               <para>The open lower bound of f1.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>x3</term>
			  
            <listitem>
				  
               <para>The closed lower bound of f1, and the open upper bound of f2.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>x5</term>
			  
            <listitem>
				  
               <para>The closed upper bound of f2.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqco</term>
			  
            <listitem>
				  
               <para>A plq function that is the convex hull of f1 and f2 on (x1,x5].
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     Takes two adjacent pieces of a plq function, and the intervals over which they are defined, and returns a plq function that is defined over the domain of both of the pieces, and is the convex hull of both of the pieces.
    </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
plqf = [1,1,0,0; 4,0,0,1]; 
f1 = plqf(1,:);
f2 = plqf(2,:);
x1=-2.5;
x3=f1(1,1);
x5=f2(1,1);
result = _plq_conv_on_interval(f1,f2,x1,x3,x5); // [0.1270167,1,0,0; 4,0,0.2540333,-0.0161332]
plq_plot(plqf, result, -2.5, 4);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_coDirect'>plq_coDirect</link>
      </member>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='CCA'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>CCA</refname><refpurpose>Computational Convex Analysis toolbox description</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsection><title>Description</title>
	
      <para>
		The CCA package contains numerical algorithms to compute several fundamental transforms of convex analysis for convex and nonconvex functions. Most of its algorithms take a function as input, either as evaluated on a grid or given as a black box, and return the evaluation of the transform on a grid.
	</para>

        <para>
          Many exact transforms work with piecewise linear-quadratic functions and their subdifferentials, and visualizing these models is easy.  See the main pages for <link linkend='plq_function'>PLQ functions</link> and their <link linkend='gph_function'>subdifferentials</link>.
        </para>
	
      <para>
		The transforms currently implemented are:
	</para>
	
      <itemizedlist>
	
         <listitem>
		
            <variablelist>
			
               <varlistentry><term>lft</term><listitem>
				
                  <para>The <literal>Legendre-Fenchel transform</literal> (also called Legendre-Fenchel conjugate, Fenchel conjugate, or convex conjugate): 
					<programlisting>
    f*(s) = sup [ &lt; s, x &gt; - f(x)].
             x
</programlisting>
                  </para>

                  <para>The notation <programlisting>&lt;., .&gt;</programlisting> denotes the standard scalar product. Several linear-time algorithms are implemented (functions with names lft_*).</para>
			
               </listitem></varlistentry>

			
               <varlistentry><term>me</term><listitem>
				
                  <para>The <literal>Moreau envelope</literal> (also called Moreau-Yosida approximate):
					<programlisting>
                                 2
    M(s) = inf f(x) + || s - x ||.
            x
</programlisting>
                  </para>
				
                  <para>The notation <programlisting>||.||</programlisting> denotes the Euclidean norm. Several linear-time algorithms are implemented (functions with names me_*).</para>
			
               </listitem></varlistentry>

			
               <varlistentry><term>pl_bb</term><listitem>
				
                  <para>The lower <literal>convex envelope</literal> (also called <literal>convex hull</literal>): It is the largest convex function minoring a given function. The implementation uses the Beneath-Beyond algorithm to achieve a linear-time worst-case complexity when the points are sorted along the x-axis. It is used by some fast transform algorithms.</para>
			
               </listitem></varlistentry>

            
               <varlistentry><term>pa</term><listitem>
              
                  <para>The <literal>proximal average</literal> transforms one convex function into another continuously:
                <programlisting>
    P(f0,lambda,f1) = [ (1-lambda)(f0 + ||.||^2/2)* + lambda(f1 + ||.||^2/2)* ]* - ||.||^2/2
</programlisting>
                where <programlisting>*</programlisting> is the Fenchel conjugate above.
              </para>
              
                  <para>
                This transform works even if the functions have only partially overlapping or completely disjoint domains.  This algorithm, part of the PLQ framework, runs in O(N(f1) + N(f2)) time, where N(f) is the number of pieces in the PLQ function f.
              </para>
            
               </listitem></varlistentry>

            
               <varlistentry><term>fitz</term><listitem>
              
                  <para>The <literal>Fitzpatrick function</literal> of a finite operator A defined on the real line (functions with names op_fitz* and plq_fitz*):
                <programlisting>
                                               n-2
    F[A,n](x,xstar) =         sup              sum [ &lt;a(i+1)-a(i),astar(i)&gt; ] + &lt;x-a(n-1),astar(n-1)&gt; + &lt;a(1),xstar&gt;
                      (a(1),astar(1)) in A     i=1
                              ...
                   (a(n-1), astar(n-1)) in A
</programlisting>
                The most efficient general algorithm implemented runs in worst-case cubic time.  Other algorithms with fixed parameters are implemented that further reduce the time complexity.
              </para>
            
               </listitem></varlistentry>

            
               <varlistentry><term>rock</term><listitem>
              
                  <para>The <literal>Rockafellar function</literal> of a real, finite operator A:
                <programlisting>
    R(A, a(k))(x) = { (x-a(i))*bm(i) + sum(j=i+1:k, (a(j-1)-a(j))*bm(j)) , if a(i-1) &lt; x &lt;= a(i) &lt;= a(k)
                    { (x-a(i))*bp(i) + sum(j=k:i-1, (a(j+1)-a(j))*bp(j)) , if a(k) &lt;= a(i) &lt;= x &lt;= a(i+1)
</programlisting>
                This algorithm uses PLQ functions to achieve a worst-case linear time complexity.
              </para>
            
               </listitem></varlistentry>
		
            </variablelist>
	
         </listitem>
	
      </itemizedlist>
	
      

  
   </refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
	
      <member>Main functions:</member>
	
      <member>
         <link linkend='pl_lft_llt'>pl_lft_llt</link>
      </member>
    
      <member>
         <link linkend='pl_lft_llt_2d'>pl_lft_llt_2d</link>
      </member>
	
      <member>
         <link linkend='pl_me_llt'>pl_me_llt</link>
      </member>
	
      <member>
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link>
      </member>		
	
      <member>
         <link linkend='pl_bb'>pl_bb</link>
      </member>
	
	
      <member>Alternative algorithms:</member>
	
      <member>
         <link linkend='pl_me_nep'>pl_me_nep</link>
      </member>
	
      <member>
         <link linkend='pl_me_nep_2d'>pl_me_nep_2d</link>
      </member>
	
      <member>
         <link linkend='pl_me_pe'>pl_me_pe</link>
      </member>
	
      <member>
         <link linkend='pl_me_pe_2d'>pl_me_pe_2d</link>
      </member>

    
      <member>Fitzpatrick/Rockafellar algorithms:</member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
	
	
      <member>Functions provided for comparison only:</member>
	
      <member>
         <link linkend='pl_lft_direct'>pl_lft_direct</link>
      </member>
	
      <member>
         <link linkend='pl_lft_direct_2d'>pl_lft_direct_2d</link>
      </member>
	
      <member>
         <link linkend='pl_me_direct'>pl_me_direct</link>
      </member>
	
      <member>
         <link linkend='pl_me_direct_2d'>pl_me_direct_2d</link>
      </member>
	
      <member>
         <link linkend='pl_me_brute_2d'>pl_me_brute_2d</link>
      </member>	
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Contributors</title>
     
      <simplelist>
        <member>Yves Lucet (PI, 1996-)</member>
        <member>Bryan Gardiner (Research Assistant 2008-)</member>
        <member>Scott Fazackerley (USRA 2007, Honours student 2007-08)</member>
        <member>Michael Trienis (M.Sc. student 2006-2007)</member>
        <member>Jeff Dicker (USRA student 2005)</member>
        <member>Andrew Tonner (Research Assistant 2005)</member>
      </simplelist>
  
   </refsection>

  
   <refsection><title>Bibliography</title>
		
         <itemizedlist>
		
            
            <listitem>B. Gardiner, Y. Lucet, Submitted February 2010, Convex Hull Algorithms for Piecewise Linear-Quadratic Functions in Computational Convex Analysis.</listitem>

            <listitem>B. Gardiner, Y. Lucet, Submitted January 2010, Graph-Matrix Calculus for Computational Convex Analysis.</listitem>

            <listitem>B. Gardiner, Y. Lucet, 2009, Numerical Computation of Fitzpatrick Functions, Journal of Convex Analysis, 16(4).</listitem>
        
            <listitem>H. H. Bauschke, Y. Lucet, and M. Trienis, 2008, How To Transform One Convex Function Continuously Into Another, 50(1):115-132.</listitem>

            <listitem>F. P. Preparata and M. I. Shamos, Computational Geometry An Introduction, Series: Monographs in Computer Science, 1st ed. 1985. Corr. 5th printing 1993.</listitem>
        
            <listitem>Y. Lucet, H. H. Bauschke, and M. Trienis, 2007, The Piecewise Linear-Quadratic Model for Computational Convex Analysis, Computational Optimization and Applications.</listitem>
		
            <listitem>Y. Lucet, 2006, Fast Moreau Envelope Computation I: Numerical Algorithms, Numerical Algorithms, 43(3):235-249.</listitem>
		
            <listitem>Y. Lucet, 2005, A linear Euclidean distance transform algorithm based on the Linear-time Legendre Transform, Proceedings of the Second Canadian Conference on Computer and Robot Vision (CRV 2005), IEEE Computer Society Press, 2005.</listitem>
		
            <listitem>Y. Lucet, 1997, Faster than the fast Legendre transform, the linear-time Legendre transform, Numerical Algorithms, 16(2):171-185. Code in Netlib.</listitem>
		
            <listitem>Y. Lucet, 1996, A fast computational algorithm for the Legendre-Fenchel transform, Computational Optimization and Applications, 6(1):27-57.</listitem>

            <listitem> W. L. Hare, 2009, The Proximal Average of Nonconvex Functions: A Proximal Stability Perspective, SIAM Journal on Optimization, 20(2), pp.650-666.</listitem>
	
         </itemizedlist>

  
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_bb'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_bb</refname><refpurpose>Lower convex envelope/convex hull, Beneath-Beyond algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[bbx,bby] = pl_bb (X,Y)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Y</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually Y(i)=f(X(i)) for some function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>bbx</term>
    
            <listitem>
       
               <para>column vector. X-coordinates of the vertices of the lower convex hull.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>bby</term>
    
            <listitem>
       
               <para>column vector. Y-coordinates of the vertices of the lower convex hull.
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>

     
         <para>
        Compute numerically the lower convex envelope of the set of points (X(i), Y(i)) and returns the coordinates of the vertices of the lower convex hull.
     </para>
     
         <para>
	pl_bb implements the Beneath-Beyond algorithm to achieve a linear-time algorithm.
     </para>

  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-2:0.5:2]&apos;;
    Y=(X.^2-1)^2;
    [bbx,bby]=pl_bb(X,Y);
    plot2d(X,Y,2,rect=[-3,-1,3,5]);
    plot(X,Y,&apos;squareblue&apos;);
    plot(bbx,bby,&apos;*red&apos;);
    plot2d(bbx,bby,5);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
	  
      <member> 
         <link linkend='pl_lft_llt'>pl_lft_llt</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title>

   <itemizedlist>

     <listitem>F. P. Preparata and M. I. Shamos, Computational Geometry An Introduction, Series: Monographs in Computer Science, 1st ed. 1985. Corr. 5th printing 1993.</listitem>

   </itemizedlist>

   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='common_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>common_version</refname>
    <refpurpose>Miscellaneous routines, library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = common_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the miscellaneous functions in common_version.sci.  This file is named the same as this function, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
       <member><link linkend='plq_version'>plq_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_generic'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_generic</refname><refpurpose>Generic Legendre Fenchel Transform (LFT)</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   
  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[Conj]=pl_lft_generic(X,Y,S)
[Conj]=pl_lft_generic(X,Y,S,isConvex)
[Conj]=pl_lft_generic(Xr,Xc,f,Sr,Sc)
[Conj]=pl_lft_generic(Xr,Xc,f,Sr,Sc,isConvex)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>
    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Y</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually Y(i)=f(X(i)) for some function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>
    
         <varlistentry>
	  
            <term>isConvex</term>
	  
            <listitem>
		  
               <para>Boolean value either true or false depending if the given function is known to be convex or not. (Note, if convex parameter is true then must use method lft for computation)
		  </para>
	  
            </listitem>
    
         </varlistentry>
  
         <varlistentry>
	  
            <term>Xr</term>
	  
            <listitem>
		  
               <para>column vector of length n.
		  </para>
	  
            </listitem>
  
         </varlistentry>

  
         <varlistentry>
	  
            <term>Xc</term>
	  
            <listitem>
		  
               <para>column vector of length m.
		  </para>
	  
            </listitem>
  
         </varlistentry>

  
         <varlistentry>
	  
            <term>f</term>
	  
            <listitem>
		  
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=fu(Xr(i),Xc(j)) for some function fu.
		  </para>
	  
            </listitem>
  
         </varlistentry>

  
         <varlistentry>
	  
            <term>Sr</term>
	  
            <listitem>
		  
               <para>column vector of size m1.
		  </para>
	  
            </listitem>
  
         </varlistentry>

  
         <varlistentry>
	  
            <term>Sc</term>
	  
            <listitem>
		  
               <para>column vector of size m2. The Conjugate is computed on a grid SrxSc.
		  </para>
	  
            </listitem>
  
         </varlistentry>

  
         <varlistentry>
	  
            <term>Conj</term>
	  
            <listitem>
		  
               <para>matrix of size m1xm2 containing the Conjugate of the function f.
		  </para>
	  
            </listitem>
  
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	The fenchel function is a wrapper for two different conjugate computations depending on the calling sequence. 
	The first calling sequence [Conj]=pl_lft_generic(X,Y,S) uses pl_lft_llt function for the 1D lft computation. 
	The third calling sequence [Conj]=pl_lft_generic(Xr,Xc,f,Sr,Sc) uses the pl_lft_llt_2d function for the 2D lft computation.
	The second and fourth calling sequence have an additional boolean parameter isConvex to speed up computational time for each dimension.
	For a more detailed description see links below.
    </para>
  
   </refsection>
  
   <refsection><title>Examples</title><programlisting role='example'>
//Example 1. First Calling Sequence
X = [1:1:10]&apos;
Y = 0.5.*(X.^2)
[Conjw] = pl_lft_generic(X, Y, X);

//Example 2. Second Calling Sequence
X = [1:1:10]&apos;
Y = 0.5.*(X.^2)
[Conjw] = pl_lft_generic(X, Y, X, %t);

//Example 3. Third Calling Sequence
//xr and xc is the grid which f is evaluated on
Xr=(-2:1:2)&apos;; //x
Xc=(-2:1:2)&apos;; //y
//sr and sc is the grid which f* is evaluated on
Sr=(-2:1:2)&apos;;
Sc=(-2:1:2)&apos;;
f = rand(size(Xr,1),size(Xc,1));
[Conj] = pl_lft_generic(Xr,Xc,f,Sr,Sc);

//Example 4. Fourth Calling Sequence
Xr=(-2:1:2)&apos;; //x
Xc=(-2:1:2)&apos;; //y
//sr and sc is the grid which f* is evaluated on
Sr=(-2:1:2)&apos;;
Sc=(-2:1:2)&apos;;
f = rand(size(Xr,1),size(Xc,1));
[Conj] = pl_lft_generic(Xr,Xc,f,Sr,Sc,%f);
  </programlisting></refsection>

   <refsection><title>See Also</title><simplelist type='inline'>	
	
      <member> 
         <link linkend='pl_lft_llt'>pl_lft_llt</link> 
      </member>
	
      <member> 
         <link linkend='pl_lft_llt_2d'>pl_lft_llt_2d</link> 
      </member>

   </simplelist></refsection>
	
  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_add'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_add</refname>
    <refpurpose>Graph-matrix calculus (GPH), Addition of two functions</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>gph3 = gph_add(gph1, gph2)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph1</term>
         <listitem>
           <para>matrix. A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gph2</term>
         <listitem>
           <para>matrix. A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gph3</term>
         <listitem>
           <para>matrix. The GPH function that is the sum of gph1 and gph2.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the sum of two functions given in GPH matrix form.
       The domain of the resulting function is the intersection of the
       domains of the two input functions.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph1 = [-2,-1,1,2; -2,0,0,2; 1,0,0,1];
gph2 = [0,0,2,2; 0,1,1,2; %inf,0,2,%inf];
gph3 = gph_add(gph1, gph2),
scf(); gph_plot(gph1, gph2);
scf(); gph_plot(gph3);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_eval'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_eval</refname>
    <refpurpose>Graph-matrix calculus (GPH), Function evaluation</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>Y = gph_eval(gph, X)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>X</term>
         <listitem>
           <para>column vector.  The nondecreasing X values at which to evaluate the function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>Y</term>
         <listitem>
           <para>column vector.  The values obtained by evaluating gph at each X value.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Evaluates the given GPH function at a list of points.  Returns
       a vector containing the function value at each point.  Assumes
       that X is in nondecreasing order, to evaluate in linear time.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph = [-1,  0, 0, 1, 2; ..
       -1, -1, 0, 0, 2; ..
        1,  0, 0, 0, 1];
X = (-3:4)&apos;;
Y = gph_eval(gph, X),
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_function'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_function</refname>
    <refpurpose>Graph-matrix calculus (GPH), Function model</refpurpose>
  </refnamediv>

   <refsection>
     <title>Description</title>

     <para>
       A continuous, convex, possibly nonsmooth, PLQ function can be encoded in a &quot;GPH matrix&quot; as follows:

       <programlisting role='example'>
    [x(0)  x(1)  x(2)  ..  x(n)  x(n+1)]
    [s(0)  s(1)  s(2)  ..  s(n)  s(n+1)]
    [y(0)  y(1)  y(2)  ..  y(n)  y(n+1)]

where

x(i) are points in the function&apos;s domain,
s(i) are subgradients of f at x(i),
y(i) are the value of f at x(i): y(i) = f(x(i)).

For all i &lt;= j: x(i) &lt;= x(j)
                s(i) &lt;= s(j)
</programlisting>
     </para>

     <para>
       This is a useful representation because the subdifferentials of
       functions under many convex transforms can be computed by a
       matrix multiplication with the graph of the subdifferential of
       the original function.  The above matrix stores the graph of
       the subdifferential.
     </para>

     <para>
       The subdifferential of a PLQ function f is a piecewise affine
       function, with potentially vertical regions where f is
       nonsmooth.  Hence the matrix merely needs to store the vertices
       in the subdifferential, that are necessary to recover the
       entire graph using piecewise linear interpolation.  Breakpoints
       in the domain of f will be x values in gph, but the converse is
       not necessarily true: redundant points may be stored in the
       matrix, as will often be the case after performing a convex
       transform.  Uniqueness of representation is not guaranteed, as
       it is with PLQ functions.
     </para>

     <para>
       The points at index 0 and n+1 are stored to capture the
       subdifferential on the intervals [-%inf,x(1)] and [x(n),%inf],
       respectively.  To indicate that a function has bounded domain
       on the left, set x(0)=x(1) and y(0)=%inf, and for boundedness
       on the right, set x(n)=x(n+1) and y(n+1)=%inf.  All other y(i),
       and all x(i) and s(i), must be finite.
     </para>

     <para>
       The indicator function of a point x0, f(x) = I_{x0}(x) + y0, is
       stored as the matrix

       <programlisting role='example'>
    [x0 x0]
    [s0 s1]
    [y0 y0]
</programlisting>

       for any s0 &lt; s1.  (If s0 = s1 then the matrix collapses to
       a single column, and the graph is no longer maximal.)
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>

     <para>
       (The matrices listed are just potential representations, that are
     minimal in size.)
     </para>

     <programlisting role='example'>
f(x) = x^2:
    [0 1]
    [0 2]
    [0 1]

f(x) = |x|:
    [-1  0  0  1]
    [-1 -1  1  1]
    [ 1  0  0  1]

f(x) = 0 on [-1,1]; f(x) = %inf elsewhere:
    [ -1 -1  1   1 ]
    [ -1  0  0   1 ]
    [%inf 0  0 %inf]

f(x) = 0 on [-1,1]; f(x) = x^2 - 1 elsewhere:
    [-2 -1 -1  1  1  2]
    [-4 -2  0  0  2  4]
    [ 3  0  0  0  0  3]
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_add'>gph_add</link></member>
       <member><link linkend='gph_eval'>gph_eval</link></member>
       <member><link linkend='gph_isBounded'>gph_isBounded</link></member>
       <member><link linkend='gph_isEqual'>gph_isEqual</link></member>
       <member><link linkend='gph_lft'>gph_lft</link></member>
       <member><link linkend='gph_me'>gph_me</link></member>
       <member><link linkend='gph_pa'>gph_pa</link></member>
       <member><link linkend='gph_plot'>gph_plot</link></member>
       <member><link linkend='gph_prox'>gph_prox</link></member>
       <member><link linkend='gph_scalar'>gph_scalar</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

   <refsection>
     <title>Bibliography</title>
     <itemizedlist>
       <listitem>B. Gardiner, Y. Lucet, Submitted January 2010, Graph-Matrix Calculus for Computational Convex Analysis.</listitem>
     </itemizedlist>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_isBounded'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_isBounded</refname>
    <refpurpose>Graph-matrix calculus (GPH), Function domain bounded test</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>B = gph_isBounded(gph)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>B</term>
         <listitem>
           <para>1x2 boolean matrix.  Whether the function is left- or right-bounded.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Returns a 1x2 boolean matrix B indicating whether the domain of
       the given function is left- or right-bounded.

       <itemizedlist>
         <listitem>B(1) == %t, if and only if gph&apos;s domain is left-bounded.</listitem>
         <listitem>B(2) == %t, if and only if gph&apos;s domain is left-bounded.</listitem>
       </itemizedlist>
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph = [-1,  0, 0, 1, 2; ..
       -1, -1, 0, 0, 2; ..
        1,  0, 0, 0, 1];
B = gph_isBounded(gph),

gph = [0, 0, 1; ..
       0, 1, 1; ..
       0, 0, 1];
B = gph_isBounded(gph),
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_isEqual'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_isEqual</refname>
    <refpurpose>Graph-matrix calculus (GPH), Model equivalence test</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>b = gph_isEqual(gph1, gph2)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph1</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gph2</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>b</term>
         <listitem>
           <para>boolean.  Whether or not the models are equivalent.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Accepts two GPH matrices, and returns true if and only if both
       models represent the same PLQ function, ignoring rounding error
       and redundant points.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph1 = [0 1; 0 2; 0 1];
gph2 = [-1 -0.5; -2 -1; 1 0.25];
b = gph_isEqual(gph1, gph2),
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_lft'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_lft</refname>
    <refpurpose>Graph-matrix calculus (GPH), Legendre-Fenchel conjugate</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>gphstar = gph_lft(gph)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gphstar</term>
         <listitem>
           <para>matrix.  The conjugate of the function gph, in GPH matrix form.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the Legendre-Fenchel conjugate of a given GPH
       function.  For a convex PLQ function f with GPH matrix [x;s;y],
       the GPH matrix of the conjuagte, f*, is

       <programlisting>
    [ [ 0 1 ]   [ x ] ]     [     s      ]
    [ [     ] * [   ] ]     [            ]
    [ [ 1 0 ]   [ s ] ]  =  [     x      ] .
    [                 ]     [            ]
    [   s .* x - y    ]     [ s .* x - y ]
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph = [-1,  0, 0, 1, 2; ..
       -1, -1, 0, 0, 2; ..
        1,  0, 0, 0, 1];
gphstar = gph_lft(gph),
scf(); gph_plot(gph, gphstar);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_me'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_me</refname>
    <refpurpose>Graph-matrix calculus (GPH), Moreau envelope (Moreau-Yoshida approximate)</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>gphme = gph_me(gph, lambda)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant.  A positive smoothing parameter.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gphme</term>
         <listitem>
           <para>matrix.  The Moreau envelope of the function gph, as a GPH matrix.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the Moreau Envelope of a convex PLQ function f, given
       in GPH matrix form.  The Moreau envelope is defined as

       <programlisting>
  (  me   f)(y) = inf [ f(x) + (1/2/lambda)||x-y||^2 ]
   lambda          x
</programlisting>

       For a convex PLQ function f with GPH matrix [x;s;y], the GPH
       matrix of the Moreau envelope with smoothing parameter L &gt; 0 is

       <programlisting>
    [ [ 1 L ]   [ x ] ]     [    x + L*s     ]
    [ [     ] * [   ] ]     [                ]
    [ [ 0 1 ]   [ s ] ]  =  [       s        ] ,
    [                 ]     [                ]
    [ y + (L/2)*s.^2  ]     [ y + (L/2)*s.^2 ]
</programlisting>

       which can be derived from the Moreau envelope formula for
       convex functions (here * denotes the Legendre-Fenchel
       conjugate),

       <programlisting>
    (  me   f) = (f* + (1/2/lambda)||.||^2)* .
     lambda
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph = [-1,  0, 0, 1, 2; ..
       -1, -1, 0, 0, 2; ..
        1,  0, 0, 0, 1];
lambda = 3;
gphme = gph_me(gph, lambda);
scf(); gph_plot(gph, gphme);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_pa'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_pa</refname>
    <refpurpose>Graph-matrix calculus (GPH), Proximal Average (PA)</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[G, X1, X2, Y1, Fq1, Fq2] = gph_pa(G1, G2, lambda)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>G1</term>
         <listitem>
           <para>matrix.  The first input function f1, in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>G2</term>
         <listitem>
           <para>matrix.  The second input function f2, in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant in [0,1].  lambda = lambda2 = the weighting of G2 in the PA.  The weight of G1 is lambda1 = (1-lambda).</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>G</term>
         <listitem>
           <para>matrix.  The proximal average, in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>X1, X2</term>
         <listitem>
           <para>vectors.  The points at which the infimum is attained; X = lambda1.*X1 + lambda2.*X2.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>Y1</term>
         <listitem>
           <para>vector.  Y1=f1(X1), and S = Y1-X is the subdifferential of the PA.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>Fq1, Fq2</term>
         <listitem>
           <para>vectors.  Images of X1 and X2 so the PA is F = lambda1.*Fq1 + lambda2.*Fq2 - X.^2/2.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the proximal average (PA) of two convex functions in
       GPH matrix form.  Computing the PA requires finding the points
       in each of the functions&apos; domains that make the proximal
       average exact for a specific X value.  This is done by
       parameterizing the graph with respect to X1, and determining
       the corresponding X2 values.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
G1 = [-1 0 0 1; -1 -1 0 2; 1 0 0 1];
G2 = [0 0; 0 1; 1 1];
scf();
for lambda = 0:0.1:1
    gph_plot(gph_pa(G1, G2, lambda));
    sleep(250);
end;
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_plot'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_plot</refname>
    <refpurpose>Graph-matrix calculus (GPH), Subdifferential plot</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>gph_plot(gph1, ..., gphN)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph1, ..., gphN</term>
         <listitem>
           <para>matrices.  Functions in GPH matrix form, whose subdifferentials will be plotted.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Plots the subdifferential of each of the functions gph1, ...,
       gphN in turn, on the current graphics window.  Plots the
       piecewise linear interpolation of the points stored in the ith
       matrix with colour i, and puts a mark at each of the points
       with style -i (via plot2d).
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph1 = [-1,  0, 0, 1, 2; ..
        -1, -1, 0, 0, 2; ..
         1,  0, 0, 0, 1];
gph2 = [ 0.5, 0.5,   1; ..
          -1,   1,   1; ..
        %inf,   5, 5.5];

// Plot the subdifferentials.
scf();
gph_plot(gph1, gph2);

// Plot the functions.
scf();
plq_plot(plq_gph(gph1), plq_gph(gph2));
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_plq'><info><pubdate>12-Oct-2009</pubdate></info><refnamediv><refname>gph_plq</refname><refpurpose>Convert a standard PLQ model to a Graph-Matrix Calculus (GPH) model.</refpurpose></refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>gph = gph_plq(plq)</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>plq</term>
        <listitem>
          <para>matrix.  A PLQ function.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>

    <para>
      Converts a PLQ function into a matrix representing its subdifferential by storing points on the subdifferential&apos;s graph, as well as the values of the original function, in order to be able to integrate.
    </para>

    <para>
      This function runs in linear time with respect to the number of pieces in the PLQ function.
    </para>

  </refsection>


  <refsection><title>Examples</title><programlisting role='example'>
// The absolute-value function.
plq = [0,0,-1,0; %inf,0,1,0];
gph = gph_plq(plq),
// gph  =
// 
//  - 1.    0.    0.    1.  
//  - 1.  - 1.    1.    1.  
//    1.    0.    0.    1.  

// A &quot;\_/&quot; function.
plq = [0,0,-1,0; 1,0,0,0; %inf,0,1,-1];
gph = gph_plq(plq),
// gph  =
// 
//  - 1.    0.    0.    1.    1.    2.  
//  - 1.  - 1.    0.    0.    1.    1.  
//    1.    0.    0.    0.    0.    1.  
  </programlisting></refsection>


  <refsection><title>See Also</title><simplelist type='inline'>
      <member>
        <link linkend='gph_function'>gph_function</link>
        <link linkend='plq_gph'>plq_gph</link>
      </member>
  </simplelist></refsection>


  <refsection><title>Authors</title><para>
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_prox'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_prox</refname>
    <refpurpose>Graph-matrix calculus (GPH), Proximal mapping</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>gphprox = gph_prox(gph, lambda)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant.  A positive smoothing parameter.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gphprox</term>
         <listitem>
           <para>matrix.  The proximal mapping of the function gph, as a GPH matrix.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the proximal mapping of a given GPH function.  The
       proximal mapping is the set of minimizers of the Moreau
       envelope,

       <programlisting>
  (  me   f)(y) = argmin [ f(x) + (1/2/lambda)||x-y||^2 ]
   lambda           x
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph = [-1  , 0, 1, 2; ..
        0  , 1, 3, 3; ..
       -0.5, 0, 2, 3];
lambda = 2;
gphprox = gph_prox(gph, lambda),
scf(); gph_plot(gph, gphprox);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_scalar'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_scalar</refname>
    <refpurpose>Graph-matrix calculus (GPH), Function scalar multiplication</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>gph2 = gph_scalar(gph1, lambda)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>gph1</term>
         <listitem>
           <para>matrix.  A function in GPH matrix form.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant.  Nonnegative scalar to multiply by.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>gph2</term>
         <listitem>
           <para>matrix.  The function gph1 scaled by lambda.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Multiplies the function gph1 by the given nonnegative scalar,
       lambda, and returns the new function as a GPH matrix.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
gph1 = [-1,  0, 0, 1, 2; ..
        -1, -1, 0, 0, 2; ..
         1,  0, 0, 0, 1];
gph2 = gph_scalar(gph1, 0.25);
scf(); gph_plot(gph1, gph2);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='gph_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>gph_version</refname>
    <refpurpose>Graph-Matrix Calculus (GPH), library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = gph_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the gph_* functions.  The file gph_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
       <member><link linkend='plq_version'>plq_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_ll'><info><pubdate>02-May-2006</pubdate></info><refnamediv><refname>pl_ll</refname><refpurpose>The Lasry-Lions double envelope approximation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>L = pl_ll(X,Y,S,lambda,mu,algo)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Y</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually f(i)=fu(X(i)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.  
       </para>
    
            </listitem>
    
         </varlistentry>
  
  
    
         <varlistentry>
    
            <term>lambda</term>
    
            <listitem>
       
               <para>constant. This value determines how close the Lasry-Lions envelope will be to the original function.
       </para>
    
            </listitem>
    
         </varlistentry> 

    
         <varlistentry>
    
            <term>mu</term>
    
            <listitem>
       
               <para>constant. This value determines the smoothness factor inside the nonconvex function (i.e. not on the convex hull).  Note: mu &gt; lambda.
       </para>
    
            </listitem>
    
         </varlistentry>
    
    
         <varlistentry>
    
            <term>algo</term>
    
            <listitem>
       
               <para>text. Name of the fast algorithm used to compute the Moreau envelope
       </para>
    
            </listitem>
    
         </varlistentry>  
    
  
      </variablelist>
  
   </refsection>
 
 
 
 
  
   <refsection><title>Description</title>
     
         <para>
            Compute numerically the Lasry-Lions double envelope
	of a set of planar points (X(i),Y(i)) at 
	slopes S, i.e., (M is the Moreau envelope) <programlisting>
    
                 h[mu,lambda]=-M[mu](-M[lambda](x)).
                 
</programlisting>
	It has a complexity which is dependent on the type of algorithm used to compute the Moreau Envelope.
     </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-2:0.01:2]&apos;;
    Y=abs(abs(X)-1);
    S=X;
    mu=0.7;
    lambda=0.4;

    scf(0);clf;
    L = pl_ll(X,Y,S,mu,lambda,pl_me_direct);
    plot2d([abs(abs(X)-1),L]); 
    xtitle(&quot;Lasry Lions double envelope&quot;);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
  	
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
        
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
        
      <member> 
         <link linkend='pl_me_nep'>pl_me_nep</link> 
      </member>
        
      <member> 
         <link linkend='pl_me_pe'>pl_me_pe</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_direct'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_direct</refname><refpurpose>[For comparison only] Legendre-Fenchel conjugate, direct computation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_direct(X,Y,S)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Y</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually Y(i)=f(X(i)) for some function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Conj</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the conjugate f* of the function f evaluated at the points S(j). In other words: Conj(j) = Max(S(j) * X(i) - Y(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
         Warning: This function is provided only for comparison purposes and unit testing, use the more efficient <link linkend='pl_lft_llt'>pl_lft_llt</link> or <link linkend='pl_lft_plt'>pl_lft_plt</link> for faster computation.
       </para>
     
         <para>
            Compute numerically the discrete Legendre transform
	of a set of planar points (X(i),Y(i)) at 
	slopes S, i.e., <programlisting>
                 Conj(j)=max[S(j)*X(i)-Y(i)].
                          i
</programlisting>
	It uses straight computation for a quadratic-time algorithm theta(n*m) with n=length(X)=length(Y) and m=length(S).
     </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    S=(-10:1:10)&apos;;
    X1=(-2:0.2:2)&apos;;f=abs(X1);C1 = pl_lft_direct(X1, f, S);
    X2=(-4:0.4:4)&apos;;f=abs(X2);C2 = pl_lft_direct(X2, f, S);
    X3=(-8:0.8:8)&apos;;f=abs(X3);C3 = pl_lft_direct(X3, f, S);
    X4=(-160:16:160)&apos;;f=abs(X4);C4 = pl_lft_direct(X4, f, S);

    scf(0);clf;
    plot2d([S S S S],[C1 C2 C3 C4],rect=[-3,-0.5,3,10]);
    xtitle(&quot;Convergence of the discrete Legendre transform of the absolute value to the indicator of [-1,1]&quot;);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='pl_lft_direct_d'>pl_lft_direct_d</link>
      </member>
    
      <member>
         <link linkend='pl_lft_llt'>pl_lft_llt</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_direct_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_direct_2d</refname><refpurpose>[For comparison only] 2D Legendre-Fenchel conjugate, direct computation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_direct_2d (Xr, Xc, f, Sr, Sc)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>Xr</term>
			  
            <listitem>
				  
               <para>column vector of length n.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Xc</term>
			  
            <listitem>
				  
               <para>column vector of length m.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>f</term>
			  
            <listitem>
				  
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=ff(Xr(i),Xc(j)) for some function ff.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Sr</term>
			  
            <listitem>
				  
               <para>column vector of size m1.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Sc</term>
			  
            <listitem>
				  
               <para>column vector of size m2. The Conjugate is computed on a grid SrxSc.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Conj</term>
			  
            <listitem>
				  
               <para>matrix of size m1xm2 containing the Conjugate of the function f.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
         Warning: This function is provided only for comparison purposes and unit testing, use the more efficient <link linkend='pl_lft_llt_2d'>pl_lft_llt_2d</link> for faster computation.
       </para>
     
         <para>
       Numerically compute the discrete Legendre transform on the grid Sr x Sc, given a function f(x,y) defined on a grid Xr x Xc, using the <link linkend='pl_lft_direct'>pl_lft_direct</link> algorithm to compute the conjugate in one dimension, then to compute it in the other dimension.  If n==length(Xr)==length(Xc)==length(Sr)==length(Sc) and N=n^2, this function calls pl_lft_direct n times in one dimension and then n times in the other dimension (2*n^3), giving a O(N^(3/2)) running time with respect to the O(n^2) input size.
     </para>
     
         <para>
	    The conjugate of a function in R^2 can be factored to several conjugates which are elements of R.
	 <programlisting>
        f*(s(1),s(2)) = Sup [x(1)y(1) + x(2)y(2) - f(x(1),x(2))]
                     x(1),x(2)
  
                      = Sup [s(1)x(1) + Sup[s(2)x(2) - f(x(1),x(2))]]
                        x(1)            x(2)

</programlisting>
     
         </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    Xr=(-2:0.1:2)&apos;; 
    Xc=(-2:0.1:2)&apos;; 
    Sr=(-2:0.1:2)&apos;;
    Sc=(-2:0.1:2)&apos;;
    deff(&apos;[z]=f(Xr,Xc)&apos;,[&apos;z= Xr^2 + Xc^2&apos;]);
    z=eval3d(f,Xr,Xc);
    result_llt = pl_lft_llt_2d (Xr, Xc, z, Sr, Sc, 0); //llt method
    result_direct = pl_lft_direct_2d (Xr, Xc, z, Sr, Sc, 1); //direct method
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_lft_llt_2d'>pl_lft_llt_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_lft_direct'>pl_lft_direct</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_direct_d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_direct_d</refname><refpurpose>[For comparison only] Legendre-Fenchel conjugate, direct computation on {1,...,n}</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_direct_d(Y)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>Y</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid {1,...,n}: usually Y(i)=f(i) for some function f, with 1 &lt;= i &lt;= n and n=length(Y).
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Conj</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the conjugate f* of the function f evaluated at the points j. In other words: Conj(j) = Max(j * i - Y(i) | over all indexes i).
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
         Warning: This function is provided only for comparison purposes and unit testing, use the more efficient <link linkend='pl_lft_llt_d'>pl_lft_llt_d</link> for faster computation.
       </para>
     
         <para>
	     Wrap over for easier computation of distance transforms. The function calls pl_lft_direct(X,Y,S) with n=length(Y), X=(1:1:n)&apos; and S=X. See <link linkend='pl_lft_direct'>pl_lft_direct</link> for more information.
     </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
        row = [1 2.5 5 8.5 13]&apos;;
        conj_part = -1.*pl_lft_direct_d(row);
        b = isequal(conj_part, [0 -1.5 -4 -7.5 -12]&apos;);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_lft_direct'>pl_lft_direct</link> 
      </member>
    
      <member> 
         <link linkend='pl_lft_llt_d'>pl_lft_llt_d</link> 
      </member>    
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>
  
   <refsection><title>Used Functions</title>
	  
      <para>
		  
         <link linkend='pl_lft_direct'>pl_lft_direct</link>
	  
      </para>
  
   </refsection>   

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_llt'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_llt</refname><refpurpose>Legendre-Fenchel conjugate, LLT algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_llt(X,Y,S)
Conj = pl_lft_llt(X,Y,S,isConvex)
Conj = pl_lft_llt(X,Y,S,isConvex,fusionopt)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Y</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually Y(i)=f(X(i)) for some function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
	    
            <term>isConvex</term>
	    
            <listitem>
		    
               <para>Optional. boolean. Whether or not the dataset (X,Y) is known to be convex.  If false or omitted, <link linkend='pl_bb'>pl_bb</link> is first applied to the data.
		    </para>
	    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
	    
            <term>fusionopt</term>
	    
            <listitem>
		    
               <para>Optional. integer. Select the implementation of the fusion algorithm. fusionopt=1 (or omitted) selects _pl_fusionsci, a fast implementation using scilab syntax but with nonlinear complexity. Any over value selects the _pl_fusion implementation, a (slower) loop-based implementation that runs in linear-time.
		    </para>
	    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Conj</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the conjugate f* of the function f evaluated on at the points S(j). In other words: Conj(j) = Max(S(j) * X(i) - Y(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
     Compute numerically the discrete Legendre transform
     of a set of planar points (X(i),Y(i)) at 
     slopes S, i.e., <programlisting>
        Conj(j)=max[S(j)*X(i)-Y(i)].
                 i
</programlisting>
     It uses the Linear-time Legendre Transform (LLT) algorithm for a linear-time worst-case complexity theta(n+m) with n=length(X)=length(Y) and m=length(S). The LLT algorithm first compute the lower convex envelope of the points (X(i),Y(i)), and then merge two increasing sequences.
     </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    S=(Y(2:size(Y,1))-Y(1:size(Y,1)-1))./(X(2:size(X,1))-X(1:size(X,1)-1));
    Conj=pl_lft_llt(X,Y,S);
    Conj2=pl_lft_llt(X,Y,S,1);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='pl_lft_llt_d'>pl_lft_llt_d</link>
      </member>
    
      <member>
         <link linkend='pl_lft_direct'>pl_lft_direct</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title>
    
      <para>
	Y. Lucet, 1997, Faster than the fast Legendre transform, the linear-time Legendre transform, Numerical Algorithms, 16(2):171-185. Code in Netlib.
    </para>
  
   </refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
     The convex hull computation is performed with the function <link linkend='pl_bb'>pl_bb</link>. The core of the algorithm, which amounts to merging two increasing sequences, is performed with the function <link linkend='_pl_fusion'>_pl_fusion</link> or <link linkend='_pl_fusionsci'>_pl_fusionsci</link> depending on the value of the parameter fusionopt.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_llt_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_llt_2d</refname><refpurpose>2D Legendre-Fenchel conjugate, LLT algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_llt_2d (Xr, Xc, f, Sr, Sc)
Conj = pl_lft_llt_2d (Xr, Xc, f, Sr, Sc, isConvex)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>Xr</term>
			  
            <listitem>
				  
               <para>column vector of length n.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Xc</term>
			  
            <listitem>
				  
               <para>column vector of length m.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>f</term>
			  
            <listitem>
				  
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=ff(Xr(i),Xc(j)) for some function ff.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Sr</term>
			  
            <listitem>
				  
               <para>column vector of size m1.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Sc</term>
			  
            <listitem>
				  
               <para>column vector of size m2. The Conjugate is computed on a grid SrxSc.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>isConvex</term>
			  
            <listitem>
				  
               <para>Boolean, optional.  Whether or not the given function is known to be true.  Defaults to false.  It is passed to <link linkend='pl_lft_llt'>pl_lft_llt</link>.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Conj</term>
			  
            <listitem>
				  
               <para>matrix of size m1xm2 containing the Conjugate of the function f.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
            Numerically compute the discrete Legendre transform on the grid Sr x Sc, given a function f(x,y) defined on a grid Xr x Xc, using the LLT1d algorithm to compute the conjugate in one dimension, then to compute it in the other dimension.  If n==length(Xr)==length(Xc)==length(Sr)==length(Sc), this function calls LLT1d n times in one dimension and then n times in the other dimension (2*n^2), giving a linear running time with respect to the O(n^2) input size.
     </para>
     
         <para>
	    The conjugate of a function in R^2 can be factored to several conjugates which are elements of R.
	 <programlisting>
        f*(s(1),s(2)) = Sup [x(1)y(1) + x(2)y(2) - f(x(1),x(2))]
                     x(1),x(2)
  
                      = Sup [s(1)x(1) + Sup[s(2)x(2) - f(x(1),x(2))]]
                        x(1)            x(2)

</programlisting>
     
         </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    Xr=(-2:0.1:2)&apos;; 
    Xc=(-2:0.1:2)&apos;; 
    Sr=(-2:0.1:2)&apos;;
    Sc=(-2:0.1:2)&apos;;
    deff(&apos;[z]=f(Xr,Xc)&apos;,[&apos;z= Xr^2 + Xc^2&apos;]);
    z=eval3d(f,Xr,Xc);
    result_llt = pl_lft_llt_2d (Xr, Xc, z, Sr, Sc, 0); //llt method
    result_direct = pl_lft_direct_2d (Xr, Xc, z, Sr, Sc, 1); //direct method
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='pl_lft_llt'>pl_lft_llt</link>
      </member>
    
      <member>
         <link linkend='pl_lft_direct_2d'>pl_lft_direct_2d</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
       
         <link linkend='pl_lft_llt'>pl_lft_llt</link> is called twice, once for each dimension.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_llt_3d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_llt_3d</refname><refpurpose>3D Legendre-Fenchel conjugate, LLT algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_llt_3d (Xr, Xc, Xt, f, Sr, Sc, St)
Conj = pl_lft_llt_2d (Xr, Xc, Xt, f, Sr, Sc, St, isConvex)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>Xr</term>
			  
            <listitem>
				  
               <para>column vector of length n.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Xc</term>
			  
            <listitem>
				  
               <para>column vector of length m.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Xt</term>
			  
            <listitem>
				  
               <para>column vector of length k.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>f</term>
			  
            <listitem>
				  
               <para>hypermatrix of size nxmxk. The function f is sampled on a grid Xr x Xc x Xt so f(i,j,k)=ff(Xr(i),Xc(j),Xt(k)) for some function ff.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Sr</term>
			  
            <listitem>
				  
               <para>column vector of size m1.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Sc</term>
			  
            <listitem>
				  
               <para>column vector of size m2.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>St</term>
			  
            <listitem>
				  
               <para>column vector of size m3. The Conugate is computed on a grid SrxScxSt.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>isConvex</term>
			  
            <listitem>
				  
               <para>Boolean, optional.  Whether or not the given function is known to be true.  Defaults to false.  It is passed to <link linkend='pl_lft_llt'>pl_lft_llt</link>.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Conj</term>
			  
            <listitem>
				  
               <para>hypermatrix of size m1xm2xm3 containing the Conjugate of the function f.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
            Numerically compute the discrete Legendre transform on the grid Sr x Sc x St, given a function f(x,y,z) defined on a grid Xr x Xc x Xt, using the LLT1d algorithm to compute the conjugate in one dimension, then to compute it in the other dimension.  If n==length(Xr)==length(Xc)==length(Xt)==length(Sr)==length(Sc)==length(St), this function calls LLT1d n times in each of the three dimensions (3*n^3), giving a linear running time with respect to the O(n^3) input size.
     </para>
     
         <para>
	    The conjugate of a function in R^3 can be factored to several conjugates which are elements of R.
	 <programlisting>
        f*(s(1),s(2)) =     Sup      [x(1)y(1) + x(2)y(2) + x(3)y(3) - f(x(1),x(2),x(3))]
                       x(1),x(2),x(3)
  
                      = Sup [s(1)x(1) + Sup [s(2)x(2) + Sup [s(3)x(3) - f(x(1),x(2),x(3))]]
                        x(1)            x(2)            x(3)
</programlisting>
     
         </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    Xr=(-2:0.25:2)&apos;; 
    Xc=(-2:0.25:2)&apos;; 
    Xt=(-2:0.25:2)&apos;; 
    Sr=(-2:0.25:2)&apos;;
    Sc=(-2:0.25:2)&apos;;
    St=(-2:0.25:2)&apos;;
    deff(&apos;[z]=f(Xr,Xc,Xt)&apos;,[&apos;z= Xr^2 + 2*Xc^2 + 3*Xt^2&apos;]);
    z=zeros(length(Xr), length(Xc), length(Xt));
    for i=1:length(Xr),
        for j=1:length(Xc),
            for k=1:length(Xt),
                z(i,j,k) = f(Xr(i),Xc(j),Xt(k));
            end;
        end;
    end;
    result_llt = pl_lft_llt_3d (Xr, Xc, Xt, z, Sr, Sc, St, 0);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='pl_lft_llt'>pl_lft_llt</link>
      </member>
    
      <member>
         <link linkend='pl_lft_llt_2d'>pl_lft_llt_2d</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
       
         <link linkend='pl_lft_llt'>pl_lft_llt</link> is called three times, once for each dimension.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_llt_d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_lft_llt_d</refname><refpurpose>Legendre-Fenchel conjugate, LLT algorithm on {1,...,n}</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>Conj = pl_lft_llt_d(Y)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
		  
         <varlistentry>
			  
            <term>Y</term>
			  
            <listitem>
				  
               <para>column vector. The value of the function on the grid {1,...,n}: usually Y(i)=f(i) for some function f, with 1 &lt;= i &lt;= n and n=length(Y).
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
		  
         <varlistentry>
			  
            <term>Conj</term>
			  
            <listitem>
				  
               <para>column vector. Contains the value of the conjugate f* of the function f evaluated at the points j. In other words: Conj(j) = Max(j * i - Y(i) | over all indexes i).
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
  
  
   <refsection><title>Description</title>
	  
         <para>
			  Wrap over for easier computation of distance transforms. The function calls pl_lft_llt(X,Y,S) with n=length(Y), X=(1:1:n)&apos; and S=X. See <link linkend='pl_lft_llt'>pl_lft_llt</link> for more information.
		  </para>
  
   </refsection>
  
  
   <refsection><title>Examples</title><programlisting role='example'>
            row = [1 2.5 5 8.5 13]&apos;;
            conj_part = -1.*pl_lft_llt_d(row);
            b = isequal(conj_part, [0 -1.5 -4 -7.5 -12]&apos;);
  </programlisting></refsection>
  
  
   <refsection><title>See Also</title><simplelist type='inline'>
	  
      <member> 
         <link linkend='pl_lft_llt'>pl_lft_llt</link> 
      </member>
	  
      <member> 
         <link linkend='pl_lft_direct_d'>pl_lft_direct_d</link> 
      </member>	  
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>
  
   <refsection><title>Used Functions</title>
	  
      <para>
		  
         <link linkend='pl_lft_llt'>pl_lft_llt</link>
	  
      </para>
  
   </refsection>  

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_lft_plt'><info><pubdate>02-May-2006</pubdate></info><refnamediv><refname>pl_lft_plt</refname><refpurpose>Parametric Legendre Transform, PLT algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[Conj, S] = pl_lft_plt(X, f, df)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually Y(i)=f(X(i)) for some function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>df</term>
    
            <listitem>
       
               <para>column vector. The value of the derivative of the function f evaluated on X, which is also the slope.
       </para>
    
            </listitem>
    
         </varlistentry>

  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
        Compute numerically the Legendre Fenchel transform
	by generating a uniform grid between an interval a,b and
	computing s[i] = f&apos;(x), and f*(s[i]) = x[i]s[i] - f(x[i]). Which returns a set S of slopes in the dom of f* and the values of f* on S.
     </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    function y = f(x), y=0.5 * x.^2, endfunction;
    function s = df(x), s= x, endfunction;
    b=%T;n=8;
    X=(-n/2:1:n/2)&apos;;S=df(X);Y=f(X);
    [Conj, S] = pl_lft_plt(X, f, df);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_lft_llt'>pl_lft_llt</link> 
      </member>
    
      <member> 
         <link linkend='pl_lft_direct'>pl_lft_direct</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='lft_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>lft_version</refname>
    <refpurpose>Legendre-Fenchel transform, library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = lft_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the lft_* functions.  The file lft_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
       <member><link linkend='plq_version'>plq_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_brute_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_brute_2d</refname><refpurpose>[For comparison only] 2D Moreau envelope, brute force computation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>M = pl_me_brute_2d(Xr,Xc,f,Sr,Sc)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>
  
         <varlistentry>
	  
            <term>Xr</term>
	  
            <listitem>
		  
               <para>column vector of length n.
		  </para>
	  
            </listitem>
  
         </varlistentry>
 
  
         <varlistentry>
	  
            <term>Xc</term>
	  
            <listitem>
		  
               <para>column vector of length m.
		  </para>
	  
            </listitem>
  
         </varlistentry>
  
  
         <varlistentry>
	  
            <term>f</term>
	  
            <listitem>
		  
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=fu(Xr(i),Xc(j)) for some function fu.
		  </para>
	  
            </listitem>
  
         </varlistentry>
  
  
         <varlistentry>
	  
            <term>Sr</term>
	  
            <listitem>
		  
               <para>column vector of size m1.
		  </para>
	  
            </listitem>
  
         </varlistentry>
  
  
         <varlistentry>
	  
            <term>Sc</term>
	  
            <listitem>
		  
               <para>column vector of size m2. The Moreau envelope is computed on a grid SrxSc.
		  </para>
	  
            </listitem>
  
         </varlistentry>
  
  
         <varlistentry>
	  
            <term>M</term>
	  
            <listitem>
		  
               <para>matrix of size m1xm2 containing the Moreau envelope of the function f.
		  </para>
	  
            </listitem>
  
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
  
         <para>
      Warning: This function is provided only for comparison purposes and unit testing, use more efficient linear-time algorithms for faster computation.
    </para>
  
         <para>
	Compute numerically the discrete Moreau envelope of a set of spatial points (Xr(i1),Xc(i2),f(i1,i2)) at slopes (Sr(j1),Sc(j2)), i.e. <programlisting>
                                                 2                   2
    M(j1,j2) =  min [ f(i1,i2) + (Sr(j1) - Xr(i1) + (Sc(j2) - Xc(i2))  ].
               i1,i2
</programlisting>
	It performs a brute force computation for a worst-case time complexity for a grid of size N=n^2 of O(N^2)=O(n^4), when n=length(Xr)=length(Xc)=length(Sr)=length(Sc).
  </para>
  
   </refsection>
  
  
   <refsection><title>Examples</title><programlisting role='example'>
    function f=f(lambda,x),f=lambda * x.^2,endfunction
    function g=g(lambda1,lambda2,x,y),g=f(lambda1,x)+f(lambda2,y),endfunction
    lambda1=1;lambda2=2;
    x1=(-10:10)&apos;;x2=(-5:5)&apos;;
    [X, Y]=ndgrid(x1,x2);F=g(lambda1,lambda2,X,Y);
    s1=(-4:4)&apos;;s2=(-5:6)&apos;;
    Xr=x1;Xc=x2;Sr=s1;Sc=s2;
    desired=pl_me_brute_2d(x1,x2,F,s1,s2);
    //1d computation for separable function
    Ms1=pl_me_direct(x1,f(lambda1,x1),s1);
    Ms2=pl_me_direct(x2,f(lambda2,x2),s2);
    t1 = Ms1 * ones(1,size(Ms2,1));
    t2 = ones(size(Ms1,1),1) * Ms2&apos;;
    correct=t1+t2;
    b = and(correct == desired);
</programlisting></refsection>
  
  
   <refsection><title>See Also</title><simplelist type='inline'>
	  
      <member> 
         <link linkend='pl_me_direct_2d'>pl_me_direct_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_nep_2d'>pl_me_nep_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_pe_2d'>pl_me_pe_2d</link> 
      </member>
  
   </simplelist></refsection>
  
  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>
  
  
   

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_direct'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_direct</refname><refpurpose>[For comparison only] Moreau envelope, direct computation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[M,p,P] = pl_me_direct(X,f,S)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually f(i)=fu(X(i)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the Moreau envelope M of the function f evaluated on at the points S(j). In other words: M(j) = Min(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>p</term>
    
            <listitem>
       
               <para>selection of the proximal mapping, p(j) is in  Argmin(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>P</term>
    
            <listitem>
       
               <para>proximal mapping, P(j)=Argmin(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
         Warning: This function is provided only for comparison purposes and unit testing, use more efficient linear-time algorithms for faster computation.
       </para>
     
         <para>
	Compute numerically the discrete Moreau envelope of a set of planar points (X(i),f(i)) at slopes S(j), i.e. <programlisting>
                                          2
       M(j) = min f(i) + || s(j) - x(i) ||.
               i
                                              2
       p(j) in Argmin f(i) + || s(j) - x(i) ||.
                 i
                                             2
       P(j) = Argmin f(i) + || s(j) - x(i) ||.
                i
</programlisting>
	It uses straight computation for a quadratic-time algorithm theta(n*m) with n=length(X)=length(f) and m=length(S).
	</para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    S=(Y(2:size(Y,1))-Y(1:size(Y,1)-1))./(X(2:size(X,1))-X(1:size(X,1)-1));
    [M,p,P]=pl_me_direct(X,Y,S)
</programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_direct_2d'>pl_me_direct_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_nep'>pl_me_nep</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_pe'>pl_me_pe</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_brute_2d'>pl_me_brute_2d</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   


</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_direct_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_direct_2d</refname><refpurpose>[For comparison only] 2D Moreau envelope, direct computation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>M = pl_me_direct_2d(Xr,Xc,f,Sr,Sc)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>Xr</term>
    
            <listitem>
       
               <para>column vector of length n.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Xc</term>
    
            <listitem>
       
               <para>column vector of length m.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=fu(Xr(i),Xc(j)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Sr</term>
    
            <listitem>
       
               <para>column vector of size m1.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Sc</term>
    
            <listitem>
       
               <para>column vector of size m2. The Moreau envelope is computed on a grid SrxSc.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>matrix of size m1xm2 containing the Moreau envelope of the function f.
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
    
      <para>
      Warning: This function is provided only for comparison purposes and unit testing, use more efficient linear-time algorithms for faster computation.
    </para>
	     
      <para>
	Compute numerically the discrete Moreau envelope of a set of spatial points (Xr(i1),Xc(i2),f(i1,i2)) at slopes (Sr(j1),Sc(j2)), i.e. <programlisting>
                                                 2                   2
    M(j1,j2) =  min [ f(i1,i2) + (Sr(j1) - Xr(i1) + (Sc(j2) - Xc(i2))  ].
               i1,i2
</programlisting>
	It uses the separability of the square Euclidean norm to reduce the worst-case time complexity for a grid of size N=n^2 from a brute force computation of O(N^2)=O(n^4) to O(N^(3/2)) = O(n^3), when n=length(Xr)=length(Xc)=length(Sr)=length(Sc).</para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
        function f=f(lambda,x),f=lambda * x.^2,endfunction
        function g=g(lambda1,lambda2,x,y),g=f(lambda1,x)+f(lambda2,y),endfunction
        lambda1=1;lambda2=2;
        x1=(-10:10)&apos;;x2=(-5:5)&apos;;
        [X, Y]=ndgrid(x1,x2);F=g(lambda1,lambda2,X,Y);
        s1=(-4:4)&apos;;s2=(-5:6)&apos;;
        Xr=x1;Xc=x2;Sr=s1;Sc=s2;
        desired=pl_me_direct_2d(x1,x2,F,s1,s2);
        //1d computation for separable function
        Ms1=pl_me_direct(x1,f(lambda1,x1),s1);
        Ms2=pl_me_direct(x2,f(lambda2,x2),s2);
        t1 = Ms1 * ones(1,size(Ms2,1));
        t2 = ones(size(Ms1,1),1) * Ms2&apos;;
        correct=t1+t2;
        b = and(correct == desired);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
	  
      <member> 
         <link linkend='pl_me_brute_2d'>pl_me_brute_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_nep_2d'>pl_me_nep_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_pe_2d'>pl_me_pe_2d</link> 
      </member>
	  
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title>See <link linkend='pl_me_direct'>pl_me_direct</link>   
   </refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
     Computation is reduced to one dimension, which is then handled by <link linkend='pl_me_direct'>pl_me_direct</link>.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_llt'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_llt</refname><refpurpose>Moreau envelope, LLT algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>M = pl_me_llt(X,f,S,fusionopt)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually f(i)=fu(X(i)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
	    
            <term>fusionopt</term>
	    
            <listitem>
		    
               <para>Optional. integer. Select the implementation of the fusion algorithm. fusionopt=1 (or omitted) selects _pl_fusionsci, a fast implementation using scilab syntax but with nonlinear complexity. Any over value selects the _pl_fusion implementation, a (slower) loop-based implementation that runs in linear-time.
		    </para>
	    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the Moreau envelope M of the function f evaluated on at the points S(j). In other words: M(j) = Min(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	Compute numerically the discrete Moreau envelope of a set of planar points (X(i),f(i)) at slopes S(j), i.e. <programlisting>
                                          2
       M(j) = min f(i) + || s(j) - x(i) ||.
               i
</programlisting>
	It reduces computation to computing the Legendre conjugate through the formula <programlisting>
           2                                                      2
M(j) = s(j) - 2 g*(j) with g*(j) = max [ s(j) * x(i) - 1/2 * (x(i) +  f(i)) ]
                                    i
</programlisting>
thereby resulting in a theta(n + m) linear-time algorithm with n=length(X)=length(f) and m=length(S).
	</para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    S=(Y(2:size(Y,1))-Y(1:size(Y,1)-1))./(X(2:size(X,1))-X(1:size(X,1)-1));
    M=pl_me_llt(X,Y,S)
</programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
	
      <member> 
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link> 
      </member>    
	
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
    	
      <member> 
         <link linkend='pl_me_nep'>pl_me_nep</link> 
      </member>
	
      <member> 
         <link linkend='pl_me_pe'>pl_me_pe</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   

  
   <refsection><title>Used Functions</title>
     
      <para>
     The core computation is done by <link linkend='pl_lft_llt'>pl_lft_llt</link>.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_llt_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_llt_2d</refname><refpurpose>2D Moreau envelope, LLT algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[M,g,Conjpartial,Conj] = pl_me_llt_2d(Xr,Xc,f,Sr,Sc)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>Xr</term>
    
            <listitem>
       
               <para>column vector of length n.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Xc</term>
    
            <listitem>
       
               <para>column vector of length m.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=fu(Xr(i),Xc(j)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Sr</term>
    
            <listitem>
       
               <para>column vector of size m1.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Sc</term>
    
            <listitem>
       
               <para>column vector of size m2. The Moreau envelope is computed on a grid SrxSc.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>matrix of size m1xm2 containing the Moreau envelope of the function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>g</term>
    
            <listitem>
       
               <para>matrix of size nxm containing the function g (see formula below).
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Conjpartial</term>
    
            <listitem>
       
               <para>matrix containing the partial conjugate of the function g
    i.e. the one dimensional conjugate applied to each row.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Conj</term>
    
            <listitem>
       
               <para>matrix of size m1xm2 containing the conjugate of the function g (see formula below).
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
 
   <refsection><title>Description</title>
	     
      <para>
	Compute numerically the discrete Moreau envelope of a set of spatial points (Xr(i1),Xc(i2),f(i1,i2)) at slopes (Sr(j1),Sc(j2)), i.e. <programlisting>
                                                  2                   2
    M(j1,j2) =  min [ f(i1,i2) + (Sr(j1) - Xr(i1)) + (Sc(j2) - Xc(i2))  ].
           i1,i2
</programlisting>
	It reduces computation to one dimension, and computes the Legendre conjugate through the formula <programlisting>
           2                                                      2
M(j) = s(j) - 2 g*(j) with g*(j) = max [ s(j) * x(i) - 1/2 * (x(i) + f(i)) ]
                                    i
</programlisting>
thereby resulting in a theta(n*m + m1*m2) linear-time algorithm.</para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
        function f=f(lambda,x),f=lambda * x.^2,endfunction
        function g=g(lambda1,lambda2,x,y),g=f(lambda1,x)+f(lambda2,y),endfunction
        lambda1=1;lambda2=2;
        x1=(-10:10)&apos;;x2=(-5:5)&apos;;
        [X, Y]=ndgrid(x1,x2);F=g(lambda1,lambda2,X,Y);
        s1=(-4:4)&apos;;s2=(-5:6)&apos;;
        Xr=x1;Xc=x2;Sr=s1;Sc=s2;
        desired=pl_me_llt_2d(x1,x2,F,s1,s2);
        //1d computation for separable function
        Ms1=pl_me_direct(x1,f(lambda1,x1),s1);
        Ms2=pl_me_direct(x2,f(lambda2,x2),s2);
        t1 = Ms1 * ones(1,size(Ms2,1));
        t2 = ones(size(Ms1,1),1) * Ms2&apos;;
        correct=t1+t2;
        b = and(correct == desired);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_brute_2d'>pl_me_brute_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_direct_2d'>pl_me_direct_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_nep_2d'>pl_me_nep_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_pe_2d'>pl_me_pe_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title>See <link linkend='pl_me_llt'>pl_me_llt</link>   
   </refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
     Computation is reduced to one dimension, which is then handled by <link linkend='pl_lft_llt'>pl_lft_llt</link>.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_nep'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_nep</refname><refpurpose>Moreau envelope for convex functions, NEP algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[M,P] = pl_me_nep(X,f,S)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually f(i)=fu(X(i)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the Moreau envelope M of the function f evaluated on at the points S(j). In other words: M(j) = Min(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>P</term>
    
            <listitem>
       
               <para>proximal mapping, P(j)=Argmin(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	Compute numerically the discrete Moreau envelope of a set of planar points (X(i),f(i)) at slopes S(j), i.e. <programlisting>
                                          2
       M(j) = min f(i) + || s(j) - x(i) ||.
               i
                                             2
       P(j) = Argmin f(i) + || s(j) - x(i) ||.
                i
</programlisting>
	It uses the non-expansiveness of the proximal (NEP) mapping P to run in linear time theta(n+m) with n=length(X)=length(f) and m=length(S).
	</para>
	
         <para>The algorithm only returns correct result when the proximal mapping P is <literal>nonexpansive</literal>. Otherwise, the algorithms may
     return an incorrect result. Classes of functions f that have a nonexpansive proximal mapping include <literal>convex</literal> functions and
     <literal>prox-regular</literal> functions.</para>
     
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    S=(Y(2:size(Y,1))-Y(1:size(Y,1)-1))./(X(2:size(X,1))-X(1:size(X,1)-1));
    [M,p,P]=pl_me_nep(X,Y,S)
</programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_nep_2d'>pl_me_nep_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_pe'>pl_me_pe</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_nep_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_nep_2d</refname><refpurpose>2D Moreau envelope for convex functions, NEP algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>M = pl_me_nep_2d(Xr,Xc,f,Sr,Sc)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>Xr</term>
    
            <listitem>
       
               <para>column vector of length n.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Xc</term>
    
            <listitem>
       
               <para>column vector of length m.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=fu(Xr(i),Xc(j)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Sr</term>
    
            <listitem>
       
               <para>column vector of size m1.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>Sc</term>
    
            <listitem>
       
               <para>column vector of size m2. The Moreau envelope is computed on a grid SrxSc.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>matrix of size m1xm2 containing the Moreau envelope of the function f.
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
 
   <refsection><title>Description</title>
	     
      <para>
	Compute numerically the discrete Moreau envelope of a set of spatial points (Xr(i1),Xc(i2),f(i1,i2)) at slopes (Sr(j1),Sc(j2)), i.e. <programlisting>
                                                  2                   2
    M(j1,j2) =  min [ f(i1,i2) + (Sr(j1) - Xr(i1)) + (Sc(j2) - Xc(i2))  ].
               i1,i2
</programlisting>
	It reduces computation to one dimension, and computes the Legendre conjugate with the Non-Expansive Prox algorithm thereby resulting
	in a theta(n*m + m1*m2) linear-time algorithm.</para>

	
      <para>Note that the algorithm requires the underlying function f to have a nonexpansive proximal mapping to return the correct result
	(see <link linkend='pl_me_nep'>pl_me_nep</link>).</para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
        function f=f(lambda,x),f=lambda * x.^2,endfunction
        function g=g(lambda1,lambda2,x,y),g=f(lambda1,x)+f(lambda2,y),endfunction
        lambda1=1;lambda2=2;
        x1=(-10:10)&apos;;x2=(-5:5)&apos;;
        [X, Y]=ndgrid(x1,x2);F=g(lambda1,lambda2,X,Y);
        s1=(-4:4)&apos;;s2=(-5:6)&apos;;
        Xr=x1;Xc=x2;Sr=s1;Sc=s2;
        desired=pl_me_nep_2d(x1,x2,F,s1,s2);
        //1d computation for separable function
        Ms1=pl_me_direct(x1,f(lambda1,x1),s1);
        Ms2=pl_me_direct(x2,f(lambda2,x2),s2);
        t1 = Ms1 * ones(1,size(Ms2,1));
        t2 = ones(size(Ms1,1),1) * Ms2&apos;;
        correct=t1+t2;
        b = and(correct == desired);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_brute_2d'>pl_me_brute_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_direct_2d'>pl_me_direct_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_pe_2d'>pl_me_pe_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_nep'>pl_me_nep</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title> See <link linkend='pl_me_nep'>pl_me_nep</link>  
   </refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
	Computation is reduced to one dimension, which is then handled by <link linkend='pl_me_nep'>pl_me_nep</link>.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_pe'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_pe</refname><refpurpose>Moreau envelope, Parabolic Envelope algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>M = pl_me_pe(x0,xn,f)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>x0</term>
    
            <listitem>
       
               <para>real number. Lower bound of the interval.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>xn</term>
    
            <listitem>
       
               <para>real number. Upper bound of the interval.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid
    X=(x0:h:xn)&apos;; where n=length(f), and h=(xn-x0)/(n-1); so f(i)=fu(X(i)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the Moreau envelope M of the function f evaluated on at the points S(j). In other words: M(j) = Min(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	Compute numerically the discrete Moreau envelope of a set of planar points (X(i),f(i)) at slopes S(j)=X(j), i.e. <programlisting>
                                          2
       M(j) = min f(i) + || s(j) - x(i) ||.
               i
</programlisting>
	It reduces computation to a 1,..,n grid with <programlisting>
           2               2                    2
    M(j)= h * min [ ||j-i|| + f(x_0 + i * h) / h  ]
               i
</programlisting>
        
         </para>
	
         <para>
	The algorithms runs in linear time Theta(n) with
	n=length(X)=length(f) by computing the lower parabolic envelope (PE).
	</para>
     
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    X=[-5:0.5:5]&apos;;
    Y=X.^2;
    M=pl_me_pe(-5,5,Y)
</programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_pe_2d'>pl_me_pe_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_nep'>pl_me_nep</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title>

   <itemizedlist>
      <listitem>
        Y. Lucet, 2007, Fast Moreau Envelope Computation I: Numerical Algorithms, Numerical Algorithms, 43(3):235-249.
      </listitem>
      <listitem>
        P. F. Felzenszwalb and D. P. Huttenlocher, 2004, Distance transforms of sampled functions, Tech. Rep. TR2004-1963,
		Cornell Computing and Information Science.
      </listitem>
   </itemizedlist>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_pe_2d'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_pe_2d</refname><refpurpose>2D Moreau envelope, PE algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>M = pl_me_pe_2d(x0,xn,y0,yn,f)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>x0</term>
    
            <listitem>
       
               <para>real number. Lower bound of the x-interval.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>xn</term>
    
            <listitem>
       
               <para>real number. Upper bound of the x-interval.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>y0</term>
    
            <listitem>
       
               <para>real number. Lower bound of the y-interval.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>yn</term>
    
            <listitem>
       
               <para>real number. Upper bound of the y-interval.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X=[(x0:hx:xn)&apos;] x [(y0:hy:yn)&apos;]; where n=size(f,1), hx=(xn-x0)/(n-1),
    m=size(f,2), and hy=(yn-y0)/(m-1), so  f(i,j)=fu(X(i,j)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>matrix of size nxm containing the Moreau envelope of the function f.
       </para>
    
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
 
   <refsection><title>Description</title>
	     
      <para>
	Compute numerically the discrete Moreau envelope of a set of spatial points (X(i1,i2),f(i1,i2)) at slopes (X(j1,j2)). It reduces
	computation to one dimension, and uses the one-dimensional parabolic envelope algorithm (see <link linkend='pl_me_pe'>pl_me_pe</link>) resulting in a
	theta(n*m) linear-time algorithm.</para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
        function f=f(lambda,x),f=lambda * x.^2,endfunction
        function g=g(lambda1,lambda2,x,y),g=f(lambda1,x)+f(lambda2,y),endfunction
        lambda1=1;lambda2=2;
        x1=(-10:10)&apos;;x2=(-5:5)&apos;;
        [X, Y]=ndgrid(x1,x2);F=g(lambda1,lambda2,X,Y);
        s1=(-4:4)&apos;;s2=(-5:6)&apos;;
        Xr=x1;Xc=x2;Sr=s1;Sc=s2;
        desired=pl_me_pe_2d(x1,x2,F,s1,s2);
        //1d computation for separable function
        Ms1=pl_me_direct(x1,f(lambda1,x1),s1);
        Ms2=pl_me_direct(x2,f(lambda2,x2),s2);
        t1 = Ms1 * ones(1,size(Ms2,1));
        t2 = ones(size(Ms1,1),1) * Ms2&apos;;
        correct=t1+t2;
        b = and(correct == desired);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_brute_2d'>pl_me_brute_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_direct_2d'>pl_me_direct_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_nep_2d'>pl_me_nep_2d</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_pe'>pl_me_pe</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Bibliography</title>See <link linkend='pl_me_pe'>pl_me_pe</link>   
   </refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
     Computation is reduced to one dimension, which is then
     handled by <literal>me_pe_d</literal> (me_pe_d is the same function as <link linkend='pl_me_pe'>pl_me_pe</link> except the grid is assumed to be 1,..,n times 1,...,m).
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_plt'><info><pubdate>02-May-2006</pubdate></info><refnamediv><refname>pl_me_plt</refname><refpurpose>Parametric Moreau Envelope, PME algorithm</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[M, z] = pl_me_plt(X, f, df)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>

    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually Y(i)=f(X(i)) for some function f.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>df</term>
    
            <listitem>
       
               <para>column vector. The value of the derivative of the function f evaluated on X, which is also the slope.
       </para>
    
            </listitem>
    
         </varlistentry>

  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	Compute numerically the discrete Moreau envelope of a set of planar points (X(i),f(i)) at slopes S(j), i.e. <programlisting>
                                          2
       M(j) = min f(i) + || s(j) - x(i) ||.
               i
</programlisting>
	It reduces computation to computing the Legendre conjugate through the formula <programlisting>
           2                                                      2
M(j) = s(j) - 2 g*(j) with g*(j) = max [ s(j) * x(i) - 1/2 * (x(i) + f(i)) ],
                                    i
where the conjugate is derived by the Parametric Legendre Transform.
</programlisting>
	
         </para>
     
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
    function y = f(x), y=0.5 * x.^2, endfunction;
    function s = df(x), s= x, endfunction;
    b=%T;n=8;
    X=(-n/2:1:n/2)&apos;;S=df(X);Y=f(X);
    [M,z] = pl_me_plt(X, f, df);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_nep'>pl_me_nep</link> 
      </member>
    
      <member> 
         <link linkend='pl_me_pe'>pl_me_pe</link> 
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='me_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>me_version</refname>
    <refpurpose>Moreau envelope, library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = me_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the me_* functions.  The file me_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
       <member><link linkend='plq_version'>lft_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_me_generic'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>pl_me_generic</refname><refpurpose>Generic Moreau envelope</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   
  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[M] = pl_me_generic(X,Y,S)
[M,p,P] = pl_me_generic(X,Y,S)
[M,g,Conjpartial,Conj] = pl_me_generic(Xr,Xc,f,Sr,Sc)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
  
      <variablelist>
    
         <varlistentry>
    
            <term>X</term>
    
            <listitem>
       
               <para>column vector. A grid of points on which the function is sampled.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>f</term>
    
            <listitem>
       
               <para>column vector. The value of the function on the grid X: usually f(i)=fu(X(i)) for some function fu.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>S</term>
    
            <listitem>
       
               <para>column vector. The grid on which we want to compute the conjugate: f* is evaluated on S.
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>M</term>
    
            <listitem>
       
               <para>column vector. Contains the value of the Moreau envelope M of the function f evaluated on at the points S(j). In other words: M(j) = Min(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>p</term>
    
            <listitem>
       
               <para>selection of the proximal mapping, p(j) is in  Argmin(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>

    
         <varlistentry>
    
            <term>P</term>
    
            <listitem>
       
               <para>proximal mapping, P(j)=Argmin(||S(j) - X(i)||^2 + f(i) | over all indexes i)
       </para>
    
            </listitem>
    
         </varlistentry>
     
         <varlistentry>
     
            <term>Xr</term>
     
            <listitem>
        
               <para>column vector of length n.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>Xc</term>
     
            <listitem>
        
               <para>column vector of length m.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>f</term>
     
            <listitem>
        
               <para>matrix of size nxm. The function f is sampled on a grid Xr x Xc so f(i,j)=fu(Xr(i),Xc(j)) for some function fu.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>Sr</term>
     
            <listitem>
        
               <para>column vector of size m1.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>Sc</term>
     
            <listitem>
        
               <para>column vector of size m2. The Moreau envelope is computed on a grid SrxSc.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>M</term>
     
            <listitem>
        
               <para>matrix of size m1xm2 containing the Moreau envelope of the function f.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>g</term>
     
            <listitem>
        
               <para>matrix of size nxm containing the function g (see formula below).
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>Conjpartial</term>
     
            <listitem>
        
               <para>matrix containing the partial conjugate of the function g
     i.e. the one dimensional conjugate applied to each row.
        </para>
     
            </listitem>
     
         </varlistentry>
 
     
         <varlistentry>
     
            <term>Conj</term>
     
            <listitem>
        
               <para>matrix of size m1xm2 containing the conjugate of the function g (see pl_me_llt_2d for formula).
        </para>
     
            </listitem>
    
         </varlistentry>
  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	The moreau function is a wrapper for three different moreau envelope computations depending on the calling sequence. 
	The first calling sequence [M] = pl_me_generic(X,Y,S) uses pl_me_llt function for the 1D me computation. 
	The second calling sequence [M,p,P] = pl_me_generic(X,Y,S) uses the pl_me_direct function for the 1D me computation.
	The last calling sequence [M,g,Conjpartial,Conj] = pl_me_generic(Xr,Xc,f,Sr,Sc) uses pl_me_llt_2d function for the 2D me computation.
	For a more detailed description see links below.
    </para>
    
   </refsection>
  
   <refsection><title>Examples</title><programlisting role='example'>
//Example 1. First Calling Sequence
X = (1:10)&apos;;S = X;
F=X.^2;
[M] = pl_me_generic(X, F, S);

//Example 2. Second Calling Sequence
X = (1:10)&apos;;S = X;
F=X.^2;
[M,p,P] = pl_me_generic(X,F,S);

//Example 3. Third Calling Sequence
Xr = [1 2.2 3]&apos;; Sr = Xr;
Xc = [1 2 3]&apos;; Sc = Xc;
F = [3 100 100;100 100 100;100 100 2 ];
[MY,g,Conjpartial,Conj] = pl_me_generic(Xr, Xc, F, Sr, Sc);
  </programlisting></refsection>

   <refsection><title>See Also</title><simplelist type='inline'>	
	
      <member> 
         <link linkend='pl_me_llt'>pl_me_llt</link> 
      </member>
	
      <member> 
         <link linkend='pl_me_direct'>pl_me_direct</link> 
      </member>
	
      <member> 
         <link linkend='pl_me_llt_2d'>pl_me_llt_2d</link> 
      </member>

   </simplelist></refsection>
	
  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='op_fitz'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>op_fitz</refname><refpurpose>Evaluate the Fitzpatrick function of a given operator on a grid using the LLT2d algorithm.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>F = op_fitz(A, n, x, xstar)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>A</term>
        
            <listitem>
          
               <para>matrix. An operator [a;a*] where a and a* are row vectors.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>n</term>
        
            <listitem>
          
               <para>integer. The order of the Fitzpatrick function to compute.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector. The x values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>xstar</term>
        
            <listitem>
          
               <para>column vector. The x* values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Evaluates the Fitzpatrick function with order n of an operator A on a grid (x,x*).
      </para>
      
         <para>
        This function uses a recursive algorithm that employs LLT2d to achieve a running time of O(n*m^2 + m*Nxstar + N).  When m==Nx==Nxstar, the running time is O(m^3).
<programlisting>
    F(A, 1, x, xstar) = x * xstar&apos;

    F(A, 2, x, xstar) =       max         [ x*astar + a*xstar - a*astar - I(a,astar*) ]
                         (a,astar) in A

    F(A, 3, x, xstar) =       max         [ x*astar2 + a1*xstar + f(a1,astar2) ]
                        (a1,astar2) in A
    f(a1, a2)         =       max         [ -a1*astar1 - a2*astar2 - I(a1,astar1) - I(a2,astar2) ]
                        (astar1,a2) in A

    where I is the indicator function for the set A (I(x)=0 if x is in A, +%inf otherwise).

    m = size(A, 2);
    Nx = size(x, 1);
    Nxstar = size(xstar, 1);
    N = Nx * Nxstar;
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = -2:2;
astar = 3*a - a + 3;
x = -3:3;
xstar = -3:3;
F1 = op_fitz([a; astar], 1, x, xstar);
F2 = op_fitz([a; astar], 2, x, xstar);
F3 = op_fitz([a; astar], 3, x, xstar);

clf(); alpha=60; theta=-60;
subplot(131); plot3d(x, xstar, F1, alpha=alpha, theta=theta);
subplot(132); plot3d(x, xstar, F2, alpha=alpha, theta=theta);
subplot(133); plot3d(x, xstar, F3, alpha=alpha, theta=theta);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='op_fitz_brute'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>op_fitz_brute</refname><refpurpose>[For comparison only] Evaluate the Fitzpatrick function of a given operator on a grid.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>F = op_fitz_brute(A, n, x, xstar)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>A</term>
        
            <listitem>
          
               <para>matrix. An operator [a;a*] where a and a* are row vectors.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>n</term>
        
            <listitem>
          
               <para>integer. The order of the Fitzpatrick function to compute.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector. The x values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>xstar</term>
        
            <listitem>
          
               <para>column vector. The x* values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Warning: This function is provided only for comparison and unit testing.  Faster results are achieved by using <link linkend='op_fitz'>op_fitz</link>.
      </para>
      
         <para>
        Evaluates the Fitzpatrick function with order n of an operator A on a grid (x,x*).
      </para>
      
         <para>
        This function uses the brute-force approach given by following formula.  For each (x,x*) combination, it computes the maximum of the sums from all permutations of n-1 (a,a*) pairs.  The algorithm runs in exponential O(n*m^(n-1)*N) time, and if m==Nx==Nxstar, then it runs O(n*m^(n+1)).
<programlisting>
                                                 n-2
    F(A, n, x, xstar) =         sup              sum [ &lt;a(i+1)-a(i),astar(i)&gt; ] + &lt;x-a(n-1),astar(n-1)&gt; + &lt;a(1),xstar&gt;
                        (a(1),astar(1)) in A     i=1
                                ...
                     (a(n-1), astar(n-1)) in A

    where &lt;., .&gt; is the scalar dot product.

    m = size(A, 2);
    Nx = size(x, 1);
    Nxstar = size(xstar, 1);
    N = Nx * Nxstar;
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = 1:4;
astar = 2*a^2 - 9;
x = 0:5;
xstar = -1:5;
F = op_fitz_brute([a; astar], 2, x, xstar),

clf(); alpha=51; theta=162;
plot3d(x, xstar, F, alpha=alpha, theta=theta);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='op_fitz_direct'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>op_fitz_direct</refname><refpurpose>[For comparison only] Evaluate the Fitzpatrick function of a given operator on a grid.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>F = op_fitz_direct(A, n, x, xstar)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>A</term>
        
            <listitem>
          
               <para>matrix. An operator [a;a*] where a and a* are row vectors.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>n</term>
        
            <listitem>
          
               <para>integer. The order of the Fitzpatrick function to compute.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector. The x values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>xstar</term>
        
            <listitem>
          
               <para>column vector. The x* values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Warning: This function is provided only for comparison and unit testing.  Faster results are achieved by using <link linkend='op_fitz'>op_fitz</link>.
      </para>
      
         <para>
        Evaluates the Fitzpatrick function with order n of an operator A on a grid (x,x*).
      </para>
      
         <para>
        This function uses the recursive algorithm given by following formula.  It first precomputes F with n-1 for all (a,xstar) pairs, then computes the maximum across all (a,astar) in A for each (x,xstar) pair.  The function F for n=1 is defined to be x*xstar&apos;.  T(n,N), the time required to compute F(A,n,x,xstar), is O(n*m^2*Nxstar + m*N).  If m==Nx==Nxstar, then T(n,N) = O(m^4).
<programlisting>
    F(A, n, x, xstar) =      sup        [ F(A, n-1, a, xstar) + x*astar - a*astar ]
                        (a,astar) in A

    m = size(A, 2);
    Nx = size(x, 1);
    Nxstar = size(xstar, 1);
    N = Nx * Nxstar;
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = 1:4;
astar = 2*a^2 - 9;
x = 0:5;
xstar = -1:5;
F1 = op_fitz_direct([a; astar], 1, x, xstar);
F2 = op_fitz_direct([a; astar], 2, x, xstar);
F3 = op_fitz_direct([a; astar], 3, x, xstar);

clf(); alpha=60; theta=-60;
subplot(131); plot3d(x, xstar, F1, alpha=alpha, theta=theta);
subplot(132); plot3d(x, xstar, F2, alpha=alpha, theta=theta);
subplot(133); plot3d(x, xstar, F3, alpha=alpha, theta=theta);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='op_fitzinf'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>op_fitzinf</refname><refpurpose>Evaluate the Fitzpatrick function of infinite order of an operator on a grid using Rockafellar functions.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>F = op_fitzinf(B, x, xstar)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>B</term>
        
            <listitem>
          
               <para>matrix. An matrix [a;bm;bp] where a, bm (b-), and bp (b+) are row vectors as defined below.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector. The x values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>xstar</term>
        
            <listitem>
          
               <para>column vector. The x* values of the grid on which the Fitzpatrick function is evaluated.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Evaluates the Fitzpatrick function of infinite order of an operator A on a grid (x,x*) using Rockafellar functions, where B is defined as:
<programlisting>
    B : x -&gt; conv(A*x):
          m
        union ( {a(i)} cross [bm(i),bp(i)] )
         i=1

    with a(1) &lt; a(2) &lt; ... &lt; a(m),
         bm(1) &lt;= bp(1) &lt;= bm(2) &lt;= bp(2) &lt;= ... &lt;= bm(m) &lt;= bp(m),
         a(0) = bm(0) = bp(0) = -%inf,
         a(m+1) = bm(m+1) = bp(m+1) = %inf,
         m = size(B,2).
</programlisting>
      
         </para>
      
         <para>
        This function computes the Rockafellar functions R(A,a(k)) for all k=1..m, evaluates the functions at (x,x*), then uses LLT1d algorithm to find the maximum result.  It runs in O(m^2 + m*Nx + N) time, or O(m^2) when m==Nx==Nxstar.  See also <link linkend='plq_rock'>plq_rock</link>, which returns PLQ Rockafellar functions, and <link linkend='plq_fitzinf0'>plq_fitzinf0</link>, which returns PLQ Fitzpatrick functions.
<programlisting>
    F(A, %inf, x, xstar) =    sup     [ a*xstar + R(A,a)(x) ]
                           a in Dom A

    R(A, k)(x) = { (x-a(i))*bm(i) + sum(j=i+1:k, (a(j-1)-a(j))*bm(j)) , if a(i-1) &lt; x &lt;= a(i) &lt;= a(k)
                 { (x-a(i))*bp(i) + sum(j=k:i-1, (a(j+1)-a(j))*bp(j)) , if a(k) &lt;= a(i) &lt;= x &lt;= a(i+1)

    m = size(A, 2);
    Nx = size(x, 1);
    Nxstar = size(xstar, 1);
    N = Nx * Nxstar;
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = -4:4;
bm = [-15,-13,-10,-7,-6,-4,0.5,1,1];
bp = [-13,-11,- 8,-6,-5, 0,  1,1,2];
B = [a;bm;bp];
x = -10:10;
xstar = -10:10;
F = op_fitzinf(B, x, xstar),

clf(); alpha=30; theta=60;
plot3d(x, xstar, F, alpha=alpha, theta=theta);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='op_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>op_version</refname>
    <refpurpose>Finite operator algorithms (OP), library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = op_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the op_* functions.  The file op_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
       <member><link linkend='plq_version'>plq_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_co'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_co</refname>
    <refpurpose>Convex operators via optimization (OPT), Convex hull</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[y, argmin] = opt_me(f, df, domf, x, output)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>f</term>
         <listitem>
           <para>Univariate function, continuous but (potentially) nonsmooth.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>df</term>
         <listitem>
           <para>Univariate function: derivative of f.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf</term>
         <listitem>
           <para>Domain of the function f (set of points where the
           function is finite).  Domains are stored as intervals
           I=[lb,ub] with ub&lt;lb storing an empty set.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>s</term>
         <listitem>
           <para>Vector of points at which to evaluate the convex hull.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>output</term>
         <listitem>
           <para>0: no output, 1: progress bar.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y</term>
         <listitem>
           <para>The values of the convex hull evaluated at each x.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>argmin</term>
         <listitem>
           <para>A point at which the convex hull attains its minimum, for
           each x.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       CURRENTLY BROKEN: NEED A NONCONVEX NONSMOOTH SOLVER (Neldermead
       in Scilab 5.2.0: fminsearch with infinite penalization or
       neldermead with Box complex algorithm). BUT optim WON&apos;T WORK
       SINCE &apos;nd&apos; IS A BUNDLE METHOD (only works for convex functions).
     </para>

     <para>
       Computes the convex hull of a (potentially) nonconvex function
       f, evaluated on vector s, giving the values y such that

       <programlisting>
    y = (co f)(x)

      =    min     {(1-lambda) f(x1) + lambda f(x2) : lambda&gt;=0, (1-lambda) x1 + lambda x2 = x} ,
       x1,x2,lambda
</programlisting>

       where x1,x2,lambda are vectors of the same dimension as x.
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_ic'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_ic</refname>
    <refpurpose>Convex operators via optimization (OPT), Inf-convolution</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[y, argmin] = opt_ic(f1, df1, domf1, f2, df2, domf2, x, output)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>f1, f2</term>
         <listitem>
           <para>Univariate functions, continuous but (potentially) nonsmooth.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>df1, df2</term>
         <listitem>
           <para>Univariate functions: derivatives of f1 and f2 (respectively).</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf1, domf2</term>
         <listitem>
           <para>Domains of functions f1, f2 (set of points where
           function is finite).  Domains are stored as intervals
           I=[lb,ub] with ub&lt;lb storing an empty set.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>x</term>
         <listitem>
           <para>Vector on which the inf-convolution is evaluated.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>output</term>
         <listitem>
           <para>0: no output, 1: progress bar.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y</term>
         <listitem>
           <para>The values of the inf-convolution evaluated at each x.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>argmin</term>
         <listitem>
           <para>A point at which the inf-convolution attains its
           minimum, for each x.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the infimal convolution (a.k.a. epi-addition) of f1 and f2
       evaluated on vector x, giving the values y such that

       <programlisting>
    y = (f1 ic f2)(x) = inf [f1(y) + f2(x-y)] .
                         y
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_ka'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_ka</refname>
    <refpurpose>Convex operators via optimization (OPT), Kernel average</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[y, argmin] = opt_ka(f1, df1, domf1, f2, df2, domf2, g, dg, domg, x, lambda, output)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>f1, f2, g</term>
         <listitem>
           <para>Univariate functions, continuous but (potentially) nonsmooth.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>df1, df2, dg</term>
         <listitem>
           <para>Univariate functions: derivatives of f1, f2, g (respectively).</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf1, domf2, domg</term>
         <listitem>
           <para>Domains of functions f1, f2, g (set of points where
           function is finite).  Domains are stored as intervals
           I=[lb,ub] with ub&lt;lb storing an empty set.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>x</term>
         <listitem>
           <para>Vector of points at which to evaluate the kernel average.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>real number.  lambda1 = 1 - lambda.  lambda2 = lambda.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>output</term>
         <listitem>
           <para>0: no output, 1: progress bar.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y</term>
         <listitem>
           <para>The values of the kernel average evaluated at x.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>argmin</term>
         <listitem>
           <para>A point at which the kernel average attains its
           minimum, for each x.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the (kernel average) g-average of f1 and f2 evaluated
       on vector x, giving the values y such that

       <programlisting>
    y =          inf       [lambda1 f1(y1) + lambda2 f2(y2) + lambda1 lambda2 g(y1-y2)] .
       (lambda1 y1+lambda2 y2=x)
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_lft'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_lft</refname>
    <refpurpose>Convex operators via optimization (OPT), Legendre-Fenchel transform (LFT)</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[y, argmin] = opt_lft(f, df, domf, s, output)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>f</term>
         <listitem>
           <para>Univariate function, continuous but (potentially) nonsmooth.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>df</term>
         <listitem>
           <para>Univariate function: derivative of f.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf</term>
         <listitem>
           <para>Domain of the function f (set of points where the
           function is finite).  Domains are stored as intervals
           I=[lb,ub] with ub&lt;lb storing an empty set.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>s</term>
         <listitem>
           <para>Vector of points at which to evaluate the LFT.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>output</term>
         <listitem>
           <para>0: no output, 1: progress bar.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y</term>
         <listitem>
           <para>The values of the LFT evaluated at each x.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>argmin</term>
         <listitem>
           <para>A point at which the LFT attains its minimum, for
           each x.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the Legendre-Fenchel transform of f evaluated on
       vector s, giving the values y such that

       <programlisting>
    y = f^*(s) = sup [s*x - f(x)] .
                  x
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_me'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_me</refname>
    <refpurpose>Convex operators via optimization (OPT), Moreau envelope</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[y, argmin] = opt_me(f, df, domf, x, lambda, output)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>f</term>
         <listitem>
           <para>Univariate function, continuous but (potentially) nonsmooth.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>df</term>
         <listitem>
           <para>Univariate function: derivative of f.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf</term>
         <listitem>
           <para>Domain of the function f (set of points where the
           function is finite).  Domains are stored as intervals
           I=[lb,ub] with ub&lt;lb storing an empty set.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>x</term>
         <listitem>
           <para>Vector of points at which to evaluate the Moreau envelope.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>Real number.  Positive smoothing parameter.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>output</term>
         <listitem>
           <para>0: no output, 1: progress bar.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y</term>
         <listitem>
           <para>The values of the Moreau envelope evaluated at each x.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>argmin</term>
         <listitem>
           <para>A point at which the Moreau envelope attains its
           minimum, for each x.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the Moreau envelope of f (with smoothing parameter
       lambda) evaluated on vector x, giving the values y such that

       <programlisting>
    y =  M(f)(x) = inf [f(y) + 1/(2*lambda) ||x-y||^2] .
       lambda       y
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_pa'>
  <info>
    <pubdate>17-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_pa</refname>
    <refpurpose>Convex operators via optimization (OPT), Proximal average</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[y, argmin] = opt_pa(f1, df1, domf1, f2, df2, domf2, x, lambda, output)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>f1, f2</term>
         <listitem>
           <para>Univariate functions, continuous but (potentially) nonsmooth.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>df1, df2</term>
         <listitem>
           <para>Univariate functions: derivatives of f1 and f2 (respectively).</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>domf1, domf2</term>
         <listitem>
           <para>Domains of functions f1, f2 (set of points where
           function is finite).  Domains are stored as intervals
           I=[lb,ub] with ub&lt;lb storing an empty set.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>x</term>
         <listitem>
           <para>Vector of points at which to evaluate the proximal average.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>real number.  lambda1 = 1 - lambda.  lambda2 = lambda.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>output</term>
         <listitem>
           <para>0: no output, 1: progress bar.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>y</term>
         <listitem>
           <para>The values of the proximal average evaluated at x.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>argmin</term>
         <listitem>
           <para>A point at which the proximal average attains its
           minimum, for each x.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the (lambda1,lambda2) proximal average of f1 and f2
       evaluated on vector x, giving the values y such that

       <programlisting>
    y =          inf       [lambda1 f1(y1) + lambda2 f2(y2) + 1/2 lambda1 lambda2 ||y1-y2||^2] .
       (lambda1 y1+lambda2 y2=x)
</programlisting>
     </para>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <simplelist>
         <member>
           Yves Lucet, University of British Columbia, BC, Canada
         </member>
       </simplelist>
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='opt_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>opt_version</refname>
    <refpurpose>Convex operators via optimization (OPT), library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = opt_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the opt_* functions.  The file opt_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
       <member><link linkend='plq_version'>plq_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='pl_ph_direct'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>pl_ph_direct</refname>
    <refpurpose>Discrete Pasch-Hausdorff envelope</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>ph = pl_ph_direct(X, Y, S, lambda)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>X</term>
         <listitem>
           <para>column vector of size m.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>Y</term>
         <listitem>
           <para>column vector of size m.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>S</term>
         <listitem>
           <para>column vector of size n.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant.  Scaling parameter for the norm function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>ph</term>
         <listitem>
           <para>The Pasch-Hausdorff envelope evaluated at S.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the Pasch-Hausdorff envelope of a function described
       by the vectors X and Y, where y(i)=f(x(i)).  Returns the
       envelope evaluated at the points in the vector S.  The
       Pasch-Hausdorff envelope is the inf-convolution of the function
       with a scaled norm term,
       <programlisting>
    (f ic lambda||.||)(s) = inf [f(x) + lambda||x-s||].
                             x
</programlisting>
       The discrete Pasch-Hausdorff envelope is computed using the
       formula
       <programlisting>
    S = min [y_i + lambda |x_i - s_i|].
         i
</programlisting>
     </para>

     <para>
       This function runs in O(mn) time.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
lambda = 0.5;
X = [-2;-1;0;1;2];
Y = abs(abs(X)-1);
S = X;
ph = pl_ph_direct(X,Y,S,lambda),
</programlisting>
   </refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plot_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plot_version</refname>
    <refpurpose>Function visualization routines, library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = plot_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the plot_* functions.  The file plot_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plq_version'>plq_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_add'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_add</refname><refpurpose>Piecewise linear quadratic (plq), addition of two plq functions</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqfg = plq_add(plqf,plqg)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqf</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqg</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n&apos; x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqfg</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n&apos;&apos; x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
            Computes the addition of two plq functions (plqf, plqg) and stores the result in plqfg.
    </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
plqf = [-1,1,0,0;1,0,0,1;%inf,1,0,0];
plqg = [0,1,0,0;2,0,1,0;%inf,1,0,-2];
result=plq_add(plqf,plqg);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_build'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_build</refname><refpurpose>Piecewise linear quadratic (plq), build a zeroth- or first-order function approximation</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqf = plq_build(x,f,df)
plqf = plq_build(x,f,df [,needEval] [,exclude] [,method] [,extrapolate])</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>x</term>
			  
            <listitem>
				  
               <para>column vector. A grid of points on which the function is sampled.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>f</term>
			  
            <listitem>
				  
               <para>function or column vector. The function to build a PLQ representation of.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>df</term>
			  
            <listitem>
				  
               <para>function or column vector, optional.  The derivative of f.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>needEval</term>
			  
            <listitem>
				  
               <para>boolean, optional. False, or not entered implies that function does not need to be evaluated and the function is vectorized, otherwise evaluate point by point.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>exclude</term>
			  
            <listitem>
				  
               <para>boolean, optional.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>method</term>
			  
            <listitem>
				  
               <para>boolean, optional.  The method &apos;plq&apos; or not entered implies a normal plq approximation. The method &apos;soqs&apos; uses a Shape-Preserving Osculatory Spline approximation (see McAllister and Roulier, ACM TOMS, Sep. 1981). If no derivatives are provided, forward differentiation is used for &apos;plq&apos; and shape-preserving calculation is used for &apos;soqs&apos;.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>extrapolate</term>
			  
            <listitem>
				  
               <para>string, optional.  &apos;constant&apos; (default) or &apos;bounded&apos; to extend outside of domain by constant of %inf.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
     
         <para>
	    Builds a plq approximation of a function when given a function and optionally the function&apos;s derivative.  If df is given, a first-order model is built, otherwise a zeroth-order model is built.
    </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
//Example 1
x=linspace(0,4)&apos;;
plqf = plq_build(x,exp,exp);
y=plq_eval(plqf,x);

//Example 2
function y=f(x),i1=find(x&lt;0);i2=find(x==0);i3=find(x&gt;0);y(i1)=%inf*ones(i1);y(i2)=0;y(i3)=x(i3).*log(x(i3))-x(i3);endfunction
function y=df(x),i1=find(x&lt;=0);i2=find(x&gt;0);y(i1)=%inf*ones(i1);y(i2)=log(x(i2));endfunction
x=linspace(0,20,3)&apos;;
plqf = plq_build(x,f,df);
y = plq_eval(plqf,x);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_check'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_check</refname>
    <refpurpose>Piecewise linear quadratic (plq), Consistency check</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[b, er] = plq_check(plqf, ind)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A plq function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>ind</term>
         <listitem>
           <para>optional integer.  Which tests to perform on plqf.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>b</term>
         <listitem>
           <para>boolean.  True if and only if plqf is a valid PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>er</term>
         <listitem>
           <para>real number.  The maximum error found in the last test run.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Performs a number of sanity checks on the PLQ function plqf.  If all of
       the tests pass, %t is returned, otherwise %f is returned.
     </para>

     <para>
       Test 1 tests that the plqf&apos;s x values (first column) are increasing.
       Test 2 checks that plqf is continuous.  By default, both tests are
       performed.  The optional index argument can specify an individual test,
       or vector of tests, to run.
     </para>

     <para>
       If test 1 fails, then er is the largest decrease in x value between two
       consecutive pieces.  If test 2 fails, then er is the maximum absolute
       difference between the values of two consecutive pieces at their meeting
       point.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-1 0 0 %inf; 0 0 0 0; 1 0 0 1; %inf 0 0 %inf];
plq_check(plqf),    // False - discontinuous.

plqf = [-1 0 0 %inf; 0 0 0 0; -0.5 0 0 0; %inf 0 0 %inf];
plq_check(plqf),    // False - X not increasing.

plqf = [0 0 -1 0; %inf 0 1 0];
plq_check(plqf),    // True.
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_clean'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_clean</refname><refpurpose>Piecewise linear quadratic (plq), clears duplicate rows</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   
  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[plqClean] = plq_clean(plqDirty)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqDirty</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqClean</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     The plq_clean function is used to help clear duplicate rows which arise during the plq fenchel conjugate operation. For example, the function reduces the number of rows by merging these two pieces of a plq function into one e.g. [0,1,0,0;0,1,0,0] -&gt; [0,1,0,0]. The function also compresses duplicate point values e.g. [0,1,0,1;0,2,0,0] -&gt; [0,1,0,1], and merges adjacent rows that are always infinite (which arise in plq_add).
    </para>

    <para>
      This algorithm runs in O(n) time, where n is the number of pieces in plqf.
    </para>
 	
   </refsection>
  
   <refsection><title>Examples</title><programlisting role='example'>
// Example 1. Clear Duplicate Points
plqDirty=[0,1,0,0;0,2,0,0;1,2,3,4;%inf,3,0,0];
plqClean=plq_clean(plqDirty);
// plqClean == [0,1,0,0;1,2,3,4;%inf,3,0,0];

// Example 2. Clear Duplicate Rows
plqDirty=[0,1,0,0;0,1,0,0;1,2,3,4;%inf,3,0,0];
plqClean=plq_clean(plqDirty);
// plqClean == [0,1,0,0;1,2,3,4;%inf,3,0,0];

// Example 3. Clear Duplicate Infinites
plqDirty = [-1  ,  0,  -1, %inf; ...
            -0.5,  0,   1, %inf; ...
             0  ,  0,   1, 1   ; ...
             0.5,  0,  -1, 1   ; ...
             1  ,  0,  -1, %inf; ...
            %inf,  0,   1, %inf];
plqClean = plq_clean(plqDirty);
// plqClean == [-0.5,  0,  0, %inf; ...
//               0  ,  0,  1, 1   ; ...
//               0.5,  0, -1, 1   ; ...
//              %inf,  0,  0, %inf];
            

  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_co'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_co</refname>
    <refpurpose>Piecewise linear quadratic (plq), Convex hull</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>plqco = plq_coSplit(plqf [,method])</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A plq function whose convex hull will be computed.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>method</term>
         <listitem>
           <para>optional string (default &quot;direct&quot;). Selects the algorithm used.  May be &quot;direct&quot; or &quot;split&quot;.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqco</term>
         <listitem>
           <para>matrix. A plq function that is the convex hull of the original function.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the convex hull of a continuous, but not necessarily
       convex, plq function, where the input and output are given in
       the form of a plq matrix.
     </para>

     <para>
       The method argument selects which algorithm to use.  The
       default is to use the faster, linear-time plq_coDirect
       algorithm, denoted by &quot;direct&quot;.  The plq_coSplit algorithm,
       which is based on convex duality, may be used as well, by
       specifying &quot;split&quot;.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
// The hull of a linear-linear-quadratic function:
plqf = [0,0,0,%inf; 1,0,-1,1; 2,0,1,-1; 3,0,-1,3; 4,0,1,-3; %inf,0,0,%inf];
result = plq_co(plqf),
scf(); plq_plotMultiple(%f, %f, plqf, result);

// The hull of a more complicated function:
plqf = [-5,0,0,%inf; -4,0,0,4; -3,0,-1,0; -2,0,-2,-3; 0,0,-0.5,0; ..
		1,0,1,0; 2,0,0,1; 3,0,1,-1; 4,0,-1,5; 5,0,1,-3; 6,0,2,-8; ..
		6.5,0,0,4; %inf,0,2,-9];
result = plq_co(plqf),
scf(); plq_plotMultiple(%f, %f, plqf, result);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_coDirect'>plq_coDirect</link></member>
       <member><link linkend='plq_coSplit'>plq_coSplit</link></member>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

   <refsection>
     <title>Bibliography</title>
     <itemizedlist>
       <listitem>B. Gardiner, Y. Lucet, Submitted February 2010, Convex Hull Algorithms for Piecewise Linear-Quadratic Functions in Computational Convex Analysis.
       </listitem>
     </itemizedlist>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_coDirect'><info><pubdate>05-May-2008</pubdate></info><refnamediv><refname>plq_coDirect</refname><refpurpose>Piecewise linear quadratic (plq), Convex hull (direct algorithm)</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqco = plq_coDirect(plqf)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqf</term>
			  
            <listitem>
				  
               <para>matrix. A plq function whose convex hull will be computed.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqco</term>
			  
            <listitem>
				  
               <para>matrix. A plq function that is the convex hull of the original function.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     Computes the convex hull of a continuous, but not necessarily convex, plq function, where the input and output are given in the form of a plq matrix.
    </para>

    <para>
      This algorithm performs a left-to-right plane sweep, examining
      two adjacent pieces at a time.  It convexifies two pieces, and
      moves rightward, adding to the &quot;current convex hull&quot; to the left
      of the index, or backtracks if convexity was broken at a point.
      This algorithm runs in linear time, as each iteration either
      moves rightward, backtracks and merges two pieces, or backtracks
      without merging, but this can happen at most a linear number of
      times.
    </para>

   <para>
     A special case is when three adjacent pieces are quadratic,
     linear, and quadratic, each quadratic piece contains the vertex
     of the quadratic, and a linear piece which is not the convex hull
     is between.  To prevent cycling convergent behaviour, the linear
     piece is directly replaced with the convex hull of the two
     quadratic pieces.
   </para>
  
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
// The hull of a linear-linear-quadratic function:
plqf = [0,0,1,0;2,0,0,0;%inf,1,-4,4];
result = plq_coDirect(plqf),
scf(); plq_plot(plqf, result);

// The hull of a more complicated function:
plqf =[-3,1,8,16;0,0,-1,-2;3,0,1,-2;%inf,1,-8,16];
result = plq_coDirect(plqf),
scf(); plq_plot(plqf, result);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>

       <member>
         <link linkend='plq_co'>plq_co</link>
       </member>

       <member>
         <link linkend='plq_coSplit'>plq_coSplit</link>
       </member>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Used Functions</title>
    
      <para>
      
         <link linkend='_plq_conv_on_interval'>_plq_conv_on_interval</link> is used to ensure that pieces of a function are convex on an interval.
    </para>
  
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_coSplit'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_coSplit</refname>
    <refpurpose>Piecewise linear quadratic (plq), Convex hull (splitting algorithm)</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>plqco = plq_coSplit(plqf)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A plq function whose convex hull will be computed.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqco</term>
         <listitem>
           <para>matrix. A plq function that is the convex hull of the original function.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the convex hull of a continuous, but not necessarily convex, plq
       function, where the input and output are given in the form of a plq
       matrix.
     </para>

     <para>
       This algorithm works by reformulating the convex hull of f as
       <programlisting role='example'>
    co f = co min (co g_1, co g_2, ..., co g_n) = (max(g_1*, g_2*, ..., g_n*))* ,
       </programlisting>
       where co represents the convex hull, max/min are functions that
       are the pointwise minima and maxima of their arguments, * is
       the convex conjugate, and each g_i is defined via
       <programlisting role='example'>
    g_i(x) = { f(x), if X(i-1) &lt;= x &lt;= X(i);
             { %inf, otherwise.

    X is the x-values in the GPH matrix: X = gph(1,:).
       </programlisting>
     </para>

     <para>
       plq_coSplit requires worst-case quadratic time, and best-case
       linear time.  g_i* require O(1) work, but the model may grow as
       its maximum is computed with each g_i*, so the max takes O(n^2)
       time to compute, where n is the number of points stored in f&apos;s
       GPH matrix.  The final conjugate is a linear operation.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
// The hull of a linear-linear-quadratic function:
plqf = [0,0,0,%inf; 1,0,-1,1; 2,0,1,-1; 3,0,-1,3; 4,0,1,-3; %inf,0,0,%inf];
result = plq_coSplit(plqf),
scf(); plq_plotMultiple(%f, %f, plqf, result);

// The hull of a more complicated function:
plqf = [-3,1,8,16;0,0,1,4;3,0,-1,4;%inf,1,-8,16];
result = plq_coSplit(plqf),
scf(); plq_plotMultiple(%f, %f, plqf, result);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_co'>plq_co</link></member>
       <member><link linkend='plq_coDirect'>plq_coDirect</link></member>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

   <refsection>
     <title>Bibliography</title>
     <itemizedlist>
       <listitem>B. Gardiner, Y. Lucet, Submitted February 2010, Convex Hull Algorithms for Piecewise Linear-Quadratic Functions in Computational Convex Analysis.</listitem>
     </itemizedlist>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_deconv_lft'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_deconv_lft</refname>
    <refpurpose>Piecewise linear quadratic (plq), deconvolution (via LFT)</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>plqic = plq_deconv_lft(plqf, plqg)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqg</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqic</term>
         <listitem>
           <para>matrix.  The PLQ function that is the deconvolution of plqf and plqg.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the deconvolution of two convex PLQ functions.  The
       deconvolution is defined by the formula
       <programlisting>
    (f ic g)(x) = sup [f(x-y) - g(y)].
                   y
</programlisting>
       Under certain conditions, deconvolution can be rewritten to use
       the Legendre-Fenchel conjugate (denoted *),
       <programlisting>
    (f dc g) = (f* - g*)*.
</programlisting>
       This deconvolution is also a PLQ function.  This algorithm
       runs in O(n + m) time, where n and m are the size of f and g,
       respectively.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-2.5,0,-1,-1.25; -2,1,4,5; 0,0,0,1; 0.5,1,0,1; %inf,0,1,0.75];
plqg = [%inf,1,2,1];
plqdc = plq_deconv_lft(plqf, plqg),
plq_plotMultiple(-4, 3, plqf, plqg, plqdc);
xtitle(&quot;PLQ Convex Deconvolution&quot;);
legend([&quot;f&quot;, &quot;g&quot;, &quot;f dc g&quot;]);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_infconv_lft'>plq_infconv_lft</link></member>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_diff'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_diff</refname>
    <refpurpose>Piecewise linear quadratic (plq), function differentiation</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>plqdf = plq_diff(plqf)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix.  A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqdf</term>
         <listitem>
           <para>matrix.  The PLQ function that is the derivative of plqf.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the piecewise linear derivative of plqf as a PLQ
       function.  An error will be raised if plqf is not differentiable.
     </para>

     <para>
       This function runs in O(n) time, where n is the number of
       pieces in plqf.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-1,1,2,1; 1,0,0,0; %inf,1,-2,1];
plqdf = plq_diff(plqf),
scf(); plq_plot(plqf);
scf(); plq_plot(plqdf);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_dom'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_dom</refname>
    <refpurpose>Piecewise linear quadratic (plq), function effective domain</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>I = plq_minPt(plqf)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>I</term>
         <listitem>
           <para>1x2 matrix [lb;ub].  Gives the interval [lb,ub] on which plqf is finite.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes and returns the effective domain of the given PLQ
       function.  Assumes that the effective domain of the function is
       connected, so that the effective domain is either a closed
       interval [lb,ub], or the empty set (if plqf is %inf everywhere).
     </para>

     <para>
       This function runs in O(1) time.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-2,0,0,%inf; 1,1,0,0; %inf,0,0,%inf];
I = plq_dom(plqf),

plqf = [5,0,0,10];
I = plq_dom(plqf),
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_eval'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_eval</refname><refpurpose>Piecewise linear quadratic (plq), evaluate a plq function on a grid</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[y, k] = plq_eval(plqf,X)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqf</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>X</term>
			  
            <listitem>
				  
               <para>column vector. A grid of points on which the function is sampled.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>y</term>
			  
            <listitem>
				  
               <para>column vector. A grid of points on which the plq function is evaluated on.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>k</term>
			  
            <listitem>
				  
               <para>matrix. A 3 x n matrix with information about which pieces of the plq function contained which X points.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     Evaluates a plq function on a grid. This function is necessary as it allows the plq functions to be simplified into more manageable data with scilab functions such as plotting.  
     </para>
     
         <para>
       k is a matrix shaped like the following, with a column for each unique piece of the plq function an X value was in.  For the i&apos;th unique piece, the values X(L(i):R(i)) were evaluated using the I(i)&apos;th row of the plq function.
<programlisting>
        [I(0)    I(1)    ...     I(n-1)  I(n) ]
        [L(0)    L(1)    ...     L(n-1)  L(n) ]
        [R(0)    R(1)    ...     R(n-1)  R(n) ]

</programlisting>
     
         </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
//Example 1
X=[1;2;4;5;7;8;9];
plqf=[3,0.5,0,0;6,0,0,0;%inf,0,1,0];
[y,k] = plq_eval(plqf,X);

//Example 2
x=linspace(0,4)&apos;;
plqf = build_plq(x,exp,exp);
y=plq_eval(plqf,x);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_fitzinf0'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>plq_fitzinf0</refname><refpurpose>Compute the PLQ Fitzpatrick function of infinite order of an operator on an (x,0) grid using Rockafellar functions.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>F = plq_fitzinf0(B)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>B</term>
        
            <listitem>
          
               <para>matrix. A matrix [a;bm;bp] where a, bm (b-), and bp (b+) are row vectors as defined below.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>F</term>
        
            <listitem>
          
               <para>The infinite-order, PLQ Fitzpatrick function of the operator A.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Compute the PLQ Fitzpatrick function of infinite order of an operator A on a grid (x,0) as a maximum over Rockafellar functions, where B is defined as:
<programlisting>
    B : x -&gt; conv(A*x):
          m
        union ( {a(i)} cross [bm(i),bp(i)] )
         i=1

    with a(1) &lt; a(2) &lt; ... &lt; a(m),
         bm(1) &lt;= bp(1) &lt;= bm(2) &lt;= bp(2) &lt;= ... &lt;= bm(m) &lt;= bp(m),
         a(0) = bm(0) = bp(0) = -%inf,
         a(m+1) = bm(m+1) = bp(m+1) = %inf,
         m = size(B,2).
</programlisting>
      
         </para>
      
         <para>
        This function computes the PLQ Fitzpatrick function in optimal linear time by iterating only over i and using an explicit formula to calculate the maximum over k at each step.  See also <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>, which is an unoptimized version of plq_fitzinf0.
<programlisting>
    F(A, %inf, x, 0) =    sup     [ R(A,a(k))(x) ]
                       a in Dom A

    R(A, k)(x) = { (x-a(i))*bm(i) + sum(j=i+1:k, (a(j-1)-a(j))*bm(j)) , if a(i-1) &lt; x &lt;= a(i) &lt;= a(k)
                 { (x-a(i))*bp(i) + sum(j=k:i-1, (a(j+1)-a(j))*bp(j)) , if a(k) &lt;= a(i) &lt;= x &lt;= a(i+1)
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = -4:4;
bm = [-15,-13,-10,-7,-6,-4,0.5,1,1];
bp = [-13,-11,- 8,-6,-5, 0,  1,1,2];
B = [a;bm;bp];
x = -6:6;
F = plq_fitzinf0(B),
plq_eval(F, x),
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_fitzinf0_direct'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>plq_fitzinf0_direct</refname><refpurpose>[For comparison only] Compute the PLQ Fitzpatrick function of infinite order of an operator on an (x,0) grid using Rockafellar functions.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>F = plq_fitzinf0_direct(B)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>B</term>
        
            <listitem>
          
               <para>matrix. A matrix [a;bm;bp] where a, bm (b-), and bp (b+) are row vectors as defined below.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>F</term>
        
            <listitem>
          
               <para>The infinite-order, PLQ Fitzpatrick function of the operator A.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Warning: This function is provided only for comparison and unit testing.  Faster results are achieved by using <link linkend='plq_fitzinf0'>plq_fitzinf0</link>.
      </para>
      
         <para>
        Compute the PLQ Fitzpatrick function of infinite order of an operator A on a grid (x,0) as a maximum over Rockafellar functions, where B is defined as:
<programlisting>
    B : x -&gt; conv(A*x):
          m
        union ( {a(i)} cross [bm(i),bp(i)] )
         i=1

    with a(1) &lt; a(2) &lt; ... &lt; a(m),
         bm(1) &lt;= bp(1) &lt;= bm(2) &lt;= bp(2) &lt;= ... &lt;= bm(m) &lt;= bp(m),
         a(0) = bm(0) = bp(0) = -%inf,
         a(m+1) = bm(m+1) = bp(m+1) = %inf,
         m = size(B,2).
</programlisting>
      
         </para>
      
         <para>
        This function computes the PLQ Fitzpatrick function in quadratic time by calculating R(A,a(k)) for each k=1:m and taking the PLQ maximum.  See also <link linkend='plq_rock'>plq_rock</link>, which plq_fitzinf0_direct uses to generate Rockafellar functions.
<programlisting>
    F(A, %inf, x, 0) =    sup     [ R(A,a(k))(x) ]
                       a in Dom A

    R(A, k)(x) = { (x-a(i))*bm(i) + sum(j=i+1:k, (a(j-1)-a(j))*bm(j)) , if a(i-1) &lt; x &lt;= a(i) &lt;= a(k)
                 { (x-a(i))*bp(i) + sum(j=k:i-1, (a(j+1)-a(j))*bp(j)) , if a(k) &lt;= a(i) &lt;= x &lt;= a(i+1)
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = -4:4;
bm = [-15,-13,-10,-7,-6,-4,0.5,1,1];
bp = [-13,-11,- 8,-6,-5, 0,  1,1,2];
B = [a;bm;bp];
x = -6:6;
F = plq_fitzinf0_direct(B),
plq_eval(F, x),
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_rock'>plq_rock</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_function'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_function</refname><refpurpose>Piecewise linear quadratic (plq) function description</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   
 
  
   <refsection><title>Description</title>
     
         <para>
	     A plq function is a piecewise function, where each piece is either a linear or a quadratic polynomial.  It is stored as a matrix, where each row represents one piece of the function.
    </para>

         <programlisting>

Typical plq matrix 

        [x(1)    a(1)    b(1)    c(1) ]      f(x) = a(1)*x^2 + b(1)*x + c(1), if -%inf &lt; x &lt;= x(1)
        [x(2)    a(2)    b(2)    c(2) ]      f(x) = a(2)*x^2 + b(2)*x + c(2), if x(1) &lt; x &lt;= x(2)
        [ &apos;        &apos;       &apos;       &apos;  ]       &apos;           &apos;            &apos;            &apos;           &apos;
        [ &apos;        &apos;       &apos;       &apos;  ]       &apos;           &apos;            &apos;            &apos;           &apos;
        [x(n-1)  a(n-1)  b(n-1) c(n-1)]      f(x) = a(n-1)*x^2 + b(n-1)*x + c(n-1), if x(n-2) &lt; x &lt;= x(n-1)
        [%inf    a(n)    b(n)   c(n)  ]      f(x) = a(n)*x^2 + b(n)*x + c(n), if x(n-1) &lt; x &lt;= %inf

Where 

&apos;x&apos; is where the domain is defined
&apos;a&apos; is the quadratic term
&apos;b&apos; is the linear term
&apos;c&apos; is the constant term

And a typical row is  a(i)*x^2 + b(i)*x + c(i) if x(i-1) &lt; x &lt;= x(i).

</programlisting>
	
         <para>
		Note that singleton indicator functions are given in a special form such that [x(1),0,0,c(1)] = I_{x(1)}(x) + c(1).
	</para>
 	
   </refsection>
  
   <refsection><title>Examples</title><programlisting role='example'>
plqAbs = [0,0,-1,0;%inf,0,1,0]; // The function y = |x|
plqQuad = [%inf,1/5,-4/5,4/5];  // The function y = (x-2)^2 / 5 = (x^2 - 4*x + 4) / 5
plq_plot(plqAbs, plqQuad);      // Plot the functions together
  </programlisting></refsection>

   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_add'>plq_add</link>
      </member>
    
      <member>
         <link linkend='plq_build'>plq_build</link>
      </member>
    
      <member>
         <link linkend='plq_check'>plq_check</link>
      </member>
    
      <member>
         <link linkend='plq_clean'>plq_clean</link>
      </member>
    
      <member>
         <link linkend='plq_co'>plq_co</link>
      </member>
    
      <member>
         <link linkend='plq_coDirect'>plq_coDirect</link>
      </member>
    
      <member>
         <link linkend='plq_coSplit'>plq_coSplit</link>
      </member>
    
      <member>
         <link linkend='plq_deconv_lft'>plq_deconv_lft</link>
      </member>
    
      <member>
         <link linkend='plq_diff'>plq_diff</link>
      </member>
    
      <member>
         <link linkend='plq_dom'>plq_dom</link>
      </member>
    
      <member>
         <link linkend='plq_eval'>plq_eval</link>
      </member>
    
      <member>
         <link linkend='plq_infconv_lft'>plq_infconv_lft</link>
      </member>
    
      <member>
         <link linkend='plq_isConvex'>plq_isConvex</link>
      </member>
    
      <member>
         <link linkend='plq_isEqual'>plq_isEqual</link>
      </member>
    
      <member>
         <link linkend='plq_lft'>plq_lft</link>
      </member>
    
      <member>
         <link linkend='plq_max'>plq_max</link>
      </member>
    
      <member>
         <link linkend='plq_me'>plq_me</link>
      </member>
    
      <member>
         <link linkend='plq_me_max_scale'>plq_me_max_scale</link>
      </member>
    
      <member>
         <link linkend='plq_min'>plq_min</link>
      </member>
    
      <member>
         <link linkend='plq_minPt'>plq_minPt</link>
      </member>
    
      <member>
         <link linkend='plq_gpa'>plq_gpa</link>
      </member>
    
      <member>
         <link linkend='plq_pa'>plq_pa</link>
      </member>
	
      <member>
         <link linkend='plq_pa_mu'>plq_pa_mu</link>
      </member>
    
      <member>
         <link linkend='plq_plot'>plq_plot</link>
      </member>
    
      <member>
         <link linkend='plq_plotMultiple'>plq_plotMultiple</link>
      </member>
    
      <member>
         <link linkend='plq_plotpa'>plq_plotpa</link>
      </member>
    
      <member>
         <link linkend='plq_plotpa_lambdaSet'>plq_plotpa_lambdaSet</link>
      </member>
    
      <member>
         <link linkend='plq_plotpa_muSet'>plq_plotpa_muSet</link>
      </member>
    
      <member>
         <link linkend='plq_proj'>plq_proj</link>
      </member>
    
      <member>
         <link linkend='plq_scalar'>plq_scalar</link>
      </member>

   </simplelist></refsection>
  
   <refsection><title>Authors</title><para>
	
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_gpa'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_gpa</refname>
    <refpurpose>Piecewise linear quadratic (plq), generalized proximal average</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>pa = plq_gpa(p0, p1, lambda, r)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>p0, p1</term>
         <listitem>
           <para>matrices. PLQ functions.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant in [0,1].  lambda1 = 1 - lambda.  lambda2 = lambda.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>r</term>
         <listitem>
           <para>positive constant.  Parameter to the Moreau envelope.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the nonconvex proximal average of two (potentially
       nonconvex) PLQ functions p0 and p1, via the formula
       <programlisting>
    PA[r,lambda1,lambda2](p0, p1) = -M[1/(r+lambda1*lambda2)] ( -lambda1 M[1/r](f) - lambda2 M[1/r](g) ),
</programlisting>
       where M[k] is the Moreau envelope with smoothing parameter k.
     </para>

     <para>
       This algorithm runs in O(n + m) time, where n and m are the
       number of pieces in p0 and p1, respectively.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
p0 = [0,0,0.5,-1; %inf,0,-0.5,-1];
p1 = [%inf,0.25,0,0];
pa = plq_gpa(p0,p1,0.5,1),
scf(); plq_plotMultiple(-5, 5, p0, p1, pa);
legend([&quot;p0&quot;, &quot;p1&quot;, &quot;pa&quot;]);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
       <member><link linkend='plq_pa'>plq_pa</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

   <refsection>
     <title>Bibliography</title>
     <itemizedlist>
       <listitem>
         
         W. L. Hare, 2009, The Proximal Average of Nonconvex Functions: A Proximal Stability Perspective, SIAM Journal on Optimization, 20(2), pp.650-666.
       </listitem>
     </itemizedlist>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_gph'><info><pubdate>12-Oct-2009</pubdate></info><refnamediv><refname>plq_gph</refname><refpurpose>Convert a PLQ subdifferential model to a standard PLQ model.</refpurpose></refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>plq = plq_gph(gph)</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>gph</term>
        <listitem>
          <para>matrix.  The subdifferential of a PLQ function.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>

    <para>
      Converts the graph of the subdifferential of a PLQ function into the corresponding PLQ data structure.  Uses the value of the function stored at each x value in gph and integrates across each segment.
    </para>

    <para>
      This function runs in linear time with respect to the number of points in the input graph.
    </para>

  </refsection>


  <refsection><title>Examples</title><programlisting role='example'>
// The indicator function I_[-1,1].
// Defined to be 0 inside [-1,1] and %inf outside.
gph = [-1, -1, 1, 1; ..
       -1, 0, 0, 1; ..
       %inf, 0, 0, %inf];
plq = plq_gph(gph),
// plq  =
// 
//  - 1.    0.    0.   Inf  
//    1.    0.    0.    0.  
//   Inf    0.    0.   Inf  

// A PLQ function:
//   x in [-1,1]: 0
//     otherwise: x^2 - 1
gph = [-2, -1, -1, 1, 1, 2; ..
       -4, -2, 0, 0, 2, 4; ..
       3, 0, 0, 0, 0, 3];
plq = plq_gph(gph),
// plq  =
// 
//  - 1.    1.    0.  - 1.  
//    1.    0.    0.    0.  
//   Inf    1.    0.  - 1.  
  </programlisting></refsection>


  <refsection><title>See Also</title><simplelist type='inline'>
      <member>
        <link linkend='gph_plq'>gph_plq</link>
        <link linkend='plq_function'>plq_function</link>
      </member>
  </simplelist></refsection>


  <refsection><title>Authors</title><para>
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_infconv_lft'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_infconv_lft</refname>
    <refpurpose>Piecewise linear quadratic (plq), Inf-convolution (via LFT)</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>plqic = plq_infconv_lft(plqf, plqg)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqg</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqic</term>
         <listitem>
           <para>matrix.  The PLQ function that is the inf-convolution of plqf and plqg.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the infimal convolution (or epi-addition) of two
       convex PLQ functions.  The inf-convolution is defined by the
       formula
       <programlisting>
    (f ic g)(x) = inf [f(y) + g(x-y)].
                   y
</programlisting>
       When f and g are convex (and proper, lower-semicontinuous), we
       rewrite the inf-convolution in terms of the Legendre-Frenchel
       conjugate (denoted by *),
       <programlisting>
    (f ic g) = (f* + g*)*.
</programlisting>
       This inf-convolution is also a PLQ function.  This algorithm
       runs in O(n + m) time, where n and m are the size of f and g,
       respectively.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-1,0,-1,0; 1,0,0,1; %inf,0,1,0];
plqg = [%inf,1,2,1];
plqic = plq_infconv_lft(plqf, plqg),
plq_plotMultiple(-4, 3, plqf, plqg, plqic);
xtitle(&quot;PLQ Convex Inf-convolution&quot;);
legend([&quot;f&quot;, &quot;g&quot;, &quot;f ic g&quot;]);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_deconv_lft'>plq_deconv_lft</link></member>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_isConvex'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_isConvex</refname>
    <refpurpose>Piecewise linear quadratic (plq), convexity test</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>b = plq_isConvex(plqf)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>b</term>
         <listitem>
           <para>boolean.  Whether or not plqf is a convex function.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Determines whether or not plqf is a convex PLQ function, by
       testing whether it is equal to its convex hull.  True is
       returned if and only if plqf is convex.  This function runs in
       O(n) time, where n is the number of pieces in plqf.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-1,1,0,-1; 1,0,0,0; %inf,1,0,-1];
plq_isConvex(plqf),
scf(); plq_plot(plqf);

plqf = [-3,1,8,16;0,0,-1,-2;3,0,1,-2;%inf,1,-8,16];
plq_isConvex(plqf),
scf(); plq_plot(plqf);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>


<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_isEqual'>
  <info>
    <pubdate>14-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_isEqual</refname>
    <refpurpose>Piecewise linear quadratic (plq), Model equivalence test</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>b = plq_isEqual(plqf, plqg)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix.  A PLQ function with dimensions n x 4.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqg</term>
         <listitem>
           <para>matrix.  A PLQ function with dimensions n&apos; x 4.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>b</term>
         <listitem>
           <para>boolean.  Whether or not the models are equivalent.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Accepts two PLQ functions, and returns true if and only if the
       functions are equal, ignoring rounding error and duplicate
       adjacent pieces.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [%inf 1 0 0];
plqg = [0 1 0 0;%inf 1 0 0];
b = plq_isEqual(plqf, plqg),

eps = 1e-12;
plqf = [%inf 1 0 0];
plqg = [%inf 1+eps eps -eps];
b = plq_isEqual(plqf, plqg),
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='gph_function'>gph_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_lft'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_lft</refname><refpurpose>Piecewise linear quadratic (plq), Legendre-Fenchel conjugate</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqfstar = plq_lft(plqf)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqf</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqfstar</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
            Compute the Legendre-Fenchel transform (LFT) of a convex plq function, where the input and output are given in the form of a plq matrix. 
    </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
//Example 1.
plqf=[0,1,0,0;1,0,1,0;%inf,3, -4, 2];
result= plq_lft(plqf);

//Example 2.
//Building a plq function from the exponential function. i.e. plq_lft function requires a plq function as input, therefore we must build it.
plqf=plq_build(linspace(-2,2,10),exp,exp,%f);
x=linspace(0,4)&apos;; result= plq_lft(plqf);  y=plq_eval(plqf,x);
plot2d(x,y);

  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_ll'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_ll</refname>
    <refpurpose>Piecewise linear quadratic (plq), Lasry-Lions double envelope</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>plqg = plq_ll(plqf, lambda, mu)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>lambda</term>
         <listitem>
           <para>constant.  This value determines how close the Lasry-Lions envelope will be to the original function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>mu</term>
         <listitem>
           <para>constant.  This value determines the smoothness factor inside the nonconvex function (i.e. not on the convex hull).  Note: mu &gt; lambda.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>plqg</term>
         <listitem>
           <para>matrix.  The resulting PLQ function.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Computes the Lasry-Lions double envelope of a given PLQ function, using the formula (M is the Moreau envelope)
       <programlisting>
    h[mu,lambda]=-M[mu](-M[lambda](x)).
</programlisting>
     </para>

     <para>
       This algorithm, like its subroutines, runs in linear time.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-1,0,-1,-1; 0,0,1,1; 1,0,-1,1; %inf,0,1,-1];
mu = 0.7;
lambda = 0.4;
plqg = plq_ll(plqf, lambda, mu);
plq_plot(plqf, plqg, -3, 3);
xtitle(&quot;Lasry-Lions double envelope&quot;);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_max'><info><pubdate>22-Aug-2008</pubdate></info><refnamediv><refname>plq_max</refname><refpurpose>Piecewise linear quadratic (plq), Maximum function</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[plqm, maxf] = plq_max(plqf, plqg)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>plqf</term>
        
            <listitem>
          
               <para>matrix. One of the plq functions to compute the maximum of.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>plqg</term>
        
            <listitem>
          
               <para>matrix. The other plq function to compte the maximum of.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>plqm</term>
        
            <listitem>
          
               <para>matrix. A plq function equal to the maximum of plqf and plqg.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>maxf</term>
        
            <listitem>
          
               <para>matrix. Specifies the intervals over which each function was the maximum.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Creates a plq function representing the maximum of plqf and plqg for all x values.  This function runs in O(m+n) time and returns a plq function containing O(m+n) pieces, where m and n are the number of pieces in plqf and plqg, respectively.
      </para>
     
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
plqf = [-1,0,-1,-1;%inf,0,1,1];
plqg = [1,0,-1,1;%inf,0,1,-1];
plqm = plq_max(plqf, plqg),
clf(); plq_plotMultiple(-4, 4, plqf, plqg, plqm);

plqf = [%inf,1,0,0];
plqg = [0,0,-3,-1;%inf,0,3,-1];
plqm = plq_max(plqf, plqg),
clf(); plq_plotMultiple(-4, 4, plqf, plqg, plqm);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_me'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_me</refname><refpurpose>Piecewise linear quadratic (plq), Moreau envelope</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqme = plq_me(plqf,lambda)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqf</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>lambda</term>
			  
            <listitem>
				  
               <para>constant, positive smoothing parameter.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqme</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     Compute the Moreau envelope (ME) transform of a convex plq function, where the input and output is given in the form of a plq matrix. The Moreau Envelope is computed using the formula:<programlisting>
    M[lambda](s) = (1/2lambda)||s||^2 - (1/lambda)g*[lambda](s),
    where g[lambda](x) = (1/2)*||x||^2 + lambda*f(x),
      and * represents the Fenchel Conjugate.
</programlisting>
    
         </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
lambda=1;
fctn = [%inf,1/2,0,0];
result = plq_me(fctn,lambda);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

  
   <refsection><title>Used Functions</title>
     
      <para>
       
         <link linkend='plq_me_max_scale'>plq_me_max_scale</link> is called when nonconvexity conditions apply.
     </para>
  
   </refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_me_max_scale'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_me_max_scale</refname><refpurpose>Piecewise linear quadratic (plq), Maximum scale for Moreau envelope</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>scale = plq_me_max_scale(plqf1, ..., plqfN)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>plqf1 ... plqfN</term>
        
            <listitem>
          
               <para>matrices. PLQ functions for which to compute the maximum scale.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>scale</term>
        
            <listitem>
          
               <para>constant. The maximum smoothing parameter that plq_me will accept over all the given functions.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>
  
  
   <refsection><title>Description</title>
      
         <para>
        This function computes the maximum smoothing parameter that may be passed as &quot;lambda&quot; or &quot;mu&quot; into <link linkend='plq_me'>plq_me</link> such that a set of nonconvex functions have finite Moreau envelopes.  Otherwise, if the smoothing parameter is too high, g* below will be infinite everywhere because a convex hull cannot be computed.
        <programlisting>
    Moreau envelope formula:
    M[lambda](s) = (1/2lambda)||s||^2 - (1/lambda)g*[lambda](s),
    where g[lambda](x) = (1/2)*||x||^2 + lambda*f(x),
      and * represents the Fenchel Conjugate.
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
f1 = [0,-1,0,0;%inf,-2,0,0];
plq_me_max_scale(f1),          # -1/2/(-2) == 0.25
f2 = [1,0,1,0;2,0,-1,2;%inf,-3,0,0];
plq_me_max_scale(f2),          # -1/2/(-3) == 0.167
plq_me_max_scale(f1, f2);      # 0.167
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_min'><info><pubdate>22-Aug-2008</pubdate></info><refnamediv><refname>plq_min</refname><refpurpose>Piecewise linear quadratic (plq), Minimum function</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[plqm, minf] = plq_min(plqf, plqg)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>plqf</term>
        
            <listitem>
          
               <para>matrix. One of the plq functions to compute the minimum of.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>plqg</term>
        
            <listitem>
          
               <para>matrix. The other plq function to compte the minimum of.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>plqm</term>
        
            <listitem>
          
               <para>matrix. A plq function equal to the minimum of plqf and plqg.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>minf</term>
        
            <listitem>
          
               <para>matrix. Specifies the intervals over which each function was the minimum.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Creates a plq function representing the minimum of plqf and plqg for all x values.  This function runs in O(m+n) time and returns a plq function containing O(m+n) pieces, where m and n are the number of pieces in plqf and plqg, respectively.
      </para>
     
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
plqf = [-1,0,-1,-1;%inf,0,1,1];
plqg = [1,0,-1,1;%inf,0,1,-1];
plqm = plq_min(plqf, plqg),
clf(); plq_plotMultiple(-4, 4, plqf, plqg, plqm);

plqf = [%inf,1,0,0];
plqg = [0,0,-3,-1;%inf,0,3,-1];
plqm = plq_min(plqf, plqg),
clf(); plq_plotMultiple(-4, 4, plqf, plqg, plqm);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_minPt'>
  <info>
    <pubdate>19-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_minPt</refname>
    <refpurpose>Piecewise linear quadratic (plq), minimum point</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>[fmin, xmin] = plq_minPt(plqf)</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Parameters</title>
     <variablelist>

       <varlistentry>
         <term>plqf</term>
         <listitem>
           <para>matrix. A PLQ function.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>fmin</term>
         <listitem>
           <para>real number, or infinite.  The minimum value of the function plqf.</para>
         </listitem>
       </varlistentry>

       <varlistentry>
         <term>xmin</term>
         <listitem>
           <para>column vector.  A vector of points in the argmin of plqf.</para>
         </listitem>
       </varlistentry>

     </variablelist>
   </refsection>

   <refsection>
     <title>Description</title>

     <para>
       Performs a linear scan of plqf, checking each of its pieces, to
       determine the set of points at which plqf attains its minimum.
       fmin may be %inf (if plqf is %inf everywhere) or -%inf (if plqf
       reaches -%inf somewhere, or in the limit).
     </para>

     <para>
       The vector xmin will contain all minimizers of plqf, except
       when plqf is minimized over an interval, in which case xmin
       will contain only the boundaries of this interval.  If plqf is
       a constant function, then xmin is simply [0].  The vector xmin
       is always returned in nondecreasing order.
     </para>

     <para>
       This algorithm runs in O(n log n) time, due to the use of
       sorting subroutines.
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role='example'>
plqf = [-3 0 -0.5 -0.5;-2 0  2 7;0 0 -0.5 2;%inf 0 2 2];
[fmin, xmin] = plq_minPt(plqf),
scf(); plq_plotMultiple(%f, %f, plqf);

plqf  = [-15.495963    0.         -0.6666667  -2.2597654;
          -5.3940994    0.0058845  -0.4842946  -0.8467499;
          -4.002795     0.100625     0.5377847    1.9098488;
          -3.8909938  -0.0993827  -1.0633951  -1.2947485;
          -0.3961698    0.100625     0.4930625    1.7333349;
           0.9454451  -0.0993827    0.3345885    1.7019436;
           4.1586957    0.100625   -0.0436042    1.8807238;
          10.626398    0.0803995    0.1246192    1.5309288;
         %inf          0.           1.8333333  -7.5478088];
[fmin, xmin] = plq_minPt(plqf),
scf(); plq_plotMultiple(%f, %f, plqf);
</programlisting>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='plq_function'>plq_function</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_pa'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_pa</refname><refpurpose>Piecewise linear quadratic (plq), convex proximal average via conjugates</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>pa = plq_pa(f1,f2,lambda_pa)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>f1</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>f2</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>lambda_pa</term>
			  
            <listitem>
				  
               <para>constant. An intermediate function.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>pa</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     Compute the proximal average (PA) of two plq functions at a specified lambda_pa value. The PA is computed using the following formula, where * represents the Fenchel Conjugate.
<programlisting>
    P(f1,lambda,f2) = [ (1 - lambda)(f1 + (1/2)||.||^2)* + lambda(f2 + (1/2)||.||^2)* ]* - (1/2)||.||^2
</programlisting>
    
         </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
lambda_pa = 0.5;
f1 = [%inf, 0, 1, 0];
f2 = [%inf, 0, -1, 5]; 
result = plq_pa(f1, f2, lambda_pa);
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
         <link linkend='plq_pa'>plq_pa</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_pa_mu'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_pa_mu</refname><refpurpose>Piecewise linear quadratic (plq), nonconvex proximal average via Moreau envelopes</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>pa = plq_pa_mu(mu, lambda, f1, f2)
pa = plq_pa_mu(mu, lambdas, f1, ..., fN)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	
      <variablelist>
	  
         <varlistentry>
		
            <term>mu</term>
		
            <listitem>
		  
               <para>constant. Smoothing parameter.
		  </para>
		
            </listitem>
	  
         </varlistentry>
	  
         <varlistentry>
		
            <term>lambda</term>
		
            <listitem>
		  
               <para>constant. The lambda value to associate with f2.
		  </para>
		
            </listitem>
	  
         </varlistentry>
	  
         <varlistentry>
		
            <term>lambdas</term>
		
            <listitem>
		  
               <para>vector. The lambdas associated with each function.
		  </para>
		
            </listitem>
	  
         </varlistentry>
	  
         <varlistentry>
		
            <term>f1 ... fN</term>
		
            <listitem>
		  
               <para>matrix. The plq functions to take the average of.
		  </para>
		
            </listitem>
	  
         </varlistentry>
	  
         <varlistentry>
		
            <term>pa</term>
		
            <listitem>
		  
               <para>matrix. The plq proximal average of f1 through fN.
		  </para>
		
            </listitem>
	  
         </varlistentry>
	
      </variablelist>
  
   </refsection>
  
  
   <refsection><title>Description</title>
      
         <para>
	    Compute the proximal average (PA) of a variable number of plq functions at specified lambda values. The PA is computed using the following formula, where M(mu,f) represents the Moreau envelope of function f with smoothing parameter mu.  This method does not require the input functions to be convex.  If only two functions are averaged, then one lambda value can be specified for f2, and the lambda for f1 will be (1-lambda).  The proximal average is computed in linear time with respect to the size of the input functions.
		<programlisting>
    P[mu]({f1,...,fN}, {lambda1,...,lambdaN}) = -M(mu, -[ lambda1*M(mu,f1) + lambda2*M(mu,f2) + ... + lambdaN*M(mu,fN) ])
</programlisting>
      
         </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
f1 = [2,0,2,-4; %inf,0,0,0];
f2 = [-3,0,30,90; 0,0,0,0; %inf,1,0,0];
result = plq_pa_mu(0.2, 0.3, f1, f2),
clf(0,&quot;reset&quot;);
plq_plotMultiple(%f, %f, f1, f2, result);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_plot'><info><pubdate>16-Jul-2008</pubdate></info><refnamediv><refname>plq_plot</refname><refpurpose>Piecewise linear quadratic (plq), plot function</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plq_plot(plqf1, plqf2, x1, x5)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>plqf1</term>
        
            <listitem>
          
               <para>matrix.  A plq function to plot.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>plqf2</term>
        
            <listitem>
          
               <para>matrix, optional.  A secondary plq function to plot.
          </para>n
        </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x1</term>
        
            <listitem>
          
               <para>number, optional.  The lower x bound of the grid on which the functions are plotted.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x5</term>
        
            <listitem>
          
               <para>number, optional.  The upper x bound of the grid on which the functions are plotted.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Initializes and creates a plot of one or two PLQ functions computed over the interval [x1,x5].  If x1 or x5 are not provided, or are -%inf and %inf respectively, then they default to -5 and 5.
      </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
// Plotting two functions with a specific grid:
plqf1 = [-1,0,-1,-1;0,0,1,1;1,0,-1,1;%inf,0,1,-1];  // The function abs(abs(x) - 1)
plqf2 = [-1,-3,-12,-9;1,4,0,-4;%inf,-3,12,-9];      // An &quot;m&quot;
plq_plot(plqf1, plqf2, -4, 4);

// Plotting a single, noncontinuous function:
plqf = [0,-3,-18,-29;3,0,-2,6;%inf,0,40,-170];
plq_plot(plqf);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_plotMultiple'><info><pubdate>16-Jul-2008</pubdate></info><refnamediv><refname>plq_plotMultiple</refname><refpurpose>Piecewise linear quadratic (plq), plot multiple functions</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plq_plotMultiple(x1, x5, f1, ..., fN)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>x1</term>
        
            <listitem>
          
               <para>number, optional.  The lower x bound of the grid on which the functions are plotted.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x5</term>
        
            <listitem>
          
               <para>number, optional.  The upper x bound of the grid on which the functions are plotted.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>f1 ... fN</term>
        
            <listitem>
          
               <para>matrix.  The plq functions to plot.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Plots a number of PLQ functions computed over the interval [x1,x5].  If x1 or x5 are not provided, or are -%inf and %inf respectively, then they default to -5 and 5.
      </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
f1 = [-1,0,-1,-1;0,0,1,1;1,0,-1,1;%inf,0,1,-1];  // The function abs(abs(x) - 1)
f2 = [-1,-3,-12,-9;1,4,0,-4;%inf,-3,12,-9];      // An &quot;m&quot;
f3 = [0,-3,-18,-29;3,0,-2,-30;%inf,0,40,-156];   // Another function
clf();
plq_plotMultiple(-4, 4, f1, f2, f3);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_plotpa'><info><pubdate>16-Jul-2008</pubdate></info><refnamediv><refname>plq_plotpa</refname><refpurpose>Piecewise linear quadratic (plq), plot convex proximal average</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plq_plotpa(plqf1, plqf2, x, lset, rect)
plq_plotpa(plqf1, plqf2, x, lset, rect, isConvex)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>plqf1</term>
        
            <listitem>
          
               <para>matrix.  The first function of the proximal average (lambda=0).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>plqf2</term>
        
            <listitem>
          
               <para>matrix.  The second function of the proximal average (lambda=1).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector.  The points at which to evaluate the proximal average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>lset</term>
        
            <listitem>
          
               <para>column vector.  The lambda values at which to plot the proximal average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>rect</term>
        
            <listitem>
          
               <para>row vector.  [xmin,ymin,xmax,ymax] for the plot window as with plot2d.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>isConvex</term>
        
            <listitem>
          
               <para>boolean, optional.  Whether or not plqf1 and plqf2 are both convex.  Defaults to %t.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        For each lambda in lset, plots the proximal average of two PLQ functions over the provided x values.  The rect argument bounds the plot&apos;s visible region and is required.  All of the proximal averages are plotted on the same graph, and the colours of successive PA&apos;s fade from blue (lambda=0) to red (lambda=1) via jetcolormap.
      </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
plqf1 = [2,1,0,0;%inf,0,0,%inf];
plqf2 = [3,0,0,%inf;4,0,-1,4;%inf,0,1,-4];
x = linspace(-3, 7, 100)&apos;;
lset = 0:0.01:1;
rect = [-3,0,7,10];
plq_plotpa(plqf1, plqf2, x, lset, rect);
plot2d(x, [plq_eval(plqf1, x), plq_eval(plqf2, x)]);
a = gca();
a.children(1).children(1).thickness = 5;
a.children(1).children(2).thickness = 5;
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_plotpa_lambdaSet'><info><pubdate>16-Jul-2008</pubdate></info><refnamediv><refname>plq_plotpa_lambdaSet</refname><refpurpose>Piecewise linear quadratic (plq), plot nonconvex proximal average over lambda</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plq_plotpa_lambdaSet(f1, f2, x, lambdaSet, mu, rect)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>f1</term>
        
            <listitem>
          
               <para>matrix.  The first plq function of the proximal average (lambda=0).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>f2</term>
        
            <listitem>
          
               <para>matrix.  The second plq function of the proximal average (lambda=1).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector.  The points at which to evaluate the proximal average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>lambdaSet</term>
        
            <listitem>
          
               <para>column vector.  The lambda values at which to plot the proximal average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>mu</term>
        
            <listitem>
          
               <para>constant.  The smoothing parameter to apply to the average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>rect</term>
        
            <listitem>
          
               <para>row vector.  [xmin,ymin,xmax,ymax] for the plot window as with plot2d.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        For each lambda in lambdaSet, plots the proximal average of two PLQ functions over the provided x values and with the provided mu.  The proximal averages are computed with plq_pa_mu, so f1 and f2 do not have to be convex.  The rect argument bounds the plot&apos;s visible region and is required.  All of the proximal averages are plotted on the same graph, and the colours of successive PA&apos;s fade from blue (lambda=0) to red (lambda=1) via jetcolormap.
      </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
f1 = [2,0,2,-4; %inf,0,0,0];
f2 = [-3,0,30,90; 0,0,0,0; %inf,1,0,0];
clf(0,&quot;reset&quot;);
plq_plotpa_lambdaSet(f1, f2, -20:0.01:10, 0:0.05:1, 0.2, [-20,-20,10,40]);
plq_plotMultiple(-4.2, 6, f2);
plq_plotMultiple(-15.9, 10, f1);
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_plotpa_muSet'><info><pubdate>16-Jul-2008</pubdate></info><refnamediv><refname>plq_plotpa_muSet</refname><refpurpose>Piecewise linear quadratic (plq), plot nonconvex proximal average over the smoothing parameter mu</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plq_plotpa_muSet(f1, f2, x, lambda, muSet, rect)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>f1</term>
        
            <listitem>
          
               <para>matrix.  The first plq function of the proximal average (lambda=0).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>f2</term>
        
            <listitem>
          
               <para>matrix.  The second plq function of the proximal average (lambda=1).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>x</term>
        
            <listitem>
          
               <para>column vector.  The points at which to evaluate the proximal average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>lambda</term>
        
            <listitem>
          
               <para>constant.  The weight to apply to f2 in the average.  f1&apos;s weight is (1-lambda).
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>muSet</term>
        
            <listitem>
          
               <para>column vector.  The mu values at which to plot the proximal average.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>rect</term>
        
            <listitem>
          
               <para>row vector.  [xmin,ymin,xmax,ymax] for the plot window as with plot2d.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        For each mu in muSet, plots the proximal average of two PLQ functions over the provided x values and with the provided lambda.  The proximal averages are computed with plq_pa_mu, so f1 and f2 do not have to be convex.  The rect argument bounds the plot&apos;s visible region and is required.  All of the proximal averages are plotted on the same graph, and the colours of successive PA&apos;s fade from blue (lambda=0) to red (lambda=1) via jetcolormap.
      </para>
    
   </refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_proj'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_proj</refname><refpurpose>Piecewise linear quadratic (plq), projection of a (not necessarily convex) function on the set of plq (convex) functions</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>[plq,d] = plq_proj(f,x,p)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plq</term>
			  
            <listitem>
				  
               <para>matrix. A plq function.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>d</term>
			  
            <listitem>
				  
               <para>float. distance between the function f and its projection plq functions d=||f-plq||_p.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>f</term>
			  
            <listitem>
				  
               <para>vector of size n. The values of the function f on the grid x: f=f(x(i)).
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>x</term>
			  
            <listitem>
				  
               <para>vector of size n. The grid on which the function f is evaluated: f=f(x(i)).
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>p</term>
			  
            <listitem>
				  
               <para>integer. The norm for which the projection is computed. p=1, 2, or %inf for the norm ||.||_p.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
            Computes the projection of the function f on the cone of plq convex functions. Return the result as a plq function.
    </para>
    
    
         <para>
	The computation assumes the function f is sampled on the uniform grid x. The values of the projection are computed by solving the optimization problem:
	 min ||f-u||_p such that u is convex 
	For the L_2 norm, a quadratic program with linear constraints is solved.
	    
    </para>
 	
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
n=300;
x=linspace(-2,2,n)&apos;;
f=abs(abs(x)-1);

[p,d]=plq_proj(f,x,2);
u=plq_eval(p,x);

scf(0);clf();
plot2d(x,f,style=1);
plot2d(x,u,style=2);
legends([&quot;f&quot;,&quot;plq&quot;],[1,2],opt=&quot;lr&quot;);
xtitle(sprintf(&quot;Projection of f onto the cone of convex plq functions. ||f-plq||_p=%1.2f&quot;,d));
  </programlisting></refsection>


   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
	  
      <literal>Yves Lucet</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_rock'><info><pubdate>09-Jul-2008</pubdate></info><refnamediv><refname>plq_rock</refname><refpurpose>Compute the PLQ Rockafellar function R(A,a(k)) of an operator A.</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   

  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>R = plq_rock(B, k)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
    
      <variablelist>
      
         <varlistentry>
        
            <term>B</term>
        
            <listitem>
          
               <para>matrix. A matrix [a;bm;bp] where a, bm (b-), and bp (b+) are row vectors as defined below.
          </para>
        
            </listitem>
      
         </varlistentry>
      
         <varlistentry>
        
            <term>k</term>
        
            <listitem>
          
               <para>integer.  1&lt;=k&lt;=m.  The index of the a values for which to compute R(A,a(k)).  i&lt;=k use bm, i&gt;=k use bp.
          </para>
        
            </listitem>
      
         </varlistentry>
    
      </variablelist>
  
   </refsection>

  
   <refsection><title>Description</title>
      
         <para>
        Compute the PLQ Rockafellar function R(A,a(k)) of an operator A, where B is defined below.  This function runs in linear time, computing a PLQ piece for each i=1:m+1 where a(i-1) &lt; x &lt;= a(i).
<programlisting>
    B : x -&gt; conv(A*x):
          m
        union ( {a(i)} cross [bm(i),bp(i)] )
         i=1

    with a(1) &lt; a(2) &lt; ... &lt; a(m),
         bm(1) &lt;= bp(1) &lt;= bm(2) &lt;= bp(2) &lt;= ... &lt;= bm(m) &lt;= bp(m),
         a(0) = bm(0) = bp(0) = -%inf,
         a(m+1) = bm(m+1) = bp(m+1) = %inf,
         m = size(B,2).

    R(A, a(k))(x) = { (x-a(i))*bm(i) + sum(j=i+1:k, (a(j-1)-a(j))*bm(j)) , if a(i-1) &lt; x &lt;= a(i) &lt;= a(k)
                    { (x-a(i))*bp(i) + sum(j=k:i-1, (a(j+1)-a(j))*bp(j)) , if a(k) &lt;= a(i) &lt;= x &lt;= a(i+1)
</programlisting>
      
         </para>
    
   </refsection>

  
   <refsection><title>Examples</title><programlisting role='example'>
a = 1:5;
bm = [-10,-4, 1, 2, 5];
bp = [- 5, 0, 2, 4, 7];
B = [a;bm;bp];
plq_rock(B, 1),
plq_rock(B, 5),
  </programlisting></refsection>

  
   <refsection><title>See Also</title><simplelist type='inline'>
    
      <member>
         <link linkend='op_fitz_brute'>op_fitz_brute</link>
      </member>
    
      <member>
         <link linkend='op_fitz_direct'>op_fitz_direct</link>
      </member>
    
      <member>
         <link linkend='op_fitz'>op_fitz</link>
      </member>
    
      <member>
         <link linkend='op_fitzinf'>op_fitzinf</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0'>plq_fitzinf0</link>
      </member>
    
      <member>
         <link linkend='plq_fitzinf0_direct'>plq_fitzinf0_direct</link>
      </member>
  
   </simplelist></refsection>

  
   <refsection><title>Authors</title><para>
    
      <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>
<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_scalar'><info><pubdate>04-Apr-2006</pubdate></info><refnamediv><refname>plq_scalar</refname><refpurpose>Piecewise linear quadratic (plq), multiply a plq function by a scalar</refpurpose></refnamediv>
  
   
  
   
  
   
  
   
  
   
  
   <refsynopsisdiv><title>Calling Sequence</title><synopsis>plqf = plq_scalar(plqfs,lambda)</synopsis></refsynopsisdiv>

  
   <refsection><title>Parameters</title>
	  
      <variablelist>
		  
         <varlistentry>
			  
            <term>plqfs</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>lambda</term>
			  
            <listitem>
				  
               <para>constant. A scalar multiple.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
		  
         <varlistentry>
			  
            <term>plqf</term>
			  
            <listitem>
				  
               <para>matrix. A plq function with dimensions n x 4.
				  </para>
			  
            </listitem>
		  
         </varlistentry>
	  
      </variablelist>
  
   </refsection>
 
  
   <refsection><title>Description</title>
     
         <para>
	     The plq_scalar function multiplies a plq function by a constant.
    </para>
 	
   </refsection>
  
   <refsection><title>Examples</title><programlisting role='example'>
//Example 1. Clear Duplicate Points
normsquared = [%inf, 1/2, 0, 0];
negnormsquared = plq_scalar(normsquared,-1);
  </programlisting></refsection>

   <refsection><title>See Also</title><simplelist type='inline'>	
    
      <member>
         <link linkend='plq_function'>plq_function</link>
      </member>

   </simplelist></refsection>
  
   <refsection><title>Authors</title><para>
	  
      <literal>Mike Trienis</literal>, University of British Columbia, BC, Canada
  </para></refsection>

</refentry>

<refentry version='5.0-subset Scilab' xml:lang='en' xml:id='plq_version'>
  <info>
    <pubdate>18-May-2010</pubdate>
  </info>

  <refnamediv>
    <refname>plq_version</refname>
    <refpurpose>Piecewise linear quadratic (plq), library version</refpurpose>
  </refnamediv>

   <refsynopsisdiv>
     <title>Calling Sequence</title>
     <synopsis>version = plq_version()</synopsis>
   </refsynopsisdiv>

   <refsection>
     <title>Description</title>

     <para>
       This function returns the current release version of the plq_* functions.  The file plq_version.sci is named the same as this file, as required by the toolbox builder.
     </para>
   </refsection>

   <refsection>
     <title>See Also</title>
     <simplelist type='inline'>
       <member><link linkend='common_version'>common_version</link></member>
       <member><link linkend='gph_version'>gph_version</link></member>
       <member><link linkend='lft_version'>lft_version</link></member>
       <member><link linkend='me_version'>me_version</link></member>
       <member><link linkend='opt_version'>opt_version</link></member>
       <member><link linkend='op_version'>op_version</link></member>
       <member><link linkend='plot_version'>plot_version</link></member>
   </simplelist></refsection>

   <refsection>
     <title>Authors</title>
     <para>
       <literal>Bryan Gardiner</literal>, University of British Columbia, BC, Canada
     </para>
   </refsection>

</refentry>

</part>
</book>
