README.txt

   1 =====================================================
   2 ADAO: A module for Data Assimilation and Optimization
   3 =====================================================
   4
   5 About
   6 -----
   7
   8 **The ADAO module provides data assimilation and optimization** features in
   9 Python or SALOME context (see http://www.salome-platform.org/). Briefly stated,
  10 Data Assimilation is a methodological framework to compute the optimal estimate
  11 of the inaccessible true value of a system state, eventually over time. It uses
  12 information coming from experimental measurements or observations, and from
  13 numerical *a priori* models, including information about their errors. Parts of
  14 the framework are also known under the names of *calibration*, *adjustment*,
  15 *state estimation*, *parameter estimation*, *parameter adjustment*, *inverse
  16 problems*, *Bayesian estimation*, *optimal interpolation*, *mathematical
  17 regularization*, *meta-heuristics for optimization*, *model reduction*, *data
  18 smoothing*, etc. More details can be found in the full ADAO documentation (see
  19 https://www.salome-platform.org/ User Documentation dedicated section).
  20
  21 Only the use of ADAO text programming interface (API/TUI) is introduced
  22 here. This interface gives ability to create a calculation object in a
  23 similar way than the case building obtained through the graphical
  24 interface (GUI). When one wants to elaborate directly the TUI
  25 calculation case, it is recommended to extensively use all the ADAO
  26 module documentation, and to go back if necessary to the graphical
  27 interface (GUI), to get all the elements allowing to correctly set the
  28 commands.
  29
  30 A simple setup example of an ADAO TUI calculation case
  31 ------------------------------------------------------
  32
  33 To introduce the TUI interface, lets begin by a simple but complete
  34 example of ADAO calculation case. All the data are explicitly defined
  35 inside the script in order to make the reading easier. The whole set of
  36 commands is the following one::
  37
  38     from numpy import array, matrix
  39     from adao import adaoBuilder
  40     case = adaoBuilder.New()
  41     case.set( 'AlgorithmParameters', Algorithm = '3DVAR' )
  42     case.set( 'Background',          Vector = [0, 1, 2] )
  43     case.set( 'BackgroundError',     ScalarSparseMatrix = 1.0 )
  44     case.set( 'Observation',         Vector = array([0.5, 1.5, 2.5]) )
  45     case.set( 'ObservationError',    DiagonalSparseMatrix = '1 1 1' )
  46     case.set( 'ObservationOperator', Matrix = '1 0 0;0 2 0;0 0 3' )
  47     case.set( 'Observer',            Variable = "Analysis", Template = "ValuePrinter" )
  48     case.execute()
  49
  50 The result of running these commands in SALOME (either as a SALOME
  51 "*shell*" command, in the Python command window of the interface, or by
  52 the script execution entry of the menu) is the following::
  53
  54     Analysis [ 0.25000264  0.79999797  0.94999939]
  55
  56 More advanced examples of ADAO TUI calculation case
  57 ---------------------------------------------------
  58
  59 Real cases involve observations loaded from files, operators explicitly
  60 defined as generic functions including physical simulators, time dependant
  61 information in order to deal with forecast analysis in addition to calibration
  62 or re-analysis. More details can be found in the full ADAO documentation (see
  63 documentation on the reference site https://www.salome-platform.org/, with
  64 https://docs.salome-platform.org/latest/gui/ADAO/en/index.html for english or
  65 https://docs.salome-platform.org/latest/gui/ADAO/fr/index.html for french, both
  66 being equivalents).
  67
  68 License and requirements
  69 ------------------------
  70
  71 The license for this module is the GNU Lesser General Public License
  72 (Lesser GPL), as stated here and in the source files::
  73
  74     <ADAO, a module for Data Assimilation and Optimization>
  75
  76     Copyright (C) 2008-2023 EDF R&D
  77
  78     This library is free software; you can redistribute it and/or
  79     modify it under the terms of the GNU Lesser General Public
  80     License as published by the Free Software Foundation; either
  81     version 2.1 of the License, or (at your option) any later version.
  82
  83     This library is distributed in the hope that it will be useful,
  84     but WITHOUT ANY WARRANTY; without even the implied warranty of
  85     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  86     Lesser General Public License for more details.
  87
  88     You should have received a copy of the GNU Lesser General Public
  89     License along with this library; if not, write to the Free Software
  90     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  91
  92     See http://www.salome-platform.org/
  93
  94 In addition, it is requested that any publication or presentation, describing
  95 work using this module, or any commercial or non-commercial product using it,
  96 cite at least one of the references below with the current year added:
  97
  98     * *ADAO, a module for Data Assimilation and Optimization*,
  99       http://www.salome-platform.org/
 100
 101     * *ADAO, un module pour l'Assimilation de Données et l'Aide à
 102       l'Optimisation*, http://www.salome-platform.org/
 103
 104     * *SALOME The Open Source Integration Platform for Numerical Simulation*,
 105       http://www.salome-platform.org/
 106
 107 The documentation of the module is also covered by the license and the
 108 requirement of quoting.