Mplot++, what is it ?  And how does it work ?

Mplot++ is an interactive plotting program for Unix(R), Windows(R)
and MacOS X(R). Its graphical user interface is based on the
Fast Light Tool Kit, also named FLTK (you must read "fulltick"),
a light but powerfull and multi-platform graphical user interface toolkit.
Mplot++ lets the user diplay plots of bidimensional curves,
tridimensional curves and surfaces trough their parametric
equations. If in the plane (space) is assigned a couple ( a set
of three ) of cartesian axes, named x and y (and z), the
parametric equations of a curve describe the curve as the set
formed by the points (x(t),y(t)) ( or (x(t),y(t),z(t)) for a
tridimensional curve ) when the "time" parameter goes from a
value t1 to a value t2 > t1. Here x(t), y(t) and z(t) are
mathematic functions of the variable t.
For example, the parametric equations of the circle which has
its center in the point (0,0) of the cartesian plane and radius
equal to 1 are

	x(t) = cos(t)
	y(t) = sin(t),	with  0 <= t <= 2*PI,

because when t goes from 0 to 2*PI (PI = 3.14159...) the point
(sin(t), cos(t)) describes this circle as is done by the point
of a compass. Instead the parametric equations of the standard
parabola y=x^2  are

	x(t) = t
	y(t) = t^2,

because, when t goes from -oo to +oo, (x(t),y(t)) describes
the points and only the points ( of the plane ) belonging to
this curve.
More generally, given the function y=f(x), the graphic of f(x),
i.e. the set formed by the points (x,f(x)), has

	x(t) = t
	y(t) = f(t)

as its parametric equations.
If the domain of y=f(x) is given by the interval [a,b] ( a < b )
then in the previous equations t must be thought as a parameter
which goes from a to b.
The parametric equations of a surface describe the surface
as the set of the space formed by the points
(x(s,t),y(s,t),z(s,t)) when s and t go from s1 to s2 and from
t1 to t2 respectively, where s1 < s2  and  t1 < t2.
For example, the sphere which has its center in the point
(0,0,0) of the space and radius equal to 1 has

	x(s,t) = cos(s) * cos(t)
	y(s,t) = sin(s) * cos(t)
	z(s,t) = sin(t), with     0 <= s <= 2*PI  and
			      -PI/2 <= t <= PI/2,

as its parametric equations, because when s goes from 0 to
2*PI and t goes from -PI/2 to PI/2  the point
(x(s,t),y(s,t),z(s,t)) describes the entire sphere.
You must consider that 's' and 't' are, respectively, the
longitude and the latitude of the point (x(s,t),y(s,t),z(s,t)).
The parametric equations of the truncated paraboloid z= x^2+y^2,
where  a <= x <= b  and  c <= y <= d, are instead

	x(s,t) = s
	y(s,t) = t
	z(s,t) = s^2 + t^2

with  a <= s <= b  and  c <= t <= d.
More generally, given the function z=f(x,y), the parametric
equations of the graphic of this function over the rectangle
{ (x,y) / a <= x <= b,  c <= y <= d } are given by

	x(s,t) = s	    
	y(s,t) = t	 
	z(s,t) = f(s,t).

Be careful !  Because of the way Mplot++ was built, when
you will use it to display a bi- or tridimensional curve 
( like the graphic of a function y=f(x) ) you will have to
indicate by '?' the parameter 't'; when you will need to
plot a surface ( like the graphic of a function z=f(x,y) )
you will have to denote by '?' the parameter 's' and by '!'
the parameter 't' (or viceversa).
Mplot++ needs some other informations, besides the parametric equations,
to draw a bi-/tridimensional curve of surface.
First of all, you must specify what will be the "framed region", i.e. the
region of the plane or space that will be visualized by Mplot++.
Of course Mplot++ cannot display the entire cartesian plane/space
in a window but only a bounded region of it.
In the case of a bidimensional graphic this region is a rectangle and
you have to specify the coordinates x0 and y0 of the center of the rectangle
(i.e. the intersection of its diagonals) and its dimensions, width(w) and
height(h). In the case of a tridimensional graphic this region is
a sphere and you must specify the coordinates of its center (x0,y0,z0)
and its radius R. In any case, if you want to see completely the object,
curve or surface, you would like to plot then you must define the "framed 
region" in a such way that it can hold entirely this object.
If you do not this, the object will be visualized only partially or, in
the worst case, will not visualized at all.
In fact, Mplot++ lets you watch only the intersection of the object
to plot with the "framed region".
Be careful !  I have decided that the absolute value of the coordinates
x0, y0 (and z0 for 3D graphics) may not be greater than 1.0e+7 because
Mplot++ becomes less precise when you give to it very large values
for x0, y0 and z0. For the same reason, the dimensions or the radius
of the "framed region" can not be less than MIN_DIM (=0.01) and
greaters than MAX_DIM (=1.0e7): out of this range the graphics created
by Mplot++ could not be nices because there would be a lost of precision
in the drawing operations.
Again, the ratio between the radius or the smallest dimension of
the "framed region" and the largest value between abs(x0),abs(y0) and
abs(z0) (abs(x):= absolute value of x) can not be less than
MIN_DIMOCPC(=1.0e-6).
And, to terminate this topic, the aspect ratio between the dimensions
of the "framed region" in a bidimensional graphic can not be less
than MIN_AR (= 0.1) and greater than MAX_AR (=10).
Fortunately, Mplot++ will send to you a warning if you will give
unagreable values for x0,y0,z0,w,h or R and it will explain you what
is bad, i.e. what must be corrected.
Other two issues remain to deal.
First, you have to remember that Mplot++ needs to know what
is the interval of variation for each parameter that appears in the
parametric equations of the object to plot.
To be more precises, Mplot++ needs to know the lower limit and the upper
limit of the variation's interval of each parameter.
For example, if you want to visualize the 2D-curve having equations

    x(?) = cos(?)
    y(?) = sin(?),  0 <= ? <= 2*PI

( Remember!  Mplot++ wants that you use the characters '?' and '!'
  to indicate the parameters into a parametric equation. ),

you must tell to Mplot++ that 0 is the lower limit and 2*PI,
that can be approximated as 6.2832 (or 6.28, or 6.283 as you prefer),
is the upper limit of the interval of variation of '?'.
Mplot++ uses the symbols 'lb?' and 'ub?' (which means "lower bound
for ?" and "upper bound for ?" respectively) to indicate the lower
limit and the upper limit of the interval of variation of '?'.
Instead, if you want to plot a surface, like the sphere having equations

    x(?,!) = cos(?) * cos(!)
    y(?,!) = sin(?) * cos(!)
    z(?,!) = sin(!),

where '?' goes from 0 to 2*PI and '!' goes from -PI/2 to +PI/2, you must
specify the lower limit and the upper limit for the intervals of variation
of both parameters; they are 0 and 6.2832... for '?', -1.5708... and
+1.5708... for '!'.
Similarly to what happens for '?', Mplot++ uses the simbols 'lb!'
and 'ub!' to indicate the lower limit and the upper limit of the interval
of variation of '!'.
In any case, the width of the interval of variation of a parameter may
not exceed the value MAX_EXTVIPRM (= 2000).
Moreover, you must know that Mplot++ does not draw a curve or surface
directly, but first it approximates the object to draw by polygonals formed
by short segments and then it displays these polygonals in place of the
original object.
The user can control how Mplot++ does that by setting some parameters;
actually, because Mplot++ can not do anything automatically, the user
is obliged to set these parameters if he wants to visualize something; :)
so you must know what they are and how Mplot++ uses them.
Suppose that you want to display the curve having parametric equations:

	x(?) = ?
	y(?) = ?^2,

where t goes from -10 to 10. Mplot++ can not draw this curve directly;
so it divides the interval of variation of '?', in this case [-10,+10], into
a certain number of subintervals (having all the same width) and computes x(?)
and y(?) for the values of the parameter '?' corresponding to the extreme
points of these subintervals.
Then it visualizes, in place of the curve, the polygonal obtained by
connecting, in the right order, the points (x(?),y(?))
previous computed (a polygonal is a sequence of connected segments).
This polygonal is a good approximation of the curve, in the sense that
its shape is very similar to the shape of the original curve, if the
variation's interval of '?' is divided in a quite great number
of subintervals.
The user must give this number to Mplot++. Why ?  Because in this
way it can control directly the precision of the plot. Moreover,
Mplot++ can not know what can be a right value for this number.
Actually, the user is obliged to give not the number of subintervals
into which the interval of variation of '?' must be divided, but he has
to give the number of values of the parameter '?' for which Mplot++
must compute (x(?),y(?)).
These values will be taken equidistant by Mplot++.
The number of the values of the parameter '?' for which must be computed the
couple (x(?),y(?)) is indicated as 'n?'.
Let us return to the previous example. If you set 'n?' to the value 21
Mplot++ splits the interval [-10,+10] in 20 (= 21-1) subintervals
having all the same width, i.e. 1.
Then Mplot++ computes x(?) and y(?) for the values -10, -9, -8, ...,
-2, -1, 0, 1, 2, ..., 8, 9, 10, i.e. in the extreme points of the
subintervals into which [-10,+10] has been subdivided.
This points are called nodes of interpolation.
At the end, it displays the polygonal obtained by connecting, in this order,
the points (x(-10),y(-10)), (x(-9),y(-9)), ..., (x(0),y(0)), ...,
(x(9),y(9)), (x(10),y(10)).
Of course, 21 nodes of interpolation are too few if you want to have
a good plot; but you can set '?' to 200 or 2000. In this way the graphic
will turn out very precise.
In general, as more are the nodes as better it will be the precision
of the plot.
Perhaps you are wondering what happens when the object to visualize is a
surface. In this case we have 2 parameters, '?' and '!', and the user must
give to Mplot++ the number 'n?' of the values of the parameter '?' 
and the number 'n!' of those of the parameter '!' for which must be computed
the set (x(?,!), y(?.!), z(?,!)). Naturally,

    x = x(?,!)
    y = y(?,!)
    z = z(?,!)    ( a <= s <= b,  c <= t <= d ) 

are the parametric equations of the surface to display.
After obtaining the values 'n?' and 'n!' from the user, Mplot++
divides the interval of variation of '?' into n?-1  subintervals (having all
the same width) and the same does for the interval of variation of '!'
by using the value 'n!'.
In this way, a "lattice" (or grid) is fixed on the rectangular set

   { (s,t) where  a <= s <= b,  c <= t <= d },

Mplot++ computes (x(?,!), y(?.!), z(?,!)) for the values of '?' and '!'
corresponding to the nodes of the lattice and then it connects the computed
points by following the lines of the lattice.
Finally, it displays on the screen the result of these operations, that is
not the original surface but a set of crossed polygonals.
If 'n?' and 'n!' are quite greats, these polygonals form a shape similar
to the shape of the original surface.
Obviously, Mplot++ checks for the admissibility of the value(s) given
by the user for 'n?' ( and 'n!' ).
First, 'n?' and 'n!' cannot be less than 2; moreover, you must remember
that

1) If you are going to display a bidimensional curve, 'n?' may not
   be greater than MAX_NNOD_C2D  (= 12010);

2) If you are going to display a tridimensional curve, 'n?' may not
   be greater than MAX_NNOD_C3D  (= 4001);

3) If you are going to display a surface, the product 'n? * n!' may
   not be greater than MAX_NNOD_SF (= 5001).

Be careful !  If it is true that in 2D-graphic you can visualize up
to MAX_NC (= 10) curves, however you may not use different values of
'n?' for different curves. Moreover, what I told you before is not exact,
because it is the product of 'n?' for the number of the curves to
display that must remain less or equal to MAX_NNOD_C2D. Similarly,
you may not specify different values for the lower limit and the upper
limit of the variation's interval of the parameter '?'
(I am very sorry for this).

A last queerness: With Mplot++ the symbol '$' must be used to mean the
		  mathematical constant PI ( = 3.14159... ).

End of the Introduction
 
