TITLE:  YagiUda-1.09.tar.Z and yagiu109.zip

PURPOSE: To analyse performance of Yagi-Uda antennas. You
give the dimensions and positions of each element, and the
program calculates gain, input impedance, front-to back ratio,
beam-patterns etc. An optimisation program 'optimise' tries to
optimise a design. The optimiser can also tell you the sensitivity
of a good design, to small mechanical errors.

AUTHOR: David Kirkby BSc. MSc.  G8WRB.
email:davek@medphys.ucl.ac.uk
	     Department of Medical Physics,
	     University College London,
	     11-20 Capper St,
	     London WC1E 6JA.
	     Telephone: 071-380-9700
	     Fax: 071-380-9577. 

The *latest* version will be found on the anonymous ftp site medphys.ucl.ac.uk
While other ftp sites are keeping the program (eg ftp.funet.fi), I'm always
goind to put the latest version on my machine at work first. 

INTRODUCTION.
Four binary programs, INPUT, YAGI, OUTPUT, OPTIMISE and FIRST
are used for the analysis and optimisation:

INPUT asks for data about a Yagi and writes it to a disk file, in
a standard ASCII format. The file name the data is written to is
specified by the user, in response to the program.

FIRST puts data about a very rough Yagi into a file. It is used for getting
dimensions of Yagis of arbitrary number of elements quickly. It will *not*
give a good design, but can be used as a starting point for further 
optimisation.

YAGI computes yagi performance, using as input the file created
by INPUT or FIRST. It writes data to a file with a '.out' suffix. The '.out'
file is a binary file containing (amongst other things) the element
currents. On a PC, running unix, fitted with 16Mb of RAM, a 400
element Yagi has been analysed! As far as I'm aware, the size of
antenna that can be analysed is not limited in any way by 
the program - only your memory available.

OUTPUT reads the element currents from the '.out' file and
computes forwardgain, input impedance, front to back ratio etc
and puts these in a file with a '.dat' suffix. The gain in both
the E and H planes is put into a file with a '.gai' prefix. Both
the '.dat' and '.gai' files are ASCII and their format is easy to
understand by inspection.

OPTIMISE takes a design you have, then tries to randomly
change element lengths and positions, so that the antenna works
better. If it's better, it keeps the new design, if not its scraped.
What is 'better' is defined by the user. For example is an
antenna that has higher gain, but also higher VSWR better or 
worst? You choose what you want to optimise. Optimising just
gain usually results in an antenna with an impractically low input
impedance.
If, for example, the user runs INPUT, and enters '4ele' as the
filename, then INPUT creates a file called '4ele'. After typing
'yagi 4ele', we will have a file '4ele.out', containing the element
currents. We then type 'output 4ele' where we will get the
following files: '4ele.dat' and '4ele.gai'. If we then type
'optimise 4ele 123' this will take the design for the 4
element yagi, try to change lengths or positions upto 0.1%,
using juest parasitic elements, optimising for gain,
F/B ratio and vswr. It will try this 123 times. Run
'optimise' with no arguments to get a list of the required parameters.
Optimise gives you a running commentry of its current best performance
on the screen (stdout) and in a file '4ele.up'. The best design (ie
positions of elements etc) is in a file '4ele.bes'.

If you create a file called 'stop' in the directory in which optimise 
is running, optimise will stop after a few seconds. This allows one to
set it running for a long time, but pause it if needed. Simply killing
the process will of cource stop it, but it may leave you with no results,
as the results files are continuously being deleted! If you ask 'optimise'
to run for say 123 iterations (as in the example above), but it stops after 
just 100, its probably becuse you have a file called 'stop' in existance. Use
'touch stop' to create 'stop' and 'rm stop' to remove it.



IMPORTANT

To achieve high accuracy, accurate analytical equations are used
in the program. These equations need evaluation of the sine
integral and cosine integral. Some copy-righted software is used
in evaluating these functions. Also, copy-righted software is
used in matrix computations and complex number calculations.
Hence the full source code is *not* given. However, the
copy-righted routines can *very* cheaply be purchased. They are
printed in the book 'Numerical Recipes in C', 2nd edition, by Press
et al, Cambridge University Press (1992). Many scientific academic 
departments (physics, maths, engineering etc etc) will have
a copy of the book, but it can be purchased easily by anyone. A
disk with the routines on can also be purchased. Unfortunately,
the  1st edition of the book will not do, as one of the routines
used 'cisc()' for sine and cosine integral evaluation, was not
printed in the 1st edition.

FILES:

better.c                   Determines if a design is better or not.
cis_hack.c                 Calculation of sine and cosine integrals.
com_hack.c                 Complex number routines.
copym.c                    Copy matrix a to matrix b.
gain.c                     Gain of an antenna
ga_lib.c                   Genetic algorithm library routines.
getfiles.c                 Checks arguments, then opens files.
header.c                   Writes header to disk file.
input.c                    Program requests data, then writes to ASCII file.
lub_hack.c                 Back substitution (matrix algebra).
lud_hack.c                 LU decomposition (matrix algebra)
mpr_hack.c                 Iterative improvment of simultaneous equ's
mutual.c                   Calculates mutual impedance between elements.
nrutil.c                   PD Numerical routines (utilite routines).
num_ele.c                  Returns number of elements from data file.
optimise.c                 Program to optimise a Yagi-Uda antenna design.
output.c                   Program to put Yagi performance into ASCII file.
pin.c                      Calculates power input to antenna (in Watts).
print_z.c                  Prints the impedance matrix; for debugging.
randomis.c                 Randomises element positions/lengths.
read_data.c                Reads a yagi description into memory.
read_header.c              Reads a header created by 'yagi'.
read_perf.c                Reads perpormance of yagi (gain. F/B etc)
refco.c                    Calculates the reflection coefficent.
self.c                     Calculates self impedance of an element.
string.c                   Allocates and frees memory for strings.
v.c                        Fills voltage vector (V).
vswr.c                     Calculates the VSWR of antenna.
write_cords.c              Writes coordinates of elements to disk.
write_gain.c               Writes gain in E and H plane.  
write_ip_dat.c             Used by 'input'. Writes yagi to disk.
yagi.c                     Main program for calculation of element currents.
z.c                        Fills impedance (Z) matrix.
zbr_hack.c                 Hacked version of zbrent.c in NR book.
z_input.c                  Computes input impedance of yagi.
CHANGES                    List of changes made.
dosmake                    DOS Makefile
makefile                   Unix makefile.
optimise.1                 Unix man page for optimise.
optimise.doc               ASCII version of above.
optimise.cat               Catable man page (does not require nroff).

There are also some example files (see below), plus a few others (shell scrips
etc) that I used. These are of no use, but I dont always remeber to remove them.

PLATFORMS TESTED ON.

This set of program have been test on these systems:
1) A i486 PC with 16Mb of RAM running Interactive Systems Unix, System V, 
version 3.2, release 2.0.2. Compiled with g++.
2) A  Sun Classic running SunOs 4.1.3_U1. Compiled with acc.
3) A 90MHz Pentium PC running DOS. Compiled with gcc. 

There are few if any system specific calls or anything that I think
will cause problems if converted to other systems. Memory requiremnts are 
modest by todays standards. The memory necessary depends on the size of the
antenna, as bigger arrays are necessary to hold more element data for large
Yagis. A minimum of 2Mb will probably be necessary, but I can't say
for sure.


BUILDING THE EXECUTABLES

Since some routines are missing, its important to follow these
instructions carefully.

1) Get hold of the following files from the 2nd edition of the
Numerical Recipes book. Please dont ask me for them.

cisi.c                   Sine and cosine integral evaluation.
complex.c                General complex maths.
lubksb.c                 Back substitution of a real matrix.
ludcmp.c                 LU decomposition of a real matrix.
mprove.c                 Iterative improvement of simulateous equ's.
zbrent.c                 Brent's algoritm for root searching.
nrutil.c                 Utility programs.

2) Change *all* references in the first 6 files from  float to double.
Do *not* alter nrutil.c at all.
Any references to routines 'vector' should be changed to 'dvector'
, references to 'matrix' should be changed to 'dmatrix',
references to 'free_vector' to 'free_dvector' etc.
The routines 'vector', 'matrix' are numerical recipe routines
for allocating memory for single precision vectors or matrices.
The 'dvector' etc is for double precision.

Rename all files with ie. cisi.c to cis_hack.c, complex.c to 
com_hack.c ludcmp.c lud_hack.c and lubksb.c to lub_hack.c and mprove.c to
mpr_hack.c, zbrent.c zbr_hack.c. This will avoid confusion later if you 
happen to use the recipes in another application. 

3) Remove any references to "nr.h", "nrutil.h" in these 5 files.

4) Add a line:
#include "yagi.h" to each of the five files. "yagi.h" includes
hacked versions of the original numerical recipe header files.

5) In the file complex_hack.c, delete the line (line 5) that says:

typedef struct FCOMPLEX ...

5) Type 'make'. You should get five executables, 'input', 'yagi', 
'output', 'optimise' ,'first' and 'rantest'. Its assumed that your compiler 
defines 'i386' on a unix PC, 'sun' on a Sun and DOS on a DOS PC. There are a 
few '#ifdef sun' statements in a few of the C files. On other systems you might
try defining one or the other of these using (usually) the -D
option on your compiler. Try defining 'sun' or 'i386' in the makefile,
on the CFLAGS in the makefile where 'ANSI' has been defined. 

6) Run the program 'rantest' and check the output is as its says it
should be. If not, there are problems with the random number generators,
which are used extensivly in the 'optimise' program, but not in any of the
others.

EXAMPLES 

There are a number of example files. I've included the '.dat' and '.gain' 
files from 'output'. These might be of use when testing your programs.

1ele        This is a single element, exactly 1.0m long. It is obviously
	    a half-wave at exactly 150MHz. Note that it resonates not at
	    150MHz, but at approximately 145MHz, where its gain is 2.11dBi.
	    At 150MHz its gain is the well known 2.15dBi (2.15dBi=0dB 
	    referenced to a dipole), but its not resonate. 

70cm33      A 33 ele yagi for 70cm amateur band.

200         This is just a test design. It has 200 elements! Its not
		 any good at all as an antenna, but is included to test
	    the programs for a large design. The program 'optimise' is
	    most likely to limit you for large antennas. The matrices
	    used in 'optimise' are much bigger than in 'output'. 'yagi'
				also needs large matirces.
2m6         2m, 6element yagi.

SCRIPT FILE

A file called 'TYPESCRIPT' should be included with the distribution you 
received. This is a complete session of using the programs to analyse
and optimise a yagi. This was produced using the program 'script' on the
Sun computer. It should help you see exactly how to use the programs.

FILE FORMATS:

The files created by 'input' and 'output' are ASCII and their
format should be easy to see by inspection. Lines beginning with
a hash (#) are comments. The .out file, as created by yagi is a
binary file and its format is described below. There is a 100 byte
header, consisting of:

offset(bytes)              info                 data-type

0                          elements             int
4                          driven               int
8                          parasitic            int
12                         min_frequency        double
20                         max_frequency        double
28                         design frequency     double
36                         step_frequency       double
44                         angular_step         double
52                         0                    double
.                          .                      .
.                          .                      .
.                          .                      .
92                         0                    double

Following the header, there starts the coordinates(x,y,l) of each
element and the voltage applied to each element. Then we write
the element currents one after the other, at each frequency.
Hence the element currents will be written 12,000 times with a
3 element yagi analysed at 4,000 different frequencies.
100                        x1                   double /* coordinates */
108                        y1                   double
116                        l1                   double
100+(n-1)*24               x_n                  double
100+(n-1)*24+8             y_n                  double
100+(n-1)*24+16            l_n                  double
.............. Repeated for each element.
100+24*elements            Voltage1             fcomplex 
100+24*elements+(n-1)*16   Voltage_n            fcomplex
.............. Repeated for each element n at each frequency step f.
100+40*elements         Current1@f1             fcomplex
100+40*elements+(n-1)*16 Current_n@f1           fcomplex

100+56*elements         Current@f2              fcomplex
100+40*elements+(n-1)*16 Current_n@f2           fcomplex

The file with the extension '.gai' gives the gain at every frequency
in both the H(xy) and E(xz) planes. It is difficult to make the coordinate
system clear without a diagram. See Lawsons book, as I've used exactly the
same system as him.

The antenna sits in the horizontal (xz) plane. The forward direction of
gain is towards the +x direction. Phi, the elevation angle varies from
0 degrees along the x axis, through 90 degrees along the y axis, to 180
degrees along the -x axis. The gain on the H plane is given in both units
relative to an isotropic radiator (dBi) in the ( gain-H(dBi) column ) and
dB relative to the peak (in the gain(H)-peak column). Phi is listed 
from 0 to 180 degrees.

The gain in the E (xz) plane is also given in two columns, one in dBi,  
the other refered to the peak. Theta (the azimuthal angle) goes from
90 along the x axis, 180 degrees along the z axis to 270 degrees along
the -x axis.

Hence the direction of peak forward gain is theta=90, the backward
direction is theta=270. At theta is 180 degrees (off the side of the
beam), the radiation is theoretically zero. The '.gain' file lists
it at -999.0000 dBi. The  front to back ratio, which is listed in the
'.dat' file, is simply G(theta=90)/G(theta=270).

The '.gai' file has 7 columns. The first one (frequency) is common
to the other 6. However, the 2nd (theta) is only concerned with the 
3rd and 4th. It has nothing watsoever to do with the last 3. 
Similarily, the 5th column (phi) is only concerned with the 6th and 7th
coulmns. 

PUBLICATION

I've submitted the theory (not source code) of how this program works to 
RadCom, the publication of the Radio Society of Great Britain. Keep a look out 
in RadCom, since it may be published.  This was refused once, but will be
re-submited.


KNOWN PROBLEMS:
  
In a typical Yagi, the element lengths are approximately
half-wave. If a Yagi is analysed well away from the usual
frequency (3x, where elements are approximaely 1.5 wavelengths
long) then the self impedance formulae will be inaccurate, as it
assumes a sinusoidal current distribution, high in the middle,
zero at ends. This makes the input impedance of the antenna
have a negative real part. This implies a negative power absorbed
by the antenna, (ie antenna supplies power). Hence the gain
becomes negative. Taking the log (to get dB) of a negative gain
gives numerical errors. 

WARNING

Using software random number generators can be a problem. Many of the 
random number generators on computer systems are rather poor, having a
short repeat period, or subsequent numbers being correlated in some way.
Better (but slower) random number gererators are available - see for
example 'ran0()', 'ran1()' etc in the Numerical Recipes book. A system
random number generator (drand48()) has been used here, with no attempt
made to correct any defficiencies. I dont *think* its properties are critical
in this application, hence I just used the fast(ish) system supplied routine,
but warn you that it is not necessarily good. The random number generator is
only used in the optimise program. It properties will not affect the accuracy
of any results, but it may change the speed with which you get a better design.

KEEP IN TOUCH

If you find this program interesting/useful, mail me and I'll let you know of
updates etc. email:davek@medphys.ucl.ac.uk
