Parametric module documentation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-This module is still experimental in Salome 6.6 and is not documented yet.
-Documentation and full support will be available in Salome 7.
+This documentation covers the usage of PARAMETRIC module in Salome. This module
+aims at creating and running parametric studies in Salome. Here, the term
+"parametric study" means a simulation where one or several numerical parameters
+can vary in a given range. This module provides a way to run the simulation for
+different values of those parameters, and to distribute the computations across
+several machines.
-In particular, please note that the persistence format is not final yet. This
-means that you will not be able to reuse the Parametric Studies created with
-Salome 6.6 in future versions. Be sure to export your results in CSV files
-before migrating to Salome 7.
+The documentation of this module is currently only a tutorial that gives a
+quick insight in the usage and goals of this module.
+
+.. toctree::
+ :maxdepth: 2
+
+ tutorial.rst
--- /dev/null
+..
+ Copyright (C) 2012-2013 EDF
+
+ This file is part of SALOME PARAMETRIC module.
+
+ SALOME PARAMETRIC module 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 3 of the License, or
+ (at your option) any later version.
+
+ SALOME PARAMETRIC module 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 SALOME PARAMETRIC module. If not, see <http://www.gnu.org/licenses/>.
+
+
+=====================================
+Step 1: Define the deterministic case
+=====================================
+
+The first step is to create a deterministic case, that is a description of the
+calculation to be done. As our example uses the GENERICSOLVER module, first
+you must activate this module:
+
+.. image:: /_static/activate_gensolver.png
+ :align: center
+
+.. raw:: html
+
+ <br/>
+
+.. image:: /_static/new_gensolver.png
+ :align: center
+
+Then create a calculation case:
+
+.. image:: /_static/new_detcase.png
+ :align: center
+
+You can modify the values of the different variables if you want, but note
+that the values of the variables that you will define as parametric will be
+overrided.
+
+.. image:: /_static/setvalue_detcase.png
+ :align: center
+
+You can also run a deterministic calculation of the deviation of the beam with
+the values set for the variables:
+
+.. image:: /_static/runsolver_detcase.png
+ :align: center
+
+.. raw:: html
+
+ <br/>
+
+.. image:: /_static/result_detcase.png
+ :align: center
+
+Now we have defined the target of our parametric study. It's time to describe
+what this study will look like.
+
+:ref:`tut-variables-label`
--- /dev/null
+..
+ Copyright (C) 2012-2013 EDF
+
+ This file is part of SALOME PARAMETRIC module.
+
+ SALOME PARAMETRIC module 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 3 of the License, or
+ (at your option) any later version.
+
+ SALOME PARAMETRIC module 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 SALOME PARAMETRIC module. If not, see <http://www.gnu.org/licenses/>.
+
+
+.. _tut-execution-label:
+
+===================================================
+Step 5: Run the parametric study and export results
+===================================================
+
+In this step we will launch the execution of the parametric study on the local
+computer. For that, just click on the study in the object browser with the
+right button and select "Run parametric study" in the popup menu.
+
+.. image:: /_static/popup_run_study.png
+ :align: center
+
+The execution ends after a few dozens seconds. It is now possible to export
+the results in a CSV file to analyze them with a spreadsheet for instance. For
+that, click again on the study with the right button and select "Export data
+to CSV file". You can then choose the file in which the results will be saved.
+
+.. image:: /_static/popup_export_csv.png
+ :align: center
+
+It is then possible to open this file in a spreadsheet to draw graphs, analyze
+results, etc.
+
+.. image:: /_static/spreadsheet.png
+ :align: center
--- /dev/null
+..
+ Copyright (C) 2012-2013 EDF
+
+ This file is part of SALOME PARAMETRIC module.
+
+ SALOME PARAMETRIC module 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 3 of the License, or
+ (at your option) any later version.
+
+ SALOME PARAMETRIC module 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 SALOME PARAMETRIC module. If not, see <http://www.gnu.org/licenses/>.
+
+
+.. _tut-solver-label:
+
+======================================================
+Step 4: Define the solver and the execution parameters
+======================================================
+
+In this step we will define the solver to use for our parametric study. Two
+types of solvers can be used with the PARAMETRIC module:
+
+* The solver can be a Salome component that must define a few methods with
+ given signatures.
+* The solver can be a Python script.
+
+In this tutorial, we use the Salome component DEVIATION that is defined in the
+GENERICSOLVER module. For that, we must set the component name "DEVIATION" and
+select in the object browser the deterministic case that was created in step 1.
+We can also change the name of the parametric study (the name that the study
+will have in the object browser) and the number of computations that will be
+launched in parallel.
+
+.. image:: /_static/define_solver.png
+ :align: center
+
+Finally, just click the "OK" button to validate the creation of the parametric
+study. A new item representing the study appears in the object browser.
+
+.. image:: /_static/ob_new_study.png
+ :align: center
+
+:ref:`tut-execution-label`
--- /dev/null
+..
+ Copyright (C) 2012-2013 EDF
+
+ This file is part of SALOME PARAMETRIC module.
+
+ SALOME PARAMETRIC module 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 3 of the License, or
+ (at your option) any later version.
+
+ SALOME PARAMETRIC module 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 SALOME PARAMETRIC module. If not, see <http://www.gnu.org/licenses/>.
+
+
+.. _tut-values-label:
+
+======================================================
+Step 3: Define the values for the parametric variables
+======================================================
+
+In this step we will define the values that the parametric variables will take
+in the parametric study. Three methods are proposed for that:
+
+* Define ranges for each variable. The domain that is defined by those ranges
+ will be completely sampled to build the experimental plane.
+* Write a Python script that will create the sample.
+* Import the sample from a CSV file.
+
+In this tutorial, we will use the first method. To define the ranges for the
+parametric variables, you just have to select the minimum and maximum value
+for each variable along with the sampling step, as illustrated below.
+
+.. image:: /_static/define_ranges.png
+ :align: center
+
+Then click button "Next >>" to proceed to the last step of the parametric
+study creation.
+
+:ref:`tut-solver-label`
--- /dev/null
+..
+ Copyright (C) 2012-2013 EDF
+
+ This file is part of SALOME PARAMETRIC module.
+
+ SALOME PARAMETRIC module 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 3 of the License, or
+ (at your option) any later version.
+
+ SALOME PARAMETRIC module 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 SALOME PARAMETRIC module. If not, see <http://www.gnu.org/licenses/>.
+
+
+.. _tut-variables-label:
+
+=====================================================================
+Step 2: Define the parametric variables and the variables of interest
+=====================================================================
+
+In this step we will define the variables that will be exchanged between
+the PARAMETRIC module and the calculation code (DEVIATION in our example). The
+parametric variables are the input variables of the calculation code that will
+vary in a given range. Let's say that in our example, *F* and *L* are the two
+parametric variables and *E* and *I* are fixed variables.
+
+The variables of interest are the output variables of the calculation code
+that we want to study. In our example, there is only one output variable and
+thus only one variable of interest: the deviation *dev*.
+
+To define those variables, you first have to activate the PARAMETRIC module.
+
+.. image:: /_static/activate_parametric.png
+ :align: center
+
+.. |button_new_study| image:: /_static/button_new_study.png
+ :align: middle
+
+Then click on the button |button_new_study| to create a new parametric study
+and to open the variables definition window.
+
+.. image:: /_static/select_variables_empty.png
+ :align: center
+
+Now select the item "Variables" in the object browser under the deterministic
+case and click button "Select". The left side of the window will be filled
+with all the variables in the deterministic case.
+
+.. image:: /_static/select_variables_potential_vars.png
+ :align: center
+
+Now select the two input variables *F* and *L* and click button "Add" in the
+upper part of the window. Select the output variable "dev" and click button
+"Add" in the lower part of the window. In the end, your variables definition
+window should look like this:
+
+.. image:: /_static/select_variables_full.png
+ :align: center
+
+Note that if the deterministic case does not provide a "Variables" item, you
+can still create the probabilistic variables and the variables of interest by
+using the "New..." buttons.
+
+Finally, when you have selected all the desired variables, click button
+"Next >>" to proceed to the next step.
+
+:ref:`tut-values-label`
--- /dev/null
+..
+ Copyright (C) 2012-2013 EDF
+
+ This file is part of SALOME PARAMETRIC module.
+
+ SALOME PARAMETRIC module 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 3 of the License, or
+ (at your option) any later version.
+
+ SALOME PARAMETRIC module 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 SALOME PARAMETRIC module. If not, see <http://www.gnu.org/licenses/>.
+
+
+########
+Tutorial
+########
+
+This tutorial explains how to create and run a parametric study with the
+PARAMETRIC module in Salome. In all this documentation, we will use the example
+calculation code "DEVIATION" that is defined in the module GENERICSOLVER.
+It is an implementation of a classical example: the computation of the
+deviation of a cantilever beam.
+
+.. toctree::
+ :maxdepth: 2
+
+ tut_deterministic.rst
+ tut_variables.rst
+ tut_values.rst
+ tut_solver.rst
+ tut_execution.rst
