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 }