SOLAR Eclipse General Version 8.1.1

1. Speed improvements in all SOLAR operations thanks to improved
   compiler optimization.  Polygenic runs 1.73 times faster compared
   with previous official version 7.6.4.  The biggest improvement is
   in C++ intensive mathmatrix operations based on Eigen; as a
   result of this and other changes "fphi -p" is now 25 times faster
   than in version 8.0.6.

2. The implentation of fphi p value estimation, working since 8.0.6,
   is made cleaner and slightly faster.  The use of a new mathmatrix
   operation PermuteY which eliminates the need to create an
   intermediate shuffled vector for each column of the permuted
   matrix (as had been done in 8.0.6).  Far fewer temporary matrices
   are created.  These changes had only a small effect on speed
   compared with the improved compiler optimizations.

3. fphi p value estimation now uses better random numbers to shuffle the
   Y matrix: Mersenne Twister mt19937 which has a period of 2^19937.
   AFAIK this is the best quality fast random generator available, and
   it is included in the recent C++11 standard so is widely available.

4. fphi p value calculation numerator was off by one.  Now p values
   from "fphi -p" are slightly smaller (better).


5. Other changes to fphi: Tcl code is cleaned up with much junk removed,
   variables given meaningful names, obsolete -method argument
   removed, -testonly is now called -indicator.

6. option ShuffleReseeding controls how the mt19937 random number
   generator used for matrix shuffling is seeded.  The default value
   is 1 which means the generator is reseeded to the default value
   5489u at the beginning of each matrix shuffle operation.  This
   gives consistent p value results every time, and the most
   comparable results when the same sample is used across a range of
   models.  The options are:
       1...seeded on every shuffle to 5489u for consistent results (DEFAULT)
       0...seeded first shuffle to 5489u, then free running
      -1...seeded every shuffle to time() for purely stochastic results
      -2...seeded first shuffle to time(), then free running
       Other values: seed to this value at beginning of each shuffle

7. Errors in test models in mga (either the regular test model or the
   interaction test model) would cause mga to exit.  Now such errors are
   reported to the screen and a line with SNP name but blank results is
   written to the output file.


8. option MatrixNumberFormat controls the formatting precision of numbers
   output by matrix operations such as "show".  The default of 15 eliminates
   long unrounded numbers such as 0.4999999999999999.


9. This version is the first ever to have a public source code
   release, along with the usual binary releases for Linux, Mac, and
   Microsoft Windows.  The binary releases are fully tested and
   replace Official Version 7.6.4 on the general download links at
   http://solar.txbiomedgenetics.org.  Due to the now distributed
   nature of SOLAR Eclipse development, this release is not called
   Official but instead General as in intended-for-general-use.  An
   Official version with coordinated updates from all developers may
   be available soon.
        

SOLAR Eclipse General Version 8.1.1 for Windows

Requires Microsoft Windows 7 or later, and VMware player (a free download),
plus about 10Gb diskspace for installation. Because SOLAR requires a Unix
OS or equivalent, we have prepared a VMware Virtual Machine containing SOLAR
plus the Xubuntu edition of linux which runs on Windows XP or later using the
free VMware Player. Beware this requires a very large multi 1.4 Gb download, and
will require more than 10 gigabytes free disc space during installation.
Installation requires the folowing steps:

1. Obtain and install VMware Player for Windows. This is a free download from VMware at
   www.vmware.com/products/player

2. Extract the compressed files.  The current 6.2.2 release is distributed in
   old compatible PC zip format.  With Windows XP you can use any standard
   unzip program.  With Windows Seven and later, you can simply select the
   solar_windows folder, hold down the right mouse button and choose "Extract
   Files".  You may extract the files anywhere you choose, but remember where you
   did for the next step.

3. Start the VMware player, select Open a Virtual machine then point its file
   browser to the folder where you extracted solar_windows.  Click on the
   extracted solar_windows folder, and then click on the solar_windows
   folder inside that one.  There you will see the virtual machine named
   xubx.vmx highlighted by VMware.  Select that.

4. VMWare will show a picture of the virtual machine in shutdown.  Press the green
   Play button to get it started again.

5. A Xubuntu window will appear, and after it boots up you will be promted to
   log in. Use username bagside and password bagside.  The Xubuntu
   virtual machine was originally compiled by a linux expert who calls himself
   "bagside" online.

6. The Desktop has two special icons for use with SOLAR.  The SOLAR icon runs
   SOLAR alone inside a unix terminal.  When you exit from SOLAR the terminal
   closes.  The Terminal icon runs a terminal from which you can start SOLAR with
   the command solar.  When you exit from SOLAR, you will still
   be in the shell and can give additional unix commands or even start another
   solar session later.  This latter approach is the typical way users run SOLAR on
   other systems and is more recommended.  You can also create a terminal window
   starting from the Xubuntu Applications menu:
   Applications->Accessories->Terminal.  This is the menu for the Xubuntu Virtual
   Machine, not your Windows system, so sometimes it can get obscured by the
   vertical position of the window.  7. The first time you run SOLAR, a message
   will appear saying you are not registered, and describing how you can get a key
   to run SOLAR.  Scroll to the bottom of that message by pressing return a few
   times.  At the end, you will get a solar> prompt indicating you can now
   enter more commands.

7. When you get your key, run SOLAR as above but now
   enter the command register followed by your key.  It should return
   success, and you are now ready to run solar.

8. To copy data from Windows
   into the Xubuntu virtual machine, we suggest getting a USB flash drive.  First
   mount the drive when your mouse is pointing to the Windows desktop, and copy
   your data to the drive.  Then unplug the drive. Point your mouse to the Xubuntu
   virtual machine and plug the drive back in.  It will now appear in the Xubuntu
   desktop, and you can copy files from it.  All data files should be written from
   Windows into comma separated (.csv) text files with a header line at the
   beginning.  Most Windows applications can do this directly.  SOLAR does not work
   with any proprietary Windows data formats such as .doc

9. When you close the Xubuntu window, you should choose to suspend the
   virtual machine state, which is the default, for fastest restart next time.
   Then the next time you start it, everything will be exactly the same as when
   you left, even if Windows itself has restarted in the meantime.  If you wish
   to reboot Xubuntu the next time you start it, you must shut down from the
   Xubuntu user menu.  If somehow you corrupt your virtual machine and have
   deleted the downloaded distribution file, you may download a fresh copy
   here.
    

SOLAR Eclipse General Version 8.1.1 for Mac

Requires Intel Mac and 40 megabytes (MB) of hard drive space for installation.
This is for Intel Macs only. For PowerPC Macs, go back and make correct selection.
If you have enabled "right click" for your Mac mouse, it is best to
right click and choose which folder to copy the downloaded archive to.
In that case, it would be good to create a folder named "solar" (or
whatever seems best) in your home folder, and copy the archive to
that.

If you have not enabled "right click" generally the archive will be
downloaded to your Downloads folder, from which you could move it to a
"solar" folder.  Depending on browser settings (Open Safe Files), the
archive may be unzipped or not while being downloaded, but we can take
care of both possibilities later.

As on other operating systems, SOLAR must be installed and run from a
terminal window.  So, first open a terminal
window(Applications->Utilities->Terminal).  If you wish to run SOLAR
regularly, it would be good to add the Terminal app to your Dock.

Once the terminal is opened, type the "cd" command to move to the solar
folder, and give the "ls" command to see what file(s) are there.


  cd solar
  ls


You will either see "solar_mac_intel.tar" which is the unzipped file,
or "solar_mac_intel.tar.gz" which is the zipped file.  If you see
the zipped file, ending with ".gz", use this command to unzip it:


  gunzip solar_mac_intel.tar.gz


Now you should have the file "solar_mac_intel.tar".  This is a "tarfile"
which must be unpacked.  You can do that with the following "tar"
command:


  tar -xf solar_mac_intel.tar


Now give the ls command, and you will see a number of files.  
Among the unpacked files, there is a README file which gives further
information, and the script install_solar which actually
installs the package.  if you run with no arguments like
this: ./install_solar it will explain how you can install the
solar files nearly anywhere.  However if you have created the "solar"
folder as described above, you can simply do that with this command:


  ./install_solar `pwd` `pwd`


being sure to use the 4 backtick characters exactly as shown above.
Backtick is the shorthand name given to this character which is also
called Grave Accent and is usually located on the same keyboard key as tilde (~).
Enclosing the letters "pwd" inside two backtick characters is a
shorthand way of referring to the folder that you are currently in,
known in Unix as "the working directory."  If this is too tricky, you
can simply print out the working directory name with a "pwd" command,
and then just enter that twice following "./install solar" and
separated by spaces.

Once you have run the "install_solar" command, it has created a new
program called "solar" but you also need the terminal environment to
recognize it.  To do that, you will need a file named ".profile" in
you home folder which adds the "solar" folder to the "program search
path".

The file required is very simple but must be created with a text
editor, which not all Mac users know how to use.  So we have included
a simple .profile file in the solar archive which you can simply copy
to your home folder instead.  But first you want to be sure you do not
already have a .profile file needed for something else.  Give this
command to find out.


  ls -a ~/.profile


If you already have a .profile file, you will need to modify it to add
"~/solar" to your path.  Contact [email protected] for
help.  Otherwise, you can simply copy the new .profile file straight
into your home folder with this command:


  cp script/.profile ~


Now you can run "solar" from the terminal from any folder.  Return to
the home folder and run solar:


  cd ..
  solar


Nothing useful is accomplished by clicking on the solar icon at this
time.  Just close any window that may open if you do that.  Once SOLAR is
installed, each new user should obtain a registration key as is explained by the
message that appears when they start SOLAR.