Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.mahout.math; import java.util.Iterator; import com.google.common.base.Preconditions; import org.apache.mahout.common.RandomUtils; import org.apache.mahout.math.function.DoubleDoubleFunction; import org.apache.mahout.math.function.DoubleFunction; import org.apache.mahout.math.function.Functions; /** Implementations of generic capabilities like sum of elements and dot products */ public abstract class AbstractVector implements Vector, LengthCachingVector { private int size; protected double lengthSquared = -1.0; protected AbstractVector(int size) { this.size = size; } @Override public Iterable<Element> all() { return new Iterable<Element>() { @Override public Iterator<Element> iterator() { return AbstractVector.this.iterator(); } }; } @Override public Iterable<Element> nonZeroes() { return new Iterable<Element>() { @Override public Iterator<Element> iterator() { return iterateNonZero(); } }; } /** * Iterates over all elements <p> * NOTE: Implementations may choose to reuse the Element returned for performance * reasons, so if you need a copy of it, you should call {@link #getElement(int)} for the given index * * @return An {@link Iterator} over all elements */ protected abstract Iterator<Element> iterator(); /** * Iterates over all non-zero elements. <p> * NOTE: Implementations may choose to reuse the Element returned for * performance reasons, so if you need a copy of it, you should call {@link #getElement(int)} for the given index * * @return An {@link Iterator} over all non-zero elements */ protected abstract Iterator<Element> iterateNonZero(); /** * Aggregates a vector by applying a mapping function fm(x) to every component and aggregating * the results with an aggregating function fa(x, y). * * @param aggregator used to combine the current value of the aggregation with the result of map.apply(nextValue) * @param map a function to apply to each element of the vector in turn before passing to the aggregator * @return the result of the aggregation */ @Override public double aggregate(DoubleDoubleFunction aggregator, DoubleFunction map) { if (size == 0) { return 0; } // If the aggregator is associative and commutative and it's likeLeftMult (fa(0, y) = 0), and there is // at least one zero in the vector (size > getNumNondefaultElements) and applying fm(0) = 0, the result // gets cascaded through the aggregation and the final result will be 0. if (aggregator.isAssociativeAndCommutative() && aggregator.isLikeLeftMult() && size > getNumNondefaultElements() && !map.isDensifying()) { return 0; } double result; if (isSequentialAccess() || aggregator.isAssociativeAndCommutative()) { Iterator<Element> iterator; // If fm(0) = 0 and fa(x, 0) = x, we can skip all zero values. if (!map.isDensifying() && aggregator.isLikeRightPlus()) { iterator = iterateNonZero(); if (!iterator.hasNext()) { return 0; } } else { iterator = iterator(); } Element element = iterator.next(); result = map.apply(element.get()); while (iterator.hasNext()) { element = iterator.next(); result = aggregator.apply(result, map.apply(element.get())); } } else { result = map.apply(getQuick(0)); for (int i = 1; i < size; i++) { result = aggregator.apply(result, map.apply(getQuick(i))); } } return result; } @Override public double aggregate(Vector other, DoubleDoubleFunction aggregator, DoubleDoubleFunction combiner) { Preconditions.checkArgument(size == other.size(), "Vector sizes differ"); if (size == 0) { return 0; } return VectorBinaryAggregate.aggregateBest(this, other, aggregator, combiner); } /** * Subclasses must override to return an appropriately sparse or dense result * * @param rows the row cardinality * @param columns the column cardinality * @return a Matrix */ protected abstract Matrix matrixLike(int rows, int columns); @Override public Vector viewPart(int offset, int length) { if (offset < 0) { throw new IndexException(offset, size); } if (offset + length > size) { throw new IndexException(offset + length, size); } return new VectorView(this, offset, length); } @SuppressWarnings("CloneDoesntDeclareCloneNotSupportedException") @Override public Vector clone() { try { AbstractVector r = (AbstractVector) super.clone(); r.size = size; r.lengthSquared = lengthSquared; return r; } catch (CloneNotSupportedException e) { throw new IllegalStateException("Can't happen"); } } @Override public Vector divide(double x) { if (x == 1.0) { return clone(); } Vector result = createOptimizedCopy(); for (Element element : result.nonZeroes()) { element.set(element.get() / x); } return result; } @Override public double dot(Vector x) { if (size != x.size()) { throw new CardinalityException(size, x.size()); } if (this == x) { return getLengthSquared(); } return aggregate(x, Functions.PLUS, Functions.MULT); } protected double dotSelf() { return aggregate(Functions.PLUS, Functions.pow(2)); } @Override public double get(int index) { if (index < 0 || index >= size) { throw new IndexException(index, size); } return getQuick(index); } @Override public Element getElement(int index) { return new LocalElement(index); } @Override public Vector normalize() { return divide(Math.sqrt(getLengthSquared())); } @Override public Vector normalize(double power) { return divide(norm(power)); } @Override public Vector logNormalize() { return logNormalize(2.0, Math.sqrt(getLengthSquared())); } @Override public Vector logNormalize(double power) { return logNormalize(power, norm(power)); } public Vector logNormalize(double power, double normLength) { // we can special case certain powers if (Double.isInfinite(power) || power <= 1.0) { throw new IllegalArgumentException("Power must be > 1 and < infinity"); } else { double denominator = normLength * Math.log(power); Vector result = createOptimizedCopy(); for (Element element : result.nonZeroes()) { element.set(Math.log1p(element.get()) / denominator); } return result; } } @Override public double norm(double power) { if (power < 0.0) { throw new IllegalArgumentException("Power must be >= 0"); } // We can special case certain powers. if (Double.isInfinite(power)) { return aggregate(Functions.MAX, Functions.ABS); } else if (power == 2.0) { return Math.sqrt(getLengthSquared()); } else if (power == 1.0) { double result = 0.0; Iterator<Element> iterator = this.iterateNonZero(); while (iterator.hasNext()) { result += Math.abs(iterator.next().get()); } return result; // TODO: this should ideally be used, but it's slower. // return aggregate(Functions.PLUS, Functions.ABS); } else if (power == 0.0) { return getNumNonZeroElements(); } else { return Math.pow(aggregate(Functions.PLUS, Functions.pow(power)), 1.0 / power); } } @Override public double getLengthSquared() { if (lengthSquared >= 0.0) { return lengthSquared; } return lengthSquared = dotSelf(); } @Override public void invalidateCachedLength() { lengthSquared = -1; } @Override public double getDistanceSquared(Vector that) { if (size != that.size()) { throw new CardinalityException(size, that.size()); } double thisLength = getLengthSquared(); double thatLength = that.getLengthSquared(); double dot = dot(that); double distanceEstimate = thisLength + thatLength - 2 * dot; if (distanceEstimate > 1.0e-3 * (thisLength + thatLength)) { // The vectors are far enough from each other that the formula is accurate. return Math.max(distanceEstimate, 0); } else { return aggregate(that, Functions.PLUS, Functions.MINUS_SQUARED); } } @Override public double maxValue() { if (size == 0) { return Double.NEGATIVE_INFINITY; } return aggregate(Functions.MAX, Functions.IDENTITY); } @Override public int maxValueIndex() { int result = -1; double max = Double.NEGATIVE_INFINITY; int nonZeroElements = 0; Iterator<Element> iter = this.iterateNonZero(); while (iter.hasNext()) { nonZeroElements++; Element element = iter.next(); double tmp = element.get(); if (tmp > max) { max = tmp; result = element.index(); } } // if the maxElement is negative and the vector is sparse then any // unfilled element(0.0) could be the maxValue hence we need to // find one of those elements if (nonZeroElements < size && max < 0.0) { for (Element element : all()) { if (element.get() == 0.0) { return element.index(); } } } return result; } @Override public double minValue() { if (size == 0) { return Double.POSITIVE_INFINITY; } return aggregate(Functions.MIN, Functions.IDENTITY); } @Override public int minValueIndex() { int result = -1; double min = Double.POSITIVE_INFINITY; int nonZeroElements = 0; Iterator<Element> iter = this.iterateNonZero(); while (iter.hasNext()) { nonZeroElements++; Element element = iter.next(); double tmp = element.get(); if (tmp < min) { min = tmp; result = element.index(); } } // if the maxElement is positive and the vector is sparse then any // unfilled element(0.0) could be the maxValue hence we need to // find one of those elements if (nonZeroElements < size && min > 0.0) { for (Element element : all()) { if (element.get() == 0.0) { return element.index(); } } } return result; } @Override public Vector plus(double x) { Vector result = createOptimizedCopy(); if (x == 0.0) { return result; } return result.assign(Functions.plus(x)); } @Override public Vector plus(Vector that) { if (size != that.size()) { throw new CardinalityException(size, that.size()); } return createOptimizedCopy().assign(that, Functions.PLUS); } @Override public Vector minus(Vector that) { if (size != that.size()) { throw new CardinalityException(size, that.size()); } return createOptimizedCopy().assign(that, Functions.MINUS); } @Override public void set(int index, double value) { if (index < 0 || index >= size) { throw new IndexException(index, size); } setQuick(index, value); } @Override public void incrementQuick(int index, double increment) { setQuick(index, getQuick(index) + increment); } @Override public Vector times(double x) { if (x == 0.0) { return like(); } return createOptimizedCopy().assign(Functions.mult(x)); } /** * Copy the current vector in the most optimum fashion. Used by immutable methods like plus(), minus(). * Use this instead of vector.like().assign(vector). Sub-class can choose to override this method. * * @return a copy of the current vector. */ protected Vector createOptimizedCopy() { return createOptimizedCopy(this); } private static Vector createOptimizedCopy(Vector vector) { Vector result; if (vector.isDense()) { result = vector.like().assign(vector, Functions.SECOND_LEFT_ZERO); } else { result = vector.clone(); } return result; } @Override public Vector times(Vector that) { if (size != that.size()) { throw new CardinalityException(size, that.size()); } if (this.getNumNondefaultElements() <= that.getNumNondefaultElements()) { return createOptimizedCopy(this).assign(that, Functions.MULT); } else { return createOptimizedCopy(that).assign(this, Functions.MULT); } } @Override public double zSum() { return aggregate(Functions.PLUS, Functions.IDENTITY); } @Override public int getNumNonZeroElements() { int count = 0; Iterator<Element> it = iterateNonZero(); while (it.hasNext()) { if (it.next().get() != 0.0) { count++; } } return count; } @Override public Vector assign(double value) { Iterator<Element> it; if (value == 0.0) { // Make all the non-zero values 0. it = iterateNonZero(); while (it.hasNext()) { it.next().set(value); } } else { if (isSequentialAccess() && !isAddConstantTime()) { // Update all the non-zero values and queue the updates for the zero vaues. // The vector will become dense. it = iterator(); OrderedIntDoubleMapping updates = new OrderedIntDoubleMapping(); while (it.hasNext()) { Element element = it.next(); if (element.get() == 0.0) { updates.set(element.index(), value); } else { element.set(value); } } mergeUpdates(updates); } else { for (int i = 0; i < size; ++i) { setQuick(i, value); } } } invalidateCachedLength(); return this; } @Override public Vector assign(double[] values) { if (size != values.length) { throw new CardinalityException(size, values.length); } if (isSequentialAccess() && !isAddConstantTime()) { OrderedIntDoubleMapping updates = new OrderedIntDoubleMapping(); Iterator<Element> it = iterator(); while (it.hasNext()) { Element element = it.next(); int index = element.index(); if (element.get() == 0.0) { updates.set(index, values[index]); } else { element.set(values[index]); } } mergeUpdates(updates); } else { for (int i = 0; i < size; ++i) { setQuick(i, values[i]); } } invalidateCachedLength(); return this; } @Override public Vector assign(Vector other) { return assign(other, Functions.SECOND); } @Override public Vector assign(DoubleDoubleFunction f, double y) { Iterator<Element> iterator = f.apply(0, y) == 0 ? iterateNonZero() : iterator(); while (iterator.hasNext()) { Element element = iterator.next(); element.set(f.apply(element.get(), y)); } invalidateCachedLength(); return this; } @Override public Vector assign(DoubleFunction f) { Iterator<Element> iterator = !f.isDensifying() ? iterateNonZero() : iterator(); while (iterator.hasNext()) { Element element = iterator.next(); element.set(f.apply(element.get())); } invalidateCachedLength(); return this; } @Override public Vector assign(Vector other, DoubleDoubleFunction function) { if (size != other.size()) { throw new CardinalityException(size, other.size()); } VectorBinaryAssign.assignBest(this, other, function); invalidateCachedLength(); return this; } @Override public Matrix cross(Vector other) { Matrix result = matrixLike(size, other.size()); Iterator<Vector.Element> it = iterateNonZero(); while (it.hasNext()) { Vector.Element e = it.next(); int row = e.index(); result.assignRow(row, other.times(getQuick(row))); } return result; } @Override public final int size() { return size; } @Override public String asFormatString() { return toString(); } @Override public int hashCode() { int result = size; Iterator<Element> iter = iterateNonZero(); while (iter.hasNext()) { Element ele = iter.next(); result += ele.index() * RandomUtils.hashDouble(ele.get()); } return result; } /** * Determines whether this {@link Vector} represents the same logical vector as another * object. Two {@link Vector}s are equal (regardless of implementation) if the value at * each index is the same, and the cardinalities are the same. */ @Override public boolean equals(Object o) { if (this == o) { return true; } if (!(o instanceof Vector)) { return false; } Vector that = (Vector) o; return size == that.size() && aggregate(that, Functions.PLUS, Functions.MINUS_ABS) == 0.0; } @Override public String toString() { return toString(null); } public String toString(String[] dictionary) { StringBuilder result = new StringBuilder(); result.append('{'); for (int index = 0; index < size; index++) { double value = getQuick(index); if (value != 0.0) { result.append(dictionary != null && dictionary.length > index ? dictionary[index] : index); result.append(':'); result.append(value); result.append(','); } } if (result.length() > 1) { result.setCharAt(result.length() - 1, '}'); } else { result.append('}'); } return result.toString(); } /** * toString() implementation for sparse vectors via {@link #nonZeroes()} method * @return String representation of the vector */ public String sparseVectorToString() { Iterator<Element> it = iterateNonZero(); if (!it.hasNext()) { return "{}"; } else { StringBuilder result = new StringBuilder(); result.append('{'); while (it.hasNext()) { Vector.Element e = it.next(); result.append(e.index()); result.append(':'); result.append(e.get()); result.append(','); } result.setCharAt(result.length() - 1, '}'); return result.toString(); } } protected final class LocalElement implements Element { int index; LocalElement(int index) { this.index = index; } @Override public double get() { return getQuick(index); } @Override public int index() { return index; } @Override public void set(double value) { setQuick(index, value); } } }