From 3df9ec0d4095e592fdd64d6b2b2addab5c00d7bf Mon Sep 17 00:00:00 2001
From: Farid Mohammadi <farid.mohammadi@iws.uni-stuttgart.de>
Date: Fri, 11 Mar 2022 18:01:53 +0100
Subject: [PATCH] [docs] document pylink and inputs.
---
src/bayesvalidrox/pylink/pylink.py | 124 +++++++++++++------
src/bayesvalidrox/surrogate_models/inputs.py | 77 +++++++-----
2 files changed, 135 insertions(+), 66 deletions(-)
diff --git a/src/bayesvalidrox/pylink/pylink.py b/src/bayesvalidrox/pylink/pylink.py
index 911c9f446..478256821 100644
--- a/src/bayesvalidrox/pylink/pylink.py
+++ b/src/bayesvalidrox/pylink/pylink.py
@@ -1,21 +1,5 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
-
-"""
-This program runs the model defined by the user.
-
-Author: Farid Mohammadi, M.Sc.
-E-Mail: farid.mohammadi@iws.uni-stuttgart.de
-Department of Hydromechanics and Modelling of Hydrosystems (LH2)
-Institute for Modelling Hydraulic and Environmental Systems (IWS), University
-of Stuttgart, www.iws.uni-stuttgart.de/lh2/
-Pfaffenwaldring 61
-70569 Stuttgart
-
-Created in July 2019
-
-"""
-
import os
import shutil
import h5py
@@ -23,33 +7,103 @@ import numpy as np
import time
import zipfile
import pandas as pd
-from functools import reduce
import multiprocessing
import tqdm
class PyLinkForwardModel(object):
- """A forward model binder
+ r"""
+ A forward model binder
+
This calss serves as a code wrapper. This wrapper allows the execution of
- a third-party software/solver within the scope of BayesValidRox.
- The wrapper provides two options:
- 1) link_type='PyLink':
- Runs the third-party software using a sell command with given input
- files.
- 2) link_type='function':
- For this case, it is assumed that model can be run using a function
- written separately in a Python script. This function recieves the
- parameters in an array of shape (n_samples, n_params) and returns
- a dictionary with the x_values and output arrays for given output
- names.
+ a third-party software/solver within the scope of BayesValidRox.
+
+ Attributes
+ ----------
+ link_type : str
+ The type of the wrapper. The default is `'pylink'`. This runs the
+ third-party software or an executable using a sell command with given
+ input files.
+ Second option is `'function'` which assumed that model can be run using
+ a function written separately in a Python script.
+ name : str
+ Name of the model.
+ py_file : str
+ Python file name without `.py` extension to be run for the `'function'`
+ wrapper. Note that the name of the python file and that of the function
+ must be simillar. This function must recieve the parameters in an array
+ of shape `(n_samples, n_params)` and returns a dictionary with the
+ x_values and output arrays for given output names.
+ shell_command : str
+ Shell command to be executed for the `'pylink'` wrapper.
+ input_file : str or list
+ The input file to be passed to the `'pylink'` wrapper.
+ input_template : str or list
+ A template input file to be passed to the `'pylink'` wrapper. This file
+ must be a copy of `input_file` with `<Xi>` place holder for the input
+ parameters defined using `inputs` class, with i being the number of
+ parameter. The file name ending should include `.tpl` before the actual
+ extension of the input file, for example, `params.tpl.input`.
+ aux_file : str or list
+ The list of auxiliary files needed for the `'pylink'` wrapper.
+ exe_path : str
+ Execution path if you wish to run the model for the `'pylink'` wrapper
+ in another directory. The default is `None`, which corresponds to the
+ currecnt working directory.
+ output_file_names : list of str
+ List of the name of the model output text files for the `'pylink'`
+ wrapper.
+ output_names : list of str
+ List of the model outputs to be used for the analysis.
+ output_parser : str
+ Name of the model parser file (without `.py` extension) that recieves
+ the `output_file_names` and returns a 2d-array with the first row being
+ the x_values, e.g. x coordinates or time and the rest of raws pass the
+ simulation output for each model output defined in `output_names`. Note
+ that again here the name of the file and that of the function must be
+ the same.
+ multi_process: bool
+ Whether the model runs to be executed in parallel for the `'pylink'`
+ wrapper. The default is `True`.
+ n_cpus: int
+ The number of cpus to be used for the parallel model execution for the
+ `'pylink'` wrapper. The default is `None`, which corresponds to all
+ available cpus.
+ meas_file : str
+ The name of the measurement text-based file. This file must contain
+ x_values as the first column and one column for each model output. The
+ default is `None`. Only needed for the Bayesian Inference.
+ meas_file_valid : str
+ The name of the measurement text-based file for the validation. The
+ default is `None`. Only needed for the validation with Bayesian
+ Inference.
+ mc_ref_file : str
+ The name of the text file for the Monte-Carlo reference (mean and
+ standard deviation) values. It must contain `x_values` as the first
+ column, `mean` as the second column and `std` as the third. It can be
+ used to compare the estimated moments using meta-model in the post-
+ processing step. This is only available for one output.
+ obs_dict : dict
+ A dictionary containing the measurement text-based file. It must
+ contain `x_values` as the first item and one item for each model output
+ . The default is `{}`. Only needed for the Bayesian Inference.
+ obs_dict_valid : dict
+ A dictionary containing the validation measurement text-based file. It
+ must contain `x_values` as the first item and one item for each model
+ output. The default is `{}`.
+ mc_ref_dict : dict
+ A dictionary containing the Monte-Carlo reference (mean and standard
+ deviation) values. It must contain `x_values` as the first item and
+ `mean` as the second item and `std` as the third. The default is `{}`.
+ This is only available for one output.
"""
- def __init__(self, link_type='PyLink', name=None, shell_command='',
- py_file=None, input_file=None, input_template=None,
- aux_file=None, exe_path='', multi_process=True, n_cpus=None,
- output_parser='', output_names=[], output_file_names=[],
- meas_file=None, meas_file_valid=None, mc_ref_file=None,
- obs_dict={}, obs_dict_valid={}, mc_ref_dict={}):
+ def __init__(self, link_type='pylink', name=None, py_file=None,
+ shell_command='', input_file=None, input_template=None,
+ aux_file=None, exe_path='', output_file_names=[],
+ output_names=[], output_parser='', multi_process=True,
+ n_cpus=None, meas_file=None, meas_file_valid=None,
+ mc_ref_file=None, obs_dict={}, obs_dict_valid={}, mc_ref_dict={}):
self.link_type = link_type
self.name = name
self.shell_command = shell_command
diff --git a/src/bayesvalidrox/surrogate_models/inputs.py b/src/bayesvalidrox/surrogate_models/inputs.py
index 9915ff05a..667b2dffe 100644
--- a/src/bayesvalidrox/surrogate_models/inputs.py
+++ b/src/bayesvalidrox/surrogate_models/inputs.py
@@ -1,45 +1,33 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
-"""
-Author: Farid Mohammadi, M.Sc.
-E-Mail: farid.mohammadi@iws.uni-stuttgart.de
-Department of Hydromechanics and Modelling of Hydrosystems (LH2)
-Institute for Modelling Hydraulic and Environmental Systems (IWS), University
-of Stuttgart, www.iws.uni-stuttgart.de/lh2/
-Pfaffenwaldring 61
-70569 Stuttgart
-
-Created on Sat Aug 24 2019
-"""
-
class Input:
"""
A class to define the uncertain input parameters.
- Example::
-
- Inputs.add_marginals()
- Inputs.Marginals[0].name = 'X_1'
- Inputs.Marginals[0].dist_type = 'uniform'
- Inputs.Marginals[0].parameters = [-5, 5]
- If there is no common data is avaliable, the input data can be given
- as following::
-
- Inputs.add_marginals()
- Inputs.Marginals[0].name = 'X_1'
- Inputs.Marginals[0].input_data = input_data
Attributes
----------
Marginals : obj
- Marginal objects.
+ Marginal objects. See `inputs.Marginal`.
Rosenblatt : bool
If Rossenblatt transformation is required for the dependent input
parameters.
- Methods
+
+ Examples
-------
- add_marginals():
- Adds a new Marginal object to the input object.
+ Marginals can be defined as following:
+
+ >>> Inputs.add_marginals()
+ >>> Inputs.Marginals[0].name = 'X_1'
+ >>> Inputs.Marginals[0].dist_type = 'uniform'
+ >>> Inputs.Marginals[0].parameters = [-5, 5]
+
+ If there is no common data is avaliable, the input data can be given
+ as following:
+
+ >>> Inputs.add_marginals()
+ >>> Inputs.Marginals[0].name = 'X_1'
+ >>> Inputs.Marginals[0].input_data = input_data
"""
def __init__(self):
@@ -48,14 +36,41 @@ class Input:
self.Rosenblatt = False
def add_marginals(self):
+ """
+ Adds a new Marginal object to the input object.
+
+ Returns
+ -------
+ None.
+
+ """
self.Marginals.append(Marginal())
# Nested class
class Marginal:
+ """
+ An object containing the specifications of the marginals for each uncertain
+ parameter.
+
+ Attributes
+ ----------
+ name : string
+ Name of the parameter. The default is '$x_1$'.
+ dist_type : string
+ Name of the distribution. The default is None.
+ parameters : list
+ List of the parameters corresponding to the distribution type. The
+ default is None.
+ input_data : array_like
+ The available data corresponding to the parameters. The default is [].
+ moments : list
+ List of the moments.
+ """
+
def __init__(self):
- self.name = None
+ self.name = '$x_1$'
self.dist_type = None
- self.moments = None
- self.input_data = []
self.parameters = None
+ self.input_data = []
+ self.moments = None
--
GitLab