------------------------------------------------------------
Curvature Wavefront Sensing (CWFS) Software v1.0
------------------------------------------------------------

    This software package consists of a set of Python codes that take a pair of defocused star images equally spaced on both sides of the optical focus, and calculate the incoming wavefront. The underlying baseline algorithms implemented are the iterative FFT method by the Roddiers and the series expansion based method by Gureyev and Nugent. We have made several modifications to make them work for LSST, to overcome challenges including a highly obscured pupil, the fast f-number, pupil distortion and vignetting at the field corners, and variation of the wavefront over the area covered by the split-sensors.
	    
    Please reference Xin et al., Appl. Opt. 54, 9045-9054 (2015). 

    Note that the off-axis corrections and pupil geometry as functions of field position are specific to each telescope. We have modelled these for LSST. The data can be found in data/lsst/. It may require some additional work to model these properly for your application.
	
    Authors:    Bo Xin, Chuck Claver
Large Synoptic Survey Telescope (LSST)

We'd like to thank Andy Connolly and Michael Reuter for the help with Python programming.
	
-------------
INSTALLATION:
-------------

    The code has been tested under:
    - Python 2.7.10
    - Python 3.4.3

    The following modules are needed:
    NumPy
    SciPy
    Astropy (for reading in fits images)
    Matplotlib (for making plots)

    You need to add "$PWD/python/lsst/cwfs" to your $PYTHONPATH.
	(or, you can simply do
	. ./bin/setupEnv)
	
------
USAGE#1: (on command line)
------

    To show the help message
    
    ./bin/cwfs -h

    usage examples:

    ./bin/cwfs z11_0.25_intra.txt z11_0.25_extra.txt -dir tests/testImages/LSST_NE_SN25 -ixy 1.185 1.185 -exy 1.185 1.185 -m offAxis -a exp -d -1

------
USAGE#2: (in Python environment)
------

    Please see the the two iPython notebooks in the examples directory:
	example1.ipynb
	example2.ipynb

    example1.ipynb shows how a user defines the two defocused images, the instrument, the algorithm, then run everything with the default settings.
    	
    example2.ipynb shows a more complex work session, where the user runs the iterations manually, and examine the results after each iteration.
	
------------
Directories:
------------

    bin               executables
    data              all input data (instrument specific data and algorithm parameters)
    examples          example jupyter notebooks
    python/lsst/cwfs  all source files 
    ups               files needed to use cwfs with the LSST stack
    tests             unit tests
    tests/testImages        intra and extra images on which you may run some initial tests
    tests/validation	    Matlab Results using test images in tests/testImages.
    			    	   These are used by tests/testValidation.py
    
-----------
Other Files
-----------

    COPYING                 license file
    README                  this file
    SConstruct		    used by LSST's build system, scons

    bin/cwfs                main script
    bin/setupEnv            bash command to set up the python environment needed (must be sourced)
    
    tests/SConscript	    used by LSST's build system, scons
    tests/testValidate.py   Python script for validation tests (compare to Matlab results);
    			    uses tests/validation.  Designed to be run from home directory,
			    or (more usually) via the unittest framework.