yao

Installation

Installation presupposes a basic familiarity with the command line environment. In the following, I give instructions that should be enough to get you out of troubles.

If you want to install Yao on an Apple machine and do not want to go through the trouble of installing from source, jump here.

Thanks to Yorick, Yao runs on a variety of *nix platforms. The installation ranges from straighforward (installing binaries on an apple platform) to moderately complex. The following gives a summary of what your options are and what you will need to install:

Once you are done with the installation, go to the Examples & Scripts page.

Install from sources

  1. Download the latest Yorick distribution from the yorick site (here is a copy of yorick-1.6.01.tgz). Installation is straighforward (see the README file in the main distribution directory). I suggest you install yorick in ~/yorick-1.6 (just put yorick-1.6.01.tgz in your home directory, gunzip and untar). If you already have yorick installed you may of course skip this last point.
  2. Once you have yorick compiled, checked and installed (in essence: make config; make; make check; make install;, see this link for details on how to compile on OsX machines), download yao.tar.gz.
  3. Create a directory "contrib" in the main yorick directory (~/yorick-1.6/contrib). Put yao.tar.gz in the contrib directory. Gunzip and untar (gunzip yao.tar.gz; tar xvf yao.tar;).
  4. Copy the graphic style file directory where it belongs:
    mv ~/yorick-1.6/contrib/Gist ~/.
    
    or just copy the graphic files into the main distribution directory:
    cp ~/yorick-1.6/contrib/Gist/* ~/yorick-1.6/g/.
    
    at this point you may want to create a yorick user's directory, copy the yao example directory in there and create a directory for the phase screens:
    mkdir ~/Yorick
    cp -pR ~/yorick-1.6/contrib/yao/examples ~/Yorick/examples
    mkdir ~/Yorick/data
    
  5. Compile the Yao package.
    • Apple platforms (anything running OsX):
      • You will need to have a C compiler installed. The vanilla version of OsX does not come with one. Install the Developer tools, normally provided on a CD with your OsX distribution.
      • Yorick's graphics run on Xwindows. You need apple's X11.app or Xfree86 installed and started.
      • cd ~/yorick-1.6/contrib/yao/yao_veclib
      • All instructions to compile and link yao are in the README file. Just cut and paste from there. Note that if you elect to run the FFTW version of yao (I don't see why, as the veclib version is simpler to install and faster), you may have to edit the Makefile to point to your fftw3 include and lib directories. Instructions are in the README file. Basically, the whole process boils down to (you may want to set the environment variable COPTIONS or specify the COPTIONS on the make plugin line, see the README file):
        yorick -batch make.i
        make plugin
        make check-plug
        make install-plug
        
        You will have to edit the Makefile and modify the YORICK_EXE variable to point to the yorick executable (see the README file).
      • You are set.
    • Linux platform:
      • You will need to install FFTW3 before you install Yao. This link will guide you. Once it is done, proceed to the next step.
      • cd ~/yorick-1.6/contrib/yao/yao_fftw
      • All instructions to compile and link yao are in the README file. Just cut and paste from there. It boils down to:
        yorick -batch make.i
        make plugin
        make check-plug
        make install-plug
        
        You will most probably have to edit the Makefile to point to your FFTW3 distribution (you'll need to update YORICK_EXE as well, see README).
      • You are set. Before running yao, you should however go through some initialization of FFTW. On each machine, FFTW can be optimized to run as fast as possible. To do that, the code goes through many (or all) possible factorization for any given array dimension. This has to be done only once. I have written a small routine to do that. Follow this link. If you don't do that I believe yao will still run but in a non-optimized mode (somwwhat slower).

Install the Binaries (Apple only)

The binary distribution includes both yorick-1.6.01, Yao and ytk. Do not install from binaries if you already have yorick installed.

Given the variety of Linux platforms and versions, I do not provide binaries for Linux. Also, Yao on Linux needs FFTW, which is a pretty big download which I did not want to include in a binary distribution. In any case, it's much better that you compile the package on your own platform to get the best results.

The following will install Yorick and Yao:

  1. Download the tarball yao_mac_binaries.tgz and move it to your home directory.
  2. gunzip and untar.
  3. You should now have a yorick-1.06-01 directory, which contains the binary yorick distribution and the yao plugin.
  4. For convenience, you should create a symlink to the yorick executable somewhere in your path, e.g. (I have mine in ~/bin):
    cd ~/bin
    ln -s ~/yorick-1.6-01/bin/yorick ./yorick
    
  5. You are done. Test it:
    • In a terminal, type "rehash" (if you have tcsh) or open a new Terminal/xterm to make you shell aware of the newly created "yorick" file
    • type "yorick". You should get this message:
      % yorick
       Copyright (c) 1996.  The Regents of the University of California.
       All rights reserved.  Yorick 1.6.01 ready.  For help type 'help'
      > 
      
      If you do, you are in business. Type "quit" to exit yorick. You may want to run the test package to check that everything runs smoothly:
      cd ~/yorick-1.6-01/contrib/yao/examples
      yorick -batch test-all.i
      
      This might take a few minutes. It first creates phase screen for the simulations and then run a few test cases (shack-hartmann and curvature systems, with NGS and LGS). If all goes well, it should end with the message "All Tests OK". You can proceed with the Examples and Scripts page

Installing FFTW3

  1. The package can be obtained from www.fftw.org. Download the vectorial version (Enabling the use of SIMD or Altivec), fftw-3.0.1-fma.tar.gz. Gunzip and untar.
  2. Configure and compile. You have to use special compilation flags to enable the use of the vectorial processor on your machine (if you have any). Also, you have to enable fftw3f, i.e. float operation (yao uses floats for FFTs). --enable-float enables float operations.

    If you don't have root privilege, you can install fftw3 locally. Use the --prefix to do that (see an example below)

    Each machine takes different flags. A good resource to find out which one you should use is the speed benchmark pages at fftw.org (http://www.fftw.org/speed/) i.e. http://www.fftw.org/speed/g5-2GHz/ for the G5.

    For an Dual Ahtlon, I used:

    ./configure --enable-float --enable-k7 CFLAGS="-O2 -fomit-frame-pointer -Wall -W
      -Wcast-qual -Wpointer-arith -Wcast-align -pedantic -malign-double -fstrict-aliasing
      -mpreferred-stack-boundary=4 -mcpu=pentiumpro" -prefix="/home/frigaut/fftw3/"
    The -prefix="/home/frigaut/fftw3/" points to the local installation directory. Use this if you don't have the root password to install stuff in /usr/local/ on your system. If you do have root privileges, you might as well not use the --prefix flag and run the make install as root, which will install fftw3 in /usr/local.

    For a G5, I use:

    ./configure --enable-float --enable-altivec CFLAGS="-O3 -fomit-frame-pointer 
      -fstrict-aliasing -mcpu=970 -mtune=970 -mpowerpc-gpopt"

    For a G4:

    ./configure --enable-float --enable-altivec CFLAGS="-O3 -fomit-frame-pointer 
      -mcpu=7450 -faltivec"
  3. Then:
    make
    make install
    
    or sudo make install to install as root.

Compiling Yorick on OsX

These notes apply to Panther. I haven't tested it with 10.2, but there should be no major issues.

You will need to have a C compiler installed. The vanilla version of OsX does not come with one. Install the Developer tools, normally provided on a CD with your OsX distribution.

Note: if you are using a Panther version < 10.3.4, there is a bug in the system libm that breaks yorick SIGFRE delivery (ability to detect and thus prevent NaNs). I strongly advise to upgrade to 10.3.4 or later if you have the option. Otherwise, there are ways around it (David Munro described it all in this file). I'm not going to expand on it further, as this has been fixed since 10.3.4.

The process of building Yorick is otherwise very simple. Basically, you do:

cd ~/yorick-1.6/
make config
make
make check (X11 need to be started at this point)
make install

The executable is in ~/yorick-1.6/Darwin-Power_Macinstosh/bin/.

You can gain a few percent speed by tweaking some flags during the compilation. Use:

make COPTIONS="some flags"

Alternatively, you can edit Make.cfg after the make config, or you can set the environment variable CFLAGS before doing the make config.

I personaly use

COPTIONS="-O3 -fomit-frame-pointer -fstrict-aliasing -mcpu=970 -mtune=970 -mpowerpc-gpopt"
for the G5, and
COPTIONS="-O3 -fomit-frame-pointer -mcpu=7450"
for the G4. Back to "Installation from Sources".

Running FFTW_wisdom

If you are running using FFTW, you need to initialize/optimize FFTW for your hardware (valid only on one machine!). Start yao. The first time you run it, you should have the following message :
frigaut:yao_fftw% ./yao
 I did not find a fftw_wisdom.dat file in ~/Yorick/
 When you have a minute (actually it takes several hours), run:

 init_fftw_wisdom; (default)

 or init_fftw_wisdom,nlimit; (run optimization up to n^nlimit)

 Copyright (c) 1996.  The Regents of the University of California.
 All rights reserved.  Yorick 1.6.01 ready.  For help type 'help'
> 

At this time you can choose to do it (run init_fftw_wisdom). Because it can take several hours, you can also choose to postpone it to the next night. But you will need to run before doing any serious work with yao (fftw version). To test if everything is okay, you can run now init_fftw_wisdom up to a low power of 2, e.g.

> init_fftw_wisdom,8

which will optimize fftw for array up to 128x128. That will get you going. Remember that when you have time, you should run the full monty (init_fftw_wisdom). Before you can run init_fftw_wisdom again, you need to delete the fftw_wisdom file (~/Yorick/fftw_wisdom.dat).

A note on directory organization

As already said, I advise to install yorick in ~/yorick-1.6

The root directory of Yao is in ~/yorick-1.6/contrib/yao

You will have to create ~/Yorick, which is the yorick user directory. It is convenient to put every yao user files in there. For instance, you can copy the yao/examples directory somewhere in ~/Yorick. I have also my data directory (the one containing the phase screens for yao, see the Examples & Scripts page) in ~/Yorick/data.

Page updated on UT $Date: 2007/12/12 23:29:15 $

Valid CSS!