Examples on functions

[Tim Daly-3]

Franz,

 > 2. On the download page for release 1.0.8 there is a tarball containing
 > examples. Where should they go to make them visible to )help ?

If you put a flat text file in $AXIOM/doc/spadhelp, for example,
create a file called $AXIOM/doc/spadhelp/foo.help then you can say

  )help foo

and it will type out the contents of that file. I have created
about 300 help files (which will also work in Fricas).

If you create new help files I would be happy to add them.


 > 3. What is a canonical place to put examples?
 > In Axiom (TM) there are some examples shown after the )display command,
 > which can be quite instructive.
 > I would like to prepare some examples for tensor as well.

In Axiom you can add examples to any function. The examples are just
a special syntax in the comments for a function. So if you have a
function called

    foo: % -> %
      ++ foo(x) returns x

then you can write an example by adding "++X" comments (that is,
the ++ comment followed immediately by an "X" character so you write:

   foo: % -> %
     ++ foo(x) returns x
     ++
     ++X foo(3)

Fricas could add this functionality easily but I'm not part of that
effort so someone will have to pick up the change from Axiom and
add it to Fricas.


On another topic, Axiom algebra is integrating the regression test
files with the algebra sources. If you generate new code I beg you
to write as many tests as you can, especially including a test for
each function. It is very painful for me to try to track Fricas
algebra because all I ever see is the final code with no test
cases, documentation, examples, or pointers to literature. This
makes it very difficult for me (or anyone, actually) to figure
out how to use new algebra.

Tim
Elder of the Internet




_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer

[Bertfried Fauser-3]

Dear Tim,

> On another topic, Axiom algebra is integrating the regression test
> files with the algebra sources. If you generate new code I beg you
> to write as many tests as you can, especially including a test for
> each function.

I try to comply with this rule (ralf also asked for documentation) for
the symmetric
functions and hope they make their way into AXIOM(TM) too.

However a fully documeted code is out of my working power, there is just far too
much to say about symmetric functions.

You saw possibly the mail of Martin on Clifford algebras. I have tried
to test some
Clifford issues in FriCAS (no AXIOM(TM) on my computer currently) but
that should
be identical. FriCAS is assuming that the quadratic form is diagonal,
that is very bad.
Perhaps I will find time to improve that. I tried to put up a sandbox
on newsynthesis,
but I possibyl forgot my user paseword there, since the system didn't
let me create
a new sandbox

Ciao
BF.

--
% PD Dr Bertfried Fauser
%       Research Fellow, School of Computer Science, Univ. of Birmingham
%       Honorary Associate, University of Tasmania
%       Privat Docent: University of Konstanz, Physics Dept
<http://www.uni-konstanz.de>
% contact |->    URL : http://clifford.physik.uni-konstanz.de/~fauser/
%              Phone : [phone]


_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer

[Tim Daly-3]

Bertfried Fauser wrote:

> Dear Tim,
>
>  
>> On another topic, Axiom algebra is integrating the regression test
>> files with the algebra sources. If you generate new code I beg you
>> to write as many tests as you can, especially including a test for
>> each function.
>>    
>
> I try to comply with this rule (ralf also asked for documentation) for
> the symmetric
> functions and hope they make their way into AXIOM(TM) too.
>
> However a fully documeted code is out of my working power, there is just far too
> much to say about symmetric functions.
>
> You saw possibly the mail of Martin on Clifford algebras. I have tried
> to test some
> Clifford issues in FriCAS (no AXIOM(TM) on my computer currently) but
> that should
> be identical. FriCAS is assuming that the quadratic form is diagonal,
> that is very bad.
> Perhaps I will find time to improve that. I tried to put up a sandbox
> on newsynthesis,
> but I possibyl forgot my user paseword there, since the system didn't
> let me create
> a new sandbox
>
> Ciao
> BF.
>
>  

Given working tests we have some hope of figuring out what a function
is supposed to do. Without a working test we can only guess whether the
answer is right or not. You certainly have to construct these simple
test cases in order to debug your code. Save the tests you do.

As for documentation, it helps to include a small paragraph that
contains enough so that we can find the rest in the literature.
Even something as simple as a link to Eric's mathworld or wikipedia
or a book reference would be a start. When I worked on the special
function E1 at least there was a reference to Luke's book. Nobody
can really expect you to write a tutorial or a book chapter but
references help a lot.

I'm trying to avoid just a straight "code dump" because then we
have to guess. The main reason I started added example output to
the ")display operation" command is that the new user would have
at least one working example of every function. Sometimes it is
very hard to construct the Axiom type even if you know what the
input should look like, which I'm sure you have experienced.

Tim



_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer

[Ralf Hemmecke]

> As for documentation, it helps to include a small paragraph that
> contains enough so that we can find the rest in the literature.
> Even something as simple as a link to Eric's mathworld or wikipedia
> or a book reference would be a start. When I worked on the special
> function E1 at least there was a reference to Luke's book. Nobody
> can really expect you to write a tutorial or a book chapter but
> references help a lot.

I would like to strongly support that.

Mathematics is such a huge field and with current technology we have to
means to at least include a URL to help people that want to review the
code but don't know everything about the background (yes sometimes
following different books lead to different code design). It is vital to
at least give enough hints to the literature.

Ralf


_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer

[Tim Daly-3]

Franz,

Your tensor code uses the function "listOfTerms" but I do not see
it among the exports of any category, domain, or package.
Where is this defined?

Tim



_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer

[Franz Lehner]

On Sun, 1 Nov 2009, Tim Daly wrote:
> Your tensor code uses the function "listOfTerms" but I do not see
> it among the exports of any category, domain, or package.
> Where is this defined?
Some time ago I merged "FreeModule" and "FreeModule1",
renamed "FreeModuleCat" to FreeModuleCategory" and
made "FreeModule" export "FreeModuleCategory" as it should be.
I also renamed ListOfTerms to listOfTerms in "IndexedDirectProductCategory"
and all entities which inherit the latter.

Franz


_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer

[Tim Daly-3]

Franz Lehner wrote:

> On Sun, 1 Nov 2009, Tim Daly wrote:
>> Your tensor code uses the function "listOfTerms" but I do not see
>> it among the exports of any category, domain, or package.
>> Where is this defined?
> Some time ago I merged "FreeModule" and "FreeModule1",
> renamed "FreeModuleCat" to FreeModuleCategory" and
> made "FreeModule" export "FreeModuleCategory" as it should be.
> I also renamed ListOfTerms to listOfTerms in
> "IndexedDirectProductCategory"
> and all entities which inherit the latter.
>
> Franz
>

Yes, I saw the renames. But listOfTerms does not seem to be
exported anywhere in Fricas. Try
  )d op listOfTerms

Tim



_______________________________________________
Axiom-developer mailing list
Axiom-developer@...
http://lists.nongnu.org/mailman/listinfo/axiom-developer