You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Eric Barnhill <er...@gmail.com> on 2016/05/31 09:12:06 UTC
Proposed changes to Complex method nomenclature
I propose some minor changes in Complex() methods nomenclature for 4.0 .
These relate to the collection of methods abs(), getArgument(), getReal()
and getImaginary() .
Personally I switch frequently and freely between Cartesian and polar
representations of complex numbers in my code. So to me it would make more
sense to conform the terminology of these arguments, which would
effectively make Complex unbiased as to which representation you use.
Keeping the prefix "get" has sound logic to it as it establishes these
methods as accessor type methods as opposed to other Complex methods like
sin(), which are more derivative.
Some abbreviation is in order to avoid getAbsoluteValue(), so I propose
getAbs(), getArg(), getReal(), and getImag() as the four method names.
This leaves only the question of a constructor that takes polar
representations which I think is already well handled by the present method
ComplexUtils.polar2Complex, for either Complex or Complex[] .
Eric
[Math] Re: Proposed changes to Complex method nomenclature
Posted by Gilles <gi...@harfang.homelinux.org>.
Hello.
On Wed, 1 Jun 2016 21:53:59 +0200, Eric Barnhill wrote:
> On 31/05/16 14:12, Gilles wrote:
>>
>>
>> Short as can be and close to math notation.
>>
>> Another possibility may be to keep long names and to add syntactic
>> sugar such as
>> -----
>> public static double im(Complex c) {
>> return c.getImaginary();
>> }
>> -----
>
> I have been looking at std::complex to get some ideas. Connected to
> the issue (coming soon in another thread) of conforming the Complex
> to
> C99.
>
> (http://en.cppreference.com/w/cpp/numeric/complex)
>
> Do you see any value in conforming to this reference?
We can't really conform, lacking operator overloading.
The name of the function are fine I think; no need to have long names.
Here it really depends on where to put the emphasis, common usage
or Commons usage (not sure there is such a thing)...
> If so, this
> could mostly be accomplished by adding a few syntactic sugar methods,
> while leaving in longer-name methods that follow the commons style,
> to
> which I also see benefit.
What are they?
It could help to make up my mind; a priori, I would not create more
than
one API method.
> These would include real, imag, abs, arg, conj .
>
> Then a few methods are missing which are not much trouble -- log10
> and norm are easy, but I am not familiar with proj, which is only in
> C11 anyway.
>
>>
>>> This leaves only the question of a constructor that takes polar
>>> representations which I think is already well handled by the
>>> present method
>>> ComplexUtils.polar2Complex, for either Complex or Complex[] .
>>
>> Shall we consider making the constructors "private" and define
>> factory methods (like those currently in "ComplexUtils")?
>>
>> public static Complex createCartesian(double re,
>> double im) {
>> return new Complex(re, im);
>> }
>>
>> public static Complex createPolar(double r,
>> double theta) {
>> return new Complex(r * FastMath.cos(theta),
>> r * FastMath.sin(theta));
>> }
>>
>
>
>
> It seems to follow the criteria for factory pattern, in that we want
> to give the user ways to create the object that are most convenient
> (cartesian or polar), uncoupled from object structure.
>
>> And suppress the ambiguous methods "createComplex" and
>> "valueOf".
>
> definitely
>
>>
>> Actually I think that only one constructor should stay that
>> is tied to the underlying representation (and for that reason
>> it should not be "public").
>>
>
>
>> What do you think?
>
> I figure one goal is for the Complex to not be much bigger than two
> doubles. So real and imag are probably what should be in the
> structure, with the polar values calculated, and a factory method
> used
> to construct complex from polar.
Since some computations are more efficient with one representation
and others with the other, how about having "Complex" an interface
with "CartesianComplex" and "PolarComplex" implementations?
Just mentioning: I have no idea whether the added flexibility is
worth it from a performance point-of-view.
It may depend on the application (and I have none in mind).
But perhaps you have some opinion on whether there would be something
to gain especially in computations that involve (large) arrays of
Complex objects.
Regards,
Gilles
>
> Eric
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Proposed changes to Complex method nomenclature
Posted by Eric Barnhill <er...@gmail.com>.
On 31/05/16 14:12, Gilles wrote:
>
>
> Short as can be and close to math notation.
>
> Another possibility may be to keep long names and to add syntactic
> sugar such as
> -----
> public static double im(Complex c) {
> return c.getImaginary();
> }
> -----
I have been looking at std::complex to get some ideas. Connected to the
issue (coming soon in another thread) of conforming the Complex to C99.
(http://en.cppreference.com/w/cpp/numeric/complex)
Do you see any value in conforming to this reference? If so, this could
mostly be accomplished by adding a few syntactic sugar methods, while
leaving in longer-name methods that follow the commons style, to which I
also see benefit.
These would include real, imag, abs, arg, conj .
Then a few methods are missing which are not much trouble -- log10 and
norm are easy, but I am not familiar with proj, which is only in C11 anyway.
>
>> This leaves only the question of a constructor that takes polar
>> representations which I think is already well handled by the present
>> method
>> ComplexUtils.polar2Complex, for either Complex or Complex[] .
>
> Shall we consider making the constructors "private" and define
> factory methods (like those currently in "ComplexUtils")?
>
> public static Complex createCartesian(double re,
> double im) {
> return new Complex(re, im);
> }
>
> public static Complex createPolar(double r,
> double theta) {
> return new Complex(r * FastMath.cos(theta),
> r * FastMath.sin(theta));
> }
>
It seems to follow the criteria for factory pattern, in that we want to
give the user ways to create the object that are most convenient
(cartesian or polar), uncoupled from object structure.
> And suppress the ambiguous methods "createComplex" and
> "valueOf".
definitely
>
> Actually I think that only one constructor should stay that
> is tied to the underlying representation (and for that reason
> it should not be "public").
>
> What do you think?
I figure one goal is for the Complex to not be much bigger than two
doubles. So real and imag are probably what should be in the structure,
with the polar values calculated, and a factory method used to construct
complex from polar.
Eric
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: Proposed changes to Complex method nomenclature
Posted by Gilles <gi...@harfang.homelinux.org>.
On Tue, 31 May 2016 11:12:06 +0200, Eric Barnhill wrote:
> I propose some minor changes in Complex() methods nomenclature for
> 4.0 .
>
> These relate to the collection of methods abs(), getArgument(),
> getReal()
> and getImaginary() .
>
> Personally I switch frequently and freely between Cartesian and polar
> representations of complex numbers in my code. So to me it would make
> more
> sense to conform the terminology of these arguments, which would
> effectively make Complex unbiased as to which representation you use.
That will be nice.
> Keeping the prefix "get" has sound logic to it as it establishes
> these
> methods as accessor type methods as opposed to other Complex methods
> like
> sin(), which are more derivative.
>
> Some abbreviation is in order to avoid getAbsoluteValue(), so I
> propose
> getAbs(), getArg(), getReal(), and getImag() as the four method
> names.
I'm not sure how you can draw a line between "getters" and
"derivative".
The prefix "get" is often used to imply that a field is read, but
it contradicts the idea of "encapsulation".
The advantage of full names is that they are self-documenting.
That convention is predominant is CM (i.e. no abbreviations), except
where a prior established convention exists (like for well-known math
functions).
Here we seem to fall in the latter.
So why not
* abs()
* arg()
* re()
* im()
?
Short as can be and close to math notation.
Another possibility may be to keep long names and to add syntactic
sugar such as
-----
public static double im(Complex c) {
return c.getImaginary();
}
-----
> This leaves only the question of a constructor that takes polar
> representations which I think is already well handled by the present
> method
> ComplexUtils.polar2Complex, for either Complex or Complex[] .
Shall we consider making the constructors "private" and define
factory methods (like those currently in "ComplexUtils")?
public static Complex createCartesian(double re,
double im) {
return new Complex(re, im);
}
public static Complex createPolar(double r,
double theta) {
return new Complex(r * FastMath.cos(theta),
r * FastMath.sin(theta));
}
And suppress the ambiguous methods "createComplex" and
"valueOf".
Actually I think that only one constructor should stay that
is tied to the underlying representation (and for that reason
it should not be "public").
What do you think?
Gilles
> Eric
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org