Sum.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      https://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. /*
  18.  * This is not the original file distributed by the Apache Software Foundation
  19.  * It has been modified by the Hipparchus project
  20.  */
  21. package org.hipparchus.stat.descriptive.summary;

  22. import java.io.Serializable;

  23. import org.hipparchus.exception.MathIllegalArgumentException;
  24. import org.hipparchus.exception.NullArgumentException;
  25. import org.hipparchus.stat.descriptive.AbstractStorelessUnivariateStatistic;
  26. import org.hipparchus.stat.descriptive.AggregatableStatistic;
  27. import org.hipparchus.stat.descriptive.WeightedEvaluation;
  28. import org.hipparchus.util.MathArrays;
  29. import org.hipparchus.util.MathUtils;


  30. /**
  31.   * Returns the sum of the available values.
  32.  * <p>
  33.  * If there are no values in the dataset, then 0 is returned.
  34.  * If any of the values are
  35.  * <code>NaN</code>, then <code>NaN</code> is returned.
  36.  * <p>
  37.  * <strong>Note that this implementation is not synchronized.</strong> If
  38.  * multiple threads access an instance of this class concurrently, and at least
  39.  * one of the threads invokes the <code>increment()</code> or
  40.  * <code>clear()</code> method, it must be synchronized externally.
  41.  */
  42. public class Sum extends AbstractStorelessUnivariateStatistic
  43.     implements AggregatableStatistic<Sum>, WeightedEvaluation, Serializable {

  44.     /** Serializable version identifier */
  45.     private static final long serialVersionUID = 20150412L;

  46.     /** The number of values that have been added */
  47.     private long n;

  48.     /** The currently running sum */
  49.     private double value;

  50.     /**
  51.      * Create a Sum instance.
  52.      */
  53.     public Sum() {
  54.         n = 0;
  55.         value = 0;
  56.     }

  57.     /**
  58.      * Copy constructor, creates a new {@code Sum} identical
  59.      * to the {@code original}.
  60.      *
  61.      * @param original the {@code Sum} instance to copy
  62.      * @throws NullArgumentException if original is null
  63.      */
  64.     public Sum(Sum original) throws NullArgumentException {
  65.         MathUtils.checkNotNull(original);
  66.         this.n     = original.n;
  67.         this.value = original.value;
  68.     }

  69.     /** {@inheritDoc} */
  70.     @Override
  71.     public void increment(final double d) {
  72.         value += d;
  73.         n++;
  74.     }

  75.     /** {@inheritDoc} */
  76.     @Override
  77.     public double getResult() {
  78.         return value;
  79.     }

  80.     /** {@inheritDoc} */
  81.     @Override
  82.     public long getN() {
  83.         return n;
  84.     }

  85.     /** {@inheritDoc} */
  86.     @Override
  87.     public void clear() {
  88.         value = 0;
  89.         n = 0;
  90.     }

  91.     /** {@inheritDoc} */
  92.     @Override
  93.     public void aggregate(Sum other) {
  94.         MathUtils.checkNotNull(other);
  95.         if (other.n > 0) {
  96.             this.n     += other.n;
  97.             this.value += other.value;
  98.         }
  99.     }

  100.     /**
  101.      * The sum of the entries in the specified portion of the input array,
  102.      * or 0 if the designated subarray is empty.
  103.      *
  104.      * @param values the input array
  105.      * @param begin index of the first array element to include
  106.      * @param length the number of elements to include
  107.      * @return the sum of the values or 0 if length = 0
  108.      * @throws MathIllegalArgumentException if the array is null or the array index
  109.      *  parameters are not valid
  110.      */
  111.     @Override
  112.     public double evaluate(final double[] values, final int begin, final int length)
  113.         throws MathIllegalArgumentException {

  114.         double sum = Double.NaN;
  115.         if (MathArrays.verifyValues(values, begin, length, true)) {
  116.             sum = 0.0;
  117.             for (int i = begin; i < begin + length; i++) {
  118.                 sum += values[i];
  119.             }
  120.         }
  121.         return sum;
  122.     }

  123.     /**
  124.      * The weighted sum of the entries in the specified portion of
  125.      * the input array, or 0 if the designated subarray
  126.      * is empty.
  127.      * <p>
  128.      * Throws <code>MathIllegalArgumentException</code> if any of the following are true:
  129.      * </p>
  130.      * <ul><li>the values array is null</li>
  131.      *     <li>the weights array is null</li>
  132.      *     <li>the weights array does not have the same length as the values array</li>
  133.      *     <li>the weights array contains one or more infinite values</li>
  134.      *     <li>the weights array contains one or more NaN values</li>
  135.      *     <li>the weights array contains negative values</li>
  136.      *     <li>the start and length arguments do not determine a valid array</li>
  137.      * </ul>
  138.      * <p>
  139.      * Uses the formula,</p><pre>
  140.      *    weighted sum = &Sigma;(values[i] * weights[i])
  141.      * </pre>
  142.      *
  143.      * @param values the input array
  144.      * @param weights the weights array
  145.      * @param begin index of the first array element to include
  146.      * @param length the number of elements to include
  147.      * @return the sum of the values or 0 if length = 0
  148.      * @throws MathIllegalArgumentException if the parameters are not valid
  149.      */
  150.     @Override
  151.     public double evaluate(final double[] values, final double[] weights,
  152.                            final int begin, final int length) throws MathIllegalArgumentException {
  153.         double sum = Double.NaN;
  154.         if (MathArrays.verifyValues(values, weights, begin, length, true)) {
  155.             sum = 0.0;
  156.             for (int i = begin; i < begin + length; i++) {
  157.                 sum += values[i] * weights[i];
  158.             }
  159.         }
  160.         return sum;
  161.     }

  162.     /** {@inheritDoc} */
  163.     @Override
  164.     public Sum copy() {
  165.         return new Sum(this);
  166.     }

  167. }