\documentclass[revision-guide.tex]{subfiles}
%% Current Author: LT
\setcounter{chapter}{1}
\begin{document}
\chapter{Gravitational Fields}
\spec{recall and use the fact that the gravitational field strength g is equal to the force per unit mass and hence that weight W = mg}

A \textbf{field} is a region where a particle experiences a force. If this is applied to gravitation, then we can say that a
\textbf{gravitational} field is a region where a \textbf{mass}
experiences a force.

You can only tell if a field exists when it exerts a force on something.
It is a way of envisaging (seeing in your mind's eye) the size and the
direction of the force that would be exerted on a particle when placed
in that field.

A gravitational field is produced by anything with mass.

Therefore, a gravitational field is a way of envisaging what would
happen to a mass if it were placed in the field due to another mass.

The field is usually represented by lines which show both the
\textbf{direction} and \textbf{strength} of the field.

The \textbf{strength} of a gravitational field (the field strength) at
any point is the force felt \textbf{per unit mass} at that point. This
is a \textbf{definition.}

It can be written as a word equation:

Gravitational field strength at a point (N/kg)= Force felt by mass (measured
in Newtons)/Size of mass (measured in kilograms)

Or in symbols:

\[g = \frac{F}{m} \]

The force, F, felt by any object on the surface of the Earth due to the
gravitational field strength of the Earth is known as its
\textbf{weight.} It is given the symbol \textbf{W}.

This means that we can re-write equation above for the field strength at
the surface of the Earth by putting W instead of F.

\[g = \frac{W}{m}\]

This then rearranges to an equation that you have all seen before:

\[W = mg\]

Thus the weight of an object on the surface of the Earth is its mass
multiplied by the gravitational field strength g.

\spec{recall that the weight of a body appears to act from its centre of gravity}

The centre of gravity of an object is the point where the weight acts or
appears to act.

Thus, when you draw a free-body force diagram for any object in a
gravitational field, you draw \textbf{one} arrow from the centre of
gravity of the object to represent the force due to the field. On the
Earth this is, of course, the weight and the arrow points vertically
downwards.

\spec{sketch the field lines for a uniform gravitational field (such as near the surface of the Earth)}

A uniform field is a field where the field strength is the same at all
points in the field.

This means that for a gravitational field the force felt per unit mass
(see definition) is the same at all points.

The surface of the Earth is a very good approximation to a uniform
field.

Therefore if you draw a diagram of the Earth's gravitational field at
the Earth's surface over a small area, it will look like Figure \ref{fig:uniform-field}

\begin{figure}[!h]
	\begin{center}
		\includegraphics[width=\textwidth]{figs/chapt-2/uniform-field.pdf}
	\end{center}
	\caption{Uniform Field}
	\label{fig:uniform-field}
\end{figure}

As you can see, the field lines are \textbf{parallel} and
\textbf{evenly-spaced.} This is always the case for a uniform field.

\spec{explain the distinction between gravitational field strength and force and explain the concept that a field has independent properties.}

There is a very important distinction to make between
\textbf{gravitational field strength} and \textbf{force} at this point:
The field strength at any point is the same for all bodies in the field
and is the force felt per kilogram, but the force is different and
depends on the size of the mass there.

This is best illustrated with an example: If a mass of 60kg is in the
Earth's gravitational field at the surface of the Earth, then we can
calculate the force acting on it, its weight, using equation (3):

\[W = mg = \SI{60}{\kg} \times \SI{9.8}{\N\per\kg} = \SI{590}{\N}\]

So the force felt by the 60kg mass is 590N but the field strength for
the mass \textbf{and for any other mass} is 9.8Nkg\textsuperscript{-1}.
So the field strength is fixed by your position in the field and the
size of the mass that is exerting the field, and nothing else. The force
depends on the mass in the field as well.

\end{document}


\section{Library Architecture}

\subsection{Directory structure}

\subsubsection{\filename{doc} - Documentation}

The library is documented with an analysis paper for each
implementation module.  Trivial implementations are not
discussed, but significant algorithms and design tradeoffs
are explained in considerable detail.  The idea is to
demonstrate independent development of the {\em code}, when
working from published algorithms which may have associated
copyrighted code in their own right.

A collection of stand-alone PDFs, one for each module,
can be generated with \shell{make sections}.

\subsubsection{\filename{src} - Library sources}

The library is divided into simple mathematical types
(integer, float, \dots)
and composed ones (complex numbers, polynomials, \dots).
Each type has its own directory containing modules
which follow the same guidelines.
Let's have a look to some files from the \filename{vector}
directory to illustrate that:\\
\begin{tabular}{lp{0.75\hsize}}
\filename{Vector.ig}       & main type and basic operations
  that are imported from \filename{VectorRep},
  the interface is designed for maximum genericity. \\
\filename{Vector.mg}       & \\
\filename{VectorRep.ig}    & basic operations
  which work on arrays instead of references
  and thus are more robust and efficient to use -
  This module imports routines from
  either \filename{VectorBasic.ig}
  or \filename{VectorFast.ig} \\
\filename{VectorRep.mg}    & \\
\filename{VectorBasic.ig}  & routines that invoke
  the functional interface of the underlying field,
  the implementation is more generic and less efficient -
  Avoid calling this module directly,
  this will simplify changes in the implementation of this datatype. \\
\filename{VectorBasic.mg}  & \\
\filename{VectorFast.ig}   & routines that invoke
  built-in Modula 3 operations
  and thus are fast and compact -
  Avoid calling this module directly,
  this will simplify changes in the implementation of this datatype. \\
\filename{VectorFast.mg}   & \\
\filename{VectorFmtLex.ig} & formatting for output \\
\filename{VectorFmtLex.mg} & \\
\filename{m3makefile}      & quake code for this directory \\
\filename{vector.tmpl}     & quake templates for instantiating vectors of arbitrary types
\end{tabular}

The \filename{Fast} versions of some modules
was originally designed as workarounds for the missing
\sourcecode{<*INLINE*>} support of the known Modula 3 compilers.
In fact inlining is hard to implement in a compiler
so this pragma is accepted but ignored by all current
Modula 3 compilers.
Since these modules makes use of the infix operators
plus, minus, and so on,
they are instantiated for floating point types only.
Later they were also extended by specific numerical code.

Unfortunately it is not easy to find a module naming convention
that does not collide with existing standard modules
but guarants for easy usage.
E.g. the Modula 3 inventors suggested for each data structure
to put the main type along with common operations into one module.
E.g. there is a module called \filename{LongReal}
which contains type \sourcecode{T} and
some basic operations that allow the usage
of \sourcecode{LongReal}s as part of \sourcecode{List}s and so on.
But we need more basic operations
like addition, subtraction, multiplication \dots{}.
Thus I have created a new module with suffix \filename{Basic}.
Now the situation is that some modules have this suffix
and some have not.
This makes the handling of instantiation procedures
for \filename{quake} a nightmare.

\subsubsection{\filename{test} - Test suite}

The test suite is composed of a general driver and a
collection of test modules, one for each implementation
module.
Names of test modules are composed from the string \filename{Test}
and the type name, e.g. \filename{TestVector}.

\subsection{Module Templates}

For \filename{m3na/src} there are
\filename{template.i3} and \filename{template.m3} which can be instantiated
by copying to and then replacing \sourcecode{XYZ} with the new module name.

For \filename{m3na/test/src} there is \filename{template.m3}
which can be similarly copied and
edited to make new test modules.
Also, that template has a \sourcecode{PROCEDURE TestABC} template.

\subsection{Algebraic structures}
When considering a set of (mathematical) objects
with operations that can be applied to them
and the characteristics that the operations offer
we talk about an algebraic structure.
Most of the data types that are implemented here
are algebraically rings.
For composed data types it is important to know
the capabilities that are required for the element types.

The most common operations are:\\
\begin{tabular}{lp{0.7\hsize}}
\sourcecode{New}     & make one \\
\sourcecode{Copy}    & given one, make another one \\
\sourcecode{Lex}     & make one by reading a text string (not implemented yet) \\
\sourcecode{Fmt}     & use one to make a text string \\
\sourcecode{Compare} & relational operators (can be provided only by ordered types) \\
\sourcecode{Add},
\sourcecode{Sub},
\sourcecode{Mul}     & basic operations that are supported by most types \\
\sourcecode{DivMod}  & sometimes a division is not possible, but the decomposition into a sum of a product and a remainder is possible in some way in most cases
\end{tabular}

All functions allocate new memory for their results.
This allows for easy functional
without worrying about temporary results.
It requires more allocation and deallocation operations
and more temporary memory consumption
but I hope that the garbage collector
can handle this efficiently.
This technique is more safe
because you can consider most datatypes as immutable,
that is the content of an object is not changed,
which removes the problems with functions with side effects.

In many cases the operations have neutral elements:\\
\begin{tabular}{lp{0.7\hsize}}
\sourcecode{Zero} & such that for all x holds \sourcecode{Add(Zero,x)=x} \\
\sourcecode{One}  & such that for all x holds \sourcecode{Mul(One,x)=x}
\end{tabular}

\subsection{Naming}

Some rules for chosing identifiers:
\begin{enumerate}
\item The main type is called \sourcecode{T} and
the module gets the name of the implemented data type.
Using qualified identifiers like \varid{Module}\sourcecode{.T}
makes clear what \sourcecode{T} actually means.
This follows the conventions of \filename{libm3}
and thus allows for generic templates.
\item Procedure names start with a capital letter.
\item Procedure arguments are mostly named
 \sourcecode{x}, \sourcecode{y} for easy Cut\&Copy.
\item When writing new procedures,
 look for similar ones in other modules
 for adapting argument order and naming.
\end{enumerate}

\subsection{Quake}

The \filename{quake} utility which is the counterpart
to \filename{make} for Modula 3
is a central part of current Modula 3 compiler packages.
Without \filename{quake} it would be a nightmare
to work with generic modules,
since quake generates and incorporates
modules that instantiate generic ones for you.
Every data type in the \modna{} library
is equipped with \filename{quake} procedures
stored in \varid{type}\filename{.tmpl} files.
that instantiate the data type for new element types.
It is important to respect some conventions
when writing generic modules and
corresponding \filename{quake} procedures.
\begin{itemize}
\item Module names contain almost no abbreviations for clarity.
Names of instantiated modules can become rather long, so abbreviate them when importing.
\item Names of instantiated modules follow a fixed scheme
to provide for automatic file name generation.
It also allows you to easily remember the name of such a module.
The main name is the last part, each element name is prepended.
E.g. \filename{BigIntegerFractionPolynomial}
operates on polynomials which have coefficients
that are fractions of integers of arbitrary size.
\item The instantiating helpers from \filename{libm3}
expect the specification of all element modules,
e.g. \sourcecode{Table(key,elt)}.
This was the approach for \modna{}, too, for some time,
but it turned out to be to expensive.
Instead only the element names are given
and additionally arguments specifying the flavor
of some modules (like \filename{"Fast"} or \filename{"Basic"}).
The \filename{quake} template procedures
internally constructs the filenames of all required modules.
Be prepared to build additional modules
to match all requirements.

It is possible to give a name that differs from
the long naming scheme,
e.g. calling a module \filename{BigIntFracPolynomial}
instead of the long form.
However it is not recommend to break the scheme
since it makes further instantiating even worse.
\item Abbreviate generic formals and imported modules following the same scheme.
Each name component is abbreviated with a beginning capital and
maybe following lowercase letters.
Neglict implementation extensions like \filename{Fast} and \filename{Basic}.
Examples:
\begin{itemize}
\item \sourcecode{LongRealBasic AS R}
\item \sourcecode{LongRealTrans AS RT}
\item \sourcecode{LongRealFmtLex AS RF}
\item \sourcecode{RootBasic AS Rt}
\item \sourcecode{Vector AS V}
\item \sourcecode{ComplexVector AS CV}
\item \sourcecode{ComplexVectorFmtLex AS CVF}
\end{itemize}
\item Generic formals should be ordered in increasing complexity.
That is simple types first,
other types that have the first type as element follows and so on.
Modules that add other functionality to the same type
are placed immediately after the basic module.
Example:
\sourcecode{GENERIC INTERFACE Mighty(R,RT,RF,C,CT,CF,V,VF,CV,M,MF);}
\end{itemize}

Remark: (where is a good place for it?)\\
Don't rely on order of RECORD entries,
e.g. in TexStyle, FmtStyle,
but access them by name.

Avoid VAR parameters for output of results,
because the user has to provide dummy variables,
if he doesn't need the result.
Furthermore VAR paramaters don't make clear
that it is only a result.
Use RECORD results instead,
see \sourcecode{DivMod} for example.

\subsection{Arrays}
An array is a collection of items, all of the same type,
which can be accessed by an index into the array.
Array types can be distinguished by their cell type.
Further on they could be distinguished by their meaning.
For example, a Vector is not really a general purpose array --
Instead, it supports certain operations such as a dot product.
Similarly, a polynomial might be stored in an array,
but it has specific operations such as evaluation,
or differentation.

We could distinguish these special uses of arrays by
BRANDing them.  (I [HGG] tried that for a while.)
But it is convenient to allow structural type matching,
so that one "Fmt" command works for simple arrays
as well as Vectors and rows of Matrices.
Therefore all these types are being implemented as arrays.
Modula-3 provides several ways to
implement the concept of an array.
We are generally using dynamic arrays.
There is (or may be) some overhead for
dynamic linking, and some for allocation,
but the payoff in readability is high.

In a few cases (e.g., interpolation tables),
we can expect the array to be static or constant.
So the appropriate formal is an open array.
If a dynamic array happens to be used as the actual parameter,
it can be dereferenced prior to the call:

\begin{tt} \begin{verbatim}
     y:=LongRealInterpolation.Linear(xarr^,yarr^,x);
\end{verbatim} \end{tt}

Modula-3's dynamic arrays only range 0..n-1.
But many matrix notations call for 1..n or
perhaps some offset into the array.
The zero-based indexing has proven to be the most universal.
There is no support for other schemes.