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
A single jar with all the Cognitive Foundry components.
There is a newer version: 4.0.1
/*
 * 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 );

    /**
     * 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);

}