Re: [Scilab-users] Some details on the documentation of log(), log10(), etc.

[Antoine Monmayrant]

Hello all,

On 22/02/2021 10:12, Stéphane Mottelet wrote:


Hi,

Le 22/02/2021 à 09:43, Clément David a écrit :


Hello all,

Thanks for opening the discussion on this “new user”-related topic, 
this is always good to improve our help for existing user and new 
comers ; to let them havie a clear understanding of Scilab-lingua.


One important point to me is to have a proper distinction between 
“array” (as values organized in multiple dimensions) and more precise 
terms with more constraints on dimensions “horizontal vector”, 
“matrix”, etc… For keeping the rationale up to date, I suggest you to 
edit the Localization wiki page [1].


In term of code update, I can help you finding duplicated messages 
but keep in mind that the build-system create .pot files from the 
source code. To look for duplicate, the more important is to upgrade 
the source code.


[1]: https://wiki.scilab.org/Localization in English - Standard messages

Note: AFAK the “constant” term has been removed on 6.0.0 
documentation/error message as this is the default datatype, in case 
of advanced type management the term “decimal” can be used instead.


I think that the "decimal" term has to be discussed. In no way the 
default number type in Scilab is decimal 
(https://en.wikipedia.org/wiki/Decimal). Scilab actually displays 
rounded decimal approximations but internally they are IEEE754 
double-precision floating point numbers. I think that the "floating 
point numbers" instead of "decimal" would be more suitable as is does 
not make any mention of the basis. As far as I am concerned, I don't 
have any problem with


"array of floating point numbers"


I agree with Stéphane here, "decimal" does not make sense.
It is even deceiving as some languages implement proper base10 "decimal" 
data type, whereas scilab is defaulting to double (float64) data 
representation.

But I think we should go further: "array of double" is even better.


In some contexts, typically when describing the type of arguments in 
the documentation of functions, we could be more precise by making 
reference to the actual internal object type, i.e. "double" or 
"Double", i.e.


array of type double
array of double


Yes, that's exactly what I find best.
For comparison, python3 mentions "float" and julia "float64" when 
inquiring about the default type of "a=1.1".


Scilab users are mature enough to accept a bit of technical (but 
precise) terms. But this is my personal opinion...


I agree, I don't see the point in mentioning something vague that a true 
beginner will have to learn anyway: it's better to start right away with 
learning the proper term to name the default datatype of scilab...


Antoine


S.


Regards,

Clément

*From:* users  *On Behalf Of 
*Stéphane Mottelet

*Sent:* Saturday, February 20, 2021 5:35 PM
*To:* users@lists.scilab.org
*Subject:* Re: [Scilab-users] Some details on the documentation of 
log(), log10(), etc.


By looking into the documentation messages I realized that we already 
use "array" :


./locale/de_DE/LC_MESSAGES/scilab.po-e:msgid "%s: Wrong type for 
input argument #%d: Array of double expected.\n"


S.

Le 20/02/2021 à 17:21, Stéphane Mottelet a écrit :

Hi Frederico,

In almost all other numerical software the object defined in
Scilab by a=zeros(3,3,3) is called an "array", m=zeros(3,3) a
"matrix" and x=zeros(1,3) or y=zeros(3,1) "vectors", and all of
them are called "arrays". BTW, now the "hyper" prefix sounds like
when it is used in "hyperspace"... To me, the documentation
should be revamped to always use "array" when the denoted object
can have any number of dimensions and use "matrix" only when the
array has to be a matrix. Concerning your remark about the
"constant vector or constant matrix", yes, this should be changed
by something more explicit, like "array of double". We already
use similar terms in error messages, i.e.

"%s: Wrong type for input argument #%d: A matrix of double
expected.\n"

Hence we could synchonize the uses of localized messages with the
documentation. When I say "we" it also includes "you", Frederico.
If you feel that Scilab could be improved by a better
documentation, please contribute. If you need some help to start
using the relevant tools (git, codereview) I would be glad to
help you.

S.

Le 20/02/2021 à 01:29, Federico Miyara a écrit :


Dear all,

In an old script where I needed to apply log10 to an
hyperarray I had implemented it as log(A)/log(10) with a
comment indicating that in that version log10() didn't work
for hyperarrays (unfortunately I don't recall what version it
was).

In Version 6.1.0 it does work for hyperarrays, but the
documentation still says that it applies to vectors or matrices:

https://help.scilab.org/docs/6.1.0/en_US/log10.html

Re: [Scilab-users] Some details on the documentation of log(), log10(), etc.

[Stéphane Mottelet]

Hi,

Le 22/02/2021 à 09:43, Clément David a écrit :


Hello all,

Thanks for opening the discussion on this “new user”-related topic, 
this is always good to improve our help for existing user and new 
comers ; to let them havie a clear understanding of Scilab-lingua.


One important point to me is to have a proper distinction between 
“array” (as values organized in multiple dimensions) and more precise 
terms with more constraints on dimensions “horizontal vector”, 
“matrix”, etc… For keeping the rationale up to date, I suggest you to 
edit the Localization wiki page [1].


In term of code update, I can help you finding duplicated messages but 
keep in mind that the build-system create .pot files from the source 
code. To look for duplicate, the more important is to upgrade the 
source code.


[1]: https://wiki.scilab.org/Localization in English - Standard messages

Note: AFAK the “constant” term has been removed on 6.0.0 
documentation/error message as this is the default datatype, in case 
of advanced type management the term “decimal” can be used instead.


I think that the "decimal" term has to be discussed. In no way the 
default number type in Scilab is decimal 
(https://en.wikipedia.org/wiki/Decimal). Scilab actually displays 
rounded decimal approximations but internally they are IEEE754 
double-precision floating point numbers. I think that the "floating 
point numbers" instead of "decimal" would be more suitable as is does 
not make any mention of the basis. As far as I am concerned, I don't 
have any problem with


"array of floating point numbers"

In some contexts, typically when describing the type of arguments in the 
documentation of functions, we could be more precise by making reference 
to the actual internal object type, i.e. "double" or "Double", i.e.


array of type double
array of double

Scilab users are mature enough to accept a bit of technical (but 
precise) terms. But this is my personal opinion...


S.


Regards,

Clément

*From:* users  *On Behalf Of *Stéphane 
Mottelet

*Sent:* Saturday, February 20, 2021 5:35 PM
*To:* users@lists.scilab.org
*Subject:* Re: [Scilab-users] Some details on the documentation of 
log(), log10(), etc.


By looking into the documentation messages I realized that we already 
use "array" :


./locale/de_DE/LC_MESSAGES/scilab.po-e:msgid "%s: Wrong type for input 
argument #%d: Array of double expected.\n"


S.

Le 20/02/2021 à 17:21, Stéphane Mottelet a écrit :

Hi Frederico,

In almost all other numerical software the object defined in
Scilab by a=zeros(3,3,3) is called an "array", m=zeros(3,3) a
"matrix" and x=zeros(1,3) or y=zeros(3,1) "vectors", and all of
them are called "arrays". BTW, now the "hyper" prefix sounds like
when it is used in "hyperspace"... To me, the documentation should
be revamped to always use "array" when the denoted object can have
any number of dimensions and use "matrix" only when the array has
to be a matrix. Concerning your remark about the "constant vector
or constant matrix", yes, this should be changed by something more
explicit, like "array of double". We already use similar terms in
error messages, i.e.

"%s: Wrong type for input argument #%d: A matrix of double
expected.\n"

Hence we could synchonize the uses of localized messages with the
documentation. When I say "we" it also includes "you", Frederico.
If you feel that Scilab could be improved by a better
documentation, please contribute. If you need some help to start
using the relevant tools (git, codereview) I would be glad to help
you.

S.

Le 20/02/2021 à 01:29, Federico Miyara a écrit :


Dear all,

In an old script where I needed to apply log10 to an
hyperarray I had implemented it as log(A)/log(10) with a
comment indicating that in that version log10() didn't work
for hyperarrays (unfortunately I don't recall what version it
was).

In Version 6.1.0 it does work for hyperarrays, but the
documentation still says that it applies to vectors or matrices:

https://help.scilab.org/docs/6.1.0/en_US/log10.html



In some contexts "matrix" may be interpreted as an hyperarray
or hypermatrix (for instance when speaking of N-D matrices),
but for Scilab a matrix is formally a two-dimensional array:

https://help.scilab.org/docs/6.1.0/en_US/matrices.html



I think the documentation should indicate that it applies 

Re: [Scilab-users] Some details on the documentation of log(), log10(), etc.

[Clément David]

Hello all,

Thanks for opening the discussion on this “new user”-related topic, this is 
always good to improve our help for existing user and new comers ; to let them 
havie a clear understanding of Scilab-lingua.

One important point to me is to have a proper distinction between “array” (as 
values organized in multiple dimensions) and more precise terms with more 
constraints on dimensions “horizontal vector”, “matrix”, etc… For keeping the 
rationale up to date, I suggest you to edit the Localization wiki page [1].

In term of code update, I can help you finding duplicated messages but keep in 
mind that the build-system create .pot files from the source code. To look for 
duplicate, the more important is to upgrade the source code.

[1]: https://wiki.scilab.org/Localization in English - Standard messages

Note: AFAK the “constant” term has been removed on 6.0.0 documentation/error 
message as this is the default datatype, in case of advanced type management 
the term “decimal” can be used instead.

Regards,
Clément



From: users  On Behalf Of Stéphane Mottelet
Sent: Saturday, February 20, 2021 5:35 PM
To: users@lists.scilab.org
Subject: Re: [Scilab-users] Some details on the documentation of log(), 
log10(), etc.


By looking into the documentation messages I realized that we already use 
"array" :

./locale/de_DE/LC_MESSAGES/scilab.po-e:msgid "%s: Wrong type for input argument 
#%d: Array of double expected.\n"

S.
Le 20/02/2021 à 17:21, Stéphane Mottelet a écrit :

Hi Frederico,

In almost all other numerical software the object defined in Scilab by 
a=zeros(3,3,3) is called an "array", m=zeros(3,3) a "matrix" and x=zeros(1,3) 
or y=zeros(3,1) "vectors", and all of them are called "arrays". BTW, now the 
"hyper" prefix sounds like when it is used in "hyperspace"... To me, the 
documentation should be revamped to always use "array" when the denoted object 
can have any number of dimensions and use "matrix" only when the array has to 
be a matrix. Concerning your remark about the "constant vector or constant 
matrix", yes, this should be changed by something more explicit, like "array of 
double". We already use similar terms in error messages, i.e.

"%s: Wrong type for input argument #%d: A matrix of double expected.\n"

Hence we could synchonize the uses of localized messages with the 
documentation. When I say "we" it also includes "you", Frederico. If you feel 
that Scilab could be improved by a better documentation, please contribute. If 
you need some help to start using the relevant tools (git, codereview) I would 
be glad to help you.

S.
Le 20/02/2021 à 01:29, Federico Miyara a écrit :

Dear all,

In an old script where I needed to apply log10 to an hyperarray I had 
implemented it as log(A)/log(10) with a comment indicating that in that version 
log10() didn't work for hyperarrays (unfortunately I don't recall what version 
it was).

In Version 6.1.0 it does work for hyperarrays, but the documentation still says 
that it applies to vectors or matrices:

https://help.scilab.org/docs/6.1.0/en_US/log10.html

In some contexts "matrix" may be interpreted as an hyperarray or hypermatrix 
(for instance when speaking of N-D matrices), but for Scilab a matrix is 
formally a two-dimensional array:

https://help.scilab.org/docs/6.1.0/en_US/matrices.html

I think the documentation should indicate that it applies to vectors, matrices 
and hypermatrices

Another problem is regarding log(). It says that the input argument is a 
"constant vector or constant matrix":

https://help.scilab.org/docs/6.1.0/en_US/log.html

However, it seems that "constant" has a specific meaning in Scilab as a 
predefined variable:

https://help.scilab.org/docs/6.1.0/en_US/section_421ab29126e21a1e1e403ee27a18fda4.html

As it is worded, it seems that log() is applied to predefined variables. I 
think it should refer more clearly to the type double (it doesn't work, for 
instance, for integer types such as int16(2)).

In the case of log2() the description of arguments is even stranger:

https://help.scilab.org/docs/6.1.0/en_US/log2.html

It confuses the argument section with