# Help for Ariadne

### Version 061214

## Contents

- Overview
  - Technical Overview
  - Installing Ariadne
  - Problems with Ariadne
- Usage
  - Using Ariadne through Windows
  - Copying a Window to a Document
  - Using Ariadne from the command line
- Options
- Input Files
- Output Files
- Computational Modes
- Summary of Models
  - Major Model Types
  - Minor Model Variations
  - Model Recommendations
- Command Window Hints
- History
- Old Screen Shots

## Overview

This programme is a `JAVA` application for analysis of networks of sites and their connections in the bronze age Aegean.

### Technical Overview

The core is a general class, in `islandNetwork.java`, which can be used for any island network. This is run from the main routine of `aegean.java`. Also used are input/output routines from the "Introduction to Programming using Java" of David Eck available from `http://math.hws/edu/javanotes`.

### Installing Ariadne

(See also the file is `ariadne\doc\readme.txt`)

Unzip the ariadne.zip file to the root of the C drive. Double click on the zip file and select `c:\` as the destination. This puts all the files in the correct places. They are all in the `c:\ariadne` directory.

You also need to download the jre file too. This sets up a JAVA run time environment must be set up (JRE) which runs the JAVA programming language. You may already have one. Look in the control panel (`start button`, then `settings` then `control panel`) for the `JAVA` entry. Click on that. The `java` tab and then the `view` button on the application section should give you a list of versions installed. Look for the latest one, something like `1.6.0_05`. The `update` tab will allow you to get the latest version automatically. You can also download java directly (you will need to do this if you don't already have it). Get it from http://java.sun.com/j2se/1.6.0/download.jsp and you select the Download JRE 6.0 Update 5 option (of course the version number may have gone up so all the `1.6.0_05` in what follows may have to be changed appropriately). Accept everything. It should offer to save the file `jre-1.6.0_05-windows-i586-p.exe` (or some such file starting jre) somewhere (anywhere will do, its installed somewhere else) and then just click on the file when you have it all. Just double click on the file and accept everything it suggests and it will install itself. Note the version number may change, see comments in the problems section below.

To test the programme click on the `c:\ariadne\ariadne.bat` file. In the input window just click on the calculate button and see if you get a network based on the test file `testsimple_svpdist.dat`

#### Problems

If a black window flashes up and then disappears, then it probably can not find the location of some of the programmes. These locations are listed in the file `ariadne.bat`. To look at this file open it in `notepad` (you can do this by going to start button, run then type `notepad` and enter or you will find it under the start button -> programs -> accessories) or similar text editor. Then look at the following:

- Is the ariadne directory in `C:\` ? To check, search for `ariadne.bat` to see where it is. If not you will have to alter the following line in `ariadne.bat` to point to the correct place
  `set ARIADNEDIR=C:\ariadne`
- Do you have the JAVA run time environment (the jre mentioned above) in the correct place? Are you referring to the version on your machine? Search for `java.exe`. If it is not in
  `C:\Program Files\Java\jre1.6.0_05\bin`
  then you will need to change the line
  `set JAVAEXE=C:\Program Files\Java\jre1.6.0_05\bin`
  in `ariadne.bat`. Note that the version number, the `1.6.0_05`, may change.
- The version number may have changed. If so alter all the `1.6.0_05` in the instructions above appropriately.

## Usage

### Using Ariadne through Windows

Open your favourite way of looking for files, e.g. `explorer` or `My Computer`. Got to the `C:` drive and look for the directory `ariadne`. In that directory click on the file `c:\ariadne\ariadne.bat` file. Note that the `.bat` ending may be hidden from you so look for a file called `ariadne` or `ariadne.bat` with an icon such as . Alternatively do a search (press the start button then look for search) for the file `ariadne.bat` starting at the top level `C:\`.

A black window similar to should appear. This is a command window. It displays various information, all of which is available in other files, so you can ignore it but don't kill it! The programme is running from this window. You can also use it to see if the programme has crashed as you should see occasional new lines or characters appear in this window when the programme is running normally. If you want more information on command windows see the section on Command Window Hints

A second small window is then produced. This is the Input File Name Window and looks like . Type in the start of the name of the input file. That is the input files are all of the form inroot`_input.dat` and it is the inroot stem of the file name which you should type in this window. These files must be in the ariadne directory unless you add extra directory information (use forward slashes to separate directories not backwards slashes here e.g. `data/special` will read in the file `special_input.dat` from the subdirectory `data` of the ariadne directory. You may also type a number into the jiggle scale box. This moves the sites randomly by the fraction given of the default distance scale (probably 100). Thus enter `0.05` and you get a random 5% shift in site positions. Enter 0 or less and nothing is done. When you have finished typing, press the read button to have the data read from the file. For more information on input files see the section below.

If the data is read in OK a message box to this effect appears, . The command window has more information about what data was read in to the programme. Hit the OK button.

The next box to appear it the Inputs window which looks like . Note it may obscure the input file name window which is hiding underneath. You may move and even kill this Inputs window at any time. This box allows you to change any variable other than the input file name, and then calculate or redraw the network output window. Set values as you desire (see the Options section below for further details. Press the CALCULATE button and a new network is calculated with all the details given. Press REDRAW and the last network calculated is redrawn. In this latter case changes to parameters which alter the drawing (e.g. minimum colour fraction) are used but those parameters which effect the network (e.g. mu) are not altered. Is used to see the same network in different views without redrawing the network. Try changing the zero and minimum colour fraction to see the effect.

Finally two output windows appear, one for the whole network, one for site data. It includes displays of the rank of sites as calculated by the diffusion method. For example the one showing information on the sites looks like
and one showing the network is
.

Note that there are various ways of changing these displays. All the items labelled display alter the look but not the results. Changing these variables and hitting the `REDRAW` button will produce new displays according to the new display settings but will not recalculate the results.

I have included an experimental influence calculation. In the text files in the output directory are infile_inflmat.dat files which record the estimated influence every site has on every other site. There is a parameter Influence Probability, p, which should be between 0 and 1. At zero, no one influences any of their neighbours. At 0.5 a site will influence mostly their nearest neighbours, 0.667 neighbours up to two steps away, 0.75 three steps away etc. Its a bit like the angle of the cone in the tent models of dominance used by Renfrew etc. The full matrix of everyone's influence on everyone else is hard to display. In one simple view of the network (by influence), every site i is labelled by the colour of the site whose influence is greatest at that site. As p increases the map becomes uniform as one site dominates all others. It satisfies my sense of world domination.

In the input window fill change any variables you wish. A brief explanation is given below. To calculate based on these values click on the calculate button. Wait (up to a minute for model 3). At the moment the only input files are those infile`_input` in the main directory. To select these as inputs you only type the stem of the name, that is infile.

### Copying a Window to a Document

You can make a copy of any window (not just the ariadne ones) produced by any programme in the Windows operating system. It makes a bitmap copy, that is one that can not be scaled without the . The

1. If you have not already done so, open an image aware programme such as `Word` or your favourite image manipulation software.
2. Make the window of interest active. That is make sure the blue bar at the top is bright blue not faded by clicking on it once.
3. While holding down the `Alt` and `Shift` keys, press the `Print Screen` key. (This may be labelled differently `Prt Scrn` or similar) and is often on the same key as `SysRq`). This copies an image of the window to the clipboard, just as when one copies text in a word document.
4. Activate `Word` or the image manipulation software you want to use. Open the document at the place you want to place the image, or start a new one. Select `paste` from the `edit` menu (or hit `cntrl` `v`). You should now see a copy of your window in the document.

### Using Ariadne from the command line

This is the old way of running the programme. It can also be used to generate geometric input files of various types. After the programme has been installed, a one time procedure, every time you want to set up a new session where you run the programme many times, you need to start by setting up a proper window in which this is done.

The programme is run by using the command line. On Windows 2000 and XP systems this is reached by clicking on the `start` button (usually bottom left), selecting the `run` option, and typing `cmd` in the box that comes up. This produces a black box called the command window.

Finally you need to move to the right hard disk and directory within this command window. Type in the command window `c:` then press enter to change to the disk drive where the programme and all its output files will be, `c:`. This is followed by typing `cd \ariadne\` followed by enter. The `cd` command changes the directory to the one where all the files are kept. If you are looking for any files using other methods (the graphical approaches such as my computer or explorer) look on the `c:` drive and then in the directory `cd \ariadne\`.

For general hints on using the command window see the section on Command Window Hints.

## Options

The options noted below can be set for the most part both in the input windows that ariadne produces by default, or from the command line.

To use the command line, the form is is `ariadne` Each option takes the form of a minus sign followed immediately by one or two characters, indicating which option is being set, and then followed immediately by the value.

For instance the option for setting the mu parameter is m and a valid way to do this is `-m0.3` which sets mu to be 0.3. Leaving any spaces produces errors. For instance `- m0.3` and `-m 0.3` will both produce funny error messages.

Each option must be separated from other options by one or more spaces. The kappa parameter is set by the k option so `-k1.6` sets kappa to be 1.6. If we are setting mu as above then we would type `ariadne -m0.3 -k1.6` or even `ariadne -m0.3 -k1.6`. If you tried `ariadne-m0.3 -k1.6` or `ariadne -m0.3-k1.6` funny errors will be produced. The order of the options does not matter though they are processed starting with the one on the left and working through the list so `ariadne -k1.6 -m0.3` works just as well.

Those not available in the command line as yet are indicated by a `-!!!`.

Default values listed below may be out of date.
Check by running `ariadne -wn -?` which gives the defaults actually used by your version.

Window Entry | C.L. Option | Description
--- | --- | ---
Input File Name Root | `-fi` inroot | Sets the root or stem of the input file name. Thus the programme will look for the file `inroot_input.dat` to set the names, coordinates and distances between the sites. See input files for more details. Default value `aegean`
Output File Name Root | `-fo` outroot | Sets the root or stem of the output files. Unless set to AUTO the programme will produce files such as outroot `BW.net`. See output files for more details of output files produced. When the output stem is AUTO then automatic output file names are used, built from the input file name stem followed by parameter values. Default value `AUTO`
Automatic Output File Name | `-fa` | Sends output files to directory `output` with the names of the output files given by the input file name root followed by the run name and the values of the parameters. Default value `ON`
Run Name | `-fr` runname | Sets the ending of the output files. Use to distinguish runs with identical input values. Default value `r0`
Model Number | `-v` j.n | This sets the model number to be j.n, that is major model type j variation, minor model type n. The latter has no effect if it has not been defined for major model type j. Model numbers have no effect in PPA mode. Default value 1.3.
PPA Mode MC Mode | `-u` nnn | If nnn is 1 then you get a standard Monte Carlo update. If nnn is zero then you get a PPA style update. For more details on PPA mode see below. Default value 1.0.
Maximum Edge Value | `-e` rrr | If the number rrr is zero or less then edges are set to be one or zero (on or off) only. If positive then each edge (e_ij variables) can take any value from 0 to rrr. If negative then the sum of edges coming out of a site (the out strength of that edge) must be between 0 and -rrr Default value 5.0.
Max Vertex Value | `-x` rrr | This is the maximum value a site can acquire. Remember the scale of each site is set by its size so this is really a fraction of the site size and can be larger than 1.0. That is you may allow sites to become bigger than their local resources really allow.. Default value 1.0.
j | `-j` rrr | Value of parameter j is set to be the number rrr, which controls the total population (total site size). Default value 0.0.
mu | `-m` rrr | Value of parameter mu is set to be the number rrr, which controls the total population (total site size). Default value 0.0.
kappa | `-k` rrr | Value of parameter kappa is set to be the number rrr. This controls the benefit or loss of increasing the population of any one site. Default value 1.0.
lambda | `-l` rrr | Value of parameter lambda is set to be the number rrr. This controls the benefit or loss of increasing the number or weight (importance) of links between two sites. Default value 1.0.
Distance Scale | `-dl` rrr | Value of parameter d_long, the long distance scale, is set to be the number rrr. This controls the distance beyond which the benefit of having links between two sites is heavily penalised. This is done in whatever units were used for distances in the input file. Default value 100.0.
Short Distance Scale | `-ds` rrr | Value of parameter d_{short}, the short distance scale, is set to be the number rrr. This controls the short distance behaviour below which the benefit of having links between two sites is heavily penalised. This is done in whatever units were used for distances in the input file. Default value 5.0.
Distance Metric | `-dm` rrr | Sets metric to be used for Dijkstra calculations. 0: plain distance; 1: sum of individual distance/potential using edge values; 2: inverse edge value; 3: sum of individual distance/potential using edge weights; 4: inverse edge weight. Default value 0.0.
b | `-bs` rrr | Sets the b parameter. This is used as a power in some interactions terms in some of the models (e.g. 5) Default value 1.2.
beta | `-bt` rrr | Sets the beta parameter. In Monte Carlo mode sets the initial inverse temperature to be rrr. The lower the value the more random the initial start but the slower the equilibrium for the network is found. On the other hand in PPA mode rrr is the number of edges per site (currently rounded to nearest integer). For more details on PPA mode see below. Default value 1.0.
infolevel | `-i` nnn | Sets the information level, an integer which the higher it is the more information the programme will produce. However any value above 0 produces information useful only for debugging the programme. Default value 1.0.
alpha | `-a` rrr | Sets alpha, a parameter which sets the power of the fall off over short distances (< d_s ) in the potential V used to decide the strength of interactions. Default value 4.0.
gamma | `-g` rrr | Sets gamma, a parameter which sets the power of the fall off over short distances (< d_s ) in the potential V used to decide the strength of interactions. Default value 1.0.
outputMode | `-o` iii | Binary bits control which output files are produced with 0 (1) off (on). 128=Distance Files. Default value 255.
updateMode | `-u` iii | Sets the update mode for network: 0 PPA; 1 Monte Carlo. Default value 1.
Window Mode | `-w` a | -wn sets no window mode while -wy sets windows on, default value y.
Display Maximum Site Size |  | The size of circle used for the largest site in the network diagram. Change it if they are too big or small. Default value 20.
Display Maximum Edge Width | `-De` | The largest width of edges used for the largest edge values in the network. Change it if they are too big or small. Default value .
Display Fraction for Zero Colour | `-Dz` rrr | Anything below this fraction of the maximum (as defined by values above) is displayed as having zero value, i.e.\ is switched off. Use to hide weak links. Default value 0.0.
Display Fraction for Minimum Colour | `-Dn` rrr | Anything below this fraction of the maximum (as defined by values above) is displayed as having value one, i.e.\ is switched to the colour used for the weakest non-zero links. Use to down play weak links but to leave the visible. Default value 0.1.
Display Max. Vertex Scale | `-Dvs` rrr | Sets the site weight (size times value, s[i]v[i]) which is to corresponds to the maximum on the display scale. If set to zero the largest site weight is used to set this scale and so a relative site size is displayed. Default value 20.
Display Vertex Type | `-Dvt` rrr | Displayed site sizes reflect different measures: 0 fro size, 1 for rank. Default value 0.
Display Max. Edge Scale | `-De` rrr | Sets the edge weight (edge value and source site weight, s[i]v[i]e[i][j]) which is to corresponds to the maximum on the display scale (absolute scale). If set to zero the largest edge weight is used and so a relative edge size is displayed. Default value 10.
Display Influence Prob. |  | Probability used to diffuse influence on the network. On average this will diffuse p/(1-p) links of the network for probability p. Values around 0.5 (one step) 0.66 (two steps) and 0.75 (three steps) should be useful. Default value 0.5.
Display Network Vertex Type |  | On the Network Display, sites can be displayed by circles whose size relates to the weight (total population, v*S) of the site, the rank of the site, or in terms of influence. Each site takes the colour of the site whose influence dominates, which may be itself. Default value Size
Display Site Window Display |  | On the Site Display, the information can be in one of three orders, alphabetical, by largest rank or by largest weight (total population, v*S). Default value Alpha
Generate Number of Sites | -Zn | Generates network of n sites if n>0. Default value 0
Generate Type of Input File | -Zt | Generates input file for network of type t where t is 4: circle, 3: 1D torus, 2: line, 1: 2D torus 0: 2D lattice. Default value 0

Help output from Ariadne (061214)

    --- Running aegean from runaegean.bat
    ...............................................................................
    Ariadne, iNVERSION iN081212 usage: aegean <options>
     where options are -<char><value> separated by space as follows
      -a<alpha>    Sets alpha, short distance power in edge potential, default 4.0
      -bs<b>       Sets b, power used for site terms, default 1.2
      -bt<beta>    Sets beta, inverse temperature, default 0.0010
                    Also number of edges per site in PPA mode
      -cc<culturePCopy>     probability that will copy culture of neighbour, default 0.45
      -cc<culturePSiteCopy> probability that will copy culture within site, default 0.45
      -cc<culturePInnovate> probability that will innovate new culture keeping existing culture, default 0.05
      -cc<cultureTimeScale> time scale in units of tau_2, default 10000.0
      -dl<distanceScale> Sets distance scale, 100.0
      -dm<metricNumber>  Sets metric for Dijkstra calculations, default 5.0
      -ds<shortdistanceScale> Sets short distance scale, default 5.0
      -e<edgeMode>      Sets edge max edge value or binary (0 or 1) if 0,
                        Negative indicates maximum strength, default -1.0
      -fa          Sets the output file name to AUTO,
                        i.e. automatic format as noted above
                                default aegean34S1L3
      -fij<jiggleScale>  Sets scale to jiggle input site locations, default 0.0
      -fi?<string>  Sets input file names and directories where ? given below
      -foa        Sets filename to automatic based on parameters, default true
      -foA        No automatic file name
      -fo?<string> Sets input file names and directories where ? given below
                   ? is a character taken from:-
                  'r' = root directory path
                  's' = sub directory name (relative to root)
                  'b' = basic root of file names (no '_')
                  'p' = parameter string (will have '_' at start added when needed)
                  'n' = sequence or run number (integer)
                  't' = terminating or ending string (no '_r' allowed)
                  'e' = extension (no '.' allowed)
      -g<gamma>         Sets gamma, short distance power in edge potential,
                                default 1.0
      -i<message.getInformationLevel()>     Sets information level, 0 lowest, default 0
      -j<j>        Sets j, sum over all vertex weights, default 0.0
      -k<kappa>         Sets kappa, coefficient of vertex potential, default 4.0
      -l<lambda>        Sets lambda, coefficient of edge potential, default 4.0
      -m<mu>       Sets mu, sum over all edge weights, default 0.5
      -o<outputMode>    Sets output mode by bits 1 (0)= on (off):, default 15
                        1 = general information (info)
                        2 = pajek files (pajek)
                        4 = edges as vector (elist)
                        8 = edges as matrix (ematrix)
                        16 = gene separation (gsep)
                        32 = ariadne network file (anf)
                        64 = Google Earth KML network file (KML)
      -u<updateMode>    Sets update mode: PPA 0, MC 1, DP 2, VP 3. Default IslandNetworks.UpdateMode@ee7a14
      -v<modelNumber>   Sets model number to use, default 1_3
      -w[y|n]      Sets window mode on -wy or off -wn, default true
      -xv<vertexMaximum>  Sets vertices to have a maximum value
      -xw<constantWeight> Sets total weight of vertices to be constant
                          Vertex mode and value defaults are Maximum Vertex Value , value=5.0
      -Cc MC calculation is started from a cold start
      -Ch MC calculation is started from a hot start, default HOT
      -Des<DisplayMaxEdgeScale> Sets size of edge weight (s[i]v[i]e[i][j]) for maximum
                                  colour in display (absolute),
                                  if 0 then largest value actual value used (relative),
                                   default 1.0
      -Det<DisplayEdgeType> Sets type of edge displayed, 0 size, 1 rank
                                 0 = value
                                 1 = weight
                                 2 = potential1
                                 3 = geneCorrelation
                                 4 = separation
                                 5 = correlation
                              default value
      -Dn<minColourFrac> Sets fraction of largest colour which is to be
                           represented as colour value 1 (next to minimum),
                             default 0.1
      -Dvt<DisplayVertexType> Sets type of vertex displayed,
                                 0 = Weight
                                 1 = Rank
                                 2 = Influence
                                 3 = Strength
                                 4 = Nothing
                              default Weight
      -Dvs<DisplayMaxVertexScale> Sets size of vertex weight (s[i]v[i]) for
                                  maximum colour in display (absolute),
                                  if 0 then largest value actual value used (relative),
                                   default 1.0
      -Dx<visualisationWidth>  Sets preferred width for windows in pixels, default 760
      -Dy<visualisationHeight> Sets preferred height for windows in pixels, default 760
      -Dz<zeroColourFrac> Sets fraction of largest colour which is to be
                           represented as zero colour, default 0.03
      -E<String> sets operational mode to be that of given name, default Ariadne
                 Options are: Ariadne, MultipleAnalysis, Analysis, NetworkGenerator.
      -Zn<n> Generates network of n sites
      -Zt<t> Generates network of type t
               Type 0:lattice
               Type 1:torus2D
               Type 2:line
               Type 3:torus1D
               Type 4:circle

      -???      This usage screen. Also try ariadne.html for help.
    ...............................................................................

## Distance Metrics

As of 17-12-08, the distance metrics are as follows:-

- 0: plain physical distance.
- 1: sum of individual physical distance/potential using edge values.
- 2: inverse edge value.
- 3: sum of individual physical distance/potential using edge weights.
- 4: inverse edge weight.
- 5: sum of physical distance/potential (but no edge values).

## Influence

### Influence Matrix Definitions

- 3: Raw edge values plus normalised restart vector (normalised site weight vector) to ensure markovian.
- 2: Raw edge values, tadpoles equal to remaining deficit so markovian.
- 1: Default. Normalised edge values (restart vector if deadend), no tadpoles but markovian.
- 0: Raw edge values, no tadpoles, not markovian.

The restart vector is proportional to the site weights.

## Input Files

The input files are infile`_input`. The first few lines contain information, each line starts with a keyword then is followed by the data per site in order. They are separated by white space (spaces, tabs, etc.). Best to use Excel to do this and to save it as `tab separated text file` but make sure it has the ...`_input` file name ending. These lines may be in any order.

- Site names start with keyword `Name` (optional)
- Short site names used for abreviations on the diagrams start with keyword `ShortName` (optional)
- Site sizes start with keyword `Size`
- The x coordinates line starts with `XPos`
- The y coordinates line starts with `YPos`

These coordinates are used to calculate the distances between sites unless this is followed by a line starting with `*Distances` which is followed on succeeding lines by a table of distance values.

The files which are provided are as follows

- `aegeanSL`
  This accesses `aegeanSL_svpdist.dat` which uses the original 19 sites using distances given explicitly. The SL indicates that the distances are real distances (in km here) but then modified by sea/land penalties (1:3 ratio) including further crude approximate alterations to allow for problems of reaching sites on south coast of Crete.
- `aegeanSL`
  This accesses `aegean_svpdist.dat` which again uses the original 19 sites using true distances, no penalties, given explicitly in a table.
- `aegean34`
  This accesses `aegean34_site.dat` which uses the 34 sites given in May 2005. The site locations are taken from the position on the graphical map and converted in km relative positions. The distances are then derived from these positions. There may be a as much as a 5% error in these (e.g. compare to those given for the 19 sites in the `aegean` files). No penalties have been added as yet.
- Geometric files.
  These are names by the type of shape, then the number of sites (total if a 1D shape, as `n_n` for n by n 2D format) and then the distance scale (the nearest neighbour distance). Check the directory but they should include: `circle_30_100.0`, `circle_3_100`, `lattice_3_3_100`, `lattice_6_6_100.0`, `line_30_100.0`, `line_3_100`, `torus1D_30_100.0`, `torus2D_3_3_100` and `torus2D_6_6_10.0__input.dat`. These are generated by the `ariadne` programme from the command line.
- `testsimple`
  This accesses `testsimple_site.dat` which uses 5 imaginary sites separated at scales around 100km. No penalties specified.

The format of the infile`_input.dat` files are as follows. Each entry is separated by white space (tab or spaces). Thus no entry must contain a space. Any spaces in names must be replaced by minus signs or underline characters, or similar. For instance `A_Triadha`, `P-kastro`, `A.Triadha` are all acceptable but `A. Triadha` is not. This file can be read into excel for a simple way to view and edit it. You should save it as a tab separated text file and make sure the file name ends in `SL_svpdist.dat`

First line is `Name` followed by a list of names of the sites in order, so site 1 is first, site 2 is second.

Second line is `Value` followed by the value of the sites in order. These are the fixed 'sizes' of the sites.

Third and fourth lines are the X and Y coordinates of the sites respectively, starting with `XPos` or `YPos` and then followed by a list of the relevant coordinates in order. Any units can be used.

Now this is all that is present in a infile`_site.dat` file. The distances will then be calculated from the positions given. In this case the units of the distances are those used for the positions. However there are two other types of file with further data.

For infile`_svpdist.dat` and infile`_sitepen.dat` files, each remaining line starts with the name of the site (must be in the same order as line 1) followed by a list of distances (infile`_svpdist.dat`) or penalties (infile`_sitepen.dat` ) to the other sites.

Note that the units for distances in infile`_svpdist.dat` can be anything but remember to set the distance scale d_s, the `-s` option, in these units too. The distance need have nothing to do with the coordinates so for instance one can add penalties by making some links longer than their real world distance to reflect additional difficulties for some routes. Further the distance between sites need nt be symmetric, so one can have the return journey being 'longer' (i.e. harder) if one wishes.

On the other hand the distances in infile`_sitepen.dat` are calculated from the coordinates so set the distance scale d_s, the `-s` option, in these units too. However they are then multiplied by a modification factor, the penalty factors read in from the fifth line and beyond. So one can specify a penalties to make some links longer than their real world distance to reflect additional difficulties in that routes, e.g a 3x factor for a land trip. Further the penalties between sites need not be symmetric, so one can have the return journey harder if one wishes.

Example In the following example of a infile`_input.dat` type file there are three sites, all of equal strength.

``

# | This | is a | comment line
Name | A | B | C
Size | 1 | 1 | 1
XPos | 0.1 | 0.2 | 0.3
Ypos | 0.5 | 0.4 | 0.3
*Distances |  |  |
A | 0 | 2 | 3
B | 2 | 0 | 6
C | 3 | 6 | 0

## Output Files

The files produced, given the output file name stem outfile (set using a `-fo` outfile option) are as follows:

outfile_info.dat | Simple text file shoing basic information on input and output parameters.
outfileBareNet.dat | Simple text file suitable for reading into `MAPLE`. The first line starts with a # character and is treated as a comment by `MAPLE`. Line 2 has the number of sites and line 3 has the site values in order (site 1 first). After that line number (3+j) has the values of the edges from site j to sites i in order (site i=1 first column).
outfile_edgevalues.dat | Simple text file containing edge values (e_{ij}).
outfile_colour.dat | Simple text file containing the colour of sites and edges values.
outfile_dijkdist.dat | Simple text file containing the 'distances' between edges as used in the Dijkstra shortest distance algorithm (distance[i][j]). Note that distances are not always defined in terms of the as-the-crow-flies distances or the d_{ij} input distances. In some models a modified distance may be used, e.g. only following links present in the network - a network or island hopping type distance. More complicated definitions may also be used.
outfileBW.net | `pajek` format file using Greyscale scheme. Read this into `pajek` for further analysis or to produce postscript of bitmap (bmp) files of network.
outfileC.net | `pajek` format file using coloured output. Read this into `pajek` for further analysis or to produce postscript of bitmap (bmp) files of network.
outfile_transmat.dat | Transfer Matrix used for calculating the rank of sites. Simple text suitable for `Maple` or `Excel`.
outfile_inflmat.dat | Influence Matrix used for calculating the influence of one site at another. Simple text suitable for `Maple` or `Excel`.
outfile_type.clu | Various integer output values suitable for use as a partition in `pajek` e.g. can be used to colour vertices in `pajek` displays.
outfile_type.vec | Various floating point output values suitable for use as a vector in `pajek` e.g. can be used to give the size of vertices in `pajek` displays.

## Computational Modes

### MC Mode

In this mode the code is run using a Monte Carlo method. A Hamiltonian or cost function, is provided, that is a formula which tells you the energy or cost of a given network, a given set of site sizes and interactions. The lowest energy or cost of the system is found (approximately) by using Monte Carlo. Basically we imagine the system is at high temperature (low beta parameter) so that it is constantly changing like water in kettle at boiling point. Values of sites or edges are changed randomly, but we always keep changes which reduce the energy and only sometimes keep those which raise the energy. The temperature is lowered slowly, the chance of keeping random changes which increase the energy of the system gets less and less. Eventually when the number of changes made falls below some predetermined amount (say 1% of changes are kept), we stop. We assume that the final configuration is a reasonable approximation to the lowest energy state.

### PPA Mode

This is a slight adaptation of the Proximal Point Analysis of Broodbank (see page 80). In this mode we add a total of beta links (the `-b` parameter rounded to nearest integer) from each site to its nearest beta neighbour. However we retain the directionality of the links and we are able to add implicit penalties to certain types of link through the distance matrix. The edges are given weights (colours, thickness of edges) with the shortest from each site given the highest value, next shortest the next highest value etc.

## Summary of Models

For full details of models see the detailed discussions in other documents. Only effects the Monte Carlo mode calculations. The model number is given as j.n which indicates that this is major model type j variation, minor model type n. The latter has no effect if it has not been defined for major model type j.

### Major Model Types

#### Model 1

Basic model. Uses the bare distances between sites provided from the input files (d_{ij}). All sites can be connected to any other. Suitable for continuous edge values or for binary edge values (edges are on or off). See minor models below.

#### Model 2

Uncertain if this is working at the moment.

#### Model 3

Similar to basic model but uses the network distances between sites. The minor model number has several uses here to select different variants of the model. Thus this takes longer to run .

#### Model 4

Uncertain if this is working at the moment.

#### Model 5

Has non-integer powers in Hamiltonian set by b parameter. Working.

### Minor Model Variations

#### Gravity vs Asymmetric Models

If site i is the source, j the target then:

- Model x.0 has a simple trade term (e_{ij}) - symmetric but useless?.
- Model x.1 has a trade term of the form (s_i v_i e_{ij}) - asymmetric, "supply side".
- Model x.2 has a trade term of the form (e_{ij} s_j v_j) - asymmetric, "demand led".
- Model x.3 is a gravity model (s_i v_i e_{ij} s_j v_j ) in the trade term, "supply and demand".

The same is true for any minor number with factors of four added to these numbers, e.g. x.3,x.7,x.11,x.15 etc are all gravity models.

Technically if the lowest bit of the minor model number is 1 (0) it sets the source term in the trade term to be the weight (size*value) of the source site (to be equal to one). If the second lowest bit of the minor model number is 1 (0) it sets the target term in the trade term to be the weight (size*value) of the source site (to be equal to one).

#### Network Distances

This only effects major model 3. If the minor model number is 0 or 1 then the distance fed in from the input files is used to calculate distances in the trade term. Edges with exactly zero edge weights are not used and distances are then these input distances along edges. These models are designed for binary edge values (edges are on or off) so set "Maximum Edge Value" to be 0 (command line option `-e0`).

However if the minor model number is 2 or 3 then the distance between sites is the 'real' distance from the input files divided by the same distance potential used in the trade term.

Technically if the third lowest bit of the minor model number is 1 (0) it chooses network distances (normal real distances).

### Model Recommendations

Models 1.1, 1.2 and 1.3: Major Model 1 should be run in MC mode, with minor models 1,2 and 3 as variations. Designed for continuous edge values (max edge value 1.0 or similar) but can be run in binary edge mode (maximum edge value 0.0).

Models 3.1,3.2,3.3,3.5,3.6,3.7: Major Model 3 should be run in MC mode, with minor models 1,2 and 3 as variations. Models 3.1 and 3.2 are asymmetric, 3.2 is gravity and 3.0 is symmetric but no site weighting in the trade term. These are designed for binary edge values only (max edge value 0.0) as these use the pure distances along network paths between sites to set the overall distance fed into the potential in the trade term. Models 3.7 (gravity) and 3.5, 3.6 (asymmetric) also use network paths but combine the potentials from each leg of the path to give the overall potential. They can be run in binary edge mode (maximum edge value 0.0) or continuous edge mode.

## Command Window Hints

There are various things you can do with the command window.

If you maximise this box (click on the symbol to the left of the X symbol in the top right hand corner) then the command window will run from the top to the bottom of the screen but will not get any wider so you can see more results and you can still see other windows.

If you press the up or down cursor keys you can recall previous commands you typed in.

Any command you type or recall can be edited. Move the cursor using the left and right cursor keys and then type. There are two modes: one where you type over the existing letters, one where you insert new characters. The toggle between these modes by pressing the insert key (sometimes labelled ins).

## Old Screen Shots

Screen shot of MC (Monte Carlo) mode, 1st June 2005, using `aegeanSL` - 19 site data with sea/land adjustment

Screen shot of PPA mode, 1st June 2005, using `aegeanSL` - 19 site data with sea/land adjustment