The package is freely available from the official website www.geos.ed.ac.uk/~lfeng as a tar.gz archive file.  




  This package is developed for a linux operation system. As it involves running a 3-D chemistry transport model with multiple tracers, we assume that the user has access to a workstation with sufficient internal memory (>4 Gb) and free disk space (>300 Gb).


  Many modules in this package have been built over other freely distributed packages and libraries. Before installing this package, following software packages are needed:



   To avoid installing the individual python packages, we recommend to download and install the pre-compiled Enthought python installation of EPD 7.0 (or higher) from www.enthough.com. This Python distribution is free for academic users, and has already included the common python extensions needed by PyOSSE.  


   PyOSSE contains a complete example OSSE system for OCO-like instruments. The example experiment is based on the GEOS-Chem community CTM (v8.02) for which more information is available at wiki.seas.harvard.edu/geos-chem. For PyOSSE, we have provided GEOS-Chem outputs to demonstrate the example.  If you want to use GEOS-Chem directly please consult the wiki for further details on how to download and install the model.  If you choose to download the model the relevant modifications are listed in otool/ESA/example/geos_chem.  



3. Unpacking and compiling


3.1 Unpacking


After downloading the file archive PyOSSE-1.0.tar.gz into your workstation, you can extract the files by using  linux  command:


  tar -zxvf PyOSSE-1.0.tar.gz


There will be 8 sub-directories built under otool/ESA/:


  The contents and purpose of these sub-directories are explained in the Directory and Modules Reference.


  In order to let the user easily read, apply or even change existing modules, we have not developed PyOSSE with any particular version of Python. The user is expected to change python searching path to load this package manually and then build the required shared libraries, following instructions in 3.3 and 3.4


3.2 Setting python searching path


  You can add PyOSSE to python searching path by inserting the following line into your .bashrc file


        export PYTHONPATH=$PYTHONPATH:/your_PyOSSE_directory/


  For some systems, it is also necessary to include runtime libraries for python installation into LD_RUN_PATH  by adding:  


        export  LD_RUN_PATH=$LD_RUN_PATH:/your_python_root/lib


3.3 Build shared libraries


  First, go to subdirectory otool/ESA/util, and change one shell script called ‘f2py_ifort’, by inserting the locations of your python installation and FORTRAN compilers:



FPY=<f2py of your python installation>

LIBPATH=< path for fortran lib>

LIBS=<your fortran libraries>


   Second, build the FORTRAN shared libraries by running the shell script ‘make_share_lib.sh’.  If compilations are successful, there will be 11 shared libraries under sub-directory otool/ESA/util/:













Contents of these libraries can be found in Section 3 for important modules. You can test these libraries by running python scripts test_interpolate.py and test_sigma_pres.py.


3.4 Generate HTML files for module interfaces


   Use build_doc.sh in otool/ESA/ to generate one HTML file for each module that describes its contents and usage. These html files are stored in otool/ESA/doc for future reference.


4.Data set


  You can download otool_data.tar.gz from the ESA-DA official wesite http:/www.esa-da.org .  They are the default data inputs, mainly for supporting complete OSSE examples.  After unzipping the data archive, you have 6 sub-directories under otool_data :  

1. clim_data:  climatology for CO2, CH4 etc profiles

2. ecmwf:  ecmwf cloud analysis.

3. enkf_output:  GEOS-Chem outputs from tagged simulations

4. enkf_rerun:  GEOS-Chem outputs from single tracer run.

5. LAI: surface vegetation type etc.  

6. oco: satellite orbit and data tables for OCO XCO2 averaging kernel and error (Boesch et al., 2011).


 You can now test these data sets, and generate virtual (‘dummy’) observations for OCO satellite, where atmospheric CO2 concentrations are fixed to a CO2 climatology profile, by:


  1) changing DATAPATH in vob_def.cfg under otool/ESA/example/obs_simulation/

  2) running gen_vob.py there.  


  If you want to run GEOS-Chem simulation by yourself, then please consult the wiki for further details on how to download and install the model wiki.seas.harvard.edu/geos-chem, and download GEOS-5 meteorological data at a horizontal resolution of 4º (latitude)×5º (longitude) for 2009. Once the model infrastructure is established, following the guidelines associated with GEOS-Chem, you can run the script ‘test_obs_gen_gc.sh’ for a control calculation.  First, a GEOS-Chem forward simulation will be launched to produce daily 3-D CO2 fields from 2009.01.01 to 2009.01.31. After the CTM forward run, the shell script will call gen_vob.py to generate dummy observations along OCO orbits, which is followed by gen_sob.py to sample CO2 profiles from time-series outputs of the GEOS-Chem simulation.