Ralf Hemmecke wrote:
On 12/22/2014 12:42 AM, Waldek Hebisch wrote:
AFAICS this was not a derivation. The line
concat(frst(f1), rst(f1) + p1 + concat(rpSt(n, 0), f1*p1))
is a recursive formula written using Spad.
How many people know what rpSt is?
Those who look up definition and specification:
-- rpSt(z, s) is a stream of length z each of whose entries is s
...
Derivation is simple, so it is better to omit it (as I and _you_
did) -- reader can easily reconstruct it.
If you believe it was easy without the knowledge of the specification of
prodiag1, then either you are wrong or I am stupid.
I am affraid that we are using different language. In my language
specification says what a function is supposed to compute. Now:
-- prodiag1([f_n, ...], n) computes
-- ((1 + z^n*f_n)*(1 + z^{n+1}*f_{n+1})... - 1)/z^n
prodiag1(ststa : ST ST A, n : Integer) : ST(A) == ...
says you exactly what 'prodiag1' should compute, so for me
it is specification.
I felt like
needlessly wasting my time over this. And you even did not commit my
comments that IMHO would help others to waste less time.
You wanted to have:
1 -- Let f = [f_1, f_2, f_3, ...] be a stream of streams of coefficients
2 -- of Taylor series. We tacitly identify a stream of coefficients with
3 -- a Taylor series in the variable z.
4 -- Let h(s), t(s) be the head and tail of a stream s, respectively.
5 -- Let p(s, n) be recursively defined by:
6 -- p(s, n) = (1+z^n*h(s)*p(t(s), n+1).
7 -- Then p(f, 1) gives the infinite product
8 -- p(f, 1) = (1+z*f_1)*(1+z^2*f_2)*(1+z^3*f_3)*...
9 -- Let q(s, n) be defined by: p(s, n) = 1 + z^n*q(s, n).
10 -- Then we get the following recursion formula for q.
11 -- q(s, n) = h(f1) + z*(r1 + q1 + z^n*f1*q1)
12 -- where
13 -- f1 = h(s)
14 -- r1 = t(s)
15 -- q1 = q(r1, n+1)
16 prodiag1(ststa : ST ST A, n : Integer) : ST(A) == delay
17 empty? ststa => zro()
18 f1 := frst ststa -- head
19 r1 := rst ststa -- tail
20 p1 := prodiag1(r1, n + 1)
21 empty? f1 => concat(0, p1)
22 concat(frst(f1), rst(f1) + p1 + concat(rpSt(n, 0), f1*p1))
Now, comments on line 18 and 19 are texbook example of bad
comments, they just restate what code is doing without
adding any insight. Lines 1-5 besides repeating what should
be already known from comment to STTAYLOR:
++ Description:
++ StreamTaylorSeriesOperations implements Taylor series arithmetic,
++ where a Taylor series is represented by a stream of its coefficients.
just introduce notation. Line 6 is the specification. I dare
to say that two line specification I gave is at least as
readable as the above specification and has advantage of
beeing shorter. Lines 7 and 8 may help if one insists
on your previous lines, but since I explicitely specify
prodiag1 as infinite product specialization to n = 1
becames obvious. I believe that for _you_ your explanation
looks clearer: simply it "resonates" with you understanding
of the subject. But for unbiased reader the two line form
has advantege of immediately presenting important part
without burdening short term memory with unimportant
details. Finally, lines 9-15 repeat what code is doing
but in different notation.
This kind of comments help if reader is unfamiliar with Spad,
but otherwise just adds bulk to the file. Bulk is bad because
every reader will spent more time reading and internalizing
what was written.
IMHO, this is wrong. Knowing SPAD is rather unimportant. What counts is
the mathematical background and the kind of algorithm that is used. And
that is missing and is tacitly hidden inside the SPAD code.
Note: I expect that active and interested
reader will re-derive the formula. Adding more detail will
not help and may hurt turning the reade to "passive mode".
Well, you expect every potential new developer to invest much time, so
you basically treat them as if they were your students. Can you count
how many active developer FriCAS has? I would have counted me as one,
but then the above tells me the I am required to waste my time. Why
would I want to do that? It's totally ineffective and frustrating. It's
not freely sharing knowledge.
I am sad that you consider analyzing code to be waste of time.
For me it is normal part of developement work. I need to modify
some routine I read it and as needed releated code. IME just
using documetation is frequently inadequte: I looking for things
not considered by original developers. Since they did not
consider them writing code they could not document them.
Yes, such analyzis takes some effort. IME most of effort
goes into filtering out irrelevant datails. Now, you
want to replace 9 lines that I commited by 22 lines. This
more than doubles amount of material that I need to scan
and filter out.
Using "literate" analogy: FriCAS code is research level, analogous
to research paper or a monograph. From readers of such works
one expects some background knowledge and familiarity with
notation. Readers of a monograpth when faced with unfamilar
notation are supposed to look it up in an index. Similarely
readear of 'prodiag1' are supposed to look up 'rpSt'. A lot
of formulas is supposed to be easy enough so that readers
will know them or provide own proof. Now, if one wants to
make a subject more accessible it is not done by "simplifing"
research papers. Rather, it is done via creation of
additional training material.
Coming back to 'prodiag1'. You say that you wasted time.
Did you spent more than 15 minutes on it? I consider 15
to be generous estimate of time needed to derive formulas
in use. Normally when seeing routine as 'prodiag1' I
consider it simple enough and assume that the author did
it right, so I would go other it essentially in time needed
to read it (this is why 22 lines versus 9 hurt!). When
I just want to know details I consider the 15 minutes
not as waste but as time well spent. When I have
reasons to belive that routine is incorrect or I need
to modify it, then IMO 15 minutes is fully justified
and unavoidable: if I can not believe the author I need
to check everthing with due care. In particular it is
better to derive formula second time because otherwise
documentation may fool me to commit the same error that
the author did. Note that on complicated projects
frequently cited norm is 10 lines a day. According to
such norm 'prodiag' would be worth more than half a day,
so there is "budget" to come back to it few times.
I guess, it would be better to lower the barrier to enter FriCAS
development rather than requiring new people to deeply dive into SPAD
code and to analyse what the code actually does even if they certainly
come with zero knowledge of the library but know the SPAD keywords.
To put is differently: your addition would be good in a
tutorial.
... that nobody will ever write...
I think that probablity of somebody writing a tutorial is larger
than probabilty that a newcomer to FriCAS would like to
look at 'prodiag1'.
But I bet that reader facing substantial amount
of code with such documentation will quickly give up
due to bulk of text to read.
How many people have you met that tell you this? You must have knowledge
of a big FriCAS community that I haven't heard of.
Well, I had a lot of contact with user of our local computer
network. I also spent some time on various support lists.
In case of systems that had a lot of documentation typical
pattern was like:
Q: Is there any documentation?
A: Here it is.
Q: That is soo long. Do you have something shorter?
On programming fora for requests to shorten text are
quite frequent.
FriCAS community is small, but I have no reason to think
that it is different than general programmer population.
When I was teaching introductory programming course given task
"turn this formula(s) into code" or even "what this piece
of code is doing" students did quite well.
I have yet to see someone who can tell, what exactly the following
Mathematica program computes and whether this program is correct.
foo[a_, b_] := (
If[a > 0,
If[TrueQ[a > b], Return[foo[b, a]]];
Return[foo[b-a, a]]
];
Return[b]
);
I have only little Mathematica knowledge. But this looks
like correct routine to compute GCD of nonnegative integers.
Mathematica is untyped so it may return useful results
if a and b are elements of an orderd group isomorphic
with integers. It fails to terminate when a and b
are positive but not comeasurable, so it makes little
sense to consider it on significantly bigger domains. AFAICS
the main unknown is domain of foo. In case of Spad types
significantly limit possible domains.