# 
# Copyright (C) 2010-2012 Platform Computing
# 
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
# 
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
# 
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
# 

Python wrapper for LSF APIs
===========================

This library allows you to call the LSF APIs from Python. The wrapper is created
by using SWIG. Some commands are left out and some typemaps are defined. Still
not all API calls are supported yet. Please see the following list for
tested and support calls.

The following calls are tested and known to work reasonably well:

Included from batch.h
---------------------

  * lsb_init
  * lsb_submit

Included from lsf.h
-------------------

  * ls_info
  * ls_getclustername
  * ls_getmastername
  * ls_gethosttype
  * ls_gethostmodel 
  * ls_gethostinfo
  * ls_loadinfo
  * ls_load
  * ls_loadofhosts

Unknown: ls_getmodelfactor, ls_gethostfactor

Not tested: ls_sharedresourceinfo, ls_placereq, ls_placeofhosts, ls_loadadj, 
            ls_eligible, ls_listrtask, ls_listltask, ls_insertrtask, 
            ls_insertltask, ls_deletertask, ls_deleteltask, all remote 
            execution routines

Convenient routines
-------------------

The following routines where added for your convenience:

  * get_load_of_hosts() - return a list of hostLoad objects
  * get_host_load() - return the current values of the resources of a host - 
                      Possible resource names (Use lsf.<name>) values:
  
        R15S - 15s exponentially averaged CPU run queue length.
        R1M - 1m exponentially averaged CPU run queue  length.
        R15M - 15m exponentially averaged CPU run queue length.
        UT - CPU utilization exponentially averaged over the last 
             minute (from 0.0 to 1.0).
        PG - Memory paging rate exponentially averaged over the last minute, 
             in pages per second.
        IO - Disk I/O rate exponentially averaged over the last minute, 
             in KBytes per second.
        LS - Number of current login users.
        IT - Idle time of the host (keyboard not touched on all logged in
             sessions), in minutes.
        TMP - Available free disk space in /tmp, in MBytes.
        SWP - Amount of currently available swap space, in MBytes.
        MEM - Amount of currently available memory, in MBytes.
  
  * get_host_names() - return the name of the hosts in the cluster
  * get_host_info() - return a list of hostInfo objects

Notes
-----

  * It might be needed to set PYTHONPATH (pointing to the _lsf.so dir) and 
    LD_LIBRARY_PATH correctly (LSF_LIBDIR needs to be included)

  * On solaris use 'export LD_PRELOAD=libsocket.so.1' and 
    '/usr/bin/amd64/python'

  * Why not using ctypes? Because the LSF libs tend to have undefined vars on 
    some platforms. The SWIG approach is more flexible to that issue.

(c) 2010-2012 Platform Computing