Lecture 3: SageMath as a Calculator -- getting Help
===================================================

In this lecture we show how to use the SageMath notebook as a calculator
and explore the extensive help facilities.

If we compute with arbitrary multiprecision, then we must raise
the precision of the field to compute the rounding errors correctly.
We illustrate this with the computation of a numerical approximation
to \ :math:`\pi`, accurate up to 30 decimal places.
We explore the help system of SageMath, priming the continued fractions
of the next lecture.

Getting Started
---------------

We run the notebook in multicell mode.
In the command line interface, the commands are executed in sequence,
in the notebook interface, we can execute commands out of order.

We enter mathematical expressions in a :index:`cell`.
The expressions are executed by clicking on the evaluate button
which appears below each cell.
For example:

::

   34^34

With the underscore we get the result from the previous computation.
Note that *previous* refers to time, not location.
To experience this, we add in the next cell the underscore,
and then in the following cell:

::

   2*3

When we evaluate we see the result 6 appear and when we evaluate
the cell with the underscore that is located above the cell 2*3,
then we will see the result change from the value of 34^34 into 6.
Consider the next cell with content

::

   pi
   pi - _

Repeatedly clicking on the evaluate button will give different results
each time.  Can you explain the differences?


At the command line interface:
(but not in the notebook interface)
we can use double and triple underscores:

::

   sage: 2
   2
   sage: 3
   3
   sage: 4
   4
   sage: ___
   2
   sage: ___
   3
   sage: ___
   4
   sage: __
   3
   sage: _
   3

Consider the computation of the
difference between pi and a 30 digit :index:`numerical approximation`
for pi.  The shortest way to obtain this is via ``pi.n(digits=30)``.
Another way is via ``numerical_approx``
as illustrated below:

::

   numerical_approx(pi,digits=30)

But often we want to compute with a precision of 30 decimal places.
Then we compute with a ``RealField`` of prescribed :index:`precision`.
For a 30-digit approximation of pi we then type in a cell:

::

   R = RealField(30*log(10,2))
   pi30 = R(pi)
   strpi30 = str(pi30)
   print('%d-digit approximation for pi : %s' % (len(strpi30),strpi30))

With ``log(10,2)`` we compute the binary logarithm of 10,
because the argument of ``RealField`` is expressed in bits.
After the creation of ``R``, we convert the symbol for the mathematical
constant pi into a 30-digit approximation for pi.
This approximation is stored in the variable ``pi30``.
The conversion to the string representation ``str(pi30)`` is used to
check that indeed we do have 30 decimal places, as in confirmed by
the output produced by the cell.
 
As simple computation of the difference between pi and pi30
can be done as

::

   R(pi - pi30)

which returns ``0.00000000000000000000000000000``

The problem with the previous computation is that the precision of the
RealField was not large enough.  To make the difference with 40 decimal
places:

::

   RealField(40*log(10,2))(pi-pi30)

yields 1.69568553528388823010177990083205496387e-31.
Thus we verified that ``pi30`` has the desired :index:`accuracy` 
of 30 decimal places. 

Next we illustrate the difference between precision and accuracy:

::

   pi40 = RealField(40*log(10,2))(pi30)

we have made a variable ``pi40`` with a working precision of 40 decimal
places.  But because it takes the value of ``pi30``, the accuracy of
``pi40`` is no more than 30 decimal places.

Getting Help
------------

To see the documentation for a specific command, in a cell we can type

::

   help(RealField)

To look for a specific topic, we can use the ``search_doc``
as illustrated below:

::

   search_doc("numerical approximation")

Then the user gets redirected to the extensive
online documentation, shown in :numref:`figsearchdoc` below.

.. _figsearchdoc:

.. figure:: ./figsearchdoc.png
    :align: center

    The documentation in SageMath consists of tutorials,
    the reference manual, constructions (how do I construct .. in Sage?),
    and PREP tutorials aimed at undergraduate students.

The list in :numref:`figsearchdoc` was produced with version 8.6
of SageMath.  As the documentation has grown, the output with current
versions is much larger.

The Packages in SageMath
------------------------

There are many packages in SageMath where we can find pi:

::

   print(type(pi))
   print(type(math.pi))
   import sympy
   print(type(sympy.pi))
   import numpy
   print(type(numpy.pi))

The second and fourth type is the ordinary ``float``
whereas the first and third type are symbolic.

To work with the pi as defined by sympy:

::

   from sympy import pi as sympypi
   print(sin(sympypi))
   print(sympypi.evalf(30))

The first number we see is ``0`` followed by a 30-digit approximation
for pi.

Assignments
-----------

In assignments where you are asked to explain,
please formulate your answers with complete sentences.

1. Explain the differences between pi and Pi in SageMath.
   Illustrate the differences with the appropriate commands.

2. Verify that SageMath knows that the exponential of the natural
   logarithm of 2 equals 2.

3. The mathematical constant *e* is just as pi a transcendental number.
   Show that SageMath knows the constant *e* by taking its natural logarithm.
   Calculate a 30-digit approximation for *e*.
   Verify the accuracy of this approximation by calculating its difference
   with the exact value.

4. Consider the following sequence of commands:

   ::

      R = RealField(30*log(10,2))
      print(tan(R(pi/2)))
      print(R(tan(pi/2)))

   Why do these two commands give different answers?
   Which of the two commands gives the correct answer?
   Also compare ``R(tan(pi))`` with ``tan(R(pi))`` 
   and explain the differences.

5. The decomposition of 2015 as a product of prime numbers is
   ``5 * 13 * 31``.  Use the help system of SageMath to find the command
   to compute the factorization of a natural number.

6. Explain the difference between 0 and 0.000
   and give two good examples of SageMath calculations that result
   in 0 and 0.000.