<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" 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' 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"><![CDATA[
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>
