From 1d5bb210e2139d936c31e77016adfb004015ab6d Mon Sep 17 00:00:00 2001 From: Renaud Barate Date: Wed, 15 May 2013 16:20:44 +0200 Subject: [PATCH] Add a small reference guide --- doc/index.rst | 6 +++-- doc/ref_csv_export.rst | 33 +++++++++++++++++++++++ doc/ref_execution.rst | 50 ++++++++++++++++++++++++++++++++++ doc/ref_solver.rst | 55 +++++++++++++++++++++++++++++++++++++ doc/ref_values.rst | 61 ++++++++++++++++++++++++++++++++++++++++++ doc/reference.rst | 32 ++++++++++++++++++++++ 6 files changed, 235 insertions(+), 2 deletions(-) create mode 100644 doc/ref_csv_export.rst create mode 100644 doc/ref_execution.rst create mode 100644 doc/ref_solver.rst create mode 100644 doc/ref_values.rst create mode 100644 doc/reference.rst diff --git a/doc/index.rst b/doc/index.rst index 58b1532..df277fb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -28,10 +28,12 @@ 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. -The documentation of this module is currently only a tutorial that gives a -quick insight in the usage and goals of this module. +The documentation of this module is divided in two parts. The tutorial gives a +quick insight in the usage and goals of this module. The reference guide +details the main features of the module. .. toctree:: :maxdepth: 2 tutorial.rst + reference.rst diff --git a/doc/ref_csv_export.rst b/doc/ref_csv_export.rst new file mode 100644 index 0000000..04511fc --- /dev/null +++ b/doc/ref_csv_export.rst @@ -0,0 +1,33 @@ +.. + 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 . + + +========================================================= +Exporting the results and analyzing them in a spreadsheet +========================================================= + +The results exported from the PARAMETRIC module have a predefined format +(comma-separated values, dot used as the decimal separator, etc.). It may be +necessary to configure the CSV import function of your spreadsheet to open the +results properly. For instance with LibreOffice Calc you will have to use the +following parameters: + +* Language: English (U.S.A) +* Separator: Comma +* Text separator: " +* Select "Detect special numbers" diff --git a/doc/ref_execution.rst b/doc/ref_execution.rst new file mode 100644 index 0000000..280f443 --- /dev/null +++ b/doc/ref_execution.rst @@ -0,0 +1,50 @@ +.. + 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 . + + +================================= +Execution of the parametric study +================================= + +The parametric study can be either executed directly on the local computer or +as a batch job on a remote cluster. + +Local execution +=============== + +For a local execution, the number of parallel computations should in most +cases be set to the number of cores of the local computer. If the solver code +uses a lot of memory, it may be necessary to decrease this number. + +Note that with a local execution, the Salome application will be freezed +during the whole computation. This mode should thus be reserved for relatively +small cases. + +Batch execution +=============== + +To execute the parametric study in batch, it is first necessary to generate a +job. This can be done easily in the graphical interface of the PARAMETRIC +module (right-click on the parametric study and select "Generate batch job"). +You can then select the resource to use to run this job. When the job is +generated, it will appear in the JOBMANAGER module and you can then manage it +as any other job, for instance to set a time limit for the job. You can then +launch and follow the job and get the results with the JOBMANAGER module. With +those results comes a new Salome study that contains the results of the +parametric computation. Open it and export the results in a CSV file to +analyze them. diff --git a/doc/ref_solver.rst b/doc/ref_solver.rst new file mode 100644 index 0000000..acc0714 --- /dev/null +++ b/doc/ref_solver.rst @@ -0,0 +1,55 @@ +.. + 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 . + + +======================== +Definition of the solver +======================== + +The PARAMETRIC module offers two methods to define a solver code. + +Salome component +================ + +The solver can be implemented as a Salome component that provides three +services: Init, Exec and Finalize. Those services must also be available as +YACS nodes. For the detailed description of those services, please see the +documentation of OpenTURNS module. Every component adapted for OpenTURNS in +Salome can be reused directly with the PARAMETRIC module. + +If the solver code is implemented as a Salome component, the module providing +this component must also provide a way to describe a study case and store it +in Salome study so that it appears in the object browser. The user can then +select this case in the graphical interface of PARAMETRIC module to associate +the parametric study with a solver case. + +Python script +============= + +The solver can also be implemented as a Python script directly in the +graphical interface of PARAMETRIC module. This script must meet some +requirements: + +* It can (and should) use the parametric variables that are directly defined + in the environment of the script before its execution. +* It must create the variables of interest (if any). + +For instance, a solver code that computes a variable of interest C that is the +product of the two parametric variables A and B can be written simply as:: + + C = A * B diff --git a/doc/ref_values.rst b/doc/ref_values.rst new file mode 100644 index 0000000..6c161dd --- /dev/null +++ b/doc/ref_values.rst @@ -0,0 +1,61 @@ +.. + 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 . + + +==================================== +Definition of the experimental plane +==================================== + +The PARAMETRIC module offers three methods to define the experimental plane +(i.e. the set of values that the parametric variables can take). + +Complete sampling of a given domain +=================================== + +The user must define ranges for each parametric variable. A range is described +by: + +* The minimum value (that will be included in the generated sample) +* The maximum value (that will **not** be included in the generated sample) +* The step between two consecutive values + +The domain that is defined by those ranges is then sampled completely and +regularly to build the experimental plane. + +Generation by a Python script +============================= + +A Python script written by the user creates the whole sample. The script must +create a Numpy array that contains all the points of the experimental plane. +The dimension of this array must thus be (n, d) where n is the number of +points in the sample and d is the number of parametric variables. This Numpy +array must be stored in a variable named "sample". + +Importation of a sample defined in a CSV file +============================================= + +The sample is imported from a CSV file defined by the user. This file must +meet some requirements: + +* The separator character must be "," (comma). Thus the decimal separator for + numerical values must be "." (dot). +* The first line of the file must contain the name of the parametric variables + separated by commas in order to identify the columns of the file. +* Each other line must contain a number of values equal to the number of + parametric variables, separated by commas. Each line corresponds to a point + in the sample. diff --git a/doc/reference.rst b/doc/reference.rst new file mode 100644 index 0000000..2fb9e13 --- /dev/null +++ b/doc/reference.rst @@ -0,0 +1,32 @@ +.. + 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 . + + +############### +Reference Guide +############### + +This reference guide details the main features of the PARAMETRIC module. + +.. toctree:: + :maxdepth: 2 + + ref_values.rst + ref_solver.rst + ref_execution.rst + ref_csv_export.rst -- 2.39.2