com.enterprisemath.math.algebra.Hypercube Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of em-math Show documentation
Advanced mathematical algorithms.
The newest version!
package com.enterprisemath.math.algebra;

import org.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;
import org.apache.commons.lang3.builder.ToStringBuilder;

import com.enterprisemath.utils.ValidationUtils;

/**
 * This class represents cube generalized to R^n space.
 * Hypercube is closed, therefore all the limit values are also included.
 *
 * @author radek.hecl
 *
 */
public final class Hypercube {

    /**
     *
     * Builder object.
     *
     */
    public static class Builder {

        /**
         * Vector with minimum values.
         */
        private Vector min = null;

        /**
         * Vector with maximum values.
         */
        private Vector max = null;

        /**
         * Sets minimum vector.
         *
         * @param min minimum vector
         * @return this instance
         */
        public Builder setMin(Vector min) {
            this.min = min;
            return this;
        }

        /**
         * Sets maximum vector.
         *
         * @param max maximum vector
         * @return this instance
         */
        public Builder setMax(Vector max) {
            this.max = max;
            return this;
        }

        /**
         * Adds vector.
         * Meaning is that boundaries are extended in the way
         * the specified vector will be inside.
         *
         * @param vector vector
         * @return this instance
         */
        public Builder addVector(Vector vector) {
            if (min == null) {
                min = vector;
                max = vector;
            }
            else {
                min = Vector.createBoundaryMin(min, vector);
                max = Vector.createBoundaryMax(max, vector);
            }
            return this;
        }

        /**
         * Adds sub cube.
         * Meaning is that boundaries are extended in the way
         * the specified sub cube will be inside.
         *
         * @param subCube hypercube
         * @return this instance
         */
        public Builder addSubCube(Hypercube subCube) {
            addVector(subCube.getMin());
            addVector(subCube.getMax());
            return this;
        }

        /**
         * Builds the result object.
         *
         * @return created object
         */
        public Hypercube build() {
            return new Hypercube(this);
        }
    }

    /**
     * Vector with minimum values.
     */
    private Vector min;

    /**
     * Vector with maximum values.
     */
    private Vector max;

    /**
     * Creates new instance.
     *
     * @param builder builder
     */
    public Hypercube(Builder builder) {
        min = builder.min;
        max = builder.max;
        guardInvariants();
    }

    /**
     * Guards this object to be consistent. Throws exception if this is not the case.
     */
    private void guardInvariants() {
        ValidationUtils.guardNotNull(min, "min cannot be null");
        ValidationUtils.guardNotNull(max, "max cannot be null");
        ValidationUtils.guardEquals(min.getDimension(), max.getDimension(), "min and max must have same dimension");
        for (int i = 0; i < getDimension(); ++i) {
            ValidationUtils.guardGreaterOrEqualDouble(max.getComponent(i), min.getComponent(i),
                    "min must be less or equal than max for all components");
        }
    }

    /**
     * Returns the dimension.
     *
     * @return dimension
     */
    public int getDimension() {
        return min.getDimension();
    }

    /**
     * Returns vector with minimum values.
     *
     * @return vector with minimum values
     */
    public Vector getMin() {
        return min;
    }

    /**
     * Returns vector with maximum values.
     *
     * @return vector with maximum values
     */
    public Vector getMax() {
        return max;
    }

    /**
     * Returns the center of this hypercube.
     *
     * @return center of this hypercube
     */
    public Vector getCenter() {
        return Vector.avg(min, max);
    }

    /**
     * Returns vector with size values.
     *
     * @return vector with size values
     */
    public Vector getSize() {
        return Vector.sub(max, min);
    }

    /**
     * Returns whether this cube contains the specified vector or not.
     * Border is considered as inside, because hypercube is closed.
     *
     * @param x tested vector
     * @return true if this hypercube contains specified vector, false otherwise
     */
    public boolean contains(Vector x) {
        ValidationUtils.guardEquals(getDimension(), x.getDimension(), "tested vector must have same dimension");
        for (int i = 0; i < getDimension(); ++i) {
            if (x.getComponent(i) < min.getComponent(i)) {
                return false;
            }
            if (x.getComponent(i) > max.getComponent(i)) {
                return false;
            }
        }
        return true;
    }

    @Override
    public int hashCode() {
        return HashCodeBuilder.reflectionHashCode(this);
    }

    @Override
    public boolean equals(Object obj) {
        return EqualsBuilder.reflectionEquals(this, obj);
    }

    @Override
    public String toString() {
        return ToStringBuilder.reflectionToString(this);
    }

    /**
     * Creates hypercube from a given vectors.
     *
     * @param vectors vectors
     * @return created hypercube
     */
    public static Hypercube createFromVectors(Vector... vectors) {
        Hypercube.Builder builder = new Hypercube.Builder();
        for (int i = 0; i < vectors.length; ++i) {
            builder.addVector(vectors[i]);
        }
        return builder.build();
    }

}