% calculations.tex
%
% The documentation in this file is part of Pyxplot <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: calculations.tex 1302 2012-09-05 17:30:27Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Performing calculations}

Often calculations need to be performed on data before they are plotted. This
chapter and the next describe the mathematical environment which Pyxplot
provides.

Most of the examples in this chapter act on single numerical values, displaying
the results using the {\tt print} command, demonstrating how Pyxplot may be
used as a desktop calculator. The next chapter will extend this to use of
Pyxplot's mathematical environment to analyse whole datasets and produce plots.

\section{Variables}

Variables can be assigned to hold numerical values using syntax of the form

\begin{verbatim} a = 5.2 * sqrt(64) \end{verbatim}

\noindent which may optionally be written in longhand as\indcmd{let}

\begin{verbatim} let a = 5.2 * sqrt(64) \end{verbatim}

\noindent Variables can subsequently be used by name in mathematical
expressions, for example:

\begin{verbatim} print a / sqrt(64) \end{verbatim}

\noindent Having been defined, variables can later be undefined -- set to have
no value -- using syntax of the form:

\begin{verbatim} a = \end{verbatim}

Variables can also hold non-numeric data, such as strings, colors, dates, lists
and dictionaries. The syntax for defining many of these data structures is
similar to that used by python, for example:

\begin{verbatim}
myList = [8,2,1,7]
myDict = {'john':27 , 'fred':14 , 'lisa':myList}
myDate = time.fromCalendar(2012,7,1,14,30,0)
\end{verbatim}

\noindent More information about Pyxplot's data types can be found in Chapter~\ref{chap:progDataTypes}.

A list of all of the variables which are currently defined can be obtained by
typing {\tt show variables}\indcmd{show variables}. Some constants are
pre-defined by Pyxplot, and so a number of variables are listed even if none
have been set by the user.

\section{Physical constants} \label{sec:constants} \index{physical
constants}\index{constants}

Many mathematical and physical constants are pre-defined in Pyxplot.  A
complete list of these can be found Chapter~\ref{ch:constants}.  Some of these,
for example, {\tt e}, {\tt pi} and {\tt goldenRatio} are standard mathematical
constants which are accessible in the user's default namespace:

\vspace{3mm}
\input{fragments/tex/calc_pi.tex}
\vspace{3mm}

\noindent Others, such as physical constants, are of more specialist interest
and are defined in modules. For example, the speed of light is defined in the
physics module {\tt phy}:

\vspace{3mm}
\input{fragments/tex/calc_c.tex}
\vspace{3mm}

Most of the pre-defined physical constants, such as this one, make use of
Pyxplot's native ability to keep track of the physical units of quantities and
to convert them between different unit systems -- for example, between inches
and centimeters.  This will be explained in more detail in
Section~\ref{sec:units}.

To list all of the functions and variables defined in a module such as {\tt phy}, type

\begin{verbatim}
print phy
\end{verbatim}

\noindent or simply

\begin{verbatim}
phy
\end{verbatim}


\section{Functions} \label{sec:functions}

Many standard mathematical and operating system functions are pre-defined
within Pyxplot's mathematical environment. These range from everyday examples
like trigonometric functions, to very specialised functions; there is even a
function to return the phase of the Moon on any given day. As with the
mathematical constant, common functions are defined in the user's default
namespace, for example

\vspace{3mm}
\input{fragments/tex/calc_exp.tex}
\vspace{3mm}

\noindent whilst others live in modules, for example

\begin{verbatim}
print ast.moonPhase( time.now() )
\end{verbatim}

\noindent which returns the present phase of the Moon in radians, and

\begin{verbatim}
print os.path.filesize("/etc/passwd")
\end{verbatim}

\noindent which returns the size of a file (in units of bytes, of course!).

A complete list of these functioned, sorted by module, can be found in
Chapter~\ref{ch:function_list}.  Another quick way to find out some more
information about a function is the print the function object, for example:

\vspace{3mm}
\input{fragments/tex/calc_log.tex}
\vspace{3mm}

All, of Pyxplot's built-in constants, functions and modules are
contained in the module {\tt defaults}, which can also be printed to view its
contents:

\begin{verbatim}
print defaults
\end{verbatim}

\noindent It is possible to access {\tt pi}, for example, as {\tt defaults.pi},
though in practice this syntax is very rarely needed. All of the objects in the
{\tt defaults} module are always accessible by name (i.e.\ they are always in
any namespace), unless another local or global variable exists with the same
name.

The user can define his own algebraic function definitions using a similar
syntax to that used to declare new variables, as in the examples:

\begin{verbatim}
f()    = pi
g(x)   = x*sin(x)
h(x,y) = x*y
\end{verbatim}

\noindent Function objects are just like any other variables, and can even be
used as arguments to other functions:

\vspace{3mm}
\input{fragments/tex/calc_funcnest.tex}
\vspace{3mm}

User-defined functions can be undefined in the same way as any other variable,
for example by typing:

\begin{verbatim}
f =
\end{verbatim}

Where the logic required to define a particular function is greater than can be
contained in a single algebraic expression, a subroutine should be used (see
Section~\ref{sec:subroutines}); these allow an arbitrary numbers of lines of
Pyxplot code to be executed whenever a function is evaluated.

\subsection{Spliced functions} \index{function splicing} \index{splicing
functions}

The definitions of functions can be declared to be valid only within a certain
domain of argument space, allowing for error checking when models are evaluated
outside their domain of applicability. Furthermore, functions can be given
multiple definitions which are specified to be valid in different parts of
argument space. We term this {\it function splicing}, since multiple algebraic
definitions for a function are spliced together at the boundaries between
their various domains.  The following example would define a function which is
only valid within the range
$-\nicefrac{\pi}{2}<x<\nicefrac{\pi}{2}$:\footnote{The syntax {\tt
[-pi/2:pi/2]} can also be written {\tt [-pi/2 to pi/2]}.}

\begin{verbatim}
truncated_cos(x)[-pi/2:pi/2] = cos(x)
\end{verbatim}

\noindent Attempts to evaluate this function outside of the range in which it
is defined would return an error that the function is not defined at the
requested argument value. Thus, if the above function were to be plotted, no
line would be drawn outside of the range
$-\nicefrac{\pi}{2}<x<\nicefrac{\pi}{2}$. A similar effect could also have been
achieved using the {\tt select} keyword (see
Section~\ref{sec:select_modifier}). Sometimes, however, the desired behaviour
is rather that the function should be zero outside of some region of parameter
space where it has a finite value. This can be achieved as in the following
example:

\begin{verbatim}
f(x) = 0
f(x)[-pi/2:pi/2] = cos(x)
\end{verbatim}

\noindent Plotting this function would yield the following result:

\begin{center}
\includegraphics[width=8cm]{examples/eps/ex_intro_func_splice}
\end{center}

\noindent To produce this function, we have made use of the fact that if there
is an overlap in the domains of validity of multiple definitions of a function,
then later declarations are guaranteed take precedence. The definition that the
function equals zero is valid everywhere, but is overridden in the region
$-\nicefrac{\pi}{2}<x<\nicefrac{\pi}{2}$ by the second function definition.

Where functions have been spliced together, the {\tt show functions} command
will show all of the definitions of the spliced function, together with the
regions of parameter space in which they are used. This is indicated using the
same syntax that is used for defining spliced functions, such that the output can
be stored and pasted into a future Pyxplot session to redefine exactly the same
spliced function.

When a function takes more than one argument, multiple ranges can be specified,
one for each argument. Any of the limits can be left blank if there is no
upper or lower limit upon the value of that particular argument. In the
following example, the function {\tt f(a,b,c)} would only be defined when all
of {\tt a}, {\tt b} and {\tt c} were in the range $-1 \to 1$:

\begin{verbatim}
f(a,b,c)[-1:1][-1:1][-1:1] = a+b+c
\end{verbatim}

Function splicing can be used to define functions which do not have analytic
forms, or which are, by definition, discontinuous, such as top-hat functions or
Heaviside functions. The following example would define $f(x)$ to be a
Heaviside function:

\begin{verbatim}
f(x) = 0
f(x)[0:] = 1
\end{verbatim}

Similar effects may also be achieved using the ternary conditional {\tt ?:}
operator (see Section~\ref{sec:conditional_operator}), for example:

\begin{verbatim}
f(x) = (x>0) ? 1 : 0
\end{verbatim}

\example{ex:funcsplice2}{Modelling a physics problem using a spliced function}{
\noindent{\bf Question}\newline\noindent
A light bead is free to move from side to side between two walls which are
placed at $x=-2l$ and $x=2l$. It is connected to each wall by a light elastic
string of natural length $l$, which applies a force $k\Updelta x$ when extended
by an amount $\Updelta x$, but which applies no force when slack. What is the
total horizontal force on the bead as a function of its horizontal position $x$?
\nlscf
\noindent{\bf Answer}\newline\noindent
This system has three distinct regimes. In the region $-l<x<l$, both strings
are under tension. When $x<-l$, the left-hand string is slack, and only the
right-hand string exerts a force. When $x>l$, the converse is true: only the
left-hand string exerts a force. The case $|x|>2l$ is not possible, as the bead
would have to penetrate the hard walls. It is left as an exercise for the
reader to use Hooke's Law to derive the following expression, but in summary,
the force on the bead can be defined in Pyxplot as:
\nlscf
\input{examples/tex/ex_funcsplice2_1.tex}
\nlscf
\noindent where it is necessary to first define a value for {\tt l} and {\tt
k}. Plotting these functions yields the result:
\nlscf
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_funcsplice2}
\end{center}
\nlscf
Attempting to plot this function with an {\tt x}-axis which extends outside of
the range of values of $x$ for which $F(x)$ is defined, as above, will result
in error messages being returned that the function could not be evaluated at
all argument values. These can be suppressed by typing (see
Section~\ref{sec:num_errs})\vspace{2mm}
\newline\noindent {\tt set numeric errors quiet}
}

\example{ex:funcsplice}{Using a spliced function to calculate the Fibonacci numbers}{
The Fibonacci numbers are defined to be the sequence of numbers in which each
member is the sum of its two immediate predecessors, and the first three
members of the sequence are ${0,1,1}$. Thus, the sequence runs
${0,1,1,2,3,5,8,13,21,34,55,...}$. In this example, we use function splicing to
calculate the Fibonacci sequence in an iterative and highly inefficient way,
hard-coding the first three members of the sequence and then using the
knowledge that all of the subsequent members are the sums of their two
immediate predecessors:

\nlscf
\input{examples/tex/ex_funcsplice_1.tex}
\nlfcf
This method is highly inefficient because each evaluation spawns two further
evaluations of the function, and so the number of operations required to
evaluate {\tt f(x)} scales as $2^x$.  It is inadvisable to evaluate it for
$x\gtrsim25$ unless you're prepared for a long wait.
\nlnp
A much more efficient method of calculating the Fibonacci numbers is to use Binet's formula,
\begin{displaymath}
f(x) = {\psi^x - (1-\psi)^x}{\sqrt{5}},
\end{displaymath}
where $\psi=1+\sqrt{5}/2$ is the golden ratio, which provides an analytic
expression for the sequence.  In the following script, we compare the values
returned by these two implementations. We enable complex arithmetic as Binet's
formula returns complex numbers for non-integer values of $x$.
\nlscf
\input{examples/tex/ex_funcsplice_2.tex}
\nlscf
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_funcsplice}
\end{center}
}

\section{Handling numerical errors}
\label{sec:num_errs}
\index{numerical errors}

By default, an error message is returned whenever calculations return values
which are infinite, as in the case of {\tt 1/0}, or when functions are
evaluated outside the domain of parameter space in which they are defined, as
in the case of {\tt besseli(-1,1)}.  Sometimes this behaviour is desirable: it
flags up to the user that a calculation has gone wrong, and exactly what the
problem is.  At other times, however, these error messages can be undesirable
and may lead you to miss more genuine and serious errors buried in their midst.

For this reason, the issuing of explicit error messages when calculations
return non-finite numeric results can be switched off by typing:
\indcmd{set numeric errors quiet}

\begin{verbatim}
set numeric errors quiet
\end{verbatim}

\noindent Having done this, expressions such as

\begin{verbatim}
x = besseli(-1,1)
\end{verbatim}

\noindent fail silently, and variables which contain non-finite numeric results
are displayed as {\tt NaN}\index{NaN}, which stands for {\it Not a
Number}\index{not a number}.  The issuing of explicit errors may subsequently
be re-enabled by typing: \indcmd{set numeric errors explicit}

\begin{verbatim}
set numeric errors explicit
\end{verbatim}

Having turned off the display of numerical errors, it may be useful to use the
\indcmdt{assert} to throw an error message if a calculation has failed in an
unrecoverable way that the user really ought to know about:

\begin{verbatim}
assert x>0 "Cannot continue with negative x"
\end{verbatim}

The {\tt assert} command should be followed by an algebraic expression which
must be true for execution to continue. If it is false, an error results.
Optionally, an error message can be included, as above, to tell the user what
the problem is.

\section{Working with complex numbers}
\label{sec:complex_numbers}
\index{complex numbers}

In all of the examples given thus far, algebraic expressions have only been
allowed to return real numbers: Pyxplot has not been handling any complex
numbers. Since there are many circumstances in which the data being analysed
may be known for certain to be real, complex arithmetic is disabled in Pyxplot
by default.  Expressions such as {\tt sqrt(-1)} will return either an error or
{\tt NaN}.  The most obvious example of this is the built-in variable {\tt i},
which is set to equal {\tt sqrt(-1)}:

\vspace{3mm}
\noindent\texttt{pyxplot> \textbf{print i}}\newline
\noindent\texttt{nan}
\vspace{3mm}

Complex arithmetic may be enabled by typing
\indcmd{set numeric complex}

\begin{verbatim}
set numeric complex
\end{verbatim}

\noindent and then disabled again by typing
\indcmd{set numeric real}

\begin{verbatim}
set numeric real
\end{verbatim}

\noindent Once complex arithmetic has been enabled, many of Pyxplot's built-in
mathematical functions accept complex input arguments, including the logarithm
function, all of the trigonometric functions, and the exponential function.  A
complete list of functions which accept complex inputs can be found in
Appendix~\ref{ch:function_list}.

Complex number literals can be entered into algebraic expressions in either of
the following two forms:

\begin{verbatim}
print (2 + 3*i       )
print (2 + 3*sqrt(-1))
\end{verbatim}

\noindent The former version depends upon the pre-defined system variable {\tt
i} being defined to equal $\sqrt{-1}$. The user could cause this to stop working,
of course, by re-defining this variable to have a different value.  However, in
this case the variable {\tt i} could straightforwardly be returned to its
default value by typing:

\begin{verbatim}
i=sqrt(-1)
\end{verbatim}

\noindent The user can, of course, define any other variable to equal
$\sqrt{-1}$, thus allowing him to use any other letter, e.g.\ {\tt j}, to
represent the imaginary component of a number.

Several built-in functions are provided for manipulating complex numbers. The
\indfunt{Re(z)} and \indfunt{Im(z)} functions return respectively the real and
imaginary parts of a complex number $z$. The \indfunt{arg(z)} function returns
the complex argument of $z$. And the \indfunt{abs(z)} function returns the
modulus of $z$.  The \indfunt{conjugate(z)} command returns the complex
conjugate of $z$. The following lines of code demonstrate the use of these
functions:

\vspace{3mm}
\input{fragments/tex/calc_complex.tex}
\vspace{3mm}

\section{Working with physical units}
\label{sec:units}
\index{physical units}\index{units}

Pyxplot, and all its mathematical functions, have native support for numbers to
have physical units. This means, for example, that multiplying two lengths
yields an area, and taking passing a selection of lengths to the {\tt max(...)}
function returns the longest of the lengths supplied.

This makes it a powerful desktop tool for converting measurements between
different systems of units -- for example, between imperial and metric units --
or for doing physical calculations.

The special function \indfunt{unit()} is used to specify the physical unit
associated with a quantity. For example, the expression

\begin{verbatim}
print 2*unit(s)
\end{verbatim}

\noindent takes the number~2 and multiplies it by the unit {\tt s}, which is
the SI abbreviation for seconds. Technically, the function {\tt unit(s)}
returns a numeric object equal to one second.

The resulting quantity above, which has dimensions of time, could then, for
example, be divided by the unit {\tt hr} to find the dimensionless number of
hours in two seconds:

\begin{verbatim}
print 2*unit(s)/unit(hr)
\end{verbatim}

Compound units such as miles per hour, which is defined in terms of two other
units, can be used as in

\begin{verbatim}
print 2*unit(miles/hour)
\end{verbatim}

\noindent In many cases, commonly-used units such units have their own explicit
abbreviations, in this case {\tt mph}:

\begin{verbatim}
print 2*unit(mph)
\end{verbatim}

\noindent As these examples demonstrate, the {\tt unit()} function can be
passed a string of units either multiplied together with the {\tt *} operator,
or divided using the {\tt /} operator. Units may be raised to powers with the
{\tt **} operator\footnote{The {\tt \^{}} character may be used as an alias for
the {\tt **} operator, though this notation is arguably confusing, since the
same character is used for the binary exclusive or operator in Pyxplot's normal
arithmetic.}, as in the example:

\vspace{3mm}
\input{fragments/tex/calc_units.tex}
\vspace{3mm}

\noindent As the examples above have demonstrated, units may be referred to by
either their abbreviated or full names, and each of these may be used in either
their singular or plural forms. For example, {\tt s}, {\tt second}, and {\tt
seconds} are all valid and equivalent. A complete list of all of the units
which Pyxplot recognises by default, together with all of their recognised
names, can be found in Appendix~\ref{ch:unit_list}.

SI units may be preceded with SI prefixes\index{units!SI prefixes}, as in
the examples\footnote{As the first of these examples demonstrates, the letter
{\tt u} is used as a Roman-alphabet substitute for the Greek letter $\upmu$.}:

\begin{verbatim}
a = 2*unit(um)
a = 2*unit(micrometers)
\end{verbatim}

When quantities with physical units are substituted into algebraic expressions,
Pyxplot automatically checks that the expression is dimensionally correct
before evaluating it. For example, the following expression is not
dimensionally correct and would return an error because the first term in the
sum has dimensions of velocity, whereas the second term is a length:
\index{units!dimensional analysis}

\begin{dontdo}
a = 2*unit(m)\newline
b = 4*unit(s)\newline
print a/b + a
\end{dontdo}

\noindent Pyxplot continues to throw an error in this case, even when explicit
numerical errors are turned off with the \indcmdt{set numeric errors quiet},
since it is deemed a serious error: the above expression would never be correct
for any values of {\tt a} and {\tt b} given their dimensions.

A large number of units are pre-defined in Pyxplot by default, a complete list
of which can be found in Appendix~\ref{ch:unit_list}.  However, the need may
occasionally arise to define new units. It is not possible to do this from an
interactive Pyxplot terminal, but it is possible to do so from a configuration
script which Pyxplot runs upon start-up. Such configuration scripts will be
discussed in Chapter~\ref{ch:configuration}. New units may either be derived
from existing SI units, alternative measures of existing quantities, or
entirely new base units such as numbers of CPU cycles or man-hours of labour.

\subsection{Treatment of angles in Pyxplot}
\label{sec:angles}
\index{units!angle}\index{angles, handling of}

There are a small number of cases where Pyxplot's handling of units does not
completely follow normal (i.e.\ SI) conventions, which require further
explanation. The most obvious such case is its handling of angles.

By convention, the SI system of units does not have a base unit of angle:
instead, the radian is considered to be a dimensionless unit.  There are some
strong mathematical reasons why this makes sense, since it makes it possible to
write equations such as
\begin{displaymath}
d=\theta r
\end{displaymath}
and
\begin{displaymath}
x = \exp(a+i\theta),
\end{displaymath}
which would otherwise have to be written as, for example,
\begin{displaymath}
d=2\pi\left(\frac{\theta}{2\pi\,\mathrm{rad}}\right) r=\left(\frac{\theta}{\mathrm{rad}}\right) r
\end{displaymath}
in order to be strictly dimensionally correct.

However, it also has some disadvantages since some physical quantities such as
fluxes per steradian are measured per unit angle or per unit solid angle, and
the SI system traditionally\footnote{Radians are sometimes treated in the SI
system as {\it supplementary} or derived units.} offers no way to dimensionally
distinguish these from one another or from quantities with no angular
dependence.  In addition, many of Pyxplot's vector graphics commands take
rotation angles as inputs, and it is useful to express these in units of angle.

In most cases, the user is free to decide whether angles should have units. All
of the following print statements are equivalent:

\begin{verbatim}
print sin(pi)
print sin(180*unit(deg))
print sin(pi *unit(rad))
print sin(0.5*unit(rev))
\end{verbatim}

However, it is useful to be able to define whether inverse trigonometric
functions such as {\tt asin(x)} and {\tt atan(x)} return results with units of
angle, or which are dimensionless. By default, these functions return
dimensionless results, but this may be changed using the commands:

\begin{verbatim}
set unit angle dimensionless
set unit angle nodimensionless
\end{verbatim}

\noindent Note that even when inverse trigonometric functions are set to return
dimensionless outputs, expressions such as {\tt unit(rad)+1} are still
dimensionally incorrect. Functions such as {\tt sin(x)} and {\tt exp(x)}
can always accept inputs which are either dimensionless, or have units of
angle.

\subsection{Converting between different temperature scales}
\index{temperature conversions}\index{units!temperature}

Pyxplot can convert temperatures between different temperature scales, for
example between $^\circ\mathrm{C}$, $^\circ\mathrm{F}$ and K.  However, these
conversions have some subtleties which are unique to temperature conversions.
This means they should be used with some caution.

Consider the following two questions:
\begin{itemize}
\item How many Kelvin corresponds to a temperature of $20^\circ$C?
\item How many Kelvin corresponds to a temperature {\it rise} of $20^\circ$C?
\end{itemize}
The answers to these two questions are 293\,K and 20\,K respectively: although
we are converting from $20^\circ$C in both cases, the corresponding number of
Kelvin depends whether we are talking about an {\it absolute} temperature
or a {\it relative} temperature. A heat capacity of 1\,J/$^\circ$C equals
1\,J/K, even though a temperature of $1^\circ$C does not equal a temperature of
1\,K.

The cause of this problem, and the reason why it rarely affects any physical
units other than temperatures is that there exists such a thing as absolute
temperature.

Take the example of distances. Distances are almost always relative: they
measure distance gaps between points. Occasionally people might choose to
express positions as distance from some particular origin. But if scheme A
involved measuring in meters from New York, and scheme B involved measuring in
feet from Chicago, they wouldn't expect Pyxplot to convert between the two
systems.

The problem of converting between temperature systems is just like this. One
system measures distance in degrees Fahrenheit away from 0$^\circ\mathrm{F}$;
another the distance in degrees Celsius away from
0$^\circ\mathrm{C}$.\footnote{There is one other common example of this
problem. Times are expressed as absolute quantities when dates are written
down. The year {\footnotesize AD}\,1453 implicitly corresponds to a period of
1453 years after the Christian epoch. So, similar problems arise when trying to
convert such a year into the Muslim calendar, which counts from the year
{\footnotesize AD}\,622. Pyxplot can, incidentally, make this conversion, using
date objects, as will be seen in Section~\ref{sec:time_series}.}

As Pyxplot cannot distinguish between absolute and relative temperatures, it
takes a safe approach of performing algebra consistently with any unit of
temperature, never performing automatic conversions between different
temperature scales. A calculation based on temperatures measured in
$^\circ\mathrm{F}$ will produce an answer measured in $^\circ\mathrm{F}$.
However, as converting temperatures between temperature scales is a useful task
which is often wanted, this is allowed, when specifically requested, in the
specific case of dividing one temperature by another unit of temperature to get
a dimensionless number, as in the following example:

\begin{dodo}
print 98*unit(oF) / unit(oC)
\end{dodo}

\noindent Note that the two units of temperature must be placed in separate
{\tt unit(...)} functions. The following is not allowed:

\begin{dontdo}
print 98*unit(oF / oC)
\end{dontdo}

Note that such a conversion always assumes that the temperatures supplied are
{\bf absolute} temperatures. Pyxplot has no facility for converting relative
temperatures between different scales. This must be done manually.

The conversion of derived units of temperature, such as $\mathrm{J}/\mathrm{K}$
or $^\circ\mathrm{C}^2$, to derived units of other temperature scales, such as
$\mathrm{J}/^\circ\mathrm{F}$ or $\mathrm{K}^2$, is not permitted, since in
general these conversions are ill-defined.

The moral of this story is: pick what unit of temperature you want to work in,
convert all of your temperatures to that scale, and then stick to it.

\example{ex:temperature}{Creating a simple temperature conversion scale}{
In this example, we use Pyxplot's automatic conversion of physical units to
create a temperature conversion scale.
\nlscf
\input{examples/tex/ex_tempscale_1.tex}
\nlscf
\begin{center}
\includegraphics{examples/eps/ex_tempscale}
\end{center}
}

\section{Configuring how numbers are displayed}
\label{sec:unitdisp}

\subsection{Display of physical units}

When displaying quantities that have physical units, Pyxplot searches through
its database of known units looking for the most appropriate unit, or
combination of units, to use.  By default, SI units, or combinations of SI
units, are chosen for preference, and SI prefixes such as milli- or kilo- are
applied where appropriate. This behaviour can, however, be extensively
configured.

The most general configuration option allows one of several {\it units
schemes}\index{units!unit schemes} to be selected, each of which comprises a
list of units which are deemed to be members of the particular scheme. For
example, in the CGS unit scheme\index{CGS units}\index{units!CGS}, all lengths
are displayed in centimeters, all masses are displayed in grammes, all energies
are displayed in ergs, and so forth.  In the imperial unit
scheme\index{imperial units}\index{units!imperial}, quantities are displayed in
British imperial units -- inches, pounds, pints, and so forth. In the US unit
scheme, US customary units are used. The current unit scheme can be changed
using the \indcmdt{set unit scheme}:

\vspace{3mm}
\input{fragments/tex/calc_numdisp.tex}
\vspace{3mm}

\noindent A complete list of Pyxplot's unit schemes can be found in
Table~\ref{tab:unit_schemes}.\index{natural units}\index{units!natural}

\begin{table}
\begin{center}
\begin{tabular}{|>{\columncolor{LightGrey}}l>{\columncolor{LightGrey}}p{9cm}|}
\hline
{\bf Name} & {\bf Description} \\
\hline
{\tt ancient} & Ancient units, especially those used in the Authorised Version of the Bible. \\
{\tt CGS} & CGS units. \\
{\tt Imperial} & British imperial units. \\
{\tt Planck} & Planck units, also known as natural units, which make several physical constants equal unity. \\
{\tt SI} & SI units. \\
{\tt US} & US customary units. \\
\hline
\end{tabular}
\end{center}
\caption{A list of Pyxplot's unit schemes.}
\label{tab:unit_schemes}
\end{table}

These units schemes are often sufficient to ensure that most quantities are
displayed in the desired units, but commonly there are a few specific
quantities in any particular piece of work where non-standard units are used.
For example, a study of Jupiter-like planets might express masses in Jupiter
masses, rather than kilograms. A study of the luminosities of stars might
express powers in units of solar luminosities, rather than watts. And a
cosmology paper might express distances in megaparsecs. This level of control is
made available through the \indcmdt{set unit of}. The three examples just given
could be achieved using the following commands:
\begin{verbatim}
set unit of mass Mjupiter
set unit of power solar_luminosity
set unit of length parsec
\end{verbatim}

An astronomer wishing to express masses in Pluto masses would need to first
define the Pluto mass as a user-defined unit, since it is not pre-defined unit
within Pyxplot. In Chapter~\ref{ch:configuration}, we shall see how to define
new units in a configuration script. Having done so, the following syntax would
be allowed:
\begin{verbatim}
set unit of mass Mpluto
\end{verbatim}

The \indcmdt{set unit preferred} offers a slightly more flexible way of
achieving the same result. Whereas the \indcmdt{set unit of} can only operate
on named quantities such as lengths, areas and powers, and cannot act upon
compound units such as {\tt W/Hz}, the \indcmdt{set unit preferred} can act
upon any unit or combination of units:
\begin{verbatim}
set unit preferred parsec
set unit preferred W/Hz
set unit preferred N*m
\end{verbatim}
The latter two examples are particularly useful when working with spectral
densities (powers per unit frequency) or torques (forces multiplied by
distances). Unfortunately, both of these units are dimensionally equal to
energies, and so are displayed by Pyxplot in joules by default. The above
statement overrides such behaviour. Having set a particular unit to be
preferred, this can be unset as in the following example:
\begin{verbatim}
set unit nopreferred parsec
\end{verbatim}

By default, units are displayed in their abbreviated forms, for example {\tt A}
instead of {\tt amperes} and {\tt W} instead of {\tt watts}. Furthermore, SI
prefixes such as milli- and kilo- are applied to SI units where they are
appropriate.\index{SI prefixes}\index{units!SI prefixes} Both of these
behaviours can be turned on or off, in the former case with the commands

\begin{verbatim}
set unit display abbreviated
set unit display full
\end{verbatim}

\noindent and in the latter case using the following pair of commands:

\begin{verbatim}
set unit display prefix
set unit display noprefix
\end{verbatim}

\subsection{Changing the accuracy to which numbers are displayed}

By default, when numbers are displayed, they are printed accurate to eight
significant figures, although fewer figures may actually be displayed if the
final digits are zeros or nines.

This is generally a helpful convention: Pyxplot's internal arithmetic is
generally accurate to around 16 significant figures, and so it is quite
conceivable that a calculation which is supposed to return, say, $1$, may in
fact return 0.999\,999\,999\,999\,999\,9. Likewise, when complex arithmetic is
enabled, routines which are expected to return real numbers may in fact return
results with imaginary parts at the level of one part in $10^{16}$.  By
displaying numbers to only eight significant figures in such cases, the user is
usually shown the `right' answer, instead of a noisy and unattractive one.

However, there may also be cases where more accuracy is desirable, in which
case, the number of significant figures to which output is displayed can be set
using the command\indcmd{set numerics sigfig}

\begin{verbatim}
n = 12
set numerics sigfig n
\end{verbatim}

\noindent where {\tt n} can be any number in the range 1-30. It should be noted
that the number supplied is the {\it minimum} number of significant figures to
which numbers are displayed; on occasion an extra figure may be displayed.

Alternatively, the string substitution operator, described in
Section~\ref{sec:stringsubop} may be used to specify how a number should be
displayed on a one-by-one basis, as in the examples:

\vspace{3mm}
\input{fragments/tex/calc_numsf.tex}

\subsection{Creating pastable text}
\label{sec:pastable}

Pyxplot's default convention of displaying numbers in a format such as

\begin{verbatim}
(2+3i) meters
\end{verbatim}

\noindent is well-suited for creating text which is readable by human users, but
is less well-suited for creating text which can be copied and pasted into
another calculation in another Pyxplot terminal, or for creating text which
could be used in a \latexdcf\ text label on a plot. For this reason, the
\indcmdt{set numerics display} allows the user to choose between three
different ways in which numbers can be displayed:

\vspace{3mm}
\input{fragments/tex/calc_numtype.tex}
\vspace{3mm}

The first case is the default way in which Pyxplot displays numbers. The second
case produces text which forms a valid algebraic expression which could be
pasted into another Pyxplot calculation. The final case produces a string of
\latexdcf\ text which could be used as a label on a plot.

\section{Numerical integration and differentiation}

\index{differentiation}\index{integration} Two special functions,
\indfunt{int\_dx()} and \indfunt{diff\_dx()}, may be used to integrate or
differentiate algebraic expressions numerically.  In each case, the letter {\tt
x} is the dummy variable which is to be used in the integration or
differentiation and may be replaced by any valid variable name of up to
16~characters in length.

The function {\tt int\_dx()} takes three parameters -- firstly the expression
to be integrated, which may optionally be placed in quotes, followed by the
minimum and maximum integration limits. These may have any physical dimensions,
so long as they match, but must both be real numbers. For example, the
following would plot the integral of the function $\sin(x)$:

\begin{verbatim}
plot int_dt('sin(t)',0,x)
\end{verbatim}

The function {\tt diff\_dx()} takes two obligatory parameters plus one further
optional parameter. The first is the expression to be differentiated, which,
as above, may optionally placed in quotes for clarity. This should be followed
by the numerical value $x$ of the dummy variable at the point where the
expression is to be differentiated. This value may have any physical
dimensions, and may be a complex number if complex arithmetic is enabled. The
final, optional, parameter to the {\tt diff\_dx()} function is an approximate
step size, which indicates the range of argument values over which Pyxplot
should take samples to determine the gradient. If no value is supplied, a value
of $10^{-6}x$ is used, replaced by $10^{-6}$ if $x=0$.  The following example
would evaluate the differential of the function $\cos(x)$ with respect to $x$
at $x=1.0$:

\begin{dodo}
print diff\_dx('cos(x)', 1.0)
\end{dodo}

When complex arithmetic is enabled, Pyxplot checks that the function being
differentiated satisfies the Cauchy-Riemann equations, and returns an error if
it does not, to indicate that it is not differentiable.  The following is an
example of a function which is not differentiable, and which throws an error
because the Cauchy-Riemann equations are not satisfied:

\begin{dontdo}
set num comp\newline
print diff\_dx(Re(sin(x)),1)
\end{dontdo}

Advanced users may be interested to know that \indfunt{int\_dx()} function is
implemented using the {\tt gsl\_\-integration\_\-qags()} function of the Gnu
Scientific Library\index{GSL} (GSL), and the \indfunt{diff\_dx()} function is
implemented using the {\tt gsl\_\-deriv\_\-central()} function of the same library.
Any caveats which apply to the use of these routines also apply to Pyxplot's
numerical calculus.

\example{ex:calculus}{Integrating the function $\mathrm{sinc}(x)$}{
The function $\mathrm{sinc}(x)$ cannot be integrated analytically, but it can be shown that
\begin{displaymath}
\int_0^{\pm\infty} \mathrm{sinc}(x)\,\mathrm{d}x = \pm\pi/2 .
\end{displaymath}
In the following script, we use Pyxplot's facilities for numerical integration to produce a plot of
\begin{displaymath}
y=\int_0^{x} \mathrm{sinc}(x)\,\mathrm{d}x .
\end{displaymath}
We reduce the number of samples taken along the abscissa axis to~80, as
evaluation of the numerical integral may be time consuming on older computers.
We use the \indcmdt{set xformat} (see Section~\ref{sec:set_xformat}) to demark
both the {\tt x}- and {\tt y}-axes in fractions of $\pi$:
\nlscf
\input{examples/tex/ex_integration_1.tex}
\nlscf
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_integration}}
}

\section{Solving systems of equations}

The \indcmdt{solve} can be used to solve systems of one or more simultaneous
equations numerically. It takes as its arguments a comma-separated list of the
equations which are to be solved, and a comma-separated list of the variables
which are to be found. The latter should be prefixed by the word {\tt
via}, to separate it from the list of equations:

\begin{verbatim}
solve <equation 1>, ... via <variable 1>, ...
\end{verbatim}

Note that the time taken by the solver dramatically increases with the number
of variables which are simultaneously found, whereas the accuracy achieved
simultaneously decreases. The following example solves a simple pair of
simultaneous equations of two variables:

\vspace{3mm}
\input{fragments/tex/calc_solve1.tex}
\vspace{3mm}

\noindent No output is returned to the terminal if the numerical solver
succeeds, otherwise an error message is displayed. If any of the fitting
variables are already defined prior to the {\tt solve} command's being called,
their values are used as initial guesses, otherwise an initial guess of unity
for each fitting variable is assumed. Thus, the same \indcmdt{solve} returns
two different values in the following two cases:

\vspace{3mm}
\input{fragments/tex/calc_solve2.tex}
\vspace{3mm}

\noindent In cases where any of the variables being solved for are not
dimensionless, it is essential that an initial guess with appropriate units be
supplied, otherwise the solver will try and fail to solve the system of
equations using dimensionless values:

\begin{dontdo}
x =\newline
y = 5*unit(km)\newline
solve x=y via x
\end{dontdo}

\begin{dodo}
x = unit(m)\newline
y = 5*unit(km)\newline
solve x=y via x
\end{dodo}

The \indcmdt{solve} works by minimising the squares of the residuals of all of the
equations supplied, and so even when no exact solution can be found, the best
compromise is returned. The following example has no solution -- a system of
three equations with two variables is over-constrained -- but Pyxplot
nonetheless finds a compromise solution:

\vspace{3mm}
\input{fragments/tex/calc_solve3.tex}
\vspace{3mm}

When complex arithmetic is enabled, the \indcmdt{solve} allows each of the
variables being fitted to take any value in the complex plane, and thus the
number of dimensions of the fitting problem is effectively doubled -- the real
and imaginary components of each variable are solved for separately -- as in
the following example:

\vspace{3mm}
\input{fragments/tex/calc_solve4.tex}
\vspace{3mm}

\section{Searching for minima and maxima of functions}

The \indcmd{minimize}\indcmd{maximize} {\tt minimize} and {\tt maximize}
commands can be used to find the minima or maxima of algebraic expressions. In
each case, a single algebraic expression should be supplied for optimisation,
together with a comma-separated list of the variables with respect to which it
should be optimised. In the following example, a minimum of the sinusoidal
function $\cos(x)$ is sought:

\vspace{3mm}
\input{fragments/tex/calc_min1.tex}
\vspace{3mm}

\noindent Note that this particular example doesn't work when complex
arithmetic is enabled, since $\cos(x)$ diverges to $-\infty$ at $x=\pi+\infty
i$.

Various caveats apply both to the {\tt minimize} and {\tt maximize} commands,
as well as to the {\tt solve} command.  All of these commands operate by
searching numerically for optimal sets of input parameters to meet the criteria
set by the user. As with all numerical algorithms, there is no guarantee that
the {\it locally} optimum solutions returned are the {\it globally} optimum
solutions. It is always advisable to double-check that the answers returned
agree with common sense.

These commands can often find solutions to equations when these solutions are
either very large or very small, but they usually work best when the solution
they are looking for is roughly of order unity.  Pyxplot does have mechanisms
which attempt to correct cases where the supplied initial guess turns out to be
many orders of magnitude different from the true solution, but it cannot be
guaranteed not to wildly overshoot and produce unexpected results in such
cases.  To reiterate, it is always advisable to double-check that the answers
returned agree with common sense.

\example{ex:eqnsolve}{Finding the maximum of a blackbody curve}{
When a surface is heated to any given temperature $T$, it radiates thermally.
The amount of electromagnetic radiation emitted at any particular frequency,
per unit area of surface, per unit frequency of light, is given by the Planck
Law:
\begin{displaymath}
B_\nu(\nu,T)=\left(\frac{2h^3}{c^2}\right)\frac{\nu^3}{\exp(h\nu/kT)-1}
\end{displaymath}
The visible surface of the Sun has a temperature of approximately
$5800\,\mathrm{K}$ and radiates in such a fashion. In this example, we use the
{\tt solve}, {\tt minimize} and {\tt maximize} commands to locate the frequency
of light at which it emits the most energy per unit frequency interval.  This
task is simplified as Pyxplot has a system-defined mathematical function {\tt
Bv(nu,T)} which evaluates the expression given above.
\nlnp
Below, a plot is shown of the Planck Law for $T=5800\,\mathrm{K}$ to aid in
visualising the solution to this problem:
\nlscf
\begin{center}
\includegraphics[width=\textwidth]{examples/eps/ex_eqnsolve}
\end{center}
\nlnp
To search for the maximum of this function using the \indcmdt{maximize}, we
must provide an initial guess to indicate that the answer sought should have
units of Hz:
\nlscf
\input{fragments/tex/calc_min2.tex}
\nlnp
This maximum could also be sought be searching for turning points in the
function $B_\nu(\nu,T)$, i.e.\ by solving the equation
\begin{displaymath}
\frac{\mathrm{d}B_\nu(\nu,T)}{\mathrm{d}\nu}=0.
\end{displaymath}
This can be done as follows:
\nlscf
\input{fragments/tex/calc_min3.tex}
\nlnp
Finally, this maximum could also be found using Pyxplot's built-in function {\tt Bvmax(T)}:\vspace{2mm}\newline
\input{fragments/tex/calc_min4.tex}
}

\section{Working with time-series data}
\label{sec:time_series}

Time-series data need to be handled carefully. If times and dates are specified
in local time, then conversions may be necessarily between timezones,
especially around the beginning and end of daylight saving time.

Even when this it not an issue, months have different lengths and leap years
have an extra day, which mean it is not straightforward to convert a series of
calendar dates into elapsed times between the \datapoint s.

On a more basic level, even time expressed in hours and minutes are complicated
by being expressed as non-decimal fractions of days.

To simplify the process of working with dates and times, Pyxplot has native
{\tt date} object type, together with pre-defined functions in the {\tt time}
module for creating and manipulating such objects.  A date object represents a
specific moment in time, and can be created from a time and date specified in
any arbitrary timezone. It is then possible to read out the time and date
components of this date object in any other arbitrary timezone.

The functions for creating {\tt date} objects are as follows:

\vspace{2mm}\noindent{\tt time.fromCalendar(year,month,day,hour,min,sec,<timezone>)}\vspace{2mm}

\noindent This function creates a date object from the specified calendar date.
It takes six compulsary numerical inputs: the year, the month number (1--12),
the day of the month (1--31), the hour of day (0--24), the number of minutes
(0--59), and the number of seconds (0--59). To enter dates before
{\footnotesize AD}\,1, a year of~$0$ should be passed to indicate
1\,{\footnotesize BC}, $-1$ should be passed to indicate the year
2\,{\footnotesize BC}, and so forth.

A timezone may optionally be specified as the final argument to the function.
If no timezone is specified, then the default is used, which may be set using
the {\tt set timezone} command. The timezone should be specified as a location string,
of the form {\tt Europe/London}, {\tt America/New\_York} or {\tt
Australia/Perth}, as used by the {\tt tz database}. A complete list of
available timezones can be found here:
\url{http://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.

Daylight saving time will be applied as appropriate for the specified location.
Note that strings such as {\tt GMT}, {\tt EDT} or {\tt CEST} are {\it not}
allowed as timezones; a {\it location} should be specified.

If universal time is used, the timezone may be specified as {\tt UTC}.

\vspace{2mm}\noindent{\tt time.fromUnix(t)}\vspace{2mm}

\noindent This function creates a date object from the specified numerical Unix time -- i.e.\ the number of seconds ellapsed since midnight on 1st January 1970 UTC.

\vspace{2mm}\noindent{\tt time.fromJD(t)}\vspace{2mm}

\noindent This function creates a date object from the specified numerical
Julian date.

\vspace{2mm}\noindent{\tt time.fromMJD(t)}\vspace{2mm}

\noindent This function creates a date object from the
specified numerical modified Julian date.

\vspace{2mm}\noindent{\tt time.now()}\vspace{2mm}

This function takes no arguments, returns a {\tt date} object corresponding to
the current system clock time, as in the following example:

\vspace{3mm}
\noindent\texttt{pyxplot> \textbf{print time.now()}}\newline
\noindent\texttt{Tue 2012 Sep 4 20:57:00 UTC}\newline
\noindent\texttt{pyxplot> \textbf{set timezone "America/Los\_Angeles"}}\newline
\noindent\texttt{pyxplot> \textbf{print time.now()}}\newline
\noindent\texttt{Tue 2012 Sep 4 13:57:41 PDT}\newline
\vspace{3mm}

Note that the date object created by the {\tt time.now()} function is identical
regardless of timezone, but it is {\it displayed} differently depending upon
the current timezone.

The following example creates a date object representing midnight on 1st
January 2000, in universal time, and in Western Australian time:

\vspace{3mm}
\input{fragments/tex/calc_date1.tex}
\vspace{3mm}

Once created, it is possible to add numbers with physical units of time to
dates, as in the following example:

\vspace{3mm}
\input{fragments/tex/calc_date3.tex}
\vspace{3mm}

Standard string representations of calendar dates can be produced with the {\tt
print} command.  It is also possible to use the string substitution operator,
as in {\tt "\%s"\%(date)}, or the {\tt str} method of {\tt date} objects, as in
{\tt date.str()}.

In addition, the {\tt time.string} function can be used to choose a custom
display format for the date, or to specify the timezone in which the date
should be displayed. Its arguments are as follows:

\vspace{2mm}\noindent{\tt time.string(t,<format>,<timezone>)}\vspace{2mm}

\noindent This function returns a string representation of the specified date object $t$. The second argument is optional, and may be used to control the format of the output. If no format string is provided, then the format \newline\noindent{\tt "\%a \%Y \%b \%d \%H:\%M:\%S \%Z"}\newline\noindent is used. In such format strings, the following tokens are substituted for various parts of the date:
\begin{longtable}{|>{\columncolor{LightGrey}}l|>{\columncolor{LightGrey}}l|}
\hline \endfoot
\hline
Token & Value \\
\hline \endhead
{\tt \%\%} & A literal \% sign.\\
{\tt \%a} & Three-letter abbreviated weekday name.\\
{\tt \%A} & Full weekday name.\\
{\tt \%b} & Three-letter abbreviated month name.\\
{\tt \%B} & Full month name.\\
{\tt \%C} & Century number, e.g. 21 for the years 2000-2099.\\
{\tt \%d} & Day of month.\\
{\tt \%H} & Hour of day, in range~00-23.\\
{\tt \%I} & Hour of day, in range~01-12.\\
{\tt \%k} & Hour of day, in range~0-23.\\
{\tt \%l} & Hour of day, in range~1-12.\\
{\tt \%m} & Month number, in range~01-12.\\
{\tt \%M} & Minute, in range~00-59.\\
{\tt \%p} & Either {\tt am} or {\tt pm}.\\
{\tt \%S} & Second, in range~00-59.\\
{\tt \%y} & Last two digits of year number.\\
{\tt \%Y} & Year number.\\
{\tt \%Z} & Timezone name (e.g. UTC, CEST, EDT). \\
\end{longtable}

The third argument is also optional, and specifies the timezone that the time
should be displayed in. As above, this should be specified in the form {\tt
Europe/London}, {\tt America/New\_York} or {\tt Australia/Perth}, as used by
the {\tt tz database}. A complete list of available timezones can be found
here: \url{http://en.wikipedia.org/wiki/List_of_tz_database_time_zones}.  If
universal time is used, the timezone may be specified as {\tt UTC}. If no
timezone is specified, the default is used as set in the {\tt set timezone}
command.

Several functions are provided for converting {\tt date} objects back into
various numerical forms of timekeeping and components of calendar dates, which
are listed below. Where appropriate, an optional timezone may be specified to
obtain a calendar date for a particular location:

\methdef{toDayOfMonth($<timezone>$)}{returns the day of the month of a date object in the current calendar.}
\methdef{toDayWeekName($<timezone>$)}{returns the name of the day of the week of a date object.}
\methdef{toDayWeekNum($<timezone>$)}{returns the day of the week (1--7) of a date object.}
\methdef{toHour($<timezone>$)}{returns the integer hour component (0--23) of a date object.}
\methdef{toJD()}{converts a date object to a numerical Julian date.}
\methdef{toMinute($<timezone>$)}{returns the integer minute component (0--59) of a date object.}
\methdef{toMJD()}{converts a date object to a modified Julian date.}
\methdef{toMonthName($<timezone>$)}{returns the name of the month in which a date object falls.}
\methdef{toMonthNum($<timezone>$)}{returns the number (1--12) of the month in which a date object falls.}
\methdef{toSecond($<timezone>$)}{returns the seconds component (0--60) of a date object, including the non-integer component.}
\methdef{toUnix()}{converts a date object to a Unix time.}
\methdef{toYear($<timezone>$)}{returns the year in which a date object falls in the current calendar.}

For example:

\vspace{3mm}
\input{fragments/tex/calc_date2.tex}
\vspace{3mm}

\subsection{Calendars}

By default, the {\tt time.fromCalendar} function makes a transition from the
old Julian calendar to the new Gregorian calendar at midnight on 14th~September
1752 (Gregorian calendar), when Britain and the British Empire switched
calendars.  Thus, dates between 2nd~September and 14th~September 1752 are not
valid input dates, since they days never occurred in the British calendar.

This behaviour may be changed using the \indcmdt{set calendar}, which offers a
choice of nine different calendars listed in Table~\ref{tab:calendars}. Most of
the these calendars differ only in the date on which the transition is made
between the old (Julian) calendar and the new (Gregorian) calendar.

The exceptions are the Hebrew and Islamic calendars, which have entirely
different systems of months.

\begin{table}
\begin{center}
\begin{tabular}{|>{\columncolor{LightGrey}}l|>{\columncolor{LightGrey}}p{9cm}|}
\hline
{\bf Calendar} & {\bf Description} \\
\hline
British &
Use the Gregorian calendar from 14th~September 1752 (Gregorian), and the Julian calendar prior to 2nd~September 1752 (Julian). \\
French &
Use the Gregorian calendar from 20th~December 1582 (Gregorian), and the Julian
calendar prior to 9th~December 1582 (Julian). \\
Greek &
Use the Gregorian calendar from 1st~March 1923 (Gregorian), and the Julian
calendar prior to 15th~February 1923 (Julian). \\
Gregorian &
Use the Gregorian calendar for all dates. \\
Hebrew &
Use the Hebrew (Jewish) calendar. \\
Islamic &
Use the Islamic (Muslim) calendar. Note that the Islamic calendar is undefined prior to 1st~Muharram {\footnotesize AH}\,1, corresponding to 18th~July {\footnotesize AD}\,622. \\
Julian &
Use the Julian calendar for all dates. \\
Papal &
Use the Gregorian calendar from 15th~October 1582 (Gregorian), and the Julian
calendar prior to 4th~October 1582 (Julian). \\
Russian &
Use the Gregorian calendar from 14th~February 1918 (Gregorian), and the Julian
calendar prior to 31st~January 1918 (Julian). \\
\hline
\end{tabular}
\end{center}
\caption{The calendars supported by the \protect\indcmdt{set calendar}, which can be
used to convert dates between calendar dates and Julian Day numbers.}
\label{tab:calendars}
\end{table}

Optionally, the \indcmdt{set calendar} can be used to set different calendars
to use when converting calendar dates into {\tt date} objects, and when
converting in the opposite direction. This is useful when converting data from
one calendar to another. The syntax used to do this is as follows:
\begin{verbatim}
set calendar in Julian     # only applies to time.fromCalendar()
set calendar out Gregorian # does not apply to time.fromCalendar()
set calendar in Julian out Gregorian   # change both
show calendar              # show calendars currently being used
\end{verbatim}

\example{ex:tolstoy}{Calculating the date of Leo Tolstoy's birth}{
The Russian novelist Leo Tolstoy was born on 28th~August~$1828$ and died on
7th~November~$1910$ in the Russian calendar. What dates do these correspond to
in the Western calendar?
\nlscf
\input{fragments/tex/calc_tolstoy.tex}
}

\subsection{Time intervals}

The time interval between two date objects can be found by subtracting one from
the other.  The following example calculates the time interval between Albert
Einstein's birth and death. The result is returned as a numerical object with
physical dimensions of time:

\vspace{3mm}
\input{fragments/tex/calc_date4.tex}
\vspace{3mm}

The function {\tt time.interval(t1,t2)} has the same effect.  The next example
calculate the time elapsed between the traditional date for the foundation of
Rome by Romulus and Remus in 753\,{\footnotesize BC} and that of the deposition
of the last Emperor of the Western Empire in {\footnotesize AD}\,476:

\vspace{3mm}
\input{fragments/tex/calc_interval.tex}
\vspace{3mm}

The function {\tt time.intervalStr()}\indfun{time.intervalStr({\it
t}$_1$,\-{\it t}$_2$,\-{\it format})} is similar, but returns a textual
representation of the time interval.  It takes an optional third parameter
which specifies the textual format in which the time interval should be
represented. If no format is supplied, then the following verbose format is
used:
\vspace{3mm}\newline
\noindent {\tt "\%Y years \%d days \%h hours \%m minutes and \%s seconds"}
\vspace{3mm}\newline
Table~\ref{tab:time_diff_string_subs} lists the tokens which are substituted
for various parts of the time interval. The following examples demonstrate the
use of the function:

\begin{table}
\begin{center}
\begin{tabular}{|>{\columncolor{LightGrey}}l|>{\columncolor{LightGrey}}l|}
\hline
Token & Substitution value \\
\hline
{\tt \%\%} & A literal \% sign.\\
{\tt \%d} & The number of days elapsed, modulo 365.\\
{\tt \%D} & The number of days elapsed. \\
{\tt \%h} & The number of hours elapsed, modulo 24.\\
{\tt \%H} & The number of hours elapsed.\\
{\tt \%m} & The number of minutes elapsed, modulo 60.\\
{\tt \%M} & The number of minutes elapsed.\\
{\tt \%s} & The number of seconds elapsed, modulo 60.\\
{\tt \%S} & The number of seconds elapsed.\\
{\tt \%Y} & The number of years elapsed.\\
\hline
\end{tabular}
\end{center}
\caption{Tokens which are substituted for various components of the time interval by the {\tt time\_diff\_string} function.}
\label{tab:time_diff_string_subs}
\end{table}

\vspace{3mm}
\input{fragments/tex/calc_interval2.tex}
\vspace{3mm}

\example{ex:timeseries}{A plot of the rate of downloads from an Apache webserver}{
In this example, we use Pyxplot's facilities for handling dates and times to
produce a plot of the rate of downloads from an Apache webserver based upon the
download log which it stores in the file {\tt /var/log/apache2/access.log}.
This file contain a line of the following form for each page or file requested
from the webserver:
\vspace{3mm}\newline\noindent{\tt\footnotesize 127.0.0.1 - - [14/Jun/2012:16:43:18 +0100] "GET / HTTP/1.1" 200 484 "-" "Mozilla/5.0 (X11; Linux x86\_64) AppleWebKit/535.19 (KHTML, like Gecko) Ubuntu/12.04 Chromium/18.0.1025.151 Chrome/18.0.1025.151 Safari/535.19"}\vspace{3mm}\newline
However, Pyxplot's default input filter for {\tt .log} files (see Section~\ref{sec:filters}) manipulates the dates in strings such as these into the form
\vspace{3mm}\newline\noindent{\tt\footnotesize 127.0.0.1 - -~~[~14~~6~~2012~16~43~18~+0100~]~~"GET~~~HTTP 1.1" 200 484 "-" "Mozilla/5.0 (X11; Linux x86\_64) AppleWebKit/535.19 (KHTML, like Gecko) Ubuntu/12.04 Chromium/18.0.1025.151 Chrome/18.0.1025.151 Safari/535.19"}\vspace{3mm}\newline
such that the day, month, year, hour, minute and second components of the date
are contained in the 5th to 10th white-space-separated columns respectively.
In the script below, the {\tt time.fromCalendar()} function and {\tt toUnix()} method are then used to convert
these components into Unix times. The \indcmdt{histogram} (see
Section~\ref{sec:histogram}) is used to sort each of the web accesses recorded
in the Apache log file into hour-sized bins.  Because this may be a
time-consuming process for large log files on busy servers, we use the
\indcmdt{tabulate} (see Section~\ref{sec:tabulate}) to store the data into a
temporary \datafile on disk before deciding how to plot it:
\nlscf
\input{examples/tex/ex_apachelog_1.tex}
\nlscf
Having stored our histogram in the file {\tt apache.dat}, we
now plot the resulting histogram, labelling the horizontal axis with the days
of the week.  The commands used to achieve this will be introduced in
Chapter~\ref{ch:plotting}. The major axis ticks along the horizontal axis are
placed at daily intervals, and minor axis ticks are placed along the axis every
quarter day, i.e.\ every six hours.
\nlscf
\input{examples/tex/ex_apachelog_2.tex}
\nlscf
The plot below shows the graph which results on a moderately busy webserver
which hosts, among many other sites, the Pyxplot website:
\nlscf
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_apachelog}}
}