From: Renaud Barate Date: Tue, 14 May 2013 15:33:13 +0000 (+0200) Subject: Add tutorial in the documentation X-Git-Tag: V7_2_0~1 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=3ff3f89596bfa56f4124fc01fa6bd171980b0792;p=modules%2Fparametric.git Add tutorial in the documentation --- diff --git a/doc/_static/activate_gensolver.png b/doc/_static/activate_gensolver.png new file mode 100644 index 0000000..69b3396 Binary files /dev/null and b/doc/_static/activate_gensolver.png differ diff --git a/doc/_static/activate_parametric.png b/doc/_static/activate_parametric.png new file mode 100644 index 0000000..0fda39c Binary files /dev/null and b/doc/_static/activate_parametric.png differ diff --git a/doc/_static/button_new_study.png b/doc/_static/button_new_study.png new file mode 100644 index 0000000..83bb8de Binary files /dev/null and b/doc/_static/button_new_study.png differ diff --git a/doc/_static/define_ranges.png b/doc/_static/define_ranges.png new file mode 100644 index 0000000..b2c58cc Binary files /dev/null and b/doc/_static/define_ranges.png differ diff --git a/doc/_static/define_solver.png b/doc/_static/define_solver.png new file mode 100644 index 0000000..53791f9 Binary files /dev/null and b/doc/_static/define_solver.png differ diff --git a/doc/_static/new_detcase.png b/doc/_static/new_detcase.png new file mode 100644 index 0000000..c86d78f Binary files /dev/null and b/doc/_static/new_detcase.png differ diff --git a/doc/_static/new_gensolver.png b/doc/_static/new_gensolver.png new file mode 100644 index 0000000..8a7317a Binary files /dev/null and b/doc/_static/new_gensolver.png differ diff --git a/doc/_static/ob_new_study.png b/doc/_static/ob_new_study.png new file mode 100644 index 0000000..ff656a1 Binary files /dev/null and b/doc/_static/ob_new_study.png differ diff --git a/doc/_static/popup_export_csv.png b/doc/_static/popup_export_csv.png new file mode 100644 index 0000000..acdbdb7 Binary files /dev/null and b/doc/_static/popup_export_csv.png differ diff --git a/doc/_static/popup_run_study.png b/doc/_static/popup_run_study.png new file mode 100644 index 0000000..fcfd1db Binary files /dev/null and b/doc/_static/popup_run_study.png differ diff --git a/doc/_static/result_detcase.png b/doc/_static/result_detcase.png new file mode 100644 index 0000000..916d425 Binary files /dev/null and b/doc/_static/result_detcase.png differ diff --git a/doc/_static/runsolver_detcase.png b/doc/_static/runsolver_detcase.png new file mode 100644 index 0000000..1123123 Binary files /dev/null and b/doc/_static/runsolver_detcase.png differ diff --git a/doc/_static/select_variables_empty.png b/doc/_static/select_variables_empty.png new file mode 100644 index 0000000..0d69588 Binary files /dev/null and b/doc/_static/select_variables_empty.png differ diff --git a/doc/_static/select_variables_full.png b/doc/_static/select_variables_full.png new file mode 100644 index 0000000..28005ef Binary files /dev/null and b/doc/_static/select_variables_full.png differ diff --git a/doc/_static/select_variables_potential_vars.png b/doc/_static/select_variables_potential_vars.png new file mode 100644 index 0000000..f25a3b2 Binary files /dev/null and b/doc/_static/select_variables_potential_vars.png differ diff --git a/doc/_static/setvalue_detcase.png b/doc/_static/setvalue_detcase.png new file mode 100644 index 0000000..db461b1 Binary files /dev/null and b/doc/_static/setvalue_detcase.png differ diff --git a/doc/_static/spreadsheet.png b/doc/_static/spreadsheet.png new file mode 100644 index 0000000..d633efd Binary files /dev/null and b/doc/_static/spreadsheet.png differ diff --git a/doc/index.rst b/doc/index.rst index efba8c8..58b1532 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -21,10 +21,17 @@ 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 diff --git a/doc/tut_deterministic.rst b/doc/tut_deterministic.rst new file mode 100644 index 0000000..350cd9f --- /dev/null +++ b/doc/tut_deterministic.rst @@ -0,0 +1,66 @@ +.. + 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 . + + +===================================== +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 + +
+ +.. 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 + +
+ +.. 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` diff --git a/doc/tut_execution.rst b/doc/tut_execution.rst new file mode 100644 index 0000000..e9b40b8 --- /dev/null +++ b/doc/tut_execution.rst @@ -0,0 +1,45 @@ +.. + 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 . + + +.. _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 diff --git a/doc/tut_solver.rst b/doc/tut_solver.rst new file mode 100644 index 0000000..ee1745a --- /dev/null +++ b/doc/tut_solver.rst @@ -0,0 +1,49 @@ +.. + 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 . + + +.. _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` diff --git a/doc/tut_values.rst b/doc/tut_values.rst new file mode 100644 index 0000000..aae5e3a --- /dev/null +++ b/doc/tut_values.rst @@ -0,0 +1,44 @@ +.. + 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 . + + +.. _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` diff --git a/doc/tut_variables.rst b/doc/tut_variables.rst new file mode 100644 index 0000000..d662443 --- /dev/null +++ b/doc/tut_variables.rst @@ -0,0 +1,72 @@ +.. + 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 . + + +.. _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` diff --git a/doc/tutorial.rst b/doc/tutorial.rst new file mode 100644 index 0000000..2291921 --- /dev/null +++ b/doc/tutorial.rst @@ -0,0 +1,37 @@ +.. + 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 . + + +######## +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