From: barate <barate>
Date: Wed, 27 Apr 2011 08:39:14 +0000 (+0000)
Subject: Complete doc for package salome.kernel.parametric
X-Git-Tag: V6_3_0b1~16
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=f21a25383071628e33ec8feaa0a0ebd199cfe8aa;p=modules%2Fkernel.git

Complete doc for package salome.kernel.parametric
---

diff --git a/doc/docutils/parametric.rst b/doc/docutils/parametric.rst
index 25e815c90..f868080f0 100644
--- a/doc/docutils/parametric.rst
+++ b/doc/docutils/parametric.rst
@@ -13,3 +13,10 @@
 
 .. automodule:: salome.kernel.parametric.compo_utils
    :members:
+
+
+:mod:`pyscript_utils` -- Useful functions for Python scripts used in parametric studies
+---------------------------------------------------------------------------------------
+
+.. automodule:: salome.kernel.parametric.pyscript_utils
+   :members:
diff --git a/src/KERNEL_PY/kernel/parametric/compo_utils.py b/src/KERNEL_PY/kernel/parametric/compo_utils.py
index c96675944..503b57720 100644
--- a/src/KERNEL_PY/kernel/parametric/compo_utils.py
+++ b/src/KERNEL_PY/kernel/parametric/compo_utils.py
@@ -18,9 +18,32 @@
 #  email : webmaster.salome@opencascade.com
 #
 
+"""
+This module provides utility functions for the computation codes intended for
+use in parametric studies. The computation codes must be implemented as SALOME
+components to use these functions. If the computation code is implemented as a
+Python script or function, use module
+:mod:`salome.kernel.parametric.pyscript_utils` instead. 
+"""
+
 import SALOME_TYPES
 
 def create_input_dict(deterministic_dict, parametric_input):
+    """
+    This function returns a dictionary containing the input values to be used
+    in the computation code.
+    
+    :type  deterministic_dict: dict
+    :param deterministic_dict: dictionary containing the fixed values (i.e.
+                               non-parametric). This dictionary can be empty
+                               if all variables are parametric.
+
+    :type  parametric_input: SALOME_TYPES/ParametricInput
+    :param parametric_input: structure containing the description and values
+                             of the parametric variables.
+
+    :return: a dictionary containing the input values for the computation code.
+    """
     # Simply get the first point from input (no time series, single observation)
     input_point = parametric_input.inputValues[0][0]
 
@@ -34,6 +57,22 @@ def create_input_dict(deterministic_dict, parametric_input):
     return input_dict
 
 def create_normal_parametric_output(output_dict, parametric_input):
+    """
+    This function returns a structure describing the output of the computation
+    code in parametric studies.
+    
+    :type  output_dict: dict
+    :param output_dict: dictionary containing the output values of the
+                        computation code (the keys are the variable names, the
+                        values are the variable values).
+
+    :type  parametric_input: SALOME_TYPES/ParametricInput
+    :param parametric_input: structure containing the description and values
+                             of the parametric variables.
+
+    :return: a structure of type SALOME_TYPES/ParametricOutput containing the
+             output of the computation code.
+    """
     output_values = [[[]]]
     for output_var in parametric_input.outputVarList:
         output_values[0][0].append([output_dict[output_var]])
@@ -43,6 +82,16 @@ def create_normal_parametric_output(output_dict, parametric_input):
                                          errorMessage = "")
 
 def create_error_parametric_output(error_message):
+    """
+    This function returns a structure describing the output of the computation
+    code in parametric studies in case of error.
+    
+    :type  error_message: string
+    :param error_message: the error message.
+
+    :return: a structure of type SALOME_TYPES/ParametricOutput describing the
+             error.
+    """
     return SALOME_TYPES.ParametricOutput(outputValues = [],
                                          specificOutputInfos = [],
                                          returnCode = 1,
diff --git a/src/KERNEL_PY/kernel/parametric/pyscript_utils.py b/src/KERNEL_PY/kernel/parametric/pyscript_utils.py
index 6a36c32bc..8bea30874 100644
--- a/src/KERNEL_PY/kernel/parametric/pyscript_utils.py
+++ b/src/KERNEL_PY/kernel/parametric/pyscript_utils.py
@@ -18,7 +18,30 @@
 #  email : webmaster.salome@opencascade.com
 #
 
+"""
+This module provides utility functions for the computation codes intended for
+use in parametric studies. The computation codes must be implemented as a
+Python script or function to use these functions. If the computation code is
+implemented as a SALOME component, use module
+:mod:`salome.kernel.parametric.compo_utils` instead. 
+"""
+
 def create_input_dict(deterministic_dict, parametric_input):
+    """
+    This function returns a dictionary containing the input values to be used
+    in the computation code.
+    
+    :type  deterministic_dict: dict
+    :param deterministic_dict: dictionary containing the fixed values (i.e.
+                               non-parametric). This dictionary can be empty
+                               if all variables are parametric.
+
+    :type  parametric_input: dict
+    :param parametric_input: dictionary containing the description and values
+                             of the parametric variables.
+
+    :return: a dictionary containing the input values for the computation code.
+    """
     # Simply get the first point from input (no time series, single observation)
     input_point = parametric_input["inputValues"][0][0]
 
@@ -32,6 +55,22 @@ def create_input_dict(deterministic_dict, parametric_input):
     return input_dict
 
 def create_normal_parametric_output(output_dict, parametric_input):
+    """
+    This function returns a dictionary describing the output of the
+    computation code in parametric studies.
+    
+    :type  output_dict: dict
+    :param output_dict: dictionary containing the output values of the
+                        computation code (the keys are the variable names, the
+                        values are the variable values).
+
+    :type  parametric_input: dict
+    :param parametric_input: dictionary containing the description and values
+                             of the parametric variables.
+
+    :return: a dictionary containing the representation of the output of the
+             computation code.
+    """
     output_values = [[[]]]
     for output_var in parametric_input["outputVarList"]:
         output_values[0][0].append([output_dict[output_var]])
@@ -41,6 +80,15 @@ def create_normal_parametric_output(output_dict, parametric_input):
             "errorMessage" : ""}
 
 def create_error_parametric_output(error_message):
+    """
+    This function returns a dictionary describing the output of the
+    computation code in parametric studies in case of error.
+    
+    :type  error_message: string
+    :param error_message: the error message.
+
+    :return: a dictionary describing the error.
+    """
     return {"outputValues" : [],
             "specificOutputInfos" : [],
             "returnCode" : 1,