[ https://issues.apache.org/jira/browse/MATH765?page=com.atlassian.jira.plugin.system.issuetabpanels:alltabpanel
]
Sébastien Brisard updated MATH765:

Description:
{panel:title=WarningborderStyle=solid}
This is not a bug report, but rather a summary of all discussions which have taken place on
the mailing list regarding the refactoring of the vector and matrix classes. Indeed, it has
been argued many times that the {{RealVector}} and {{RealMatrix}} interfaces are really cluttered,
and could benefit from other approaches (like functional programming).
The description of this ticket will be updated as the discussion progresses on the mailinglist,
and new JIRA tickets will be created to carry out the "real" work. {color:red}In order to
keep this ticket tidy, contributors should refrain from commenting on this website. Instead,
messages should be posted on the dev mailinglist{color}.
{panel}
h1. The current API (version 3.0)
In this section, the current interfaces for vectors and matrices are compared. Vectors and
matrices are two mathematical objects which are very close in nature. Their implementations
should therefore be as similar as possible. The methods will be sorted as follows
* methods reflecting the mathematical structure of vector space: addition, multiplication
by a scalar, matrixvector product, ...
* methods reflecting the mathematical structure of euclidean space
* ...
h2. Methods reflecting the mathematical structure of vector space
h3. List of the methods
 {{RealVector}}  {{RealMatrix}}
 Comments 
 {{RealVector add(RealVector v)}}  {{RealMatrix add(RealMatrix m)}}
 
 {{int getDimension()}}  {{int getRowDimension()}},\\ {{int getColumnDimension()}}
 
 {{RealVector mapMultiply(double d)}}  {{scalarMultiply(double d)}}
 (1) 
  {{double getTrace()}}
 
  {{multiply(RealMatrix m)}}
 
  {{double[] operate(double[])}}
 (2) 
  {{RealVector operate(RealVector)}}
 
  {{RealMatrix power(int p)}}
 
  {{double[] preMultiply(double[])}}
 (2) 
  {{RealMatrix preMultiply(RealMatrix)}}
 
  {{RealVector preMultiply(RealVector)}}
 
  {{RealMatrix transpose()}}
 
h3. Comments on the above methods
h4. Comment (1)
{{RealVector RealVector.mapMultiply(double)}} and {{RealMatrix RealMatrix.scalarMultiply(double)}}
perform essentially the same task. Readibility of the classes would be improved if they add
the same name. This is very important since these methods reflect the fact that the space
of vectors as well as the space of matrices are two vector spaces.
h4. Comment (2)
Prior to the release of version 3.0, all methods involving taking as argument, or returning,
{{double[]}} representing vectors were removed. The rationale for this is that calling {{new
ArrayRealVector(double[], false)}} is very easy, and comes at virtually no cost (see MATH653
and MATH660). It might be worth considering the same simplification for the {{RealMatrix}}
interface.
h2. Methods reflecting the mathematical structure of euclidean space
h3. List of the methods
 {{RealVector}}  {{RealMatrix}}  Comments 
 {{double cosine(RealVector v)}}   
 {{double dotProduct(RealVector v)}}   (3) 
 {{double getDistance(RealVector v)}}   
 {{double getNorm()}}   
 {{RealVector projection(RealVector v)}}   
 {{void unitize()}}   (4) 
 {{RealVector unitVector()}}   
h3. Comments on the above methods
h4. Comment (3)
In a way, {{RealMatrix RealMatrix.transpose()}} could be seen as a method inherent to the
euclidean structure, and the generalization of the dot product. For this reason, {{transpose()}}
should probably _not_ be externalized.
h4. Comment (4)
This could be externalized with the visitor pattern (see below).
h4. Comment (5)
Could be externalized in a factory class.
h2. Constructors, factory methods and related methods
h2. Manipulation of entries
h2. Various norms
h2. Functionalprogramminglike methods
was:
{panel:title=WarningborderStyle=solid}
This is not a bug report, but rather a summary of all discussions which have taken place on
the mailing list regarding the refactoring of the vector and matrix classes. Indeed, it has
been argued many times that the {{RealVector}} and {{RealMatrix}} interfaces are really cluttered,
and could benefit from other approaches (like functional programming).
The description of this ticket will be updated as the discussion progresses on the mailinglist,
and new JIRA tickets will be created to carry out the "real" work. {color:red}In order to
keep this ticket tidy, contributors should refrain from commenting on this website. Instead,
messages should be posted on the dev mailinglist{color}.
{panel}
h1. The current API (version 3.0)
In this section, the current interfaces for vectors and matrices are compared. Vectors and
matrices are two mathematical objects which are very close in nature. Their implementations
should therefore be as similar as possible. The methods will be sorted as follows
* methods reflecting the mathematical structure of vector space: addition, multiplication
by a scalar, matrixvector product, ...
* methods reflecting the mathematical structure of euclidean space
* ...
h2. Methods reflecting the mathematical structure of vector space
h3. List of the methods
 {{RealVector}}  {{RealMatrix}}
 Comments 
 {{RealVector add(RealVector v)}}  {{RealMatrix add(RealMatrix m)}}
 
 {{int getDimension()}}  {{int getRowDimension()}},\\ {{int getColumnDimension()}}
 
 {{RealVector mapMultiply(double d)}}  {{scalarMultiply(double d)}}
 (1) 
  {{double getTrace()}}
 
  {{multiply(RealMatrix m)}}
 
  {{double[] operate(double[])}}
 (2) 
  {{RealVector operate(RealVector)}}
 
  {{RealMatrix power(int p)}}
 
  {{double[] preMultiply(double[])}}
 (2) 
  {{RealMatrix preMultiply(RealMatrix)}}
 
  {{RealVector preMultiply(RealVector)}}
 
  {{RealMatrix transpose()}}
 
h3. Comments on the above methods
h4. Comment (1)
{{RealVector RealVector.mapMultiply(double)}} and {{RealMatrix RealMatrix.scalarMultiply(double)}}
perform essentially the same task. Readibility of the classes would be improved if they add
the same name. This is very important since these methods reflect the fact that the space
of vectors as well as the space of matrices are two vector spaces.
h4. Comment (2)
Prior to the release of version 3.0, all methods involving taking as argument, or returning,
{{double[]}} representing vectors were removed. The rationale for this is that calling {{new
ArrayRealVector(double[], false)}} is very easy, and comes at virtually no cost (see MATH653
and MATH660). It might be worth considering the same simplification for the {{RealMatrix}}
interface.
h2. Methods reflecting the mathematical structure of euclidean space
h2. Constructors, factory methods and related methods
h2. Manipulation of entries
h2. Various norms
h2. Functionalprogramminglike methods
> Refactoring the vector and matrix classes
> 
>
> Key: MATH765
> URL: https://issues.apache.org/jira/browse/MATH765
> Project: Commons Math
> Issue Type: Improvement
> Affects Versions: 4.0
> Reporter: Sébastien Brisard
> Labels: apichange, linear
>
> {panel:title=WarningborderStyle=solid}
> This is not a bug report, but rather a summary of all discussions which have taken place
on the mailing list regarding the refactoring of the vector and matrix classes. Indeed, it
has been argued many times that the {{RealVector}} and {{RealMatrix}} interfaces are really
cluttered, and could benefit from other approaches (like functional programming).
> The description of this ticket will be updated as the discussion progresses on the mailinglist,
and new JIRA tickets will be created to carry out the "real" work. {color:red}In order to
keep this ticket tidy, contributors should refrain from commenting on this website. Instead,
messages should be posted on the dev mailinglist{color}.
> {panel}
> h1. The current API (version 3.0)
> In this section, the current interfaces for vectors and matrices are compared. Vectors
and matrices are two mathematical objects which are very close in nature. Their implementations
should therefore be as similar as possible. The methods will be sorted as follows
> * methods reflecting the mathematical structure of vector space: addition, multiplication
by a scalar, matrixvector product, ...
> * methods reflecting the mathematical structure of euclidean space
> * ...
> h2. Methods reflecting the mathematical structure of vector space
> h3. List of the methods
>  {{RealVector}}  {{RealMatrix}}
 Comments 
>  {{RealVector add(RealVector v)}}  {{RealMatrix add(RealMatrix m)}}
 
>  {{int getDimension()}}  {{int getRowDimension()}},\\ {{int getColumnDimension()}}
 
>  {{RealVector mapMultiply(double d)}}  {{scalarMultiply(double d)}}
 (1) 
>   {{double getTrace()}}
 
>   {{multiply(RealMatrix m)}}
 
>   {{double[] operate(double[])}}
 (2) 
>   {{RealVector operate(RealVector)}}
 
>   {{RealMatrix power(int p)}}
 
>   {{double[] preMultiply(double[])}}
 (2) 
>   {{RealMatrix preMultiply(RealMatrix)}}
 
>   {{RealVector preMultiply(RealVector)}}
 
>   {{RealMatrix transpose()}}
 
> h3. Comments on the above methods
> h4. Comment (1)
> {{RealVector RealVector.mapMultiply(double)}} and {{RealMatrix RealMatrix.scalarMultiply(double)}}
perform essentially the same task. Readibility of the classes would be improved if they add
the same name. This is very important since these methods reflect the fact that the space
of vectors as well as the space of matrices are two vector spaces.
> h4. Comment (2)
> Prior to the release of version 3.0, all methods involving taking as argument, or returning,
{{double[]}} representing vectors were removed. The rationale for this is that calling {{new
ArrayRealVector(double[], false)}} is very easy, and comes at virtually no cost (see MATH653
and MATH660). It might be worth considering the same simplification for the {{RealMatrix}}
interface.
> h2. Methods reflecting the mathematical structure of euclidean space
> h3. List of the methods
>  {{RealVector}}  {{RealMatrix}}  Comments 
>  {{double cosine(RealVector v)}}   
>  {{double dotProduct(RealVector v)}}   (3) 
>  {{double getDistance(RealVector v)}}   
>  {{double getNorm()}}   
>  {{RealVector projection(RealVector v)}}   
>  {{void unitize()}}   (4) 
>  {{RealVector unitVector()}}   
> h3. Comments on the above methods
> h4. Comment (3)
> In a way, {{RealMatrix RealMatrix.transpose()}} could be seen as a method inherent to
the euclidean structure, and the generalization of the dot product. For this reason, {{transpose()}}
should probably _not_ be externalized.
> h4. Comment (4)
> This could be externalized with the visitor pattern (see below).
> h4. Comment (5)
> Could be externalized in a factory class.
> h2. Constructors, factory methods and related methods
> h2. Manipulation of entries
> h2. Various norms
> h2. Functionalprogramminglike methods

This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
