		      User Manual for 3D Magnetico

				INDEX


	      (1) - Introduction
	      1.1 - What is Magnetico3D
	      1.2 - Minimum requisits for running Magnetico3D
	      1.3 - Advised requisits for running Magnetico3D
	      1.4 - How to run Magnetico3D
	      
	      (2) - Physics Principals
	      2.1 - Outside the cube
	      2.2 - Inside the cube
	      2.3 - Magnetic field and perpendicular velocities
	      2.4 - Magnetic field and paralel velocities
	      2.5 - Magnetic field and obliquos velocities
	      2.6 - Electric field
	      2.7 - Electric and Magnetic Field

	      (3) - Description of Magnetico3D
	      3.1 - We don't do Windows!
	      3.2 - Presentation
	      3.3 - What do the values mean?
	      3.4 - Graphic modes and animations
	      3.5 - The rotatating Cube
	      3.6 - Repeating the simulation

	      (4) - The Simulation
	      4.1 - Help during the simulation
	      4.2 - How to spin th cube
	      4.3 - Zooms
	      4.4 - Straff
	      4.5 - F keys
	      4.6 - Measuring
	      
	      (5) - Data file
	      5.1 - What's it for
	      5.2 - File format
	      5.3 - Data loss
	      5.4 - Full file





			    (1) - Introduction

 1.1 - What is Magnetico3D:
This program is used to simulate the movement of a particule with a charge "q"
that starts by moving inside a cube where there is a magnetic and/or electric
uniform field with the direction and intensity that the user wishes, and
outside the cube there is no magnetic and electric field.
Besides the magnetic field, the values of the charge, mass of the particule
starting speed and Euler-Cromer time division are chosen by the user.

 1.2 - Minimum requisits for running Magnetico3D:
A 386 with 200K of free memory, an FPU and a VGA board.

 1.3 - Advised requisits for running Magnetico3D
A Pentium 133Hz with 620K  and 16 Mb of RAM in case you want to calculate
ten milion points or something, and a VESA board to use SVGA resolutions.

 1.4 - How to run Magnetico3D:
Enter the directory where the MAGNET.EXE is and type MAGNET. This program
needs no adicional files to run, but to run correctly you should have the
following files in the directory where you are runing the program:

CORTINA.RAW     CORTINA.PAL
BLACK.RAW       BLACK.PAL
EXEMPLOS.DAT




			   (2) - Physics Principals

 2.1 - When a particule moves in a region of space in witch there is no 
presence of any field (that means, outside the cube), ignoring the action of
the gravity, the sum of the forces that actuate on it is null, there for we
conclude that acording to inercia, the particule will describe a uniform and
rectilineum movement.
This way the equation that translates the variation of the position in 
function of the time is given by: x=x_0+v*t (x=position ; v=speed ; t=time)

 2.2 - When a particule moves in a region of space where there is a magnetic
and/or electric field, and ignoring again the action of gravity, there are
several diferent cases to study:

 2.3 - When it is subjected to only one force: the magnetic force Fmag = q.v*B
where "." designates usual product and "*" designates internal product:
If the speed and magnetic field are in perpendicular planes, then by 
definition of external product, the magnetic force will have a direction
perpendicular to the plane of v and B. Since on each instante the particule's
speed is perpendicular, it will work has a centrifugus force, forcing the
particule toi describe a circular movement and uniform while it moves inside 
the cube:   Fmag=m*v*v/r <=> r=m*v/q*B 
(m=mass ; r=radius of trajectorie ; "*" designates the usual product now)

 2.4 - If the speed and magnetic field are paralell, then, again, by 
definition of external product, the magnetic force will be null and the
particule would describe a rectilinium uniform movement.

 2.5 - If the speed and magnetic field have perpendicular components and
paralell between (they are obliquos), then the particule will execute the
resulting movement of the composition of the rectilinium uniform and circular
uniform, that is, an helicoidal movement.

 2.6 - When it is subject to only one force: the electric force Fel = q.E:
Doing again F = m.a <=> a = q.E/m , that means, that the electric field
will only influence the movement if it has the same direction as the speed
(or one of the components). It can acelerate the particule or slow it down,
acording to the charge and directions of the speed and electric vectors.

 2.7 - When the particule is simultaneous subjected to the action of a 
magnetic and electric force:
 -> In case the null them each other, the particule will be subjected to a 
 resulatant of null forces. Therefore the particule will describe a circular
 and uniform movement that has already been explained.
 -> In case they don't null each other the particule will be subject to a
 resultant of forces not null, describing a very special tipe o composed
 movement that is called a trocoid.
 For any of the cases th equations for the particule movement wiil be:

    x=x_0+vx*t     (parametrix equations of the movement)
    y=y_0+vy*t
    z=z_0+vz*t
    vx=vx_0+ax*t   (vx,vy and vz are the velocity components in the xx,yy and zz axle)
    vy=vy_0+ay*t
    vz=vz_0+az*t

 ax,ay and az are the acelerations on each axle and are calculated from the
 dinamics fundamental law, using the external product when needed

 We used the Euler-Cromer method in this program but a Runge-Kutta 4 order
would probably give better results, maybe we'll try some day...






		       (3) - Description of Magnetico3D

 3.1 - As soon as you run the program a warning message will appear if you
are running the program in a Windows environment. The program can detect
Windows 3.1, Windows 3.11 and Windows 95 when the stealth option isn't on.
This routine can't detect Windows NT or OS2 Warp but the message still 
applies to both this OS: Windows is GUI (Graphical User Interface), use X11!

 3.2 - If the user is not runing MS-Windows or he decides to continue the the
program will fade and an image of a courtin with the Graviton Productions 
Logo will appear. After that an image of a black hole seen by an X-Ray 
telescope will show.
At any moment this intro can be stoped by pressing Escape.

 3.3.0 - After the graphics intro the program returns to text mode and it will
ask the user to press Enter so he can the punch in the values that he wants.
To ask the user for some values we used a function to replace scanf that we
called Scan_double and that allows the user to press Enter and choose the
default value. This function also allows to use the cursor keys, backspace and
delete to edit the value.
The cursor in the box will not go over the box so the biggest number the user
can punch can only have 10 decimal places. For really big numbers or very 
small numbers then it's better to use cientific notation.

 3.3.1 - By this time the program asks the user to punch in the value of the
starting speed of the particule in the xx axle, in the yy axle and then in the
zz axle. The default value is one metre per second but the user can easely
change this value if he does not like it.

 3.3.2 - After this the program asks the value of the uniform magnetic field
inside the cube in the xx,yy and zz axles.

 3.3.3 - After that the program asks for the intensity of the uniform electric
field inside the cube in the xx,yy and zz axles.

 3.3.4 - After this the program asks for the mass of the particule and the
default value is the mass of an electron.

 3.3.5 - Then it is asked for the user to give the value of the time division
for the Euler-Cromer method, witch is 1e-15 seconds has default. If the user
wants more precision then he should use a smaller value, if he wants less
precision then he should use a bigger value, but he must pay attention that if
the value is to high the results may be very caothic and wrong.

 3.3.6 - Then the user must punch in the value of the particule's electric
charge. The default value is the electron charge in Coulombs.

 3.3.7 - Finaly the program asks the user to input the number of points for
the trajectorie. On a 486 DX2 1000 points runs very smoothly and more than
5000 is a drag, but on a pentium the perfomancers are quite better, you better
try and see. If you use less than 500 the trajectorie will probably be very
faint and hard to see.

 3.3.8 - After inputing the values it his possible that a warning message 
appears saying that the dt is very high or very low. If this happens then the
results of the simulation will probably won't be very good, but you should
try it any way! If it seems weird then try again but with a better dt.
For those who do not know, the dt is the Euler-Cromer infinitesimal time
division!

 3.4 - After this, a menu will appear on the screen that allows the user to
select the graphics mode desired. The 640x480x16 and 320x200x256 modes will
work for all VGA boards but the other ones will only work with VESA 1.x 
compatible boards. 

 3.5 - Shortly after a white cube will be drawn on the screen and inside will
be the trajectorie of the particule drawn in a white line. The user can then
press (F1) to see the available keys and what each of them does. For a
detailed description of these commands you better read chapter 
(4) - The Simluation.

 3.6 - When you get tired of watching the trajectorie then you can press 
(Escape) and the program will return to text mode and shore the results of
this simulation. The program will then ask if the user wants to make another
simulation. If the user says No then the program exits to MS-DOS, if the
user says Yes then the program will return to the value input menu, where
the default values will be the ones that the user used before, instead of
the ones the authors chose.




			     (4) - The Simulation

 4.1 - Help during the simulation
To get help during the simulation the user can press the (F1) key witch will
show a short list with all the available commands. The keys are showned at
lightblue and what they do is at white. To ende the simulation the user just 
has to press the (Escape) key.

 4.2 - How to rotate the cube:
The Magnetico 3D is a three dimensional program that allows to do rotations.
To rotate the cube and the trajectorie of the particule you just need to use
the cursor keys or the numeric keys of the keypad in the following way:

7 8 9        The numeric keys rotate in the direcction they point.
 \|/         The (0) and (5) keys have no function.
4---6        Make shure the NumLock is on otherwise the functions will be a
 /|\         little different.
1 2 3         

If the user wants to make rotations in the zz axle then he must use the (x) and
(z) keys to spin clockwise and counter-clockwise.

 4.3 - Zooms:
The Magnetico 3D also allows to make zooms. To do this the user must user the
(+) key to zoom in and the (-) key to zoom out. But these keys zoom very 
slowly so if you want to zoom fast you must use the PageUp (PgUp) key to
zoom in and the PageDown (PgDn) key to zoom out.

 4.4 - Straff
To straff the cube, the user should use the (q),(a),(o) and (p) keys in the
following way:

  q       The (q) key moves the cube up.
  |       The (a) key moves the cube down.
o---p     The (o) key moves the cube left.
  |       The (p) key moves the cube right.
  a

 4.5 - Function keys:
Each one of the function keys (F keys) executes a command:

 (F1) - When the user presses this key he will be able to see the Help Online
that shows a resume of the keys and what they do.

 (F2) - When you turn this option on you will be able to see the axles of
the trajectorie. The xx axle will be in red, the yy axle will be in light blue
the zz axle will be in light green and the starting speed vector will be in 
dark red.

 (F3) - This key enables to show or hide a vector that joins two points that
can be moved by the user with the (n),(m),(,) and (.) keys and the real
distance beteween these two points will be displayed on the corner of the
screen in purple. See (4.6 - Measuring).

 (F4) - This option enables to show or hide the cube that delimitates the
electric and/or magnetic field.

 (F5) - This key allows you to see the data off the trajectorie that are
presenting seeing and save it for later in a file called (EXEMPLOS.DAT) so
later you can compare it with other trajectories.

 (F6) - When you press this key you will see a menu with the name of the
trajectories that are saved in the file EXEMPLOS.DAT. You can then choose a
trajectorie and compare it with the ones that are already on the screen.
The scale is always adjusted to the first trajectorie and the limit of
diferent trajectories that you can watch at the same time is four. The colors
of the trajectories are as follows:
			 
 First->   White        Since the scaling is automaticly adjusted to the first
 Second->  Yellow       trajectorie, it his possible that the other 
 Third->   Grey         trajectories look too big or just a dot in the middle of
 Fourth->  Blue         the cube

 (F7) - This is used to show or hide the vector of the direction of the
magnetic field in dark red.

 (F8) - This is used to show or hide the vector of the direction of the 
electric field in dark blue.

 (F9) - This to show or hide the first trajectorie (in white).

 (F9) - This to show or hide the second trajectorie (in yellow).

 (F9) - This to show or hide the third trajectorie (in grey).

 (F9) - This to show or hide the fourth trajectorie (in blue).

 4.6 - Measuring:
 Since the Magnetico 3d has no scales like normal graphics and charts, the
only way to measure a distance beteween two points is using the (F3) option
witch will show the real distance in the upper left corner of the screen in
purple.
 Inicialy the two points are the same and they're at the center of the cube.
The user can then shoose other points in the same trajectorie using for this
effect the (.) and (,) keys to advance and retrocede point 2 or the (m) and 
(n) keys to advance and retroced point 1.





			(5) - Data file (EXEMPLOS.DAT)

 5.1 - What's it for:
 The data file is used to record the values of a simulation that the user is
watching and would like to see again later to compare with other trajectories.

 5.2 - File format:
 The data file is a plain text file that can be edited with a simple text
 processor like MS-DOS's EDIT. This file must have some caracteristics:

 5.2.1 - The first two words of the file are coments and are always ignored
but if the user removes them the program might crash when you press (F6).

 5.2.2 - Each line of this file corresponds to a trajectorie and the meaning
of each data field his the following:

 5.2.2 - Cada linha corresponde a uma trajectoria e o significado dos campos
e' o seguinte:
 
 1 Name of the trajectorie     8 Electric field in xx
 2 Starting speed in xx        9 Electric field in yy
 3 Starting speed in yy       10 Electric field in zz 
 4 Starting speed in zz       11 Particule's mass
 5 Magnetic field in xx       12 Time division (dt)
 6 Magnetic field in yy       13 Particule's charge
 7 Magnetic field in zz       14 Numer of points in the trajectorie

 5.3 - If the data file is damaged or destroyed:
 In case the original data file is destroyed there is a backup called file 
EXEMPLOS.BAK, you just have to type:
COPY EXEMPLOS.BAK EXEMPLOS.DAT
If that file gets destroyed also then you can make a new one from the 
following lines:

----Cut-here---------Cut-here---------Cut-here--------Cut-here-------Cut-here-
Dont_erase_this_line!When_you_run_out_of_slots_in_F6_erase_one_of_the_lines_below_!_Read_the_MANUAL!
Dont_erase_this_line!_Os_campos_sao_os_seguintes:Titulo,vx,vy,vz,Bx,By,Bz,Ex,Ey,Ez,massa,dt,carga,pontos

Weird_values  1 0 0 1 0 10 0 0 0 1 0.01 1 1000
Test 1 0 0 1 0 10 0 0 0 1 0.04 1 1000
nada 1 0 0 1 0 10 0 0 0 2 0.01 1 1000
blabla 1 0 0 1 0 10 0 0 0 1 0.01 1 1000
Menu 1 0 10 1 0 0 0 0 0 1 0.04 1 1000
Electron 1 0 0 1 0 0 0 0 0 9.1e-31 1e-15 1.6e-19 3000
----Cut-here---------Cut-here---------Cut-here--------Cut-here-------Cut-here-

 5.4 - Full file:
 If your data file gets too full the only way to solve this is to erase one of
the lines (or more) manually (with EDIT) so that all available trajectories
show up when you press (F6)

 





Copyright (c) 1996     Producoes Gravitao
Coded by Morgana a Anafada & Frodo The Ring Bearer
