gov.sandia.cognition.math
Interface Ring<RingType extends Ring<RingType>>

Type Parameters:
RingType - Type of Ring that this class can operate upon, usually itself
All Superinterfaces:
Cloneable, CloneableSerializable, Serializable
All Known Subinterfaces:
DiagonalMatrix, EuclideanRing<RingType>, Field<FieldType>, InfiniteVector<KeyType>, Matrix, RandomVariable<DataType>, Vector, Vector1D, Vector2D, Vector3D, VectorSpace<VectorType,EntryType>
All Known Implementing Classes:
AbstractEuclideanRing, AbstractField, AbstractMatrix, AbstractMTJMatrix, AbstractMTJVector, AbstractRandomVariable, AbstractRing, AbstractSparseMatrix, AbstractVector, AbstractVectorSpace, ComplexNumber, DefaultInfiniteVector, DenseMatrix, DenseVector, DiagonalMatrixMTJ, LogNumber, MutableDouble, MutableInteger, MutableLong, SparseColumnMatrix, SparseMatrix, SparseRowMatrix, SparseVector, UnivariateRandomVariable, UnsignedLogNumber, Vector1, Vector2, Vector3

@CodeReviews(reviews={@CodeReview(reviewer="Kevin R. Dixon",date="2008-02-26",changesNeeded=false,comments="Looks good."),@CodeReview(reviewer="Justin Basilico",date="2006-04-25",changesNeeded=false,comments="Interface definition looks good. Edited the spacing of some of the elements.")})
@PublicationReference(author="Wikipedia",
                      title="Ring (mathematics)",
                      type=WebPage,
                      year=2008,
                      url="http://en.wikipedia.org/wiki/Ring_(mathematics)")
public interface Ring<RingType extends Ring<RingType>>
extends CloneableSerializable

Defines something similar to a mathematical ring. Specifies: equality, element-wise multiplication, addition, subtraction, scaling, negation, deep copy, as well as inline versions of each of these.

Since:
1.0
Author:
Kevin R. Dixon

Method Summary
 RingType clone()
          Returns a smart copy of this, such that changing the values of the return class will not effect this
 RingType dotTimes(RingType other)
          Element-wise multiplication of this and other
 void dotTimesEquals(RingType other)
          Inline element-wise multiplication of this and other
 boolean equals(Object other)
          Determines if two RingType objects are equal
 boolean equals(RingType other, double effectiveZero)
          Determines if two RingType objects are effectively equal
 boolean isZero()
          Determines if this ring is equal to zero.
 boolean isZero(double effectiveZero)
          Determines if this ring is equal to zero using the element-wise effective zero value.
 RingType minus(RingType other)
          Arithmetic subtraction of other from this
 void minusEquals(RingType other)
          Inline arithmetic subtraction of other from this
 RingType negative()
          Returns the element-wise negation of this, such that this.plus( this.negative() ) has only zero elements.
 void negativeEquals()
          Inline element-wise negation of this
 RingType plus(RingType other)
          Arithmetic addition of this and other
 void plusEquals(RingType other)
          Inline arithmetic addition of this and other
 RingType scale(double scaleFactor)
          Element-wise scaling of this by scaleFactor
 RingType scaledMinus(double scaleFactor, RingType other)
          Arithmetic subtraction other after element-wise scaling of other by scaleFactor from this.
 void scaledMinusEquals(double scaleFactor, RingType other)
          Inline arithmetic subtraction of other after element-wise scaling of other by scaleFactor from this.
 RingType scaledPlus(double scaleFactor, RingType other)
          Arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
 void scaledPlusEquals(double scaleFactor, RingType other)
          Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
 void scaleEquals(double scaleFactor)
          Inline element-wise scaling of this by scaleFactor
 void zero()
          Zeros out all elements of this, so that the following are equivalent r1.scaleEquals( 0.0 ); and r1.zero(); Furthermore, r1.zero(); anything.dotTimes( r1 ).equals( r1 );
 

Method Detail

equals

boolean equals(Object other)
Determines if two RingType objects are equal

Overrides:
equals in class Object
Parameters:
other - RingType to compare against this
Returns:
True if the two objects are equal, false otherwise

equals

boolean equals(RingType other,
               double effectiveZero)
Determines if two RingType objects are effectively equal

Parameters:
other - RingType to compare against this
effectiveZero - tolerance threshold for element-wise equality
Returns:
True if the two objects are equal, false otherwise

clone

RingType clone()
Returns a smart copy of this, such that changing the values of the return class will not effect this

Specified by:
clone in interface CloneableSerializable
Returns:
smart copy of this

plus

RingType plus(RingType other)
Arithmetic addition of this and other

Parameters:
other - object to add to this
Returns:
sum of this and other

plusEquals

void plusEquals(RingType other)
Inline arithmetic addition of this and other

Parameters:
other - object to add to this

minus

RingType minus(RingType other)
Arithmetic subtraction of other from this

Parameters:
other - object to subtract from this
Returns:
difference of this and other

minusEquals

void minusEquals(RingType other)
Inline arithmetic subtraction of other from this

Parameters:
other - object to subtract from this

dotTimes

RingType dotTimes(RingType other)
Element-wise multiplication of this and other

Parameters:
other - elements of other will be multiplied to the corresponding elements of this
Returns:
element-wise multiplication of this and other

dotTimesEquals

void dotTimesEquals(RingType other)
Inline element-wise multiplication of this and other

Parameters:
other - elements of other will be multiplied to the corresponding elements of this

scale

RingType scale(double scaleFactor)
Element-wise scaling of this by scaleFactor

Parameters:
scaleFactor - amount to scale the elements of this
Returns:
scaling of this

scaleEquals

void scaleEquals(double scaleFactor)
Inline element-wise scaling of this by scaleFactor

Parameters:
scaleFactor - amount to scale the elements of this

scaledPlus

RingType scaledPlus(double scaleFactor,
                    RingType other)
Arithmetic addition of this and other after element-wise scaling of other by scaleFactor. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x + a * y. It is typically a more efficient way of doing this.plus(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.
Returns:
The result of applying the scale factor to other then adding to this.

scaledPlusEquals

void scaledPlusEquals(double scaleFactor,
                      RingType other)
Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x += a * y. It is typically a more efficient way of doing this.plusEquals(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.

scaledMinus

RingType scaledMinus(double scaleFactor,
                     RingType other)
Arithmetic subtraction other after element-wise scaling of other by scaleFactor from this. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x - a * y. It is typically a more efficient way of doing this.minus(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Parameters:
scaleFactor - The scale factor to multiply by the elements of other before subtracting from the elements of this.
other - Object to scale and then subtract from this.
Returns:
The result of applying the scale factor to other then subtract from this.

scaledMinusEquals

void scaledMinusEquals(double scaleFactor,
                       RingType other)
Inline arithmetic subtraction of other after element-wise scaling of other by scaleFactor from this. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x -= a * y. It is typically a more efficient way of doing this.minusEquals(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.

negative

RingType negative()
Returns the element-wise negation of this, such that this.plus( this.negative() ) has only zero elements.

Returns:
element-wise negation of this

negativeEquals

void negativeEquals()
Inline element-wise negation of this


zero

void zero()
Zeros out all elements of this, so that the following are equivalent r1.scaleEquals( 0.0 ); and r1.zero(); Furthermore, r1.zero(); anything.dotTimes( r1 ).equals( r1 );


isZero

boolean isZero()
Determines if this ring is equal to zero.

Returns:
True if all of the elements of this ring are zero.

isZero

boolean isZero(double effectiveZero)
Determines if this ring is equal to zero using the element-wise effective zero value.

Parameters:
effectiveZero - Tolerance threshold for element-wise equality
Returns:
True if all of the elements of this ring are effectively zero.