APO software README file

-------------------------------------------
                   CONTENTS
-------------------------------------------
1. INSTALLATION
2. TEST
3. INPUT/OUTPUT FILES = CONFIGURATION FILES
4. VISUALIZATION WITH IDL ROUTINES
5. EXISTING PROGAMS
-------------------------------------------

1.INSTALLATION
--------------

* APO is a C++ library

* the software can be downloaded from
  http://aramis.obspm.fr/~boone/arraydesign/software/

* to unpack: 
        $ gunzip APO-2.tar.gz
        $ tar xvf APO-2.tar

* if not already installed on your computer 
  create the cfitsio library:
        $ cd APO-2
        $ gunzip cfitsio2401.tar.gz
        $ tar xvf cfitsio2401.tar
        $ cd cfitsio
        $ ./configure
        $ make
        $ cd ..
  In case of troubles consult the doc:
   cfitsio/fitsio.ps

* if the library is already installed somewhere on 
  your computer remove the package:
        $ cd APO-2
        $ rm cfitsio2401.tar.gz
  and specify the correct path in the corresponding 
  line of APO.h: Replace
  #include "cfitsio/fitsio.h"
  with your path to the library from the APO-2 directory.

2. TEST
-------

* compile the testAPO.cpp program:
        $ make testAPO       

* execute the program:
	$ ./testAPO -i cpct.conf -o cpct_out.conf

  this will take the configuration file cpct.conf and 
  optimize it with only 2 iterations. 
  The result is written in the config file cpct_out.conf.
  Note: the result is not supposed to be of good quality here:
  most of the parameters are not optimaly set. This step 
  is only aimed at checking the library.

* having a look at the testAPO.cpp file can be usefull for
  learning how to use the APO library. It doesn't use
  all the capability of the library but gives a first idea
  on how to build an optimization program.

3. INPUT/OUTPUT FILES = CONFIGURATION FILES
-------------------------------------------

* All the parameters required to define the instrument
  (class Instrume) the observation situation (class Obs)
  etc.. can be given in the optimization program and
  only the resulting antenna locations can be listed in
  a file.
  It is however much easier and lighter for the writting of
  optimization programs to use input and output files as defined
  by the class Configfile.

* A Configfile is an ascii file containing all the informations 
  about the instrument to be optimized, the observation situation,
  and the site.
  A description is given at:
  http://aramis.obspm.fr/~boone/arraydesign/software/inputfile.html
  
  You can also have a look at the cpct.conf and cpct_out.conf files.

* The lines in testAPO.cpp related to the Configfiles are the following:

  Configfile filei, fileo;     
  ...

  filei=namei;
  fileo=nameo;
  filei.read(&alma, &Chaj, &obs1, &mod1);  
  ...

  fileo.write(&alma, &Chaj, &obs1, &mod1);

  They are explained below:

  + Configfile filei, fileo;
    Instantiate the class Configfile twice.
    One instantiation is named filei and the other fileo.

  + filei=namei;
    filei is related to the file which name is 
    the string that was entered in the command 
    line after the -i option (contained in the
    namei variable):
    	$ ./testAPO -i cpct.conf -o cpct_out.conf

  + fileo=nameo;
    fileo is related to the file which name is 
    the string that was entered in the command 
    line after the -o option (contained in the
    nameo variable):
    	$ ./testAPO -i cpct.conf -o cpct_out.conf

  + filei.read(&alma, &Chaj, &obs1, &mod1);
    initialize the parameters of the instrument alma,
    the site Chaj, the observation situation obs1 and
    the model (gaussian) mod1 from the informations
    contained in the file to which filei is related.  

  + fileo.write(&alma, &Chaj, &obs1, &mod1);
    write the parameters of the instrument alma,
    the site Chaj, the observation situation obs1 and
    the model (gaussian) mod1 into the configfile
    to which fileo is related. The file is overwritten 
    or created if necessary.

4. VISUALIZATION WITH IDL ROUTINES
----------------------------------

* Unfortunately the APO library has not 
  its own graphic interface yet.
  But IDL routines to visualize
  the configurations. 
  They are in the APO-2/idl directory.
 
* To view the configfile cpct.conf:
	$ cd APO-2/idl
	$ idl
	IDL> .r plotAPO1
	IDL> plotAPO1,'../cpct.conf'

* To plot it in a Postscript file named cpct.ps:
	IDL> plotAPO1,'../cpct.conf','../cpct.ps'

* To plot it in a Postscript file named cpct.ps,
  but in black and white:
	IDL> plotAPO1,'../cpct.conf','../cpct.ps',1

* To plot it in a Postscript file named cpct.ps,
  in color but without the header:
	IDL> plotAPO1,'../cpct.conf','../cpct.ps',0,1

* Note: if the configfile requires a digital mask in
        a fits file. The fits file should be copied in
        the idl directory (or linked : 
	$ ln -s ../file.fits)

5. EXISTING PROGAMS
-------------------

* Some programs already exist for the optimization
  of interferometer arrays, e.g.:

  + cpct.cpp
    optimize a compact configuration

  + optimize.cpp
    optimize a single configuration or several configurations
    for a single observation (multiconfiguration observation).

  + optimizearray.cpp
    optimize several configurations, each one for a given
    scientific goal defined in a file ScGoals.data.  

* to compile:
  	$ make cpct (or optimize or optimizearray)
      
* to get help:
        $ ./cpct (or ./optimize or ./optimizearray)

* Note: if the configfile requires a digital mask
  for the topographic constraints is should be in
  the APO-2 directory.

==================================================
   IMPORTANT NOTE:
Since version APO-2 the digital topographic 
mask should equal:
	1 where the antennas are allowed
        0 where the antennas are forbidden
(this is the convention for the ALMA topographic
masks)