FAQ

FriCAS FAQ.

Section 1 - About

1.1: What is FriCAS?
1.2: What is relation between FriCAS and Axiom?
1.3: What does the FriCAS name mean?

Online resources:

2.1: Where I can find online information about FriCAS?
2.2: Where should I report bugs?
2.3: Where I can find documentation?

3.1: How one can use FriCAS in a pipe?
3.2: How one can use FriCAS in batch mode?
3.3: How to find where an exported functions is implemented?

1.1: What is FriCAS

FriCAS is an advanced computer algebra system.  Its capabilities range
from calculus (integration and differentiation) to abstract algebra.
It can plot functions and has integrated help system.

1.2: What is relation between FriCAS and Axiom

FriCAS forked from Axiom in 2007.  FriCAS seeks different developement
methodology and after fork removed several unused parts (without removing
functionality).  FriCAS fixed a lot of bugs and added new functionality.
Currently (April 2013) in the src/algebra subdirectory, which hosts
mathematical functionality about 25% of code was added after fork.

1.3: What does the FriCAS name mean

The prefix Fri is a deliberate misspeling of Free -- FriCAS sounds
like Free CAS.  There is also a second meaning: Polish word
"frykas" (which sounds similar to FriCAS) denotes generally
tasty food,  French word "fricasse" and German "Frikasse" name
a particluar food.


2.1: Where I can find online information about FriCAS?

The FriCAS home page is at SourceForge:

http://fricas.sf.net

There is mailing list (please sign up before posting a message):

http://groups.google.com/group/fricas-devel?hl=en

This list intended both for users and developers.


2.2: Where should I report bugs?

FriCAS has a bug tracker at SourceForge:

http://sourceforge.net/tracker/?atid=972421&group_id=200168

bugs specific to FriCAS should be reported there.  There are
also Wiki pages collecting information about bugs in all
Axiom derivatives:

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

Currently the wiki contains much more reports than SourceForge
bug tracker, but many (most of them) do not apply to FriCAS.

2.3: Where I can find documentation?

The main source of information about FriCAS is "Axiom book" by
Jenks and Sutor.  Its content is shown by the integrated HyperDoc
help system.  You can also access the book in .pdf form at:

http://fricas.sourceforge.net/doc/book.pdf

and in .xhtml form at:

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

3.1: How one can use FriCAS in a pipe?

Currently trying to run plain 'fricas' command in a pipe hangs
(this is a bug, but fix requires substantial change).
Instead, one needs to pass '-nosman' option like:

fricas -nosman < tst.input > tst.output

Note: Simlarely to command line pipe mode requires each function
to be defined in a single line.

3.2: How one can use FriCAS in batch mode?

Pass ')read file.input' in pipe mode like:

echo ')read tst.input' | fricas -nosman > tst.output

3.3: How to find where an exported functions is implemented?

In Hyperdoc 'Browse' window enter constructor name or abbreviation
and click on 'Constructors'.  In the resulting form specify
all parameters.  Than click on 'Operatations' and then on
'Implementations'.  If you are interested in a single operation
after clicking on 'Operatations' click on operation name and
than on 'Implementations'.

----------------------------------------------------------------------
----------------------------------------------------------------------

Below is old Axiom FAQ

FAQ 12: The axiom command fails.
FAQ 13: How can I create and access Lisp functions from Axiom?
FAQ 15: How can I see what the interpreter is trying to do?
FAQ 16: How can I record console output?
FAQ 17: Graphics don't work or sman fails to start ?
FAQ 19: How can I get equations written on one line?
FAQ 20: Axiom hangs when graphics should be displayed.
FAQ 24: What is the purpose of the domain HACKPI?
FAQ 25: Can I create or edit hypertex pages?
FAQ 28: Graphics does not work inside TeXmacs?
FAQ 32: How can I input an equation as a string?
FAQ 33: How can I run hypertex standalone?
FAQ 35: Why do .axiom.input defined functions fail in axiom?
FAQ 38: How can I debug algebra code?
FAQ 39: How can I access lisp code from the Axiom command line?

===================================================================
FAQ 12: The axiom command fails.
===================================================================

This is likely one of two problems. Axiom uses clef as its command
line editor. This has functionality similar to GNU Readline but
was written independently. The axiom command uses:

  clef -e $AXIOM/bin/AXIOMsys

Clef attempts to create new terminals and this might fail.
The first thing to check is the permission bits on /dev/pty.

Next it is possible to run the axiom image, called AXIOMsys, directly.
Just type AXIOMsys. It won't have command recall or command line
editing but everything else is there.

===================================================================
FAQ 13: How can I create and access Lisp functions from Axiom?
===================================================================

SExpression is the domain that handles raw lisp objects.
It is possible to create SExpression elements directly contruction:

m:=[1::SEX, 2::SEX]
  [1,2]
                             Type: List SExpression
n:=m::SEX
  (1 2)
                             Type: SExpression
car(n)
  1
                             Type: SExpression

You can access lisp functions directly with:

GENSYM()$Lisp

Lisp is the domain, known to the interpreter and compiler, that contains
lisp functions and symbols.

Notice that Axiom is case-sensitive and that generally lisp symbols
are upper case.

You can also create and call lisp functions. For instance:

)lisp (defun foo () (print "it works"))
    Value = FOO

FOO()$Lisp
 "it works"

    it works
                             Type: SExpression

While accessing and writing functions in Lisp is possible it is
generally not recommended as Axiom contains a programming language
that should be able to achieve almost everything you need.

===================================================================
FAQ 15: How can I see what the interpreter is trying to do?
===================================================================

)set message bottomup on

will tell you the signatures that the interpreter is trying to use.

Another method is to do

)lisp (setq |$monitorNewWorld| t)

and you can view database calls with

)lisp (setq *miss* t)

===================================================================
FAQ 16: How can I record console output?
===================================================================
)spool filename
    starts sending output to the file called filename
)spool )off
    stops sending output to the file

===================================================================
FAQ 17: Graphics don't work or sman fails to start ?
===================================================================

First try running sman as :
sman -debug -noclef -nonag -noht
If graphics still don't work or sman fails to start then
look at the error messages.

===================================================================
FAQ 18: How can the user use the batch mode?
===================================================================

1) create an input file:

echo '2+2' >tst.input
echo '3+3' >>tst.input

2) make sure the AXIOM variable is set

export AXIOM=/path/axiom/mnt/linux
export PATH=$AXIOM/bin:$PATH

3) pipe a )read command to AXIOMsys and capture the output

echo ')read tst.input' | AXIOMsys >tst.output

===================================================================
FAQ 19: How can I get equations written on one line?
===================================================================

> Dear Axiom supporters,
> 2. I would also like to have the output of kind
>
>  "  - (s-1) * (s+1) * (p^4 +(2*e^3 + (24*s^2 - 4)*e)*p^3 * ...) * ...
>  "
>
> For example, my DoCon program can read this format ...
>
> 2.1 It prints these polynomials like for  (Z[e])[p]:
>                                               " (e^2 + 2e)*p "
>     How to print it like for  Z[p,e]:
>                                               " 2*p*e + e^2 "

You may wish to use the InputForm domain, where you can find some
bizarre functions. In your case, "unparse" may help you, as follows.

(1) -> p:=(a+b+y)^2*y+1-(x+y+z)^4

   (1)
        4               3        2             2  2
     - z  + (- 4y - 4x)z  + (- 6y  - 12x y - 6x )z
   +
          3        2      2      3      4              3        2            2
     (- 4y  - 12x y  - 12x y - 4x )z - y  + (- 4x + 1)y  + (- 6x  + 2b + 2a)y
   +
          3    2           2      4
     (- 4x  + b  + 2a b + a )y - x  + 1
                                                     Type: Polynomial Integer
(2) -> pi:=p::InputForm

  (2)
  (+
     (+
       (+  (+ (* - 1 (** z 4)) (* (+ (* - 4 y) (* - 4 x)) (** z 3)))
       (* (+ (+ (* - 6 (** y 2)) (* (* - 12 x) y)) (* - 6 (** x 2))) (** z 2)))

      (*
         (+
           (+  (+ (* - 4 (** y 3)) (* (* - 12 x) (** y 2)))
           (* (* - 12 (** x 2)) y))
          (* - 4 (** x 3)))
        z)
      )

    (+
       (+
         (+  (+ (* - 1 (** y 4)) (* (+ (* - 4 x) 1) (** y 3)))
         (* (+ (* - 6 (** x 2)) (+ (* 2 b) (* 2 a))) (** y 2)))
        (* (+ (* - 4 (** x 3)) (+ (+ (** b 2) (* (* 2 a) b)) (** a 2))) y))
      (+ (* - 1 (** x 4)) 1))
    )
                                                              Type: InputForm
(3) -> unparse(pi)

   (3)
  "(-z**4)+((-4*y)+(-4*x))*z**3+((-6*y*y)+(-12*x*y)+(-6*x*x))*z*z+((-4*y**3)+(-
  12*x*y*y)+(-12*x*x*y)+(-4*x**3))*z+(-y**4)+((-4*x)+1)*y**3+((-6*x*x)+2*b+2*a)
  *y*y+((-4*x**3)+b*b+2*a*b+a*a)*y+(-x**4)+1"
                                                                 Type: String


Aternatively you can get the LaTex output string:

(4) -> )lisp (|parseAndInterpret| "integrate(sin(x),x)::TexFormat::OutputForm")


   (4)  ["$$","-{\cos ","\left(","{x} ","\right)}","$$"]
                                                             Type: OutputForm
Value = ((|OutputForm|) WRAPPED BRACKET (AGGLST "\"$$\"" "\"-{\\cos \""
"\"\\left(\"" "\"{x} \"" "\"\\right)}\"" "\"$$\""))

or the text form:

(5) -> )lisp (|parseAndInterpret| "integrate(sin(x),x)::OutputForm")

   (5)  - cos(x)
                                                             Type: OutputForm
Value = ((|OutputForm|) WRAPPED "-" (|cos| |x|))

or the actual string output:

Axiom's algebra gets output to a stream called |$algebraOutputStream|
Thus you can get the output you want by:

)set message autoload off
)lisp (progn
          ; we need a new output stream that is backed by a string
        (setq tmpout (make-string-output-stream))
          ; we hold on to the regular algebra output stream
        (setq save |$algebraOutputStream|)
          ; we capture the algebra output into the string stream
        (setq |$algebraOutputStream| tmpout)
          ; we generate output from string input
        (|parseAndInterpret| "(x+1)^9")
          ; we save the output into the result variable
        (setq result (get-output-stream-string |$algebraOutputStream|))
          ; we restore the regular algebra output stream
        (setq |$algebraOutputStream| save)
          ; and we return the string as our value
        result)

)lisp result

result contains the output from axiom that you want.

Alternatively you can see the internal representation using |pf2Sex|
(parsed function to s-expression) by doing:

if you start axiom and type

   )trace (|pf2Sex|)

and then type some expression

   1

you'll see the input and output of this function. This function
(parsed function to s-expression) is internal to the axiom interpreter.
it takes the parsed input line and converts it to a lisp s-expression.
so the above '1' input yields

 1> (|pf2Sex| ((|Integer| (|posn (0 "1" 1 1 "strings") . 0)) . "1"))
 1< (|pf2Sex| 1)

the "1>" line tells you the function input.
the "1<" line tells you the function output.

notice that even a simple input line generates type information.

this function is not part of the exposed user interface because
there is nothing at the user level that needs this information.


===================================================================
FAQ 20: Axiom hangs when graphics should be displayed.
===================================================================

Be sure that your X server will allow you to display windows. try:
'xhost +'

===================================================================
FAQ 24: What is the purpose of the domain HACKPI?
===================================================================

HACKPI is a hack provided for the benefit of the axiom interpreter.
As a mathematical type, it is the simple transcendental extension
Q(\pi) of the rational numbers. This type allows interactive users to
use the name '%pi' without a type both where a numerical value is
expected [ as in draw(sin x,x=-%pi..%pi) ] or when the exact symbolic
value is meant.  The interpreter defaults a typeless %pi to HACKPI and
then uses the various conversions to cast it further as required by
the context.

One could argue that it is unfair to single %pi out from other
constants, but it occurs frequently enough in school examples
(specially for graphs) so it was worth a special hack. In a
non-interactive environment (library), HACKPI would not exist.


===================================================================
FAQ 25: Can I create or edit hypertex pages?
===================================================================
The hypertex is intended to be edited by users. We are looking to
build special purpose pages around courses such as linear algebra.

Assume HERE=$AXIOM/doc/hypertex/pages

The text can be found in $HERE/foo.ht or $HERE/foo.pht

The macros are tex-like and live in $HERE/util.ht

To change a page you need to:

cd $HERE
edit the page
rm *~ (to delete backup copies)
htadd *
hypertex

the htadd command takes arguments:

htadd [-s|-l|-f db-directory] [-d|-n] filenames

but, i'm sorry to say, these have not been fully documented.

The htadd function will maintain the file called $HERE/ht.db
which is a database of absolute byte indexes into files.
Forgetting to run htadd will still work, sort-of, until you
hit a bad byte index and then it will fail.

Hypertex can also be directed elsewhere by using the HTPATH
shell variable.

===================================================================
FAQ 28: Graphics does not work inside TeXmacs?
===================================================================

> No, I am not able to get graphics to appear in an X-window
> from inside TeXmacs.  That's what I *want* to be able to do.
>
> I have TeXmacs 1.0.4.4 (latest being 1.0.4.5).   I know the
> plugin calls AXIOMsys, and I tried to make it call "axiom"
> or "sman" with no immediate success.

Ok great. You are obviously on the right track. If you compiled
TeXmacs from source then to make tm_axiom call "axiom", the
simplest thing to do is to modify the souce file tm_axiom.c by
replacing "AXIOMsys" with "axiom" and then recompile it. It is
a simple C program with no dependencies and can be compiled
separately. Move the tm_axiom.exe file to the appropriate place
in the TeXmacs installation directory.

If you didn't compile TeXmacs from source you can get just the
tm_axiom.c file from the CVS, modify it and compile as above.

The Axiom graphics process has the ability to create a
postscript format output file containing the graphic.
This can be initiated from the user interface of the
graphics window or also from an Axiom command. Check "Chapter
7 Graphics" of the Axiom book, specifically section "7.1.8
Operations for Two-Dimensional Graphics", `write' operation.
It works something like this:

     viewPort := draw(sin x, x=-%pi..%pi)
     write(viewPort, "output.ps","postscript")

These commands can be included directly in the TeXmacs document.

===================================================================
FAQ 32: How can I input an equation as a string?
===================================================================

There is an embedded command server within AXIOMsys.
Look at:
http://daly.axiom-developer.org/TimothyDaly_files/lisptalk/pages/lisp35.html

In particular, see the function

  parseAndInterpret stringBuf

(which is boot language code. So in lisp I have
to tack on the | | onto the function name and then I can
call it like this:

  (1) -> )lisp (|parseAndInterpret| "integrate(sin x,x)")

   (1)  - cos(x)
                          Type: Union(Expression Integer,...)

  Value = ((|Union| (|Expression| (|Integer|)) (|List| (|Expression|
(|Integer|)))
  ) WRAPPED 0 (1 #<vector 10ccde54> (1 0 . -1)) 0 . 1)

  (2) ->

and sure enough! Axiom parses and interprets the string.

The result appears as stdout and the value returned
seems to contain the type information. The "WRAPPED"
information is the lisp data structure.

> The string output function mentioned in FAQ 19 is a linear
> form of the output. However Axiom's native output machinery
> is called CHARYBDIS which was a research project from the
> 60s with the goal of printing mathematics on typewriters.
> Axiom still uses that code.

===================================================================
FAQ 33: How do I run hypertex standalone?
===================================================================

export AXIOM=/whatever/mnt/linux
export HTPATH=$AXIOM/doc/hypertex/pages
export PATH=$AXIOM/bin:$PATH
hypertex

===================================================================
FAQ 35: Why do .axiom.input defined functions fail in axiom?
===================================================================
You write this in your .axiom.input file:

mrd(x:Integer,v:Integer):Integer == x+y

You can't see this function even though it appears to be defined. That's
because Axiom is working in a new frame.

When you start AXIOMsys you are running the interpreter talking directly
to the terminal. So the .input file is actually talking to a frame
at the top level. Your function is defined.

The .axiom.input file is read in a "frame" called "initial".
AXIOMsys only uses the "initial" frame (although you can define and
use new ones). A frame contains its own variables and function definitions.

The "axiom" command does several things that AXIOMsys does not. In
particular the axiom shell script starts up the 'sman' process which
starts AXIOMsys (which reads the .axiom.input file) and then sman
creates a new frame (usually a random lisp gensym name). In this new
frame (created after .axiom.input is read) your mrandom function is
not defined.

To see this do:
  AXIOMsys
  mrandom(3,3,3)   -- compiles and runs the function
  )quit

Now do:
  axiom
  mrandom(3,3,3)   -- undefined function
  )frame next
  mrandom(3,3,3)   -- compiles and runs the function
  )frame names     -- shows you all of the defined frames
  )quit


So with the axiom shell script the process is:
  axiom
    start sman                    (done by axiom shell script)
      sman starts AXIOMsys        (done by sman)
        create frame "initial"    (done by AXIOMsys)
          read .axiom.input       (define your function here)
        create frame "G00234"     (done by sman)
          put up a command prompt (in frame G00234, no functions defined)
        )frame next               (done by you)
                        .... and now you're back in frame initial
                        .... and your function is there


So your function was read and it is defined. However the function got
defined in the "initial" frame (because you defined it in the .axiom.input
file) and is not known in the frame created by sman. The ")frame next"
command will move you around the ring of frames. (See the hardcopy book
on page 579).

===================================================================
FAQ 38: How can I debug algebra code?
===================================================================

  Axiom contains some powerful commands to help with testing and
debugging library modules written in Spad and also the Axiom system
itself. The most important of these commands is ')trace'.

This command is used to trace the execution of functions that make
up the Axiom system, functions defined by users, and functions from
the system library. Almost all options are available for each type
of function but exceptions will be noted below.

To list all functions, constructors, domains and packages that are
traced, simply issue::

  )trace

To untrace everything that is traced, issue::

  )trace )off

When a function is traced, the default system action is to display
the arguments to the function and the return value when the function
is exited. Other information can be displayed or collected when a
function is traced and this is controlled by the various options.
If a domain or package is traced, the default action is to trace all
functions exported. Individual interpreter, lisp or boot functions
can be traced by listing their names after ')trace'. Any options that
are present must follow the functions to be traced. For example::

  )trace f

traces the function f. To untrace f, issue::

  )trace f )off

Note that if a function name contains a special character, it will
be necessary to escape the character with an underscore::

  )trace _/D_,1

To trace all domains or packages that are or will be created from a
particular constructor, give the constructor name or abbreviation
after ')trace'::

  )trace MATRIX
  )trace List Integer

The first command traces all domains currently instantiated with
Matrix. If additional domains are instantiated with this constructor
(for example, if you have used 'Matrix(Integer)' and 'Matrix(Float)'),
they will be automatically traced. The second command traces
'List(Integer)'.

The following are the general options for the ')trace' command.

')break after' -- causes a Common Lisp break loop to be entered after
exiting the traced function.

')break before' -- causes a Common Lisp break loop to be entered before
entering the traced function.

')break' -- is the same as )break before.

')count' -- causes the system to keep a count of the number of times the
traced function is entered.

The total can be displayed with::

   )trace )stats

and cleared with::

   )trace )stats reset

')count n' -- causes information about the traced function to be displayed
for the first n executions. After the n-th execution, the function is
untraced.

')depth n' -- causes trace information to be shown for only n levels of
recursion of the traced function.

The command::

  )trace fib )depth 10

will cause the display of only 10 levels of trace information for the
recursive execution of a user function fib.

')math' causes -- the function arguments and return value to be displayed
in the Axiom monospace two-dimensional math format.

')nonquietly' -- causes the display of additional messages when a function
is traced.

')nt' -- This suppresses all normal trace information. This option is useful
if the ')count' or ')timer' options are used and you are interested in the
statistics but not the function calling information.

')off' -- causes untracing of all or specific functions. Without an argument,
all functions, constructors, domains and packages are untraced. Otherwise,
the given functions and other objects are untraced.

To immediately retrace the untraced functions, issue::

  )trace )restore

')only listOfDataToDisplay' -- causes only specific trace information to be
shown.

')restore' -- causes the last untraced functions to be retraced. If
additional options are present, they are added to those previously in
effect.

')stats' -- causes the display of statistics collected by the use of the
')count' and ')timer' options.

')stats reset' -- resets to 0 the statistics collected by the use of the
')count' and ')timer' options.

')timer' -- causes the system to keep a count of execution times for the
traced function. The total can be displayed with ')trace )stats' and
cleared with ')trace )stats reset'.

')varbreak var1 ... varN' -- causes a Common Lisp break loop to be
entered after the assignment to any of the listed variables in the
traced function.

')vars' -- causes the display of the value of any variable after it is
assigned in the traced function. Note that library code must have been
compiled using the ')vartrace' option in order to support this option.

')vars var1  ... varN' -- causes the display of the value of any of
the specified variables after they are assigned in the traced function.
Note that library code must have been compiled using the ')vartrace'
option in order to support this option.

')within executingFunction' -- causes the display of trace information
only if the traced function is called when the given executingFunction
is running.

The following are the options for tracing constructors, domains and
packages.

')local op1 ... opN' -- causes local functions of the constructor to
be traced. Note that to untrace an individual local function, you must
use the fully qualified internal name, using the escape character before
the semicolon. For example::

  )trace FRAC )local
  )trace FRAC_;cancelGcd )off

')ops op1 ... opN' -- By default, all operations from a domain or package
are traced when the domain or package is traced. This option allows you
to specify that only particular operations should be traced.

The command::

  )trace Integer )ops min max _+ _-

traces four operations from the domain Integer. Since + and - are special
characters, it is necessary to escape them with an underscore.

Also See: ')boot', ')lisp' , and ')ltrace'. Please refer to the
Axiom Book section "Axiom System Commands" for more detailed information.

===================================================================
FAQ 39: How can I access lisp code from the Axiom command line?
===================================================================

To run a lisp command from the command line use )lisp:

 --> )lisp (+ 2 3)

If you want to run a lot of lisp commands from the command line do:

 --> )lisp (setq $dalymode t)
 --> (+ 2 3)
 --> (defun foo (x y) (+ x y))
 --> (foo 2 3)
 --> 2 + 3

$dalymode says:

   If the first character is a '('
     then it is lisp
     else it is axiom

to disable it do:

  --> (setq $dalymode nil)

I wrote this change to the interpreter because I tend to use lisp a lot
during maintenance. It breaks some syntax but you can work around that.

If you really want to "drop" into lisp do:

  --> )fin
BOOT> (+ 2 3)

and now you are talking only to lisp at a lisp command prompt in
the BOOT package. To restart Axiom type:

BOOT>(restart)