FriCAS in a console

[Alasdair McAndrew]

Better FriCAS in a console:

(1) Download and install rlwrap

(2) put the attached file somewhere in your path and make it executable (this is a copy of the "rmaxima" command with very slight changes)

(3) run "rfricas" instead of "fricas"

If we had a file containing a list of all FriCAS commands then we could use rlwrap to do command completion, too.

Note that rlwrap keeps histories between sessions, so if you quit FriCAS, or if your machine suddenly shuts down, you can fire up again and keep on from where you left off.

-Alasdair

--

[oldk1331]

On Wednesday, October 28, 2015 at 11:16:10 AM UTC+8, Alasdair wrote:

Better FriCAS in a console:

(1) Download and install rlwrap

(2) put the attached file somewhere in your path and make it executable (this is a copy of the "rmaxima" command with very slight changes)

(3) run "rfricas" instead of "fricas"

If we had a file containing a list of all FriCAS commands then we could use rlwrap to do command completion, too.

There is ${INSTALL_PREFIX}/lib/fricas/target/x86_64-unknown-linux/lib/command.list .

[Alasdair McAndrew]

It seems to do command completion anyway, of at least some commands.  But I'll add that command.list to rfricas and see what happens.

The attached file works for me... you may have to change the first few lines according to your own installation.  I just copied them from my "fricas" executable file which sets all the environment variables and directories.

--
You received this message because you are subscribed to a topic in the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/fricas-devel/qC9mzkTf3NY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to fricas-devel...@googlegroups.com.
To post to this group, send email to fricas...@googlegroups.com.
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.

[Thomas Baruchel]

Since I am a console guy, here are some thoughts I had after your post.

I have been using Fricas for about ten days and I really like it.

I have been using rlwrap with many programs for years; actually wrapping any program with rlwrap usually is the first thing I do when installing any kind of interpreter. You seem to use it from a script, aren't you (I didn't look at your attached file but I assume it is a shell-script wrapper); I usually do the same with a bash alias in my ~/.bashrc, but of course result will be the same.

The idea of using command completion is a great idea; I added it in my alias.

Two years ago, I wrote a plugin for the Vim editor for interacting with some interpreters from a Vim buffer. I didn't try to use it with Fricas yet, but maybe someone will be interested in it: https://github.com/baruchel/vim-notebook

There are however two things I don't like with Fricas:

  * I couldn't find any way to use the help system (called Hyperdoc if I am not wrong) from within the console; obviously Hyperdoc is a graphical system (which I probably didn't compile; anyway I don't want to have an external window). Maxima has a very great help system, callable from within the interpreter. Isn't there really any way to get the help from the Fricas interpreter?

  * I compiled Fricas with Clozure Lisp and with SBCL; and I can't interrupt a computation with Ctrl-C. With Clozure Lisp, Ctrl-C doesn't do anything; with SBCL I can interrupt a computation but after that the interpreter doesn't seem to work very well again. Any hint?

Best regards, tb.

[Ralf Hemmecke]

On 10/30/2015 02:49 PM, Thomas Baruchel wrote:
> I have been using Fricas for about ten days and I really like it.

Good to hear that.
May I asked you how you've found FriCAS in the first place?

> I have been using rlwrap with many programs for years; actually wrapping
> any program with rlwrap usually is the first thing I do when installing any
> kind of interpreter. You seem to use it from a script, aren't you (I didn't
> look at your attached file but I assume it is a shell-script wrapper); I
> usually do the same with a bash alias in my ~/.bashrc, but of course result
> will be the same.

Maybe next to efricas, we should add a start script to fricas that
automatically uses rlwrap, if it is installed (including command line
completion). Wouldn't that be an option to get rid of CLEF?

> Two years ago, I wrote a plugin for the Vim editor for interacting with
> some interpreters from a Vim buffer. I didn't try to use it with Fricas
> yet, but maybe someone will be interested in
> it: https://github.com/baruchel/vim-notebook

I've added a link to your vim-notebook.

http://axiom-wiki.newsynthesis.org/FriCASInVim

> There are however two things I don't like with Fricas:

Yes. I like that you tell us things that are not so nice. I call this
"contribution". Thank you.

> * I couldn't find any way to use the help system (called Hyperdoc if I am
> not wrong) from within the console; obviously Hyperdoc is a graphical
> system (which I probably didn't compile; anyway I don't want to have an
> external window).

It's a bit hard, if you want to stay at the command line. Anyway, one
thing, I can offer is http://fricas.github.io/ and in particular
http://fricas.github.io/api/. (Note that the search for FriCAS
identifiers only works on the API page.)

If you really want to stay on the command line, then you should type

)help

Then we have


(10) -> )what commands
--------------- System Commands for User Level: development ---------------
abbreviations boot cd clear
close compiler copyright credits
display edit fin frame
help history lisp library
load ltrace nopiles piles
pquit quit read set
show spool summary synonym
system trace undo what


>> System error:
The index 3 is too large.

(Oooops... there's a bug!) :-(

If you want to learn about a domain or category, say something like

(10) -> )show SemiGroup
SemiGroup is a category constructor
Abbreviation for SemiGroup is SGROUP
This constructor is exposed in this frame.
------------------------------- Operations --------------------------------
?*? : (%,%) -> % ?=? : (%,%) -> Boolean
?^? : (%,PositiveInteger) -> % coerce : % -> OutputForm
hash : % -> SingleInteger latex : % -> String
?~=? : (%,%) -> Boolean
hashUpdate! : (HashState,%) -> HashState

If you want to learn about an operation, then

(10) -> )display operation char

There are 2 exposed functions called char :
[1] String -> Character from Character
[2] Integer -> Character from Character

This text based help system is not perfect, and I would even say not
really actively maintained, but it's still there and usable.

Hope that helps.
Ralf

[Alasdair McAndrew]

Well, my newest rfricas does indeed have command completion, and resolutely ignores clef.

As to help, I strongly support Thomas's views.  I still find help in FriCAS - even using mixtures of hyperdoc, the new api web page, and as much console-based information as possible - scattered and often not helpful enough.  For example, I was trying to find out yesterday how to solve a second order linear IVP.  I can set up the ODE, but I don't know how to give the values both of y(0) and y'(0) to solve.  The only example I could find was of a first order system. 

If you enter )d op solve you find there are 33 exposed operations, including

[6] (D2,D1,Symbol,D1,List(D1)) -> Union(D1,"failed")
            from ElementaryFunctionLODESolver(D5,D1,D2)
            if D1 has Join(ACFS(D5),TRANFUN,PRIMCAT) and D5 has Join(
            COMPAR,EUCDOM,RETRACT(INT),LINEXP(INT),CHARZ) and D2 has
            LODOCAT(D1)

which, let's face it, is pretty meaningless unless to an expert user or a developer.

I think that help should exist in two forms: console based, and web based.  And every function or command should have a complete description, and copious examples.  Since )help is already used maybe we need another system command, say )about, so that for example ")about solve" gives you a list so that then ")about solve ode" gives you the help you need.  Mind you, I have no idea how this would be implemented.  Would it be possible to pull all the useful information out of spad files into a new "about" directory?

Enough of a diatribe for the moment.

-Alasdair

--
You received this message because you are subscribed to a topic in the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/fricas-devel/qC9mzkTf3NY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to fricas-devel...@googlegroups.com.
To post to this group, send email to fricas...@googlegroups.com.
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.

[Ralf Hemmecke]

On 10/30/2015 09:19 PM, Alasdair McAndrew wrote:
> ... - scattered and often not helpful enough.

Yes, you've put the finger into the wound. Unfortunately, this is a very
weak point of FriCAS. But healing it will cost a lot of time and effort.
I currently work with Kurt on making the Jupyter notebook more stable.
After that I intend to publish some notebooks that cover what you ask
for, i.e. covering a topic with examples and explanations. I hope that
will crow then and others will also contribute.

> For example, I was trying to find out yesterday how to solve a
> second order linear IVP. I can set up the ODE, but I don't know how to
> give the values both of y(0) and y'(0) to solve. The only example I could
> find was of a first order system.

Do you mean something like this?

(1) -> y := operator 'y

(1) y
Type:
BasicOperator
(2) -> deq := D(y(x), x, 2) + y(x)

,,
(2) y (x) + y(x)

Type:
Expression(Integer)
(3) -> solve(deq, y, x)

(3) [particular= 0,basis= [cos(x),sin(x)]]
Type: Union(Record(particular: Expression(Integer),basis:
List(Expression(Integer))),...)

-- initial values y(0)=1, y'(0)=2

(4) -> solve(deq, y, x=0, [1,2])

(4) 2sin(x) + cos(x)
Type:
Union(Expression(Integer),...)

In fact, for that, hyperdoc has some examples. Look under

Topics -> Solving Equations -> Solution of Differential Equations ->
8.10.1 Closed-Form Solutions of Linear Differential Equations

Yes. The bad thing with HyperDoc is, that one cannot easily search
through it.

> If you enter )d op solve you find there are 33 exposed operations, including
>
> [6] (D2,D1,Symbol,D1,List(D1)) -> Union(D1,"failed")
> from ElementaryFunctionLODESolver(D5,D1,D2)
> if D1 has Join(ACFS(D5),TRANFUN,PRIMCAT) and D5 has Join(
> COMPAR,EUCDOM,RETRACT(INT),LINEXP(INT),CHARZ) and D2 has
> LODOCAT(D1)
>
> which, let's face it, is pretty meaningless unless to an expert user or a
> developer.

I would count myself as a developer, but honestly you need deep
understanding of the type system to make any sense out of this. And a
signature alone without documentation carries not enough information for
the end user.

> I think that help should exist in two forms: console based, and web based.

> And every function or command should have a complete description, and
> copious examples.

Exactly. I think we could very much learn from the Sage project. But
unfortunately, although the ++ docstrings are there, SPAD (in contrast
to python) does not clearly define how docstrings should be written and
structured. (Well, if I'm not completely wrong then they should probably
be formatted in HyperTeX, but who would bother to learn that language?
We should rather aim for RestructuredText or MarkDown. (I'm just praying...)

> Since )help is already used maybe we need another system
> command, say )about, so that for example ")about solve" gives you a list so
> that then ")about solve ode" gives you the help you need. Mind you, I have
> no idea how this would be implemented. Would it be possible to pull all
> the useful information out of spad files into a new "about" directory?

Of course, everything is possible, but I will not touch that )help
command. That's written in BOOT and just gathers its information from
some help files -- in the commercial Axiom those helpfiles were
constructed from the .htex files. I think while I was working on the
book, I even reenabled a part of that conversion. But currently I
wouldn't trust too much what )help provides. Unfortunately, at the
moment the best source of information is the .spad files themselves. :-(

It's manpower what FriCAS is lacking. Ideas and contributions are always
welcome.

Ralf

[Alasdair McAndrew]

I agree that lack of manpower will always mean that there are more things in anybody's wishlist than there are people to actually do them.  And I think most people would rather extend FriCAS's functionality than do the nuts-and-bolts job of documentation.  If I am successful in extending Kurt and Bill's gsl.spad/lisp to cover all the functionality of QUADPACK, I'd certainly be happy to whip up some documentation.  But as you say - how should it be written? and where would it go? and how would the new user find out about it?

In GNU Octave, for example:

Octave:1> lookfor quad
dblquad             Numerically evaluate the double integral of F.
quadgk              Numerically evaluate the integral of F from A to B using adaptive Gauss-Konrod quadrature.
quadl               Numerically evaluate the integral of F from A to B using an  adaptive Lobatto rule.
quadv               Numerically evaluate the integral of F from A to B using an  adaptive Simpson's rule.
triplequad          .
qp                  A_LB, A_IN, A_UB)  Solve the quadratic program
quad_options        Query or set options for the function 'quad'.
quad                Numerically evaluate the integral of F from A to B using Fortran  routines from QUADPACK.
quadcc              Numerically evaluate the integral of F from A to B using the  doubly-adaptive Clenshaw-Curtis quadrature described by P.
quadgk              Numerically evaluate the integral of F from A to B using adaptive Gauss-Konrod quadrature.

Octave:2> help quadgk

And then you have a copious page about the function, its parameters, its output, and how it works.  The documentation is actually part of the function file: there is a file quadgk.m which describes and implements the function, and includes documentation (which is extracted by "help") as well as comments, and examples.  This makes writing new functions easier in the sense that you know where everything is meant to be.  There is also a page on the Octave web site about how to get involved.

In Maxima, much the same thing works from the console:

(%1) ?? quad

 0: Functions and Variables for QUADPACK
 1: Introduction to QUADPACK
 2: quadrilateral  (Functions and Variables for draw)
 3: quad_control  (Functions and Variables for QUADPACK)
 4: quad_qag  (Functions and Variables for QUADPACK)
 5: quad_qag <1>  (Functions and Variables for QUADPACK)
 6: quad_qagi  (Functions and Variables for QUADPACK)
 7: quad_qagi <1>  (Functions and Variables for QUADPACK)
 8: quad_qagp  (Functions and Variables for QUADPACK)
 9: quad_qagp <1>  (Functions and Variables for QUADPACK)
 10: quad_qags  (Functions and Variables for QUADPACK)
 11: quad_qags <1>  (Functions and Variables for QUADPACK)
 12: quad_qawc  (Functions and Variables for QUADPACK)
 13: quad_qawc <1>  (Functions and Variables for QUADPACK)
 14: quad_qawf  (Functions and Variables for QUADPACK)
 15: quad_qawf <1>  (Functions and Variables for QUADPACK)
 16: quad_qawo  (Functions and Variables for QUADPACK)
 17: quad_qawo <1>  (Functions and Variables for QUADPACK)
 18: quad_qaws  (Functions and Variables for QUADPACK)
 19: quad_qaws <1>  (Functions and Variables for QUADPACK)
Enter space-separated numbers, `all' or `none':

If you then enter, say 5 at the prompt, you get another page with plenty of information.  There is also a very nice web interface (as there is for Octave).

The point is that these make it very easy for the beginner to start using the system: there's lots of help, easily available, in different and usable forms.  I would say that the documentation of Axiom/FriCAS is the most off-putting aspect for the new user.  In fact the best documentation is probably the Jenks-Sutor book, which even in its Hyperdoc form goes back to 1992.

This is always likely to be a problem since there simply aren't enough people working on the project, and I don't think for anyone of them is documentation the number one priority.

So I don't have an answer...but it would be nice to have at least a unified documentation system to which anybody could easily contribute.

-Alasdair

Ralf

--
You received this message because you are subscribed to a topic in the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/fricas-devel/qC9mzkTf3NY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to fricas-devel...@googlegroups.com.
To post to this group, send email to fricas...@googlegroups.com.
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.

[Ralf Hemmecke]

> So I don't have an answer...but it would be nice to have at least a unified
> documentation system to which anybody could easily contribute.

First of all, the ++ docstrings are already there. But unfortunately
although they go into hyperdoc and into http://fricas.github.io/api as
you said, that's not enough. When I am searching how to solve a problem,
I might find a function, but in FriCAS it's always difficult to build
the respective domains first in order to apply that function, so I fully
agree that there must be more example pages demonstrating how FriCAS
functionality is used.

In fact, that is what I intend to do with http://fricas.github.io .
Well, all the data there already lives in a private git repository, but
it's not my intention to keep it private. I just find the repo is not
yet ready for the public, because it basically only works for me to
generate this webpage. But yes, soon, I'll put this repo onto github and
will accept pull requests. I'm very much interested in improving the
documentation, because I think that is one way to avoid that people
start with FriCAS and then put it aside, because there is no easy help
available. Let's face it: not every user is brave enough to send his
problems to the mailing list.

Ralf

[Alasdair McAndrew]

I don't think it should be too much of an imposition to require documentation to be written in HyperTeX - if you're a modern mathematician, you should know TeX very well anyway.  What would be nice is some way of pulling the ++ docstrings out of spad files and into the console.

And including usage examples.  For instance the docstrings for numquad.spad are very good: see the lovely new web page at http://fricas.github.io/api/NumericalQuadrature.html, but what is lacking are examples.  (And a discussion of the differences of relative and absolute errors!)

-Alasdair

Ralf

--
You received this message because you are subscribed to a topic in the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/fricas-devel/qC9mzkTf3NY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to fricas-devel...@googlegroups.com.
To post to this group, send email to fricas...@googlegroups.com.
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.

[Waldek Hebisch]

Thomas Baruchel wrote:
>
> Since I am a console guy, here are some thoughts I had after your post.
>
> I have been using Fricas for about ten days and I really like it.
>

<snip>

> There are however two things I don't like with Fricas:
> * I couldn't find any way to use the help system (called Hyperdoc if I am
> not wrong) from within the console; obviously Hyperdoc is a graphical
> system (which I probably didn't compile; anyway I don't want to have an
> external window). Maxima has a very great help system, callable from within
> the interpreter. Isn't there really any way to get the help from the Fricas
> interpreter?

I must admit that I consider myself console guy, but in case of
HyperDoc I did not think about making a console equivalent. Namely
HyperDoc is highly hyperlinked and much of utility comes from this.
On current machines I run window system and while most my windows
are terminals ocasional extra windows are not a big problem.
Anyway, it seems that nobody is going to create a text-based
hyperlinked browser talking HypeDoc protocol.

What could be done is retargeting HyperDoc to html, so that
results can be seen is a browser (possibly Lynx or links in
a console) or creating a non-hyperlinked version of pages.

> * I compiled Fricas with Clozure Lisp and with SBCL; and I can't
> interrupt a computation with Ctrl-C. With Clozure Lisp, Ctrl-C doesn't do
> anything; with SBCL I can interrupt a computation but after that the
> interpreter doesn't seem to work very well again. Any hint?

Our handling of Ctrl-C is essentially like below Lisp program:

(defun mini-repl()
(tagbody
loop
(print (eval (read)))
(force-output)
(go loop)))

(defun spad-system-error-handler(c)
(print "in spad-system-error-handler")
(force-output)
(mini-repl))

(defun main ()
(let ((*debugger-hook*
(lambda (condition previous-handler)
(spad-system-error-handler condition))
))
(handler-bind ((error #'spad-system-error-handler))
(mini-repl))))

For Closure CL the extra difficulty is that we want to
create a standalone executable, which seem to require
essentially replacing standard Lips toplevel loop with
our own.

Currently when using Closure CL the program above after
'Ctrl-C' goes into Lisp debugger, while we need to pass
control to our handler. Additinally, apparently as
a byproduct of changing toplevel 'Ctrl-C' is ignored.

If we could make executable version of this program to
work in Closure CL (where work means that 'Ctrl-C' passes
control to the handler), then the rest should be easy.
Long ago, when I asked Closure CL folks about this issue
I got some hints how to ensure that 'Ctrl-C' gets
into debugger, but no info how to pass it to our
handler...

--
Waldek Hebisch

[Waldek Hebisch]

Alasdair McAndrew wrote:
>
> In Maxima, much the same thing works from the console:
>
> (%1) ?? quad
>
> 0: Functions and Variables for QUADPACK

<snip>

> 19: quad_qaws <1> (Functions and Variables for QUADPACK)
> Enter space-separated numbers, `all' or `none':
>
> If you then enter, say 5 at the prompt, you get another page with plenty of
> information. There is also a very nice web interface (as there is for
> Octave).

I tried the above for limit. I do not see the result as superior
to HyperDoc result: in HyperDoc 'limit' gives you a list of
signatures and you can look at descriptions of some or all.
Due to overloading we have a 'limit' for graphs, but looking
at 'limit' for functions I see reasonable description. Maxima
version is more wordy, but to the effect both FriCAS description
and the Maxima one tell you that the function computes limit and
what to do to get one sided limits. Maxima description mentions
"special values", in FriCAS this is handled via types. In particular
description of 'limit' mentions 'OrderedCompletiton' and you can
click on it to get extra information. Maxima mentions extra
switches -- there are no switches in FriCAS so no need for
documentation about switches.

Let me add that in genral system architecture makes a difference:
FriCAS uses generic functions and overloading so you have
several signatures, some doing variants of the same operation,
but with different arguments some may do compeletely different
operation ('limit' for graphs is different animal than 'limit'
for functions). IIUC in Maxima there is single operation 'limit'
which acts differently depending on arguments. So in Maxima
it is natural to bundle all information about 'limit' into
single description. OTOH in FriCAS each signature has its
own description. With FriCAS approach it is natural to
have rather terse description: just what operation is supposed
to do and what arguments means (as long decription would get
duplicated between variants of signature). Also, some other
systems when documenting functions tell about methods used
to compute results. In FriCAS due to generic coding
method is "secret" of implementation. For examples 'determinant'
is declared and have a docstring in MatrixCategory, while
implementations are in differents place (and IIRC there are
3 different methods in use).

Now looking at 'guessHolo' I see a problem: there are in fact
four signatures, but Hyperdoc shows several, most without
description. I need to look why this happens, but such thing
shuld be fixed.

> The point is that these make it very easy for the beginner to start using
> the system: there's lots of help, easily available, in different and usable
> forms. I would say that the documentation of Axiom/FriCAS is the most
> off-putting aspect for the new user. In fact the best documentation is
> probably the Jenks-Sutor book, which even in its Hyperdoc form goes back to
> 1992.

Core is from 1992 but there are (small) new parts and in general
it is updated for changes in FriCAS.

--
Waldek Hebisch

[Ralf Hemmecke]

On 11/09/2015 08:38 PM, Waldek Hebisch wrote:
> What could be done is retargeting HyperDoc to html, so that
> results can be seen is a browser (possibly Lynx or links in
> a console) or creating a non-hyperlinked version of pages.

http://fricas.github.io/api looks quite reasonably in lynx.
If you like you can have these pages generated for your local computer.
That's what I use if I have not Internet.

Ralf