Added docstrings for OpenMP runtime.

src/wrf/extension.py

@@ -926,7 +926,7 @@ def _wdir(u, v, outview=None):
     return result
 
 
-# OpenMP wrappers
+# OpenMP runtime wrappers
 
 def omp_set_num_threads(num_threads):
     """Specify the number of threads to use.
@@ -1041,8 +1041,8 @@ def omp_get_num_procs():
 
 
 def omp_in_parallel():
-    """Returns 1 if the active-levels-var ICV is greater than zero; otherwise, 
-    it returns 0.
+    """Return 1 if the active-levels-var ICV is greater than zero; 
+    otherwise, return 0.
     
     The effect of the omp_in_parallel routine is to return 1 if the current 
     task is enclosed by an active parallel region, and the parallel region is 
@@ -1063,7 +1063,7 @@ def omp_in_parallel():
 
 
 def omp_set_dynamic(dynamic_threads):
-    """Enables or disables dynamic adjustment of the number of threads 
+    """Enable or disable dynamic adjustment of the number of threads 
     available for the execution of subsequent parallel regions by setting the 
     value of the dyn-var ICV.
     
@@ -1092,13 +1092,13 @@ def omp_set_dynamic(dynamic_threads):
 
 
 def omp_get_dynamic():
-    """Returns the value of the dyn-var ICV, which determines whether
+    """Return the value of the dyn-var ICV, which determines whether
     dynamic adjustment of the number of threads is enabled or disabled.
     
     This routine returns 1 if dynamic adjustment of the number of threads 
     is enabled for the current task; it returns 0, otherwise. If an 
     implementation does not support dynamic adjustment of the 
-    number of threads, then this routine always returns false.
+    number of threads, then this routine always returns 0.
     
     Returns:
     
@@ -1114,98 +1114,494 @@ def omp_get_dynamic():
 
 
 def omp_set_nested(nested):
+    """Enable or disable nested parallelism, by setting the nest-var ICV
+    
+    For implementations that support nested parallelism, if the argument to 
+    omp_set_nested evaluates to True, nested parallelism is enabled for the 
+    current task; otherwise, nested parallelism is disabled for the current 
+    task. For implementations that do not support nested parallelism, this 
+    routine has no effect: the value of nest-var remains False.
+    
+    Args:
+    
+        dynamic_threads (:obj:`bool`): Set to True to support nested 
+            parallelism, otherwise False.
+    
+    Returns:
+    
+        None
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_nested`
+    
+    """
     fomp_set_nested(nested)
 
 
 def omp_get_nested():
+    """Return the value of the nest-var ICV, which determines if nested 
+    parallelism is enabled or disabled
+    
+    This routine returns 1 if nested parallelism is enabled for the current 
+    task; it returns 0, otherwise. If an implementation does not support 
+    nested parallelism, this routine always returns 0.
+    
+    Returns:
+    
+        :obj:`int`: Returns 1 if nested parallelism is enabled, otherwise 0.
+        
+    See Also:
+    
+        :meth:`wrf.omp_set_nested`
+    
+    """
     return fomp_get_nested()
 
 
 def omp_set_schedule(kind, modifier):
+    """Set the schedule that is applied when *runtime* is used as 
+    schedule kind, by setting the value of the run-sched-var ICV.
+    
+    The effect of this routine is to set the value of the run-sched-var ICV 
+    of the current task to the values specified in the two arguments. The 
+    schedule is set to the schedule type specified by the first argument kind. 
+    It can be any of the standard schedule types or any other implementation 
+    specific one. For the schedule types static, dynamic, and guided the 
+    chunk_size is set to the value of the second argument, or to the default 
+    chunk_size if the value of the second argument is less than 1; for the 
+    schedule type auto the second argument has no meaning; for implementation 
+    specific schedule types, the values and associated meanings of the second 
+    argument are implementation defined.
+    
+    Args:
+    
+        kind (:obj:`int`):  Must be :data:`wrf.OMP_SCHED_STATIC`,
+            :data:`wrf.OMP_SCHED_DYNAMIC`, :data:`wrf.OMP_SCHED_GUIDED`, 
+            or :data:`wrf.OMP_SCHED_AUTO`.
+            
+        modifier(:obj:`int`): An implementation specific value, depending on 
+            the choice for *kind*. This parameter is alternatively named 
+            chunk_size in some OpenMP documentation.
+    
+    Returns:
+    
+        None
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_schedule`
+    
+    """
     fomp_set_schedule(kind, modifier) 
 
 
 def omp_get_schedule():
+    """Return the schedule that is applied when the runtime schedule is used.
+    
+    This routine returns the run-sched-var ICV in the task to which the routine 
+    binds. The first item is the schedule kind, which will be one of 
+    :data:`wrf.OMP_SCHED_STATIC`, :data:`wrf.OMP_SCHED_DYNAMIC`, 
+    :data:`wrf.OMP_SCHED_GUIDED`, or :data:`wrf.OMP_SCHED_AUTO`.  The second 
+    item returned is the modifier, which is often named chunk_size in 
+    OpenMP documentation.
+    
+    Returns:
+    
+        :obj:`tuple`: The first item is an :obj:`int` for the schedule *kind*.
+        The second items is :obj:`int` for the *modifier* (chunk_size).
+        
+    See Also:
+    
+        :meth:`wrf.omp_set_schedule`
+    
+    """
     return fomp_get_schedule()
 
 
 def omp_get_thread_limit(): 
+    """Return the maximum number of OpenMP threads available to participate in 
+    the current contention group.
+    
+    The omp_get_thread_limit routine returns the value of the thread-limit-var 
+    ICV.
+    
+    Returns:
+    
+        :obj:`int`: The number of OpenMP threads available to participate in 
+        the current contention group.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_max_threads`
+    
+    """
     return fomp_get_thread_limit()
 
 
 def omp_set_max_active_levels(max_levels):
+    """Limit the number of nested active parallel regions on the device, 
+    by setting the max-active-levels-var ICV.
+    
+    The effect of this routine is to set the value of the max-active-levels-var 
+    ICV to the value specified in the argument. If the number of parallel 
+    levels requested exceeds the number of levels of parallelism supported by 
+    the implementation, the value of the max-active-levels-var ICV will be set 
+    to the number of parallel levels supported by the implementation. This 
+    routine has the described effect only when called from a sequential part 
+    of the program. When called from within an explicit parallel region, the 
+    effect of this routine is implementation defined.
+    
+    Args:
+    
+        max_levels (:obj:`int`):  The maximum number of nested active parallel
+            regions.
+            
+    Returns:
+    
+        None.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_max_active_levels`
+    
+    """
     fomp_set_max_active_levels(max_levels) 
 
 
 def omp_get_max_active_levels():
+    """Return the value of the max-active-levels-var ICV, which determines 
+    the maximum number of nested active parallel regions on the device
+    
+    The omp_get_max_active_levels routine returns the value of the 
+    max-active-levels-var ICV, which determines the maximum number of nested 
+    active parallel regions on the device.
+            
+    Returns:
+    
+        :obj:`int`: The maximum number of nested active parallel regions.
+        
+    See Also:
+    
+        :meth:`wrf.omp_set_max_active_levels`
+    
+    """
     return fomp_get_max_active_levels()
 
 
 def omp_get_level():
+    """Return the value of the levels-var ICV.
+    
+    The effect of the omp_get_level routine is to return the number of nested 
+    parallel regions (whether active or inactive) enclosing the current task 
+    such that all of the parallel regions are enclosed by the outermost initial 
+    task region on the current device.
+    
+    Returns:
+    
+        :obj:`int`: The number of nested parallel regions.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_active_level`
+    
+    """
     return fomp_get_level()
    
                           
 def omp_get_ancestor_thread_num(level):
+    """Return, for a given nested level of the current thread, the thread 
+    number of the ancestor of the current thread.
+    
+    The omp_get_ancestor_thread_num routine returns the thread number of the 
+    ancestor at a given nest level of the current thread or the thread number 
+    of the current thread. If the requested nest level is outside the range of 
+    0 and the nest level of the current thread, as returned by the 
+    omp_get_level routine, the routine returns -1.
+    
+    Args:
+    
+        level (:obj:`int`):  The nested level of the current thread.
+    
+    Returns:
+    
+        :obj:`int`: The thread number of the ancestor at a given nest level 
+            of the current thread.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_max_active_levels`, :meth:`wrf.omp_get_level`
+    
+    """
     return fomp_get_ancestor_thread_num(level)
 
 
 def omp_get_team_size(level):
+    """Return, for a given nested level of the current thread, the size 
+    of the thread team to which the ancestor or the current thread belongs
+    
+    The omp_get_team_size routine returns the size of the thread team to which 
+    the ancestor or the current thread belongs. If the requested nested level 
+    is outside the range of 0 and the nested level of the current thread, as 
+    returned by the omp_get_level routine, the routine returns -1. Inactive 
+    parallel regions are regarded like active parallel regions executed with 
+    one thread.
+    
+    Args:
+    
+        level (:obj:`int`):  The nested level of the current thread.
+    
+    Returns:
+    
+        :obj:`int`: The size of the thread team.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_ancestor_thread_num`
+    
+    """
     return fomp_get_team_size(level)
 
 
 def omp_get_active_level():
+    """Return the value of the active-level-vars ICV.
+    
+    The effect of the omp_get_active_level routine is to return the number of 
+    nested, active parallel regions enclosing the current task such that all 
+    of the parallel regions are enclosed by the outermost initial task region 
+    on the current device.
+    
+    Returns:
+    
+        :obj:`int`: The number of nested activate parallel regions.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_team_size`
+    
+    """
     return fomp_get_active_level() 
 
 
 def omp_in_final():
+    """Return 1 (True) if the routine is executed in a final task region; 
+    otherwise, it returns 0 (False).
+    
+    Returns:
+    
+        :obj:`int`: Return 1 if the routine is executed in a final task 
+        region, 0 otherwise.
+    
+    """
     return fomp_in_final()
 
 
 def omp_init_lock():
+    """Initialize a simple OpenMP lock.
+    
+    Returns:
+    
+        :obj:`int`:  An integer representing the lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_init_nest_lock`, :meth:`wrf.omp_destroy_lock`
+    
+    """
     return fomp_init_lock()
 
 
 def omp_init_nest_lock():
+    """Initialize a nestable OpenMP lock.
+    
+    Returns:
+    
+        :obj:`int`:  An integer representing the nestable lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_init_lock`
+    
+    """
     return fomp_init_nest_lock()
 
 
 def omp_destroy_lock(svar):
+    """Destroy a simple OpenMP lock.
+    
+    This sets the lock to an uninitialized state.
+    
+    Args:
+    
+        svar (:obj:`int`):  An integer representing the lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_destroy_nest_lock`, :meth:`wrf.omp_init_lock`
+    
+    """
     fomp_destroy_lock(svar)
 
 
 def omp_destroy_nest_lock(nvar):
+    """Destroy a nestable OpenMP lock.
+    
+    This sets the lock to an uninitialized state.
+    
+    Args:
+    
+        nvar (:obj:`int`):  An integer representing the nestable lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_destroy_lock`, :meth:`wrf.omp_init_nest_lock`
+    
+    """
     fomp_destroy_nest_lock(nvar)
 
 
 def omp_set_lock(svar):
+    """Set a simple OpenMP lock.
+    
+    Args:
+    
+        svar (:obj:`int`):  An integer representing the lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_unset_lock`, :meth:`wrf.omp_set_nest_lock`
+    
+    """
     fomp_set_lock(svar)
 
 
 def omp_set_nest_lock(nvar):
+    """Set a nestable OpenMP lock.
+    
+    Args:
+    
+        nvar (:obj:`int`):  An integer representing the nestable lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_unset_nest_lock`, :meth:`wrf.omp_set_lock`
+    
+    """
     fomp_set_nest_lock(nvar)
 
 
 def omp_unset_lock(svar):
+    """Unset a simple OpenMP lock.
+    
+    Args:
+    
+        svar (:obj:`int`):  An integer representing the simple lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_unset_nest_lock`, :meth:`wrf.omp_set_lock`
+    
+    """
     fomp_unset_lock(svar)
 
 
 def omp_unset_nest_lock(nvar):
+    """Unset a nestable OpenMP lock.
+    
+    Args:
+    
+        nvar (:obj:`int`):  An integer representing the nestable lock.
+        
+    See Also:
+    
+        :meth:`wrf.omp_set_nest_lock`, :meth:`wrf.omp_unset_lock`
+    
+    """
     fomp_unset_nest_lock(nvar)
     
 
 def omp_test_lock(svar):
+    """Test a simple OpenMP lock.
+    
+    This method attempts to set the lock, but does not suspend execution.
+    
+    Args:
+    
+        svar (:obj:`int`):  An integer representing the simple lock.
+        
+    Returns:
+    
+        :obj:`int`:  Returns 1 (True) if the lock is successfully set, 
+        otherwise 0 (False).
+        
+    See Also:
+    
+        :meth:`wrf.test_nest_lock`, :meth:`wrf.omp_set_lock`
+    
+    """
     return fomp_test_lock(svar)
 
 
 def omp_test_nest_lock(nvar):
+    """Test a nestable OpenMP lock.
+    
+    This method attempts to set the lock, but does not suspend execution.
+    
+    Args:
+    
+        nvar (:obj:`int`):  An integer representing the simple lock.
+        
+    Returns:
+    
+        :obj:`int`:  Returns the nesting count if successful, 
+        otherwise 0 (False).
+        
+    See Also:
+    
+        :meth:`wrf.test_lock`, :meth:`wrf.omp_set_nest_lock`
+    
+    """
     return fomp_test_nest_lock(nvar)
 
 
 def omp_get_wtime():
+    """Return elapsed wall clock time in seconds.
+    
+    The omp_get_wtime routine returns a value equal to the elapsed wall clock 
+    time in seconds since some “time in the past”. The actual 
+    “time in the past” is arbitrary, but it is guaranteed not to change during 
+    the execution of the application program. The time returned is a 
+    “per-thread time”, so it is not required to be globally consistent across 
+    all threads participating in an application.
+    
+    Returns:
+    
+        :obj:`float`:  Returns the wall clock time in seconds.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_wtick`
+    
+    """
     return fomp_get_wtime()
 
 
 def omp_get_wtick():
+    """Return the precision of the timer used by :meth:`wrf.omp_get_wtime`.
+    
+    The omp_get_wtick routine returns a value equal to the number of 
+    seconds between successive clock ticks of the timer used by 
+    :meth:`wrf.omp_get_wtime`.
+    
+    Returns:
+    
+        :obj:`float`:  Returns the precision of the timer.
+        
+    See Also:
+    
+        :meth:`wrf.omp_get_wtime`
+    
+    """
     return fomp_get_wtick()