tame/core/vector/arithmetic.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  Copyright (C) 2015  LoVullo Associates, Inc.

  This file is part of tame-core.

  tame-core is free software: you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as
  published by the Free Software Foundation, either version 3 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->
<package xmlns="http://www.lovullo.com/rater"
  xmlns:c="http://www.lovullo.com/calc"
  xmlns:t="http://www.lovullo.com/rater/apply-template"
  core="true"
  desc="Vector arithmetic">

  <import package="../base" />
  <import package="../numeric/common" />
  <import package="../numeric/minmax" />



  <!-- for the time being, the vectors must be of the same length, or the first
       vector must be the longer (otherwise the values will not properly add)
       -->
  <template name="_vadd_" desc="Produce a vector resulting from the addition of two vectors">
    <param name="@a@" desc="First vector to add" />
    <param name="@b@" desc="Second vector to add" />
    <param name="@into@" desc="Variable to yield vector into" />

    <param name="@yields@" desc="Value to yield (useless)">
      <text>__</text>
      <param-value name="@into@" />
    </param>

    <param name="@gendesc@" desc="Generator description (for @into@)">
      <text>Sum of vectors </text>
      <param-value name="@a@" />
      <text> and </text>
      <param-value name="@b@" />
    </param>

    <param name="@sym@" desc="Generator symbol">
      <!-- empty by default -->
      <text></text>
    </param>

    <rate accumulate="none" yields="@yields@">
      <c:sum of="@a@" index="k" generates="@into@" desc="@gendesc@" sym="@sym@">
        <c:value-of name="@a@" index="k" />
        <c:value-of name="@b@" index="k" />
      </c:sum>
    </rate>
  </template>


  <!-- the template version of the function -->
  <template name="_maxreduce_" desc="Reduce a set to its maximum">
    <param name="@values@" desc="Values to reduce" />
    <param name="@isvector@" desc="Set to 'true' if the nodes should not be wrapped in c:set" />
    <param name="@label@" desc="Application label">
      <!-- default empty -->
      <text></text>
    </param>

    <c:apply name="maxreduce" label="@label@">
      <c:arg name="maxreduce_set">
        <!-- if we were not provided with a vector (default), create one out of
             the given nodes -->
        <unless name="@isvector@" eq="true">
          <c:set>
            <param-copy name="@values@" />
          </c:set>
        </unless>

        <!-- if they told us that they have provided a vector, then do not
             create one -->
        <if name="@isvector@" eq="true">
          <param-copy name="@values@" />
        </if>
      </c:arg>
    </c:apply>
  </template>


  <function name="maxreduce" desc="Reduce a set to its maximum">
    <param name="maxreduce_set" type="float" set="vector" desc="Set to find max of" />

    <c:let>
      <c:values>
        <c:value name="n" type="integer" desc="Length of set to reduce">
          <c:length-of>
            <c:value-of name="maxreduce_set" />
          </c:length-of>
        </c:value>
      </c:values>


      <c:cases>
        <!-- if we have no values to reduce, then simply return 0 -->
        <c:case>
          <c:when name="n">
            <c:eq>
              <c:const value="0" type="integer" desc="When there are no elements" />
            </c:eq>
          </c:when>

          <c:const value="0" type="integer" desc="No value" />
        </c:case>

        <!-- we have values; perform reduction -->
        <c:otherwise>
          <c:apply name="_maxreduce">
            <c:arg name="_maxreduce_set">
              <c:value-of name="maxreduce_set" />
            </c:arg>

            <c:arg name="_maxreduce_i">
              <t:dec>
                <c:length-of>
                  <c:value-of name="maxreduce_set" />
                </c:length-of>
              </t:dec>
            </c:arg>
          </c:apply>
        </c:otherwise>
      </c:cases>
    </c:let>
  </function>


  <!--
    Recursively determines the maximum value of the given set

    For example, given the set (2 4 3 1), here's the recursive application:
      max( 1, max( 3, max( 4, 2 ) ) )
      max( 1, max( 3, 4 ) )
      max( 1, 4 )
      4

    Of course, the above can be done manually, but this function exists
    explicitly to cut down on that manual code, especially considering how
    verbose function applications are.

    TODO: If we can support variable applications, then this simply be a
    generic reduce function that accepts max/min/etc.
  -->
  <function name="_maxreduce" desc="Recursively reduce a set to its maximum (called by maxreduce)">
    <param name="_maxreduce_set" type="float" set="vector" desc="Set to find max of" />
    <param name="_maxreduce_i"   type="integer" desc="Index" />

    <c:cases>
      <!-- base case: if we're on the last index, do not recurse -->
      <c:case>
        <c:when name="_maxreduce_i">
          <c:eq>
            <c:const value="0" type="integer" desc="Return when only one element remains" />
          </c:eq>
        </c:when>

        <!-- return the first value -->
        <c:value-of name="_maxreduce_set">
          <c:index>
            <c:const value="0" type="integer" desc="First item in set" />
          </c:index>
        </c:value-of>
      </c:case>

      <!-- we have more elements in the set; recursively determine the maximum value -->
      <c:otherwise>
        <c:apply name="max">
          <!-- the first element to compare is our index -->
          <c:arg name="max1">
            <c:value-of name="_maxreduce_set">
              <c:index>
                <c:value-of name="_maxreduce_i" />
              </c:index>
            </c:value-of>
          </c:arg>

          <!-- and we'll compare to the recursive application of the same set
               on the previous index -->
          <c:arg name="max2">
            <c:apply name="_maxreduce">
              <c:arg name="_maxreduce_set">
                <c:value-of name="_maxreduce_set" />
              </c:arg>

              <c:arg name="_maxreduce_i">
                <c:sum>
                  <c:value-of name="_maxreduce_i" />
                  <c:const value="-1" type="integer" desc="Decrement index by 1" />
                </c:sum>
              </c:arg>
            </c:apply>
          </c:arg>
        </c:apply>
      </c:otherwise>
    </c:cases>
  </function>


  <!-- simplifies retrieving the max of a set of values -->
  <template name="_maxOfEach_" desc="Take the max of the given set of values">
    <param name="@class@" desc="Class to match on" />
    <param name="@values@" desc="Individual values without set" />
    <param name="@generates@" desc="Value to generate into" />
    <param name="@index@" desc="Index to use for rate-each" />

    <param name="@yields@" desc="Yield variable">
      <text>_</text>
      <param-value name="@generates@" />
    </param>

    <rate-each class="@class@" accumulate="none" yields="@yields@" generates="@generates@" index="@index@">
      <c:apply name="maxreduce">
        <c:arg name="maxreduce_set">
          <c:set>
            <param-copy name="@values@" />
          </c:set>
        </c:arg>
      </c:apply>
    </rate-each>
  </template>


  <template name="_vsum_" desc="Yield sum of all elements of a vector as a scalar">
    <param name="@of@"     desc="Vector to sum" />
    <param name="@yields@" desc="Name of scalar to yield" />

    <rate yields="@yields@">
      <c:sum of="@of@" />
    </rate>
  </template>
</package>