src/daComposant/daNumerics/pst4mod/modelica_calibration/__init__.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # Copyright (C) 2016-2024 EDF R&D
   4 #
   5 # This library is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU Lesser General Public
   7 # License as published by the Free Software Foundation; either
   8 # version 2.1 of the License.
   9 #
  10 # This library is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # Lesser General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with this library; if not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  18 #
  19 # Author: Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D
  20 # Author: Luis Corona Mesa-Molles, luis.corona-mesa-molles@edf.fr, EDF R&D
  21
  22 __doc__ = """
  23 This module leads to easy calibration of a dynamical model from DYMOLA or
  24 Modelica, with respect to experimental measurements, with the help of
  25 optimization algorithms available in ADAO tool.
  26
  27 SYNOPSIS
  28 --------
  29
  30 The most simple use of the module, using default arguments and files living in
  31 the current directory, is the following:
  32
  33     from modelica_calibration.case import Calibration
  34     import os
  35     newcase = Calibration()
  36     resultats = newcase.calibrate(
  37         DataName             = "measures.txt",
  38         ModelName            = os.path.join("Models","dymosim.exe"),
  39         MethodName           = "parameters.py",
  40         VariablesToCalibrate = ["COP_val","hVE_val","PEE_val","hEE_val"],
  41         OutputVariables      = ["proeeF.T","Ev.P","prospC.T","Sp.Q","proseF.T"],
  42     )
  43     print()
  44     for k,v in resultats.items():
  45         print("%18s = %s"%(k,v))
  46     print()
  47
  48 ARGUMENTS TO BE GIVEN AS INPUT FOR "CALIBRATE" TASK
  49 ---------------------------------------------------
  50
  51 The "calibrate" method is used to set and realize a calibration (optimal
  52 estimation task) of model parameters using measures data. It can be directly
  53 called with all the input arguments to set the full calibration problem.
  54
  55 The input arguments are the following named ones. They are not all required,
  56 and can be divided in category.
  57
  58 Category: dynamic model description
  59
  60     ModelName............: required file (or directory name that contains the
  61         files) for the dynamic model.
  62         (default None)
  63
  64     ModelFormat..........: this indicates the format of the dynamic model. It
  65         can be given as a Dymola executable pair "dymosim.exe/dsin.txt".
  66         (default "GUESS", allowed "DYMOSIM", "PYSIM", "GUESS")
  67
  68 Category: measures description
  69
  70     DataName.............: required file name for measures
  71         (default None)
  72
  73     DataFormat...........: this indicates the format of the measures, given as
  74         columns of chronological series, with the same column names that are
  75         used for variables in the output of the model simulation.
  76         (default "GUESS", allowed "TXT", "CSV", "TSV", "GUESS")
  77
  78 Category: initial/background values description
  79
  80     BackgroundName.......: file name for initial/background. If no file name is
  81         given, it is assumed that the initial value will come from model.
  82         (default None)
  83
  84     BackgroundFormat.....: this indicates the source of the initial values used
  85         as background ones. The background values can be read in ADAO, DSIN or
  86         USER format. The priority is "USER", then "ADAO", then "DSIN".
  87         (default "GUESS", allowed "ADAO", "DSIN", "USER", "GUESS")
  88
  89 Category: calibration method description
  90
  91     MethodName...........: file name for ADAO parameters
  92         (default None)
  93
  94     MethodFormat.........: this indicates the format of the assimilation
  95         parameters, excluding background.
  96         (default "ADAO", allowed "ADAO")
  97
  98     VariablesToCalibrate.: model names to calibrate, that have to exist as
  99         input variables in the model description.
 100         (default None)
 101
 102     OutputVariables......: model names of result to compare to measures, that
 103         have to exist as output variables in the model description.
 104         (default None)
 105
 106 Category: results description
 107
 108     ResultName...........: required file name for writing results.
 109         (default "results.txt")
 110
 111     ResultFormat.........: this indicates the format of the result output.
 112         (default "GUESS", allowed "TXT", "PY", "GUESS")
 113
 114     ResultLevel..........: quantity of results that will be retrieved. By
 115         default, it will always write at least the calibration results.
 116         (default None, allowed None="Final", "Final", "IntermediaryFinal")
 117
 118     Verbose..............: True or False
 119         (default False)
 120
 121 ARGUMENTS OUTPUT THAT CAN BE OBTAINDED FOR "CALIBRATE" TASK
 122 -----------------------------------------------------------
 123
 124 The output results are returned at the end of the calibration process, and
 125 evantually during it. The output will be at least written in a file, and in the
 126 same time returned in a python dictionary containing result information. The
 127 dictionnary entries are the following ones:
 128
 129     NamesOfParameters....: names of the individual parameter variables to be
 130         calibrated.
 131
 132     InitialParameters....: initial or background parameter set, as known before
 133         calibration. If it is given by the user, it can differ from the initial
 134         model values embedded in the model.
 135
 136     OptimalParameters....: optimal parameter set, as known after calibration.
 137
 138
 139     NamesOfMeasures......: names of the measures subsets used for the
 140         calibration.
 141
 142     Measures.............: measures subsets used for calibration
 143
 144     OptimalSimulation....: simulation results obtained with optimal parameter
 145         set, using the model. It can be directly compared to measures.
 146
 147 HOW TO DESCRIBE A DYNAMIC MODEL?
 148 --------------------------------
 149
 150 Model can be given either by the name of the model parameter file (e.g.
 151 "dsin.txt") with absolute or relative path, or by the directory where live the
 152 DYMOLA compiled executable "dymosim.exe" and the parameters file "dsin.txt".
 153
 154 HOW TO DESCRIBE THE MEASURES?
 155 -----------------------------
 156
 157 Measures can be given by colums files, with named colums, in TXT, CVS or TSV
 158 file types (with respective delimiters "space", ";" and "tab" and respective
 159 file extension ".txt", ".csv" and ".tsv"). Beginning lines with "#" indicates a
 160 comment line, with the first uncommented line having to present the names of the
 161 columns variables if available.
 162
 163 Example of a TXT file:
 164     # Measures text file
 165     #
 166     Date Heure Variable1 Variable2
 167     22/04/2018 8:0:0   295    0.01
 168     23/04/2018 8:0:0   296    0.01
 169     24/04/2018 8:0:0   294    0.01
 170     25/04/2018 8:0:0   293    0.001
 171     26/04/2018 8:0:0   295    0.01
 172     27/04/2018 8:0:0   297    0.5
 173
 174 Example of a CSV file:
 175     # Measures text file
 176     #
 177     Date,Heure,Variable1,Variable2
 178     22/04/2018,8:0:0,295,0.01
 179     23/04/2018,8:0:0,296,0.01
 180     24/04/2018,8:0:0,294,0.01
 181     25/04/2018,8:0:0,293,0.001
 182     26/04/2018,8:0:0,295,0.01
 183     27/04/2018,8:0:0,297,0.5
 184
 185 HOW TO SET CALIBRATION PARAMETERS?
 186 ----------------------------------
 187
 188 ADAO parameters can be given by Python file, with named standard variables (see
 189 ADAO documentation for details). All parameters have wise defaults). Error
 190 covariance matrices can be set also in this parameter file.
 191
 192 The variables, that can (but has not to) be set (see ADAO documentation
 193 for details), are:
 194     Algorithm........: calibration algorithm (default "3DVAR")
 195     Parameters.......: dictionary of optimization parameters and of
 196                        optimization bounds (default Model ones)
 197     BackgroundError..: a priori errors covariance matrix (default 1.)
 198     ObservationError.: a priori model-observation errors covariance
 199                        matrix (default 1.)
 200     Background.......: see below.
 201
 202 Initial values and bounds of the variables to calibrate can be read from user
 203 file, ADAO parameters file or model parameters file, allowing to superseed the
 204 model initial default values. The priority is "USER", then "ADAO", then "DSIN",
 205 and the default one correspond to "DSIN". So the background can be set using
 206 three alternative ways:
 207
 208     - by reading named parameters in a user file, with 2 (or 4) colums
 209       describing pairs (or quadruplets) for each variable with the Name, the
 210       Values (and Min/Max bounds if required). The file can be in CSV or TXT
 211       format.
 212
 213       Choice:
 214           BackgroundFormat = "USER"
 215           BackgroundName = ...
 216
 217       Example of CSV file content:
 218           Name,Value,Minimum,Maximum
 219           COP_val,1.4,0.2,1
 220           hVE_val,2321820,0,None
 221           PEE_val,8.3226E06,0,None
 222           hEE_val,759483,None,None
 223
 224     - by reading values and bounds as series in the calibration parameters file
 225       with the ADAO standard syntax.
 226
 227       Choice:
 228           BackgroundFormat = "ADAO"
 229
 230       Example of subset of Python parameters calibration file:
 231           Parameters={
 232               "Bounds":[[0.2,1],[0,None],[0,None],[None,None]],
 233               }
 234           Background=[1.4,2321820,8.3226E06,759483]
 235
 236     - by reading initial values in a model description file as the "dsin.txt"
 237       for Dymola. In this case, the only information required is the names of
 238       the calibrated variables as known in Dymola "dsin.txt" file.
 239
 240       Choice:
 241           BackgroundFormat = "DSIN"
 242
 243 LICENSE
 244 -------
 245 The license for this tool and its documentation is the GNU Lesser General
 246 Public License (Lesser GPL).
 247
 248 REFERENCES
 249 ----------
 250 For more information, see:
 251     * DYMOLA User documentation
 252     * ADAO, a module for Data Assimilation and Optimization,
 253       http://www.salome-platform.org/
 254
 255 """
 256 __author__ = "Jean-Philippe Argaud, jean-philippe.argaud@edf.fr, EDF R&D"
 257 __all__ = ["case"]