yao

Links

From Sources
From Binaries
Installing FFTW3
Compile Yorick on OsX

Examples and Scripts
Performance
Data structures and parfiles
Controlling Features
Screenshots
Algorithms
Yao tk dynamic control
News/Weblog

Installation

4 december 2005: breaking news! The easiest way to install yao is now through the binary plugin installer. See this post for more details.

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:

On a Macintosh G4 or G5:
- From binaries (everything included: yao-3.5_binaries_G4.tar.gz or yao-3.5_binaries_G5.tar.gz)
- From source:
  - Yorick distribution (yorick-1.6.01.tgz) if you don't already have yorick installed.
  - Yao package (yao.tar.gz). This includes ytk.
  - FFTW if you select to run yao_fftw.
On a Linux/Unix machine (from source):
- Yorick distribution (yorick-1.6.01.tgz) if you don't already have yorick installed.
- Yao package (yao.tar.gz). This includes ytk.
- FFTW
On top of that, you will have to have tcltk installed to use yaotk (optional).

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

Install from sources

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.
Once you have yorick compiled, checked and installed (in essence: make config; make; make check; make install;), download yao.tar.gz.
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;).
Copy the graphic style file directory where they belong:
```
cd ~/yorick-1.6/contrib
mv Gist ~/.
```
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
```
Compile the Yao package.
- Apple platforms (G4, G5, 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 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. As for yao_veclib, it basically 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:

Download the tarball yao-3.5_binaries_G4.tar.gz or yao-3.5_binaries_G5.tar.gz and move it to your home directory.
gunzip and untar.
You should now have a yorick-1.06-01 directory, which contains the binary yorick distribution and the yao plugin.
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
```
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. You may want to run the test package to check 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

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.
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"
```
Then:
```
make
make install
```
or sudo make install to install as root.

Compiling Yorick on OsX

These notes apply to Panther. If you are still running 10.2, or the newest version (10.3.4 or higher), compile with the flags indicated below but ignore the HACK103 and FPU_IGNORE setenvs.

10.3.0 to 10.3.3 libm bug:

There is a major bug in the 10.3.0 to 10.3.3 libm that breaks Yorick SIGFPE delivery. I strongly advise to upgrade to 10.3.4 or later if you have the option. Otherwise, here are ways around it (David Munro described it all in this file, I'm just summarizing here):

If you have a G5, you are in luck. Not only you have a fast machine, but one that has a hardware sqrt() function. You still need to use the Hack103 flag to use tanh, ..., that are also broken, but you will be able to use SIGFPE delivery when running Yao.
1. ```
cd ~/yorick-1.6/
setenv HACK103 yes   <-- tcsh
make config
```
2. Edit Make.cfg and change the COPTIONS flag as follow:
```
COPTIONS="-O3 -fomit-frame-pointer -fstrict-aliasing -mcpu=970 -mtune=970 -mpowerpc-gpopt"
```
3. ```
make
make check (X11 need to be started at this point)
make install
```
4. The executable is in ~/yorick-1.5/Darwin-Power_Macinstosh/bin/.
If you have a G4, you will have to give up using SIGFPE delivery (you could keep it if you were using yorick alone, but you are going to link with external libraries and these have no way of being compiled with David Munro's hacked libm functions):
1. ```
cd ~/yorick-1.6/
setenv FPU_IGNORE yes   <-- tcsh
make config
```
2. Edit Make.cfg and change the COPTIONS flag as follow:
```
COPTIONS="-O3 -fomit-frame-pointer -mcpu=7450"
```
3. ```
make
make check (X11 need to be started at this point)
make install
```
4. The executable is in ~/yorick-1.5/Darwin-Power_Macinstosh/bin/.

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 into ~/Yorick. I have also my data directory (the one containing the phase screens for yao, see the Examples & Scripts page) in ~/Yorick/data.