<?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_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><![CDATA[
  (  me   f)(y) = inf [ f(x) + (1/2/lambda)||x-y||^2 ]
   lambda          x
]]></programlisting>-->
		<para>
			<inlinemediaobject>
				<imageobject>
					<imagedata fileref="gph_ImagesOfEquationsByLatex/gph_me/gph_me_1.png"/>
				</imageobject>
			</inlinemediaobject>
		</para>

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

       <!--<programlisting><![CDATA[
    [ [ 1 L ]   [ x ] ]     [    x + L*s     ]
    [ [     ] * [   ] ]     [                ]
    [ [ 0 1 ]   [ s ] ]  =  [       s        ] ,
    [                 ]     [                ]
    [ y + (L/2)*s.^2  ]     [ y + (L/2)*s.^2 ]
]]></programlisting>-->
		<para>
			<inlinemediaobject>
				<imageobject>
					<imagedata fileref="gph_ImagesOfEquationsByLatex/gph_me/gph_me_2.png"/>
				</imageobject>
			</inlinemediaobject>
		</para>

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

       <!--<programlisting><![CDATA[
    (  me   f) = (f* + (1/2/lambda)||.||^2)* .
     lambda
]]></programlisting>-->
		<para>
			<inlinemediaobject>
				<imageobject>
					<imagedata fileref="gph_ImagesOfEquationsByLatex/gph_me/gph_me_3.png"/>
				</imageobject>
			</inlinemediaobject>
		</para>
     </para>
   </refsection>

   <refsection>
     <title>Examples</title>
     <programlisting role="example"><![CDATA[
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>
