gov.sandia.cognition.math.Ring Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of cognitive-foundry Show documentation
Show all versions of cognitive-foundry Show documentation
A single jar with all the Cognitive Foundry components.
/*
* File: Ring.java
* Authors: Kevin R. Dixon
* Company: Sandia National Laboratories
* Project: Cognitive Foundry
*
* Copyright March 15, 2006, Sandia Corporation. Under the terms of Contract
* DE-AC04-94AL85000, there is a non-exclusive license for use of this work by
* or on behalf of the U.S. Government. Export of this program may require a
* license from the United States Government. See CopyrightHistory.txt for
* complete details.
*
*/
package gov.sandia.cognition.math;
import gov.sandia.cognition.annotation.CodeReview;
import gov.sandia.cognition.annotation.CodeReviews;
import gov.sandia.cognition.annotation.PublicationReference;
import gov.sandia.cognition.annotation.PublicationType;
import gov.sandia.cognition.util.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.
*
* @param Type of Ring that this class can operate upon, usually itself
* @author Kevin R. Dixon
* @since 1.0
*/
@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=PublicationType.WebPage,
year=2008,
url="http://en.wikipedia.org/wiki/Ring_(mathematics)"
)
public interface Ring>
extends CloneableSerializable
{
/**
* Determines if two RingType objects are equal
*
* @param other
* RingType to compare against this
* @return True if the two objects are equal, false otherwise
*/
public boolean equals(
Object other );
/**
* Determines if two RingType objects are effectively equal
*
* @param other
* RingType to compare against this
* @param effectiveZero
* tolerance threshold for element-wise equality
* @return True if the two objects are equal, false otherwise
*/
public boolean equals(
RingType other,
double effectiveZero );
/**
* Returns a smart copy of this, such that changing the values
* of the return class will not effect this
*
* @return smart copy of this
*/
public RingType clone();
/**
* Arithmetic addition of this and other
*
* @param other
* object to add to this
* @return sum of this and other
*/
public RingType plus(
final RingType other );
/**
* Inline arithmetic addition of this and other
*
* @param other
* object to add to this
*/
public void plusEquals(
final RingType other );
/**
* Arithmetic subtraction of other from this
*
* @param other
* object to subtract from this
* @return difference of this and other
*/
public RingType minus(
final RingType other );
/**
* Inline arithmetic subtraction of other from
* this
*
* @param other
* object to subtract from this
*/
public void minusEquals(
final RingType other );
/**
* Element-wise multiplication of this and other
*
* @param other
* elements of other will be multiplied to the corresponding
* elements of this
* @return element-wise multiplication of this and
* other
*/
public RingType dotTimes(
final RingType other );
/**
* Inline element-wise multiplication of this and
* other
*
* @param other
* elements of other will be multiplied to the corresponding
* elements of this
*/
public void dotTimesEquals(
final RingType other );
/**
* Element-wise scaling of this by scaleFactor
*
* @param scaleFactor
* amount to scale the elements of this
* @return scaling of this
*/
public RingType scale(
double scaleFactor );
/**
* Inline element-wise scaling of this by
* scaleFactor
*
* @param scaleFactor
* amount to scale the elements of this
*/
public void scaleEquals(
double scaleFactor );
/**
* Arithmetic addition of {@code this} and {@code other} after
* element-wise scaling of {@code other} by {@code 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
* {@code this.plus(other.scale(scaleFactor))} since it can avoid
* intermediate object creation.
*
* @param scaleFactor
* The scale factor to multiply by the elements of other before
* adding to the elements of this.
* @param other
* Object to scale and then add to this.
* @return
* The result of applying the scale factor to other then adding to
* this.
*/
public RingType scaledPlus(
final double scaleFactor,
final RingType other);
/**
* Inline arithmetic addition of {@code this} and {@code other} after
* element-wise scaling of {@code other} by {@code 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
* {@code this.plusEquals(other.scale(scaleFactor))} since it can avoid
* intermediate object creation.
*
* @param scaleFactor
* The scale factor to multiply by the elements of other before
* adding to the elements of this.
* @param other
* Object to scale and then add to this.
*/
public void scaledPlusEquals(
final double scaleFactor,
final RingType other);
/**
* Arithmetic subtraction {@code other} after element-wise scaling of
* {@code other} by {@code scaleFactor} from {@code 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
* {@code this.minus(other.scale(scaleFactor))} since it can avoid
* intermediate object creation.
*
* @param scaleFactor
* The scale factor to multiply by the elements of other before
* subtracting from the elements of this.
* @param other
* Object to scale and then subtract from this.
* @return
* The result of applying the scale factor to other then subtract from
* this.
*/
public RingType scaledMinus(
final double scaleFactor,
final RingType other);
/**
* Inline arithmetic subtraction of {@code other} after element-wise
* scaling of {@code other} by {@code scaleFactor} from {@code 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
* {@code this.minusEquals(other.scale(scaleFactor))} since it can avoid
* intermediate object creation.
*
* @param scaleFactor
* The scale factor to multiply by the elements of other before
* adding to the elements of this.
* @param other
* Object to scale and then add to this.
*/
public void scaledMinusEquals(
final double scaleFactor,
final RingType other);
/**
* Returns the element-wise negation of this, such that
* this.plus( this.negative() ) has only zero elements.
*
* @return element-wise negation of this
*/
public RingType negative();
/**
* Inline element-wise negation of this
*/
public void negativeEquals();
/**
* 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 );
*/
public void zero();
/**
* Determines if this ring is equal to zero.
*
* @return
* True if all of the elements of this ring are zero.
*/
public boolean isZero();
/**
* Determines if this ring is equal to zero using the element-wise effective
* zero value.
*
* @param effectiveZero
* Tolerance threshold for element-wise equality
* @return
* True if all of the elements of this ring are effectively zero.
*/
public boolean isZero(
final double effectiveZero);
}