org.jeometry.math.Vector Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jeometry-api Show documentation
Jeometry, a Mathematic and Geometry library for Java
There is a newer version: 1.0.5
package org.jeometry.math;

import org.jeometry.Jeometry;

/**
 * An interface that represents a vector as a set of double coordinates. Each coordinate is expressed belong a dimension.
 * @author Julien Seinturier - COMEX S.A. - [email protected] - https://github.com/jorigin/jeometry
 * @version {@value Jeometry#version}
 * @since 1.0.0
 */
public interface Vector {

	/**
	 * Get the dimension of this vector. The dimension is the number of components that this vector can holds.
	 * @return the dimension of this vector. 
	 */
	public int getDimension();

	/**
	 * Get the value of the coordinate expressed within the given dimension.
	 * @param dimension the dimension of the coordinate.
	 * @return the value of the coordinate expressed within the given dimension.
	 * @see #setValue(int, double)
	 */
	public double getValue(int dimension);

	/**
	 * Set the value of the coordinate expressed within the given dimension.
	 * @param dimension the dimension of the coordinate.
	 * @param value the value of the coordinate expressed within the given dimension.
	 * @see #getValue(int)
	 */
	public void setValue(int dimension, double value);

	/**
	 * Set the components of this vector with the values of the components from the given one.
	 * @param v the vector to copy
	 * @throws IllegalArgumentException if the given vector has no the same dimension as this one
	 */
	public void setValues(Vector v);

	/**
	 * Get the values of the components of this vector as an array of double.
	 * @return the values of the components of this vector as an array of double
	 * @see #getValues(double[])
	 */
	public double[] getValues();

	/**
	 * Get the values of the components of this vector as an array of double.
	 * @param components the array that has to store the values of the components of this vector
	 * @return a reference on components
	 * @see #getValues()
	 * @throws IllegalArgumentException if components is null or if its length does not match the vector dimension
	 */
	public double[] getValues(double[] components);

	/**
	 * Set the components of this vector with the values of the components from the vector represented by the input array.
	 * @param components the components value to affect to this vector
	 * @throws IllegalArgumentException if the length of the input array does not match the dimension of this vector
	 */
	public void setValues(double[] components);

	/**
	 * Set all the components of this vector to the given value.
	 * @param value the value to set to all components
	 */
	public void setValues(double value);
	
	/**
	 * Set the components of this vector according to the given {@link Matrix matrix}. 
	 * The matrix has to be a single row or a single column. 
	 * @param matrix the matrix to use as the values provider
	 * @throws IllegalArgumentException if the matrix is not single row / single column or if its size does not fit the vector
	 */
	public void setValues(Matrix matrix);
	
	/**
	 * Compute the vector that is the sum, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ + v₀, …, u_i + v_i, …, u_n + v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to add to this one
	 * @return the vector that is the sum, component by component of this vector and the given one
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector plus(Vector v);
	
	/**
	 * Compute the vector that is the sum, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ + v₀, …, u_i + v_i, …, u_n + v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to add to this one
	 * @param result the vector that holds the result
	 * @return a reference on the result vector
	 * @throws IllegalArgumentException if the input vector or the result vector dimension does not fit with this one
	 */
	public Vector plus(Vector v, Vector result);
	
	/**
	 * Affect this vector with the sum, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ + v₀, …, u_i + v_i, …, u_n + v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to add to this one
	 * @return a reference on this vector
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector plusAffect(Vector v);
	
	/**
	 * Compute the vector that is the sum, component by component of this vector and the given scalar. 
	 * More formally, let U be this vector and let s the scalar given in parameter, this method compute the vector W such that:

	 * W = (u₀ + s, …, u_i + s, …, u_n + s)
	 * 

	 * where u_i are the values of the i^th component of vector U.
	 * 
 
	 * @param scalar the scalar to add to this vector
	 * @return the vector that is the sum, component by component of this vector and the given scalar
	 */
	public Vector plus(double scalar);
	
	/**
	 * Compute the vector that is the sum, component by component of this vector and the given scalar. 
	 * More formally, let U be this vector and let s the scalar given in parameter, this method compute the vector W such that:

	 * W = (u₀ + s, …, u_i + s, …, u_n + s)
	 * 

	 * where u_i are the values of the i^th component of vector U.
	 * 
 
	 * @param scalar the scalar to add to this vector
	 * @param result the vector that holds the result
	 * @return the vector that is the sum, component by component of this vector and the given scalar
	 * @throws IllegalArgumentException if the result vector dimension does not fit with this one
	 */
	public Vector plus(double scalar, Vector result);

	/**
	 * Affect this vector with the sum, component by component of this vector and the given scalar. 
	 * More formally, let U be this vector and let s the scalar given in parameter, this method compute the vector W such that:

	 * W = (u₀ + s, …, u_i + s, …, u_n + s)
	 * 

	 * where u_i are the values of the i^th component of vector U.
	 * 
 
	 * @param scalar the scalar to add to this vector
	 * @return a reference on this vector
	 */
	public Vector plusAffect(double scalar);	
	
	/**
	 * Compute the vector that is the subtraction, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ - v₀, …, u_i - v_i, …, u_n - v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to subtract from this one
	 * @return the vector that is the subtraction, component by component of this vector and the given one
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector minus(Vector v);
	
	/**
	 * Compute the vector that is the subtraction, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ - v₀, …, u_i - v_i, …, u_n - v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to subtract from this one
	 * @param result the vector that holds the result
	 * @return a reference on the result vector
	 * @throws IllegalArgumentException if the input vector or the result vector dimension does not fit with this one
	 */
	public Vector minus(Vector v, Vector result);
	
	/**
	 * Affect this vector with the subtraction, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ - v₀, …, u_i - v_i, …, u_n - v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to subtract from this one
	 * @return a reference on this vector
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector minusAffect(Vector v);
	
	/**
	 * Compute the vector that is the difference, component by component of this vector and the given scalar. 
	 * More formally, let U be this vector and let s the scalar given in parameter, this method compute the vector W such that:

	 * W = (u₀ - s, …, u_i - s, …, u_n - s)
	 * 

	 * where u_i are the values of the i^th component of vector U.
	 * 
 
	 * @param scalar the scalar to add to this vector
	 * @return the vector that is the difference, component by component of this vector and the given scalar
	 */
	public Vector minus(double scalar);
	
	/**
	 * Compute the vector that is the difference, component by component of this vector and the given scalar. 
	 * More formally, let U be this vector and let s the scalar given in parameter, this method compute the vector W such that:

	 * W = (u₀ - s, …, u_i - s, …, u_n - s)
	 * 

	 * where u_i are the values of the i^th component of vector U.
	 * 
 
	 * @param scalar the scalar to add to this vector
	 * @param result the vector that holds the result
	 * @return the vector that is the difference, component by component of this vector and the given scalar
	 */
	public Vector minus(double scalar, Vector result);

	/**
	 * Affect this vector with the difference, component by component of this vector and the given scalar. 
	 * More formally, let U be this vector and let s the scalar given in parameter, this method compute the vector W such that:

	 * W = (u₀ - s, …, u_i - s, …, u_n - s)
	 * 

	 * where u_i are the values of the i^th component of vector U.
	 * 
 
	 * @param scalar the scalar to add to this vector
	 * @return a reference on this vector
	 */
	public Vector minusAffect(double scalar);
	
	/**
	 * Extract a vector that contains the part of this vector specified by the parameters.
	 * @param start the index of the first component to extract (inclusive)
	 * @param length the number of contiguous components to extract from the first
	 * @return a vector that contains the part of this vector delimited by the parameters
	 */
	public Vector extract(int start, int length);
	
	/**
	 * Compute the squared norm of the vector:

	 * Σⁿ_i=1c_i²

	 * Where c_i is the vector component at index i and n is the vector length.
	 * @return the squared norm of the vector.
	 */
	public double normSquare();

	/**
	 * Compute the norm of the vector:

	 * \(
	 * \sqrt{\sum\limits_{i=1}^n c_{i}^{2}}
	 * \)

	 * Where c_i is the vector component at index i and n is the vector length.
	 * @return The norm of the vector
	 */
	public double norm();

	/**
	 * Divide all the components of this vector by its {@link #norm() Euclidean norm}. When called on a vector v = (c₀, ..., c_i, ..., c_n), this method modify its components as follows:

	 * $$v\ =\ (\frac{c_{0}}{||p||},\ \ldots,\ \frac{c_{i}}{||p||},\ \ldots\ ,\ \frac{c_{n}}{||p||})$$
	 * @see #norm()
	 */
	public void normalize();

	/**
	 * Return a normalized vector that is orthogonal to this one.
	 * @return a normalized vector that is orthogonal to this one.
	 * @see #orthogonal(Vector)
	 */
	public Vector orthogonal();

	/**
	 * Set the given result vector with the normalized vector that is orthogonal to this one.
	 * @param result the vector where the result has to be stored.
	 * @return the given result vector with the normalized vector that is orthogonal to this one.
	 * @see #orthogonal()
	 * @throws IllegalArgumentException if the result vector length is not equals to this one.
	 */
	public Vector orthogonal(Vector result);

	/**
	 * Return the vector made of the multiplication of this one by the scalar given in parameter.
	 * Formally, let V = [v₀,...,v_i,...,v_n] a vector and s a scalar, 
	 * the multiplication of V by the scalar is the vector V' such that:


	 * V' = [sv₀,...,sv_i,...,sv_n]

	 * @param scalar the scalar to multiply.
	 * @return the vector made of the multiplication of this one by the scalar given in parameter.
	 */
	public Vector multiply(double scalar);

	/**
	 * Compute the multiplication of this vector by the scalar given in parameter and store the result in the given vector.
	 * Formally, let V = [v₀,...,v_i,...,v_n] a vector and s a scalar, 
	 * the multiplication of V by the scalar is the vector V' such that:


	 * V' = [sv₀,...,sv_i,...,sv_n]

	 * @param scalar the scalar to multiply
	 * @param result the vector that has to store the result
	 * @return the same reference as result.
	 * @throws IllegalArgumentException if the result vector does not fit for the multiplication.
	 */
	public Vector multiply(double scalar, Vector result) throws IllegalArgumentException;

	/**
	 * Affect this vector with the result of its multiplication by the scalar given in parameter.
	 * Formally, let V = [v₀,...,v_i,...,v_n] a vector and s a scalar, 
	 * the multiplication of V by the scalar is the vector V' such that:


	 * V' = [sv₀,...,sv_i,...,sv_n]

	 * @param scalar the scalar to multiply
	 * @return a reference to this object
	 */
	public Vector multiplyAffect(double scalar);
	
	/**
	 * Compute the vector that is the product, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ × v₀, …, u_i × v_i, …, u_n × v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to multiply to this one
	 * @return the vector that is the product, component by component of this vector and the given one
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector multiply(Vector v);

	/**
	 * Compute the vector that is the product, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ × v₀, …, u_i × v_i, …, u_n × v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to multiply to this one
	 * @param result the vector that holds the result
	 * @return a reference on the result vector
	 * @throws IllegalArgumentException if the input vector or the result vector dimension does not fit with this one
	 */
	public Vector multiply(Vector v, Vector result);

	/**
	 * Affect this vector with the product, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ × v₀, …, u_i × v_i, …, u_n × v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the vector to product from this one
	 * @return a reference on this vector
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector multiplyAffect(Vector v);
	
	/**
	 * Compute the vector that is the division, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ / v₀, …, u_i / v_i, …, u_n / v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the divider vector 
	 * @return the vector that is the division, component by component of this vector and the given one
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector divide(Vector v);

	/**
	 * Compute the vector that is the division, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ / v₀, …, u_i / v_i, …, u_n / v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the divider vector 
	 * @param result the vector that holds the result
	 * @return a reference on the result vector
	 * @throws IllegalArgumentException if the input vector or the result vector dimension does not fit with this one
	 */
	public Vector divide(Vector v, Vector result);

	/**
	 * Affect this vector with the division, component by component of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the vector W such that:

	 * W = (u₀ / v₀, …, u_i / v_i, …, u_n / v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the divider vector 
	 * @return a reference on this vector
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public Vector divideAffect(Vector v);
	
	/**
	 * Return the vector made of the division of this one by the scalar given in parameter.
	 * Formally, let V = [v₀,...,v_i,...,v_n] a vector and s a scalar, 
	 * the multiplication of V by the scalar is the vector V' such that:


	 * V' = [v₀/s,...,v_i/s,...,v_n/s]

	 * @param scalar the scalar to use as divider.
	 * @return the vector made of the division of this one by the scalar given in parameter.
	 */
	public Vector divide(double scalar);

	/**
	 * Compute the division of this vector by the scalar given in parameter and store the result in the given vector.
	 * Formally, let V = [v₀,...,v_i,...,v_n] a vector and s a scalar, 
	 * the multiplication of V by the scalar is the vector V' such that:


	 * V' = [v₀/s,...,v_i/s,...,v_n/s]

	 * @param scalar the scalar to use as divider
	 * @param result the vector that has to store the result
	 * @return the same reference as result.
	 * @throws IllegalArgumentException if the result vector does not fit for the division.
	 */
	public Vector divide(double scalar, Vector result) throws IllegalArgumentException;

	/**
	 * Affect this vector with the result of its division by the scalar given in parameter.
	 * Formally, let V = [v₀,...,v_i,...,v_n] a vector and s a scalar, 
	 * the multiplication of V by the scalar is the vector V' such that:


	 * V' = [v₀/s,...,v_i/s,...,v_n/s]

	 * @param scalar the scalar to use as divider
	 * @return a reference to this object
	 */
	public Vector divideAffect(double scalar);
	
	/**
	 * Compute the scalar product of this vector and the given one. 
	 * More formally, let U be this vector and let V the vector given in parameter, this method compute the scalar U·V such that:

	 * U·V = (u₀ × v₀ + …+ u_i × v_i + …+ u_n × v_n)
	 * 

	 * where u_i, v_i are respectively the values of the i^th component of vector U, V.
	 * 
 
	 * @param v the second operand
	 * @return the scalar product of this vector and the given one or {@link Double#NaN Double.Nan} if v is null
	 * @throws IllegalArgumentException if the input vector dimension does not fit with this one
	 */
	public double dot(Vector v);
}