1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.geometry;
23
24 import org.hipparchus.analysis.polynomials.SmoothStepFactory;
25 import org.hipparchus.exception.MathIllegalArgumentException;
26 import org.hipparchus.exception.MathRuntimeException;
27 import org.hipparchus.util.Blendable;
28
29 import java.text.NumberFormat;
30
31 /** This interface represents a generic vector in a vectorial space or a point in an affine space.
32 * @param <S> Type of the space.
33 * @param <V> Type of vector implementing this interface.
34 * @see Space
35 * @see Point
36 */
37 public interface Vector<S extends Space, V extends Vector<S,V>> extends Point<S>, Blendable<Vector<S,V>> {
38
39 /** Get the null vector of the vectorial space or origin point of the affine space.
40 * @return null vector of the vectorial space or origin point of the affine space
41 */
42 V getZero();
43
44 /** Get the L<sub>1</sub> norm for the vector.
45 * @return L<sub>1</sub> norm for the vector
46 */
47 double getNorm1();
48
49 /** Get the L<sub>2</sub> norm for the vector.
50 * @return Euclidean norm for the vector
51 */
52 double getNorm();
53
54 /** Get the square of the norm for the vector.
55 * @return square of the Euclidean norm for the vector
56 */
57 double getNormSq();
58
59 /** Get the L<sub>∞</sub> norm for the vector.
60 * @return L<sub>∞</sub> norm for the vector
61 */
62 double getNormInf();
63
64 /** Add a vector to the instance.
65 * @param v vector to add
66 * @return a new vector
67 */
68 V add(Vector<S,V> v);
69
70 /** Add a scaled vector to the instance.
71 * @param factor scale factor to apply to v before adding it
72 * @param v vector to add
73 * @return a new vector
74 */
75 V add(double factor, Vector<S,V> v);
76
77 /** Subtract a vector from the instance.
78 * @param v vector to subtract
79 * @return a new vector
80 */
81 V subtract(Vector<S,V> v);
82
83 /** Subtract a scaled vector from the instance.
84 * @param factor scale factor to apply to v before subtracting it
85 * @param v vector to subtract
86 * @return a new vector
87 */
88 V subtract(double factor, Vector<S,V> v);
89
90 /** Get the opposite of the instance.
91 * @return a new vector which is opposite to the instance
92 */
93 V negate();
94
95 /** Get a normalized vector aligned with the instance.
96 * @return a new normalized vector
97 * @exception MathRuntimeException if the norm is zero
98 */
99 default V normalize() throws MathRuntimeException{
100 double s = getNorm();
101 if (s == 0) {
102 throw new MathRuntimeException(LocalizedGeometryFormats.CANNOT_NORMALIZE_A_ZERO_NORM_VECTOR);
103 }
104 return scalarMultiply(1 / s);
105 }
106
107 /** Multiply the instance by a scalar.
108 * @param a scalar
109 * @return a new vector
110 */
111 V scalarMultiply(double a);
112
113 /**
114 * Returns true if any coordinate of this vector is infinite and none are NaN;
115 * false otherwise
116 * @return true if any coordinate of this vector is infinite and none are NaN;
117 * false otherwise
118 */
119 boolean isInfinite();
120
121 /** Compute the distance between the instance and another vector according to the L<sub>1</sub> norm.
122 * <p>Calling this method is equivalent to calling:
123 * <code>q.subtract(p).getNorm1()</code> except that no intermediate
124 * vector is built</p>
125 * @param v second vector
126 * @return the distance between the instance and p according to the L<sub>1</sub> norm
127 */
128 double distance1(Vector<S,V> v);
129
130 /** Compute the distance between the instance and another vector according to the L<sub>∞</sub> norm.
131 * <p>Calling this method is equivalent to calling:
132 * <code>q.subtract(p).getNormInf()</code> except that no intermediate
133 * vector is built</p>
134 * @param v second vector
135 * @return the distance between the instance and p according to the L<sub>∞</sub> norm
136 */
137 double distanceInf(Vector<S,V> v);
138
139 /** Compute the square of the distance between the instance and another vector.
140 * <p>Calling this method is equivalent to calling:
141 * <code>q.subtract(p).getNormSq()</code> except that no intermediate
142 * vector is built</p>
143 * @param v second vector
144 * @return the square of the distance between the instance and p
145 */
146 double distanceSq(Vector<S,V> v);
147
148 /** Compute the dot-product of the instance and another vector.
149 * @param v second vector
150 * @return the dot product this.v
151 */
152 double dotProduct(Vector<S,V> v);
153
154 /** Get a string representation of this vector.
155 * @param format the custom format for components
156 * @return a string representation of this vector
157 */
158 String toString(NumberFormat format);
159
160 /** {@inheritDoc} */
161 @Override
162 default V blendArithmeticallyWith(Vector<S,V> other, double blendingValue)
163 throws MathIllegalArgumentException {
164 SmoothStepFactory.checkBetweenZeroAndOneIncluded(blendingValue);
165 return this.scalarMultiply(1 - blendingValue).add(other.scalarMultiply(blendingValue));
166 }
167 }