001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math3.geometry;
018
019 import java.io.Serializable;
020 import java.text.NumberFormat;
021
022 import org.apache.commons.math3.exception.MathArithmeticException;
023
024 /** This interface represents a generic vector in a vectorial space or a point in an affine space.
025 * @param <S> Type of the space.
026 * @version $Id: Vector.java 1416643 2012-12-03 19:37:14Z tn $
027 * @see Space
028 * @see Vector
029 * @since 3.0
030 */
031 public interface Vector<S extends Space> extends Serializable {
032
033 /** Get the space to which the vector belongs.
034 * @return containing space
035 */
036 Space getSpace();
037
038 /** Get the null vector of the vectorial space or origin point of the affine space.
039 * @return null vector of the vectorial space or origin point of the affine space
040 */
041 Vector<S> getZero();
042
043 /** Get the L<sub>1</sub> norm for the vector.
044 * @return L<sub>1</sub> norm for the vector
045 */
046 double getNorm1();
047
048 /** Get the L<sub>2</sub> norm for the vector.
049 * @return Euclidean norm for the vector
050 */
051 double getNorm();
052
053 /** Get the square of the norm for the vector.
054 * @return square of the Euclidean norm for the vector
055 */
056 double getNormSq();
057
058 /** Get the L<sub>∞</sub> norm for the vector.
059 * @return L<sub>∞</sub> norm for the vector
060 */
061 double getNormInf();
062
063 /** Add a vector to the instance.
064 * @param v vector to add
065 * @return a new vector
066 */
067 Vector<S> add(Vector<S> v);
068
069 /** Add a scaled vector to the instance.
070 * @param factor scale factor to apply to v before adding it
071 * @param v vector to add
072 * @return a new vector
073 */
074 Vector<S> add(double factor, Vector<S> v);
075
076 /** Subtract a vector from the instance.
077 * @param v vector to subtract
078 * @return a new vector
079 */
080 Vector<S> subtract(Vector<S> v);
081
082 /** Subtract a scaled vector from the instance.
083 * @param factor scale factor to apply to v before subtracting it
084 * @param v vector to subtract
085 * @return a new vector
086 */
087 Vector<S> subtract(double factor, Vector<S> v);
088
089 /** Get the opposite of the instance.
090 * @return a new vector which is opposite to the instance
091 */
092 Vector<S> negate();
093
094 /** Get a normalized vector aligned with the instance.
095 * @return a new normalized vector
096 * @exception MathArithmeticException if the norm is zero
097 */
098 Vector<S> normalize() throws MathArithmeticException;
099
100 /** Multiply the instance by a scalar.
101 * @param a scalar
102 * @return a new vector
103 */
104 Vector<S> scalarMultiply(double a);
105
106 /**
107 * Returns true if any coordinate of this vector is NaN; false otherwise
108 * @return true if any coordinate of this vector is NaN; false otherwise
109 */
110 boolean isNaN();
111
112 /**
113 * Returns true if any coordinate of this vector is infinite and none are NaN;
114 * false otherwise
115 * @return true if any coordinate of this vector is infinite and none are NaN;
116 * false otherwise
117 */
118 boolean isInfinite();
119
120 /** Compute the distance between the instance and another vector according to the L<sub>1</sub> norm.
121 * <p>Calling this method is equivalent to calling:
122 * <code>q.subtract(p).getNorm1()</code> except that no intermediate
123 * vector is built</p>
124 * @param v second vector
125 * @return the distance between the instance and p according to the L<sub>1</sub> norm
126 */
127 double distance1(Vector<S> v);
128
129 /** Compute the distance between the instance and another vector according to the L<sub>2</sub> norm.
130 * <p>Calling this method is equivalent to calling:
131 * <code>q.subtract(p).getNorm()</code> except that no intermediate
132 * vector is built</p>
133 * @param v second vector
134 * @return the distance between the instance and p according to the L<sub>2</sub> norm
135 */
136 double distance(Vector<S> v);
137
138 /** Compute the distance between the instance and another vector according to the L<sub>∞</sub> norm.
139 * <p>Calling this method is equivalent to calling:
140 * <code>q.subtract(p).getNormInf()</code> except that no intermediate
141 * vector is built</p>
142 * @param v second vector
143 * @return the distance between the instance and p according to the L<sub>∞</sub> norm
144 */
145 double distanceInf(Vector<S> v);
146
147 /** Compute the square of the distance between the instance and another vector.
148 * <p>Calling this method is equivalent to calling:
149 * <code>q.subtract(p).getNormSq()</code> except that no intermediate
150 * vector is built</p>
151 * @param v second vector
152 * @return the square of the distance between the instance and p
153 */
154 double distanceSq(Vector<S> v);
155
156 /** Compute the dot-product of the instance and another vector.
157 * @param v second vector
158 * @return the dot product this.v
159 */
160 double dotProduct(Vector<S> v);
161
162 /** Get a string representation of this vector.
163 * @param format the custom format for components
164 * @return a string representation of this vector
165 */
166 String toString(final NumberFormat format);
167
168 }