API Reference

This is the class and function reference of batman. Please refer to previous sections for further details, as the class and function raw specifications may not be enough to give full guidelines on their uses.

batman.space: Parameter space

space.Space(corners[, sample, nrefine, …])

Manages the space of parameters.

space.Doe(n_samples, bounds, kind[, dists, …])

DOE class.

space.Refiner(data, corners[, delta_space, …])

Resampling the space of parameters.

Space module

class batman.space.Doe(n_samples, bounds, kind, dists=None, discrete=None)[source]

DOE class.

__init__(n_samples, bounds, kind, dists=None, discrete=None)[source]

Initialize the DOE generation.

In case of kind is uniform, n_samples is decimated in order to have the same number of points in all dimensions.

If kind is discrete, a join distribution between a discrete uniform distribution is made with continuous distributions.

Another possibility is to set a list of PDF to sample from. Thus one can do: dists=[‘Uniform(15., 60.)’, ‘Normal(4035., 400.)’]. If not set, uniform distributions are used.

Parameters
  • n_samples (int) – number of samples.

  • bounds (array_like) – Space’s corners [[min, n dim], [max, n dim]]

  • kind (str) – Sampling Method if string can be one of [‘halton’, ‘sobol’, ‘faure’, ‘[o]lhs[c]’, ‘sobolscramble’, ‘uniform’, ‘discrete’] otherwize can be a list of openturns distributions.

  • dists (lst(str)) – List of valid openturns distributions as string.

  • discrete (int) – Position of the discrete variable.

generate()[source]

Generate the DOE.

Returns

Sampling.

Return type

array_like (n_samples, n_features)

logger = <Logger batman.space.sampling (WARNING)>
scramble(x)[source]

Scramble function.

scrambled_sobol_generate()[source]

Scrambled Sobol.

Scramble function as in Owen (1997).

uniform()[source]

Uniform sampling.

class batman.space.Refiner(data, corners, delta_space=0.08, discrete=None, pod=None)[source]

Resampling the space of parameters.

__init__(data, corners, delta_space=0.08, discrete=None, pod=None)[source]

Initialize the refiner with the Surrogate and space corners.

Points data are scaled between [0, 1] based on the size of the corners taking into account a :param:delta_space factor.

Parameters
discrepancy()[source]

Find the point that minimize the discrepancy.

Returns

The coordinate of the point to add.

Return type

lst(float)

distance_min(point)[source]

Get the distance of influence.

Compute the Chebyshev distance, max Linf norm between the anchor point and every sampling points. Linf allows to add this lenght to all coordinates and ensure that no points will be within this hypercube. It returns the minimal distance. point will be scaled by self.corners so the returned distance is scaled.

Parameters

point (array_like) – Anchor point.

Returns

The distance to the nearest point.

Return type

float.

extrema(refined_points)[source]

Find the min or max point.

Using an anchor point based on the extremum value at sample points, search the hypercube around it. If a new extremum is found,it uses Nelder-Mead method to add a new point. The point is then bounded back by the hypercube.

Returns

The coordinate of the point to add

Return type

lst(float)

func(coords, sign=1)[source]

Get the prediction for a given point.

Retrieve Gaussian Process estimation. The function returns plus or minus the function depending on the sign. -1 if we want to find the max and 1 if we want the min.

Parameters
  • coords (lst(float)) – coordinate of the point

  • sign (float) – -1. or 1.

Returns

L2 norm of the function at the point

Return type

float

hybrid(refined_points, point_loo, method, dists)[source]

Composite resampling strategy.

Uses all methods one after another to add new points. It uses the navigator defined within settings file.

Parameters
  • refined_points (lst(int)) – points idx not to consider for extrema

  • point_loo (batman.space.point.Point) – leave one out point

  • strategy (str) – resampling method

  • dists (lst(str)) – List of valid openturns distributions as string.

Returns

The coordinate of the point to add

Return type

lst(float)

hypercube_distance(point, distance)[source]

Get the hypercube to add a point in.

Propagate the distance around the anchor. point will be scaled by self.corners and input distance has to be already scalled. Ensure that new values are bounded by corners.

Parameters
  • point (array_like) – Anchor point.

  • distance (float) – The distance of influence.

Returns

The hypercube around the point.

Return type

array_like.

hypercube_optim(point)[source]

Get the hypercube to add a point in.

Compute the largest hypercube around the point based on the L2-norm. Ensure that only the leave-one-out point lies within it. Ensure that new values are bounded by corners.

Parameters

point (np.array) – Anchor point.

Returns

The hypercube around the point (a point per column).

Return type

array_like.

leave_one_out_sigma(point_loo)[source]

Mixture of Leave-one-out and Sigma.

Estimate the quality of the POD by leave-one-out cross validation (LOOCV), and add a point arround the max error point. The point is added within an hypercube around the max error point. The size of the hypercube is equal to the distance with the nearest point.

Parameters

point_loo (tuple) – leave-one-out point.

Returns

The coordinate of the point to add.

Return type

lst(float)

leave_one_out_sobol(point_loo, dists)[source]

Mixture of Leave-one-out and Sobol’ indices.

Same as function leave_one_out_sigma() but change the shape of the hypercube. Using Sobol’ indices, the corners are shrinked by the corresponding percentage of the total indices.

Parameters
  • point_loo (tuple) – leave-one-out point.

  • dists (lst(str)) – List of valid openturns distributions as string.

Returns

The coordinate of the point to add.

Return type

lst(float)

logger = <Logger batman.space.refiner (WARNING)>
optimization(method='EI', extremum='min')[source]

Maximization of the Probability/Expected Improvement.

Parameters
  • method (str) – Flag [‘EI’, ‘PI’].

  • extremum (str) – minimization or maximization objective [‘min’, ‘max’].

Returns

The coordinate of the point to add.

Return type

lst(float)

pred_sigma(coords)[source]

Prediction and sigma.

Same as Refiner.func() and Refiner.func_sigma(). Function prediction and sigma are weighted using POD modes.

Parameters

coords (lst(float)) – coordinate of the point

Returns

sum_f and sum_sigma

Return type

floats

sigma(hypercube=None)[source]

Find the point at max Sigma.

It returns the point where the variance (sigma) is maximum. To do so, it uses Gaussian Process information. A genetic algorithm get the global maximum of the function.

Parameters

hypercube (array_like) – Corners of the hypercube.

Returns

The coordinate of the point to add.

Return type

lst(float)

sigma_discrepancy(weights=None)[source]

Maximization of the composite indicator: sigma - discrepancy.

Parameters

weights (list(float)) – respectively weights of sigma and discrepancy.

Returns

The coordinate of the point to add.

Return type

lst(float)

sigma_distance(hypercube=None, weights=[0.5, 0.5])[source]

Find the point at max Sigma.

It returns the point where the variance (sigma) is maximum. To do so, it uses Gaussian Process information. A genetic algorithm get the global maximum of the function.

Parameters
  • hypercube (array_like) – Corners of the hypercube.

  • like weights (array) – Weights for sigma and distance

Returns

The coordinate of the point to add.

Return type

lst(float)

class batman.space.Sample(type=None, space=None, data=None, plabels=None, flabels=None, psizes=None, fsizes=None, pformat='npy', fformat='npy')[source]

Container class for samples.

__init__(type=None, space=None, data=None, plabels=None, flabels=None, psizes=None, fsizes=None, pformat='npy', fformat='npy')[source]

Initialize the container and build the column index.

This index carries feature names. Features can be scalars or vectors. Vector features do not need to be of the same size. Samples are stored as a 2D row-major array: 1 sample per row.

Parameters
  • space (array-like) – parameter space (1 point per sample)

  • data (array-like) – data associated to points

  • plabels (list(str)) – parameter names (for space)

  • flabels (list(str)) – feature names (for data)

  • psizes (list(int)) – lengths of parameters (for space)

  • fsizes (list(int)) – lengths of features (for data)

  • pformat (str) – file format name for space

  • fformat (str) – file format name for data

append(other, axis=0)[source]

Append samples to the container.

Parameters
  • other (array-like or pandas.DataFrame or Sample) – samples to append (1 sample per row)

  • axis (0 or 1) – how to append (add new samples or new features).

property data

Core of the data numpy.ndarray.

property dataframe

Underlying dataframe.

empty()[source]

Remove every stored samples.

property flabels

List of data feature labels.

Returns

a list of column labels, ordered the same as the underlying array.

Return type

list(str)

property fsizes

Sizes of data features.

Returns

the number of components of each feature.

Return type

list(int)

logger = <Logger batman.space.sample (WARNING)>
property plabels

List of space feature labels.

Returns

a list of column labels, ordered the same as the underlying array.

Return type

list(str)

pop(sid=- 1)[source]

Return and remove a sample (default: last one).

property psizes

Sizes of space features.

Returns

the number of components of each feature.

Return type

list(int)

read(space_fname='sample-space.npy', data_fname='sample-data.npy', plabels=None, flabels=None)[source]

Read and append samples from files.

Samples are stored in 2 files: space and data.

Parameters
  • space_fname (str) – path to space file.

  • data_fname (str) – path to data file.

  • plabels (list(str)) – labels in space file (if different from self.plabels)

  • flabels (list(str)) – labels in data file (if different from self.flabels)

property shape

Shape of the internal array.

property space

Space numpy.ndarray (point coordinates).

property values

Underlying numpy.ndarray.

Shape is (n_sample, n_columns). There may be multiple columns per feature. See Sample.psizes and Sample.fsizes.

write(space_fname='sample-space.npy', data_fname='sample-data.npy')[source]

Write samples to files.

Samples are stored in 2 files: space and data. Override if files exist.

Parameters
  • space_fname (str) – path to space file.

  • data_fname (str) – path to data file.

class batman.space.Space(corners, sample=inf, nrefine=0, plabels=None, psizes=None, multifidelity=None, duplicate=False, threshold=0.0, gp_samplers=None)[source]

Manages the space of parameters.

__init__(corners, sample=inf, nrefine=0, plabels=None, psizes=None, multifidelity=None, duplicate=False, threshold=0.0, gp_samplers=None)[source]

Generate a Space.

Parameters
  • corners (array_like) – hypercube ([min, n_features], [max, n_features]).

  • sample (int/array_like) – number of sample or list of sample of shape (n_samples, n_features).

  • nrefine (int) – number of point to use for refinement.

  • plabels (list(str)) – parameters’ names.

  • psizes (list(int)) – number of components of each parameters.

  • multifidelity (list(float)) – Whether to consider the first parameter as the fidelity level. It is a list of [‘cost_ratio’, ‘grand_cost’].

  • duplicate (bool) – Whether to allow duplicate points in space,

  • threshold (float) – minimal distance between 2 disctinct points,

  • gp_samplers (dict) – Gaussian process samplers for functional inputs

append(points)[source]

Add points to the space.

Ignore any point that already exists or that would exceed space capacity.

Parameters

points (array_like) – Point(s) to add to space (n_samples, n_features)

Returns

Added points.

Return type

numpy.ndarray

static discrepancy(sample, bounds=None, method='CD')[source]

Compute the discrepancy.

Centered, wrap around or mixture discrepancy measures the uniformity of the parameter space. The lowest the value, the uniform the design.

Parameters
  • sample (array_like) – The sample to compute the discrepancy from (n_samples, k_vars).

  • bounds (array_like) – Desired range of transformed data. The transformation apply the bounds on the sample and not the theoretical space, unit cube. Thus min and max values of the sample will coincide with the bounds. ([min, k_vars], [max, k_vars]).

  • method (str) – Type of discrepancy. [‘CD’, ‘WD’, ‘MD’].

Returns

Discrepancy.

Return type

float.

logger = <Logger batman.space.space (WARNING)>
static mst(sample, fname=None, plot=True)[source]

Minimum Spanning Tree.

MST is used here as a discrepancy criterion. Comparing two different designs: the higher the mean, the better the design is in terms of space filling.

Parameters
  • sample (array_like) – The sample to compute the discrepancy from (n_samples, k_vars).

  • fname (str) – whether to export to filename or display the figures.

Returns

Mean, standard deviation and edges of the MST.

Rtypes

float, float, array_like (n_edges, 2 nodes indices).

optimization_results(extremum)[source]

Compute the optimal value.

Parameters

extremum (str) – minimization or maximization objective [‘min’, ‘max’].

read(path)[source]

Read space from file path.

refine(surrogate, method, point_loo=None, delta_space=0.08, dists=None, hybrid=None, discrete=None, extremum='min', weights=[0.5, 0.5])[source]

Refine the sample, update space points and return the new point(s).

Parameters
  • surrogate (batman.surrogate.SurrogateModel.) – Surrogate.

  • method (str) – Refinement method.

  • point_loo (array_like) – Leave-one-out worst point (n_features,).

  • delta_space (float) – Shrinking factor for the parameter space.

  • dists (lst(str)) – List of valid openturns distributions as string.

  • int)) hybrid (lst(lst(str,) – Navigator as list of [Method, n].

  • discrete (int) – Index of the discrete variable.

  • extremum (str) – Minimization or maximization objective [‘min’, ‘max’].

  • weights (array_like) – Weights used in composed optimisation fucntion.

Returns

List of points to add.

Return type

numpy.ndarray

sampling(n_samples=None, kind='halton', dists=None, discrete=None)[source]

Create point samples in the parameter space.

Minimum number of samples for halton and sobol: 4 For uniform sampling, the number of points is per dimensions. The points are registered into the space and replace existing ones.

Parameters
  • n_samples (int) – number of samples.

  • kind (str) – method of sampling.

  • dists (lst(str)) – List of valid openturns distributions as string.

  • discrete (int) – index of the discrete variable

Returns

List of points.

Return type

numpy.ndarray

write(path='.', fname='space.dat', doe=True)[source]

Write space to file path, then plot it.

batman.space.dists_to_ot(dists)[source]

Convert distributions to openTURNS.

The list of distribution is converted to openTURNS objects.

Example

>> from batman.space import dists_to_ot
>> dists = dists_to_ot(['Uniform(12, 15)', 'Normal(400, 10)'])
Parameters

dists (list(str)) – Distributions available in openTURNS.

Returns

List of openTURNS distributions.

Return type

list(openturns.Distribution)

batman.space.kernel_to_ot(kernel)[source]

Convert kernel to openTURNS.

The kernel is converted to openTURNS objects.

Example

>> from batman.space import kernels_to_ot
>> kernel = kernel_to_ot("AbsoluteExponential([0.5], 1.0)")
Parameters

kernel (str) – Kernel available in openTURNS.

Returns

openTURNS kernel.

Return type

list(openturns.Kernel)

batman.surrogate: Surrogate Modelling

surrogate.SurrogateModel(kind, corners, …)

Surrogate model.

surrogate.Kriging(sample, data[, kernel, …])

Kriging based on Gaussian Process.

surrogate.PC(strategy, degree, distributions)

Polynomial Chaos class.

surrogate.RBFnet(trainIn, trainOut[, …])

RBF class.

Surrogate model module

class batman.surrogate.Evofusion(sample, data)[source]

Multifidelity algorithm using Evofusion.

__init__(sample, data)[source]

Create the predictor.

Data are arranged as decreasing fidelity. Hence, sample[0] corresponds to the highest fidelity.

Parameters
  • sample (array_like) – The sample used to generate the data. (fidelity, n_samples, n_features)

  • data (array_like) – The observed data. (fidelity, n_samples, [n_features])

evaluate(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

logger = <Logger batman.surrogate.multifidelity (WARNING)>
class batman.surrogate.Kriging(sample, data, kernel=None, n_jobs=None, noise=False, global_optimizer=True)[source]

Kriging based on Gaussian Process.

__init__(sample, data, kernel=None, n_jobs=None, noise=False, global_optimizer=True)[source]

Create the predictor.

Uses sample and data to construct a predictor using Gaussian Process. Input is to be normalized before and depending on the number of parameters, the kernel is adapted to be anisotropic.

self.data contains the predictors as a list(array) of the size of the ouput. A predictor per line of data is created. This leads to a line of predictors that predicts a new column of data.

If noise is a float, it will be used as noise_level by sklearn.gaussian_process.kernels.WhiteKernel. Otherwise, if noise is True, default values are use for the WhiteKernel. If noise is False, no noise is added.

A multiprocessing strategy is used:

  1. Create a process per mode, do not create if only one,

  2. Create n_restart (3 by default) processes by process.

In the end, there is \(N=n_{restart} \times n_{modes})\) processes. If there is not enought CPU, \(N=\frac{n_{cpu}}{n_{restart}}\).

Parameters
  • sample (array_like) – Sample used to generate the data (n_samples, n_features).

  • data (array_like) – Observed data (n_samples, n_features).

  • kernel (sklearn.gaussian_process.kernels.*.) – Kernel from scikit-learn.

  • noise (float/bool) – Noise used into kriging.

  • global_optimizer (bool) – Whether to do global optimization or gradient based optimization to estimate hyperparameters.

evaluate(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

logger = <Logger batman.surrogate.kriging (WARNING)>
class batman.surrogate.Mixture(samples, data, corners, fsizes=None, pod=None, standard=True, local_method=None, pca_percentage=0.8, clusterer='cluster.KMeans(n_clusters=2)', classifier='gaussian_process.GaussianProcessClassifier()')[source]

Mixture class.

Unsupervised machine learning separate the DoE into clusters, supervised machine learning classify new sample to a cluster and local models predict the new sample.

__init__(samples, data, corners, fsizes=None, pod=None, standard=True, local_method=None, pca_percentage=0.8, clusterer='cluster.KMeans(n_clusters=2)', classifier='gaussian_process.GaussianProcessClassifier()')[source]

Cluster data and fit local models.

  1. If data is not scalar, compute PCA on data.

  2. Cluster data.

  3. Each sample is affiliated to a cluster.

  4. Fit a classifier to handle new samples.

  5. A local model for each cluster is built.

If local_method is not None, set as list of dict with options. Ex: [{‘kriging’: {**args}}]

Parameters
  • sample (array_like) – Sample of parameters of Shape (n_samples, n_params).

  • data (array_like) – Sample of realization which corresponds to the sample of parameters sample (n_samples, n_features).

  • corners (array_like) – Hypercube ([min, n_features], [max, n_features]).

  • fsizes (int) – Number of components of output features.

  • pod (dict) –

    Whether to compute POD or not in local models.

    • tolerance (float) – Basis modes filtering criteria.

    • dim_max (int) – Number of basis modes to keep.

  • standard (bool) – Whether to standardize data before clustering.

  • local_method (lst(dict)) – List of local surrrogate models for clusters or None for Kriging local surrogate models.

  • pca_percentage (float) – Percentage of information kept for PCA.

  • clusterer (str) – Clusterer from sklearn (unsupervised machine learning). http://scikit-learn.org/stable/modules/clustering.html#clustering

  • classifier (str) – Classifier from sklearn (supervised machine learning). http://scikit-learn.org/stable/supervised_learning.html

boundaries(samples, plabels=None, fname=None)[source]

Boundaries of clusters in the parameter space.

Plot the boundaries for 2D and 3D hypercube or parallel coordinates plot for more than 3D to see the influence of sample variables on cluster affiliation.

Parameters
  • samples (array_like) – Sample features (n_samples, n_features).

  • plabels (list(str)) – Names of each parameters (n_features).

  • fname (str) – Whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

estimate_quality(multi_q2=False)[source]

Estimate quality of the local models.

Compute the Q2 for each cluster and return either the Q2 for each cluster or the lowest one with its cluster affiliation.

Parameters

multi_q2 (float/bool) – Whether to return the minimal q2 or the q2 of each cluster.

Returns

q2: Q2 quality for each cluster or the minimal value

Return type

array_like(n_cluster)/float.

Returns

point: Max MSE point for each cluster or the one corresponding to minimal Q2 value.

Return type

array_like(n_cluster)/float.

evaluate(points, classification=False)[source]

Predict new samples.

Classify new samples then predict using the corresponding local model.

Parameters
  • points (array_like) – Samples to predict (n_samples, n_features).

  • classification (bool) – Whether to output classification info.

Returns

predict, sigma: Prediction and sigma of new samples.

Return type

array_like (n_samples, n_features), array_like (n_samples, n_features)

logger = <Logger batman.surrogate.mixture (WARNING)>
class batman.surrogate.PC(strategy, degree, distributions, N_quad=None, sample=None, stieltjes=True, sparse_param={})[source]

Polynomial Chaos class.

__init__(strategy, degree, distributions, N_quad=None, sample=None, stieltjes=True, sparse_param={})[source]

Generate truncature and projection strategies.

Allong with the strategies the sample is storred as an attribute. sample as well as corresponding weights: weights.

Parameters
  • strategy (str) – Least square or Quadrature [‘LS’, ‘Quad’, ‘SparseLS’].

  • degree (int) – Polynomial degree.

  • distributions (lst(openturns.Distribution)) – Distributions of each input parameter.

  • sample (array_like) – Samples for least square (n_samples, n_features).

  • stieltjes (bool) – Wether to use Stieltjes algorithm for the basis.

  • sparse_param (dict) –

    Parameters for the Sparse Cleaning Truncation Strategy and/or hyperbolic truncation of the initial basis.

    • max_considered_terms (int) – Maximum Considered Terms,

    • most_significant (int), Most Siginificant number to retain,

    • significance_factor (float), Significance Factor,

    • hyper_factor (float), factor for hyperbolic truncation strategy.

evaluate(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

fit(sample, data)[source]

Create the predictor.

The result of the Polynomial Chaos is stored as pc_result and the surrogate is stored as pc. It exposes self.weights, self.coefficients and Sobol’ indices self.s_first and self.s_total.

Parameters
  • sample (array_like) – The sample used to generate the data (n_samples, n_features).

  • data (array_like) – The observed data (n_samples, [n_features]).

logger = <Logger batman.surrogate.polynomial_chaos (WARNING)>
class batman.surrogate.RBFnet(trainIn, trainOut, regparam=0.0, radius=1.5, regtree=0, function='default', Pmin=2, Radscale=1.0)[source]

RBF class.

Calc_moyenne(Point)[source]

Compute the average.

RBFout(Point, neuroNum)[source]

Output of RBF evaluation.

__init__(trainIn, trainOut, regparam=0.0, radius=1.5, regtree=0, function='default', Pmin=2, Radscale=1.0)[source]

Initialization.

initialise le reseau principal a partir d’un tableau de points d’entrainements de taille Setsize*(Ninputs) pour les inputs et Setsize*(Noutputs) pour les outputs ds trainOut possibilite d’utiliser d’arbre de regression sur les donnees (regtree=1) le reseau est ensuite entraine sur cet ensemble avec le parametere Regparam

initialisation trainIn est copie pour le pas affecter l’original dans le prog appelant

coefs_mean()[source]

Mean coefficients.

fonction permettant de calculer le plan moyen a partir de laquelle partent les gaussiennes par regression lineaire multiple

compute_radius(cel)[source]

Radius.

calcule le rayon pour la cellule i lorsque on utilise pas l’arbre de regression ce rayon est calcule comme la demi distance a la plus proche cellule

evaluate(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

trainNet()[source]

Train.

entrainement du reseau de neurone principal : calcul des poids trainIn tableau de points d’entrainements de taille Setsize*(Ninputs) pour les inputs et Setsize pour les outputs ds trainOut

class batman.surrogate.SklearnRegressor(sample, data, regressor)[source]

Interface to Scikit-learn regressors.

__init__(sample, data, regressor)[source]

Create the predictor.

Uses sample and data to construct a predictor using sklearn. Input is to be normalized before and depending on the number of parameters, the kernel is adapted to be anisotropic.

Parameters
  • sample (array_like) – Sample used to generate the data (n_samples, n_features).

  • data (array_like) – Observed data (n_samples, n_features).

  • regressor (Either regressor object or str(sklearn.ensemble.Regressor)) – Scikit-Learn regressor.

  • regressor_options – Associated regressor hyper parameter

evaluate(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

logger = <Logger batman.surrogate.sk_interface (WARNING)>
class batman.surrogate.SurrogateModel(kind, corners, plabels, **kwargs)[source]

Surrogate model.

__call__(points)[source]

Predict snapshots.

Parameters
  • points (batman.space.Point or array_like (n_samples, n_features).) – point(s) to predict.

  • path (str) – if not set, will return a list of predicted snapshots instances, otherwise write them to disk.

Returns

Result.

Return type

array_like (n_samples, n_features)

Returns

Standard deviation.

Return type

array_like (n_samples, n_features)

__init__(kind, corners, plabels, **kwargs)[source]

Init Surrogate model.

Parameters
  • kind (str) – name of prediction method, one of: [‘rbf’, ‘kriging’, ‘pc’, ‘evofusion’, ‘mixture’, ‘LinearRegression’, ‘LogisticRegression’, ‘LogisticRegressionCV’, ‘PassiveAggressiveRegressor’, ‘SGDRegressor’, ‘TheilSenRegressor’, ‘DecisionTreeRegressor’, ‘GradientBoostingRegressor’, ‘AdaBoostRegressor’, ‘RandomForestRegressor’, ‘ExtraTreesRegressor’].

  • corners (array_like) – hypercube ([min, n_features], [max, n_features]).

  • plabels (list(str)) – labels of sample points

  • **kwargs – See below

Keyword Arguments

For Polynomial Chaos the following keywords are available

  • strategy (str) – Least square or Quadrature [‘LS’, ‘Quad’, ‘SparseLS’].

  • degree (int) – Polynomial degree.

  • distributions (lst(openturns.Distribution)) – Distributions of each input parameter.

  • sample (array_like) – Samples for least square (n_samples, n_features).

  • sparse_param (dict) – Parameters for the Sparse Cleaning Truncation Strategy and/or hyperbolic truncation of the initial basis.

    • max_considered_terms (int) – Maximum Considered Terms,

    • most_significant (int), Most Siginificant number to retain,

    • significance_factor (float), Significance Factor,

    • hyper_factor (float), factor for hyperbolic truncation strategy.

For Kriging the following keywords are available

  • kernel (sklearn.gaussian_process.kernels.*) – Kernel.

  • noise (float/bool) – noise level.

  • global_optimizer (bool) – Whether to do global optimization or gradient based optimization to estimate hyperparameters.

For Mixture the following keywords are available

  • fsizes (int) – Number of components of output features.

  • pod (dict) – Whether to compute POD or not in local models.

    • tolerance (float) – Basis modes filtering criteria.

    • dim_max (int) – Number of basis modes to keep.

  • standard (bool) – Whether to standardize data before clustering.

  • local_method (lst(dict)) – List of local surrrogate models for clusters or None for Kriging local surrogate models.

  • pca_percentage (float) – Percentage of information kept for PCA.

  • clusterer (str) – Clusterer from sklearn (unsupervised machine learning). http://scikit-learn.org/stable/modules/clustering.html#clustering

  • classifier (str) – Classifier from sklearn (supervised machine learning). http://scikit-learn.org/stable/supervised_learning.html

For all the over regressor from sci-kit learn the following keywords are available

  • regressor_options (str) – Parameter of the associated sci-kit learn regressor

estimate_quality(method='LOO')[source]

Estimate quality of the model.

Parameters

method (str) – method to compute quality [‘LOO’, ‘ValidationSet’].

Returns

Q2 error.

Return type

float.

Returns

Max MSE point.

Return type

lst(float)

fit(sample, data, pod=None)[source]

Construct the surrogate.

Parameters
  • sample (array_like) – sample (n_samples, n_features).

  • data (array_like) – function evaluations (n_samples, n_features).

  • pod (batman.pod.Pod.) – POD instance.

logger = <Logger batman.surrogate.surrogate_model (WARNING)>
read(fname='.')[source]

Load model, data and space from disk.

Parameters

fname (str) – path to a directory.

write(fname='.')[source]

Save model and data to disk.

Parameters

fname (str) – path to a directory.

batman.uq: Uncertainty Quantification

uq.UQ(surrogate[, dists, nsample, method, …])

Uncertainty Quantification class.

UQ module

class batman.uq.UQ(surrogate, dists=None, nsample=1000, method='sobol', indices='aggregated', space=None, data=None, plabels=None, xlabel=None, flabel=None, xdata=None, fname=None, test=None, mesh={})[source]

Uncertainty Quantification class.

__init__(surrogate, dists=None, nsample=1000, method='sobol', indices='aggregated', space=None, data=None, plabels=None, xlabel=None, flabel=None, xdata=None, fname=None, test=None, mesh={})[source]

Init the UQ class.

From the settings file, it gets:

  • Method to use for the Sensitivity Analysis (SA),

  • Type of Sobol’ indices to compute,

  • Number of points per sample to use for SA (\(N(2p+2)\) predictions), resulting storage is 6N(out+p)*8 octets => 184Mo if N=1e4

  • Method to use to predict a new snapshot,

  • The list of input variables,

  • The lengh of the output function.

Also, it creates the model and int_model as openturns.PythonFunction.

Parameters
  • surrogate (class:batman.surrogate.SurrogateModel.) – Surrogate model.

  • space (class:batman.space.Space.) – sample space (can be a list).

  • data (array_like) – Snapshot’s data (n_samples, n_features).

  • plabels (list(str)) – parameters’ names.

  • xlabel (str) – label of the discretization parameter.

  • flabel (str) – name of the quantity of interest.

  • xdata (array_like) – 1D discretization of the function (n_features,).

  • fname (str) – folder output path.

  • test (str) – Test function from class:batman.functions.

  • mesh (dict) –

    For 2D plots the following keywords are available

    • fname (str) – name of mesh file.

    • fformat (str) – format of the mesh file.

    • xlabel (str) – name of the x-axis.

    • ylabel (str) – name of the y-axis.

    • vmins (lst(double)) – value of the minimal output for data filtering.

error_model(indices, function)[source]

Compute the error between the POD and the analytic function.

Warning

For test purpose only. Choises are Ishigami, Rosenbrock, Michalewicz, G_Function and Channel_Flow test functions.

From the surrogate of the function, evaluate the error using the analytical evaluation of the function on the sample points.

\[Q^2 = 1 - \frac{err_{l2}}{var_{model}}\]

Knowing that \(err_{l2} = \sum \frac{(prediction - reference)^2}{n}\), \(var_{model} = \sum \frac{(prediction - mean)^2}{n}\)

Also, it computes the mean square error on the Sobol first andtotal order indices.

A summary is written within model_err.dat.

Parameters
  • indices (array_like) – Sobol first order indices computed using the POD.

  • function (str) – name of the analytic function.

Returns

err_q2, mse, s_l2_2nd, s_l2_1st, s_l2_total.

Return type

array_like.

error_propagation()[source]

Compute the moments.

1st, 2nd order moments are computed for every output of the function. Also compute the PDF for these outputs, and compute correlations (YY and XY) and correlation (YY). Both exported as 2D cartesian plots. Files are respectivelly:

  • pdf-moment.dat, moments [discretized on curvilinear abscissa]

  • pdf.dat -> the PDFs [discretized on curvilinear abscissa]

  • correlation_covariance.dat -> correlation and covariance YY

  • correlation_XY.dat -> correlation XY

  • pdf.pdf, plot of the PDF (with moments if dim > 1)

func(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

int_func(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

logger = <Logger batman.uq.uq (WARNING)>
sobol()[source]

Compute Sobol’ indices.

It returns the second, first and total order indices of Sobol’. Two methods are possible for the indices:

  • sobol

  • FAST

Warning

The second order indices are only available with the sobol method. Also, when there is no surrogate (ensemble mode), FAST is not available and the DoE must have been generated with saltelli.

And two types of computation are availlable for the global indices:

  • block

  • aggregated

If aggregated, map indices are computed. In case of a scalar value, all types returns the same values. block indices are written within sensitivity.dat and aggregated indices within sensitivity_aggregated.dat.

Finally, it calls error_pod() in order to compare the indices with their analytical values.

Returns

Sobol’ indices.

Return type

array_like.

batman.uq.cosi(sample, data)[source]

Cosine transformation sensitivity.

Use Discret Cosine Transformation (DCT) to compute sensitivity indices.

Parameters
  • sample (array_like) – Sample of parameters of Shape (n_samples, n_params).

  • data (array_like) – Sample of realization which corresponds to the sample of parameters sample (n_samples, ).

Returns

First order sensitivity indices.

Return type

(Sobol, n_features)

batman.visualization: Uncertainty Visualization

visualization.Kiviat3D(sample, data[, idx, …])

3D version of the Kiviat plot.

visualization.HdrBoxplot(data[, variance, …])

High Density Region boxplot.

visualization.doe(sample[, plabels, …])

Plot the space of parameters 2d-by-2d.

visualization.response_surface(bounds[, …])

Response surface visualization in 2d (image), 3d (movie) or 4d (movies).

visualization.corr_cov(data, sample, xdata)

Correlation and covariance matrices.

visualization.pdf(data[, xdata, xlabel, …])

Plot PDF in 1D or 2D.

visualization.kernel_smoothing(data[, optimize])

Create gaussian kernel.

visualization.reshow(fig)

Create a dummy figure and use its manager to display fig.

Visualization module

class batman.visualization.HdrBoxplot(data, variance=0.8, alpha=None, threshold=0.95, outliers_method='kde', optimize=False)[source]

High Density Region boxplot.

From a given dataset, it computes the HDR-boxplot. Results are accessibles directly through class attributes:

  • median : median curve,

  • outliers : outliers regarding a given threshold,

  • hdr_90 : 90% quantile band,

  • extra_quantiles : other quantile bands,

  • hdr_50 : 50% quantile band.

The following methods are for convenience:

Example

>> hdr = HdrBoxplot(data)
>> hdr.plot()
>> hdr.f_hops(generate=10)
>> hdr.sound()
__init__(data, variance=0.8, alpha=None, threshold=0.95, outliers_method='kde', optimize=False)[source]

Compute HDR Boxplot on data.

  1. Compute a 2D kernel smoothing with a Gaussian kernel,

  2. Compute contour lines for quantiles 90, 50 and alpha,

  3. Compute mediane curve along with quantiles regions and outlier curves.

Parameters
  • data (array_like) – dataset (n_samples, n_features).

  • variance (float) – percentage of total variance to conserve.

  • alpha (array_like) – extra quantile values (n_alpha).

  • threshold (float) – threshold for outliers.

  • outliers_method (str) – detection method [‘kde’, ‘forest’].

  • optimize (bool) – bandwidth global optimization or grid search.

  • n_contours (int) – discretization to compute contour.

band_quantiles(band)[source]

Find extreme curves for a quantile band.

From the band of quantiles, the associated PDF extrema values are computed. If min_alpha is not provided (single quantile value), max_pdf is set to 1E6 in order not to constrain the problem on high values.

An optimization is performed per component in order to find the min and max curves. This is done by comparing the PDF value of a given curve with the band PDF.

Parameters

band (array_like) – alpha values [max_alpha, min_alpha] ex: [0.9, 0.5].

Returns

[max_quantile, min_quantile] (2, n_features).

Return type

list(array_like)

f_hops(frame_rate=400, fname='f-HOPs.mp4', samples=None, x_common=None, labels=None, xlabel='t', flabel='F', offset=0.05)[source]

Functional Hypothetical Outcome Plots.

Each frame consists in a HDR boxplot and an additional outcome. If it is an outlier, it is rendered as red dashed line.

If samples is None it will use the dataset, if an int>0 it will samples n new samples ; and if array_like, shape (n_samples, n_features) it will use this.

Parameters
  • frame_rate (int) – time between two outcomes (in milliseconds).

  • fname (str) – export movie to filename.

  • int, list samples (False,) – Data selector.

  • x_common (array_like) – abscissa.

  • labels (list(str)) – labels for each curve.

  • xlabel (str) – label for x axis.

  • flabel (str) – label for y axis.

  • offset (float) – Margin around the extreme values of the plot.

find_outliers(data, data_r=None, method='kde', threshold=0.95)[source]

Detect outliers.

The Isolation forrest method requires additional computations to find the centroide. This operation is only performed once and stored in self.detector. Thus calling, several times the method will not cause any overhead.

Parameters
  • data (array_like) – data from which to extract outliers (n_samples, n_features).

  • data_r (array_like) – data_r values corresponding to data (n_samples, n_features/n_components).

  • method (str) – detection method [‘kde’, ‘forest’].

  • threshold (float) – detection sensitivity.

Returns

Outliers.

Return type

array_like (n_outliers, n_features)

logger = <Logger batman.visualization.hdr (WARNING)>
plot(samples=None, fname=None, x_common=None, labels=None, xlabel='t', flabel='F', dataset=True)[source]

Functional plot and n-variate space.

If self.n_components is 2, an additional contour plot is done. If samples is None, the dataset is used for all plots ; otherwize the given sample is used.

Parameters
  • array_like – samples to plot (n_samples, n_features).

  • fname (str) – whether to export to filename or display the figures.

  • x_common (array_like) – abscissa (1, n_features).

  • labels (list(str)) – labels for each curve.

  • xlabel (str) – label for x axis.

  • flabel (str) – label for y axis.

  • dataset (bool) – Show dataset or hide it.

Returns

figures and all axis.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

sample(samples)[source]

Sample new curves from KDE.

If samples is an int>0, n new curves are randomly sampled taking into account the joined PDF ; and if array_like, shape (n_samples, n_components) curves are sampled from reduce coordinates of the n-variate space.

Parameters

array_like samples (int,) – Data selector.

Returns

new curves.

Return type

array_like (n_samples, n_features)

sound(frame_rate=400, tone_range=None, amplitude=1000.0, distance=True, samples=False, fname='song-fHOPs.wav')[source]

Make sound from curves.

Each curve is converted into a sum of tones. This sum is played during a given time before another serie starts.

If samples is False it will use the dataset, if an int>0 it will samples n new samples ; and if array_like, shape (n_samples, n_features) it will use this.

Parameters
  • frame_rate (int) – time between two outcomes (in milliseconds).

  • tone_range (list(int)) – range of frequencies of a tone (in hertz).

  • amplitude (float) – amplitude of the signal.

  • distance (bool) – use distance from median for tone generation.

  • int, list samples (False,) – Data selector.

  • fname (str) – export sound to filename.

class batman.visualization.Kiviat3D(sample, data, idx=None, bounds=None, plabels=None, range_cbar=None, stack_order='qoi', cbar_order='qoi')[source]

3D version of the Kiviat plot.

Each realization is stacked on top of each other. The axis represent the parameters used to perform the realization.

__init__(sample, data, idx=None, bounds=None, plabels=None, range_cbar=None, stack_order='qoi', cbar_order='qoi')[source]

Prepare params for Kiviat plot.

Parameters
  • sample (array_like) – Sample of parameters of Shape (n_samples, n_params).

  • data (array_like) – Sample of realization which corresponds to the sample of parameters sample (n_samples, n_features).

  • idx (int) – Index on the functional data to consider.

  • bounds (array_like) – Boundaries to scale the colors shape ([min, n_features], [max, n_features]).

  • plabels (list(str)) – Names of each parameters (n_features).

  • range_cbar (array_like) – Minimum and maximum values for output function (2 values).

  • stack_order (str/int) – Set stacking order [‘qoi’, ‘hdr’]. If an integer, it represents the input variable to take into account.

  • cbar_order (str) – Set color mapping order [‘qoi’, ‘hdr’].

f_hops(frame_rate=400, fname='kiviat-HOPs.mp4', flabel='F', ticks_nbr=10, fill=True)[source]

Plot HOPs 3D kiviat.

Each frame consists in a 3D Kiviat with an additional outcome highlighted.

Parameters
  • frame_rate (int) – Time between two outcomes (in milliseconds).

  • fname (str) – Export movie to filename.

  • flabel (str) – Name of the output function to be plotted next to the colorbar.

  • fill (bool) – Whether to fill the surface.

  • ticks_nbr (int) – Number of ticks in the colorbar.

static mesh_connectivity(n_points, n_params)[source]

Compute connectivity for Kiviat.

Using the n_points and n_params, it creates the connectivity required by VTK’s pixel elements:

       4
3 *----*----* 5
  |    |    |
0 *----*----* 2
       1

This will output:

4 0 1 3 4
4 1 2 4 5
Parameters
  • n_points (int) – Number of points.

  • n_params (int) – Number of features.

Returns

Connectivity.

Return type

array_like of shape (n_cells, 5)

static mesh_vtk_ascii(coords, data, connectivity, fname='mesh_kiviat.vtk')[source]

Write mesh file in VTK ascii format.

Format is as following (example with 3 cells):

# vtk DataFile Version 2.0
Kiviat 3D
ASCII

DATASET UNSTRUCTURED_GRID

POINTS 6 float
-0.40  0.73 0.00
-0.00 -0.03 0.00
 0.50  0.00 0.00
-0.40  0.85 0.04
-0.00 -0.12 0.04
 0.50  0.00 0.04


CELLS 3 15
4 0 1 3 4
4 1 2 4 5
4 2 0 5 3

CELL_TYPES 3
8
8
8

POINT_DATA 6
SCALARS value double
LOOKUP_TABLE default
17.770e+0
17.770e+0
17.770e+0
17.774e+0
17.774e+0
17.774e+0
Parameters
  • coordinates (array_like) – Sample coordinates of shape (n_samples, n_features).

  • data (array_like) – function evaluations of shape (n_samples, n_features).

plot(fname=None, flabel='F', ticks_nbr=10, fill=True)[source]

Plot 3D kiviat.

Along with the matplotlib visualization, a VTK mesh is created.

Parameters
  • fname (str) – Whether to export to filename or display the figures.

  • flabel (str) – Name of the output function to be plotted next to the colorbar.

  • ticks_nbr (int) – Number of ticks in the colorbar.

  • fill (bool) – Whether to fill the surface.

Returns

figure.

Return type

Matplotlib figure instance, Matplotlib AxesSubplot instances.

class batman.visualization.Tree(sample, data, bounds=None, plabels=None, range_cbar=None)[source]

Tree.

Extend principle of batman.visualization.Kiviat3D but for 2D parameter space. Sample are represented by segments and an azimutal component encode the value from batman.visualization.HdrBoxplot.

Subclass batman.visualization.Kiviat3D by overwriting batman.visualization.Kiviat3D._axis() and batman.visualization.Kiviat3D.plane().

__init__(sample, data, bounds=None, plabels=None, range_cbar=None)[source]

Prepare params for Tree plot.

Parameters
  • sample (array_like) – Sample of parameters of Shape (n_samples, n_params).

  • data (array_like) – Sample of realization which corresponds to the sample of parameters sample (n_samples, n_features).

  • bounds (array_like) – Boundaries to scale the colors shape ([min, n_features], [max, n_features]).

  • plabels (list(str)) – Names of each parameters (n_features).

  • range_cbar (array_like) – Minimum and maximum values for output function (2 values).

batman.visualization.corr_cov(data, sample, xdata, xlabel='x', plabels=None, interpolation=None, fname=None)[source]

Correlation and covariance matrices.

Compute the covariance regarding YY and XY as well as the correlation regarding YY.

Parameters
  • data (array_like) – function evaluations (n_samples, n_features).

  • sample (array_like) – sample (n_samples, n_featrues).

  • xdata (array_like) – 1D discretization of the function (n_features,).

  • xlabel (str) – label of the discretization parameter.

  • plabels (list(str)) – parameters’ labels.

  • interpolation (str) – If None, does not interpolate correlation and covariance matrices (YY). Otherwize use Matplotlib methods from imshow such as [‘bilinear’, ‘lanczos’, ‘spline16’, ‘hermite’, …].

  • fname (str) – whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

batman.visualization.cusunoro(sample, data, plabels=None, fname=None)[source]

Cumulative sums of normalised reordered output.

  1. Data are normalized (mean=0, variance=1),

  2. Choose a feature and order its values,

  3. Order normalized data accordingly,

  4. Compute the cumulative sum vector.

  5. Plot and repeat for all features.

Parameters
  • sample (array_like) – Sample of parameters of Shape (n_samples, n_params).

  • data (array_like) – Sample of realization which corresponds to the sample of parameters sample (n_samples, ).

  • plabels (list(str)) – Names of each parameters (n_features).

  • fname (str) – whether to export to filename or display the figures.

Returns

figure, axis and sensitivity indices.

Return type

Matplotlib figure instance, Matplotlib AxesSubplot instance, array_like.

batman.visualization.doe(sample, plabels=None, resampling=0, multifidelity=False, fname=None)[source]

Plot the space of parameters 2d-by-2d.

A n-variate plot is constructed with all couple of variables. The distribution on each variable is shown on the diagonal.

Parameters
  • sample (array_like) – sample (n_samples, n_featrues).

  • plabels (list(str)) – parameters’ names.

  • resampling (int) – number of resampling points.

  • multifidelity (bool) – whether or not the model is a multifidelity.

  • fname (str) – whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

batman.visualization.doe_ascii(sample, bounds=None, plabels=None, fname=None)[source]

Plot the space of parameters 2d-by-2d in ASCII.

Parameters
  • sample (array_like) – sample (n_samples, n_featrues).

  • bounds (array_like) – Desired range of transformed data. The transformation apply the bounds on the sample and not the theoretical space, unit cube. Thus min and max values of the sample will coincide with the bounds. ([min, k_vars], [max, k_vars]).

  • plabels (list(str)) – parameters’ names.

  • fname (str) – whether to export to filename or display on console.

batman.visualization.kernel_smoothing(data, optimize=False)[source]

Create gaussian kernel.

The optimization option could lead to longer computation of the PDF.

Parameters
  • data (array_like) – output sample to draw a PDF from (n_samples, n_features).

  • optimize (bool) – use global optimization of grid search.

Returns

gaussian kernel.

Return type

sklearn.neighbors.KernelDensity.

batman.visualization.mesh_2D(fname, var=None, flabels=None, fformat='csv', xlabel='X axis', ylabel='Y axis', vmins=None, output_path=None)[source]

Visualization of specific variable on a user provided 2D mesh.

The provided mesh should contain two columns (x,y coordinates for each mesh point) and be one of batman.input_output.available_formats(). (x, y) must be respectively the first and second column. Any other column is treated as an extra variable and will be used to plot a figure. If var is not None, its content will be used as plotting variables.

Parameters
  • fname (str) – name of mesh file.

  • var (array_like) – data to be plotted shape (n_coords, n_vars).

  • flabels (list(str)) – names of the variables.

  • fformat (str) – format of the mesh file.

  • xlabel (str) – name of the x-axis.

  • ylabel (str) – name of the y-axis.

  • vmins (lst(double)) – value of the minimal output for data filtering.

  • output_path (str) – name of the output path.

Returns

figure.

Return type

Matplotlib figure instances.

batman.visualization.moment_independent(sample, data, plabels=None, scale_plt=True, fname=None)[source]

Moment independent measures.

Use both PDF and ECDF to cumpute moment independent measures. The following algorithm describes the PDF method (ECDF works the same):

  1. Compute the unconditional PDF,

  2. Choose a feature and order its values and order the data accordingly,

  3. Create bins based on the feature ranges,

  4. Compute the PDF of the ordered data on all successive bins,

  5. Plot and repeat for all features.

Parameters
  • sample (array_like) – Sample of parameters of Shape (n_samples, n_params).

  • data (array_like) – Sample of realization which corresponds to the sample of parameters sample (n_samples, ).

  • plabels (list(str)) – Names of each parameters (n_features).

  • scale_plt (bool) – Whether to scale y-axes between figures.

  • fname (str) – Whether to export to filename or display the figures.

Returns

Figure, axis and sensitivity indices.

Return type

Matplotlib figure instance, Matplotlib AxesSubplot instances, dict([‘Kolmogorov’, ‘Kuiper’, ‘Delta’, ‘Sobol’], n_features)

batman.visualization.pairplot(sample, data, plabels=None, flabel=None, fname=None)[source]

Output function of the input parameter space.

A n-variate plot is constructed with all couple of variables - output.

Parameters
  • sample (array_like) – sample (n_samples, n_featrues).

  • data (array_like) – data (n_samples, 1).

  • plabels (list(str)) – parameters’ names.

  • flabel (str) – label for y axis.

  • fname (str) – whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instance, Matplotlib AxesSubplot instances.

batman.visualization.pdf(data, xdata=None, xlabel=None, flabel=None, moments=False, dotplot=False, ticks_nbr=10, range_cbar=None, fname=None)[source]

Plot PDF in 1D or 2D.

Parameters
  • data (nd_array/dict) –

    array of shape (n_samples, n_features) or a dictionary with the following:

  • xdata (array_like) – 1D discretization of the function (n_features,).

  • xlabel (str) – label of the discretization parameter.

  • flabel (str) – name of the quantity of interest.

  • moments (bool) – whether to plot moments along with PDF if dim > 1.

  • dotplot (bool) – whether to plot quantile dotplot or histogram.

  • ticks_nbr (int) – number of color isolines for response surfaces.

  • range_cbar (array_like) – Minimum and maximum values for output function (2 values).

  • fname (str) – whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

batman.visualization.reshow(fig)[source]

Create a dummy figure and use its manager to display fig.

Parameters

fig – Matplotlib figure instance.

batman.visualization.response_surface(bounds, sample=None, data=None, fun=None, doe=None, resampling=0, xdata=None, axis_disc=None, flabel='F', plabels=None, feat_order=None, ticks_nbr=10, range_cbar=None, contours=None, fname=None)[source]

Response surface visualization in 2d (image), 3d (movie) or 4d (movies).

You have to set either (i) sample with data or (ii) fun depending on your data. If (i), the data are interpolated on a mesh in order to be plotted as a surface. Otherwize, fun is directly used to generate correct data.

The DoE can also be plotted by setting doe along with resampling.

Parameters
  • bounds (array_like) – sample boundaries ([min, n_features], [max, n_features]).

  • sample (array_like) – sample (n_samples, n_features).

  • data (array_like) – function evaluations(n_samples, [n_features]).

  • fun (callable) – function to plot the response from.

  • doe (array_like) – design of experiment (n_samples, n_features).

  • resampling (int) – number of resampling points.

  • xdata (array_like) – 1D discretization of the function (n_features,).

  • axis_disc (array_like) – discretisation of the sample on each axis (n_features).

  • flabel (str) – name of the quantity of interest.

  • plabels (list(str)) – parameters’ labels.

  • feat_order (array_like) – order of features for multi-dimensional plot (n_features).

  • ticks_nbr (int) – number of color isolines for response surfaces.

  • range_cbar (array_like) – min and max values for colorbar range (2).

  • contours (array_like) – isocontour values to plot on response surface.

  • fname (str) – whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

batman.visualization.save_show(fname, figures, **kwargs)[source]

Either show or save the figure[s].

If fname is None the figure will show.

Parameters
  • fname (str) – whether to export to filename or display the figures.

  • figure instance) figures (list(Matplotlib) – Figures to handle.

batman.visualization.sensitivity_indices(indices, conf=None, plabels=None, polar=False, xdata=None, xlabel='x', fname=None)[source]

Plot Sensitivity indices.

If len(indices)>2 map indices are also plotted along with aggregated indices.

Parameters
  • indices (array_like) – [first (n_features), total (n_features), first (xdata, n_features), total (xdata, n_features)].

  • conf (float/array_like) – relative error around indices. If float, same error is applied for all parameters. Otherwise shape (n_features, [first, total] orders).

  • plabels (list(str)) – parameters’ names.

  • polar (bool) – Whether to use bar chart or polar bar chart.

  • xdata (array_like) – 1D discretization of the function (n_features,).

  • xlabel (str) – label of the discretization parameter.

  • fname (str) – whether to export to filename or display the figures.

Returns

figure.

Return type

Matplotlib figure instances, Matplotlib AxesSubplot instances.

batman.pod: Proper Orthogonal Decomposition

pod.Pod(corners[, tolerance, dim_max])

POD class.

Pod module

class batman.pod.Pod(corners, tolerance=0.99, dim_max=100)[source]

POD class.

property VS

Compute V*S matrix product.

S is diagonal and stored as vector thus (V*S).T = SV.T

__init__(corners, tolerance=0.99, dim_max=100)[source]

Initialize POD components.

The decomposition of the snapshot matrix is stored as attributes:

  • U: Singular vectors matrix, array_like (n_features, n_snapshots), after filtering array_like(n_features, n_modes),

  • S: Singular values matrix, array_like (n_modes, n_snapshots), only the diagonal is stored, of length (n_modes),

  • V: array_like(n_snapshots, n_snapshots), after filtering (n_snapshots, n_modes).

Parameters
  • corners (array_like) – Hypercube ([min, n_features], [max, n_features]).

  • tolerance (float) – Basis modes filtering criteria.

  • dim_max (int) – Number of basis modes to keep.

directories = {'mean_snapshot': 'Mean.txt', 'modes': 'Mods.npz'}
static downgrade(S, Vt)[source]

Downgrade by removing the kth row of V.

\[\begin{split}S^{-k} &= U\Sigma R^T Q^T\\ S^{-k} &= UU'\Sigma'V'^TQ^T \\ S^{-k} &= U^{-k}\Sigma'V^{(-k)^T}\end{split}\]
Parameters
  • S – Singular vector, array_like (n_modes,).

  • Vt – V.T without one row, array_like (n_snapshots - 1, n_modes).

Returns

U’, S’, V(-k).T

Return type

array_like.

estimate_quality()[source]

Quality estimator.

Estimate the quality of the POD by the leave-one-out method.

Returns

Q2.

Return type

float.

static filtering(U, S, V, tolerance, dim_max)[source]

Remove lowest modes in U, S and V.

Parameters
  • U (array_like) – (nb of data, nb of snapshots).

  • S (array_like) – (nb of modes).

  • V (array_like) – (nb of snapshots, nb of snapshots).

  • tolerance (float) – basis modes filtering criteria.

  • dim_max (int) – number of basis modes to keep.

Returns

U (nb of data, nb of modes).

Return type

array_like.

Returns

S (nb of modes).

Return type

array_like.

Returns

V (nb of snapshots, nb of modes).

Return type

array_like.

fit(samples)[source]

Create a POD from a set of samples.

Parameters

samples (batman.space.Sample.) – Samples.

inverse_transform(samples)[source]

Convert VS back into the original space.

Parameters

samples – Samples VS to convert (n_samples, n_components).

Returns

Samples in the original space.

Return type

array_like (n_samples, n_features)

logger = <Logger batman.pod.pod (WARNING)>
pod_file_name = 'pod.npz'
points_file_name = 'points.dat'
read(path)[source]

Read a POD from disk.

Parameters

path (str) – path to a directory.

update(samples)[source]

Update POD with a new snapshot.

Parameters

samples – new samples to update the POD with.

write(path)[source]

Save a POD to disk.

Parameters

path (str) – path to a directory.

batman.functions: Functions

functions.data

Data module

functions.analytical.SixHumpCamel()

SixHumpCamel class [Molga2005].

functions.analytical.Branin()

Branin class [Forrester2008].

functions.analytical.Michalewicz([d, m])

Michalewicz class [Molga2005].

functions.analytical.Ishigami([a, b])

Ishigami class [Ishigami1990].

functions.analytical.Rastrigin([d])

Rastrigin class [Molga2005].

functions.analytical.G_Function([d, a])

G_Function class [Saltelli2000].

functions.analytical.Forrester([fidelity])

Forrester class [Forrester2007].

functions.analytical.ChemicalSpill([s, tstep])

Environmental Model class [Bliznyuk2008].

functions.analytical.Channel_Flow([dx, …])

Channel Flow class.

functions.analytical.Manning([width, slope, …])

Manning equation for rectangular channel class.

functions.utils.multi_eval(fun)

Detect space or unique point.

functions.utils.output_to_sequence(fun)

Convert float output to list.

Data module

batman.functions.data.el_nino()[source]

El Nino dataset.

batman.functions.data.marthe()[source]

MARTHE dataset.

batman.functions.data.mascaret(multizone=False, fname=None)[source]

Mascaret dataset.

Parameters
  • multizone (bool) – Use only one global Ks or 3 Ks.

  • fname (list(str)) – Path to the file that contains input and output data. File format must be npy.

batman.functions.data.tahiti()[source]

Tahiti dataset.

Analytical module

Defines analytical Uncertainty Quantification oriented functions for test and model evaluation purpose.

It implements the following classes:

In most case, Sobol’ indices are pre-computed and storred as attributes.

References

Molga2005(1,2,3,4,5,6)

Molga, M., & Smutnicki, C. Test functions for optimization needs (2005).

Dixon1978

Dixon, L. C. W., & Szego, G. P. (1978). The global optimization problem: an introduction. Towards global optimization, 2, 1-15.

Ishigami1990(1,2)

Ishigami, T., & Homma, T. (1990, December): An importance quantification technique in uncertainty analysis for computer models. In Uncertainty Modeling and Analysis, 1990. Proceedings., First International Symposium on (pp. 398-403). IEEE.

Saltelli2000(1,2)

Saltelli, A., Chan, K., & Scott, E. M. (Eds.). (2000). Sensitivity analysis (Vol. 134). New York: Wiley.

Forrester2007(1,2)

Forrester, Sobester. (2007). Multi-Fidelity Optimization via Surrogate Modelling. In Proceedings of the Royal Society A: Mathematical, Physical and Engineering Sciences.

Forrester2008(1,2)

Forrester, A., Sobester, A., & Keane, A. (2008). Engineering design via surrogate modelling: a practical guide. Wiley.

Bliznyuk2008(1,2)

Bliznyuk, N., Ruppert, D., Shoemaker, C., Regis, R., Wild, S., & Mugunthan, P. (2008). Bayesian calibration and uncertainty analysis for computationally expensive models using optimization and radial basis function approximation. Journal of Computational and Graphical Statistics, 17(2).

Surjanovic2017

Surjanovic, S. & Bingham, D. (2013). Virtual Library of Simulation Experiments: Test Functions and Datasets. Retrieved September 11, 2017, from http://www.sfu.ca/~ssurjano.

class batman.functions.analytical.Branin[source]

Branin class [Forrester2008].

\[f(x) = \left( x_2 - \frac{5.1}{4\pi^2}x_1^2 + \frac{5}{\pi}x_1 - 6 \right)^2 + 10 \left[ \left( 1 - \frac{1}{8\pi} \right) \cos(x_1) + 1 \right] + 5x_1.\]

The function has two local minima and one global minimum. It is a modified version of the original Branin function that seek to be representative of engineering functions.

\[f(x^*) = -15,310076, x^* = (-\pi, 12.275), x_1 \in [-5, 10], x_2 \in [0, 15]\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__()[source]

Set up attributes.

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Channel_Flow(dx=8000.0, length=40000.0, width=500.0, slope=0.0005, hinit=10.0)[source]

Channel Flow class.

\[\begin{split}\frac{dh}{ds}=\mathcal{F}(h)=I\frac{1-(h/h_n)^{-10/3}}{1-(h/h_c)^{-3}}\\ h_c=\left(\frac{q^2}{g}\right)^{1/3}, h_n=\left(\frac{q^2}{IK_s^2}\right)^{3/10}\end{split}\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(dx=8000.0, length=40000.0, width=500.0, slope=0.0005, hinit=10.0)[source]

Initialize the geometrical configuration.

Parameters
  • dx (float) – discretization.

  • length (float) – Canal length.

  • width (float) – Canal width.

  • slope (float) – Canal slope.

  • hinit (float) – Downstream boundary condition.

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.ChemicalSpill(s=None, tstep=0.3)[source]

Environmental Model class [Bliznyuk2008].

Model a pollutant spill caused by a chemical accident. C(x) being the concentration of the pollutant at the space-time vector (s, t), with 0 < s < 3 and t > 0.

A mass M of pollutant is spilled at each of two locations, denoted by the space-time vectors (0, 0) and \((L, \tau)\). Each element of the response is a scaled concentration of the pollutant at the space-time vector.

\[\begin{split}f(X) = \sqrt{4\pi}C(X), x \in [[7, 13], [0.02, 0.12], [0.01, 3], [30.1, 30.295]]\\ C(X) = \frac{M}{\sqrt{4\pi D_{t}}}\exp \left(\frac{-s^2}{4D_t}\right) + \frac{M}{\sqrt{4\pi D_{t}(t - \tau)}} \exp \left(-\frac{(s-L)^2}{4D(t - \tau)}\right) I (\tau < t)\end{split}\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(s=None, tstep=0.3)[source]

Definition of the time-space domain.

Parameters
  • s (list) – locations

  • tstep (float) – time-step

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Forrester(fidelity='e')[source]

Forrester class [Forrester2007].

\[\begin{split}F_{e}(x) = (6x-2)^2\sin(12x-4), \\ F_{c}(x) = AF_e(x)+B(x-0.5)+C,\end{split}\]

were \(x\in{0,1}\) and \(A=0.5, B=10, C=-5\).

This set of two functions are used to represents a high an a low fidelity.

__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(fidelity='e')[source]

Forrester-function definition.

e stands for expansive and c for cheap.

Parameters

fidelity (str) – select the fidelity ['e'|'f']

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.G_Function(d=4, a=None)[source]

G_Function class [Saltelli2000].

\[F = \Pi_{i=1}^d \frac{\lvert 4x_i - 2\rvert + a_i}{1 + a_i}\]

Depending on the coefficient \(a_i\), their is an impact on the impact on the output. The more the coefficient is for a parameter, the less the parameter is important.

__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(d=4, a=None)[source]

G-function definition.

Parameters
  • d (int) – input dimension

  • a (np.array) – (1, d)

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Ishigami(a=7.0, b=0.1)[source]

Ishigami class [Ishigami1990].

\[F = \sin(x_1)+7\sin(x_2)^2+0.1x_3^4\sin(x_1), x\in [-\pi, \pi]^3\]

It exhibits strong nonlinearity and nonmonotonicity. Depending on a and b, emphasize the non-linearities. It also has a dependence on X3 due to second order interactions (F13).

__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(a=7.0, b=0.1)[source]

Set up Ishigami.

Parameters

a, b (float) – Ishigami parameters

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Manning(width=100.0, slope=0.0005, inflow=1000, d=1)[source]

Manning equation for rectangular channel class.

__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(width=100.0, slope=0.0005, inflow=1000, d=1)[source]

Initialize the geometrical configuration.

Parameters
  • width (float) – canal width

  • slope (float) – canal slope

  • inflow (float) – canal inflow (optional)

  • dim (int) – 1 (Ks) or 2 (Ks,Q)

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Michalewicz(d=2, m=10)[source]

Michalewicz class [Molga2005].

It is a multimodal d-dimensional function which has \(d!\) local minima

\[f(x)=-\sum_{i=1}^d \sin(x_i)\sin^{2m}\left(\frac{ix_i^2}{\pi}\right),\]

where m defines the steepness of the valleys and ridges.

It is to difficult to search a global minimum when \(m\) reaches large value. Therefore, it is recommended to have \(m < 10\).

\[f(x^*) = -1.8013, x^* = (2.20, 1.57), x \in [0, \pi]^d\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(d=2, m=10)[source]

Set up dimension.

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Rastrigin(d=2)[source]

Rastrigin class [Molga2005].

It is a multimodal d-dimensional function which has regularly distributed local minima.

\[f(x)=10d+\sum_{i=1}^d [x_i^2-10\cos(2\pi x_i)]\]
\[f(x^*) = 0, x^* = (0, ..., 0), x \in [-5.12, 5.12]^d\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(d=2)[source]

Set up dimension.

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.Rosenbrock(d=2)[source]

Rosenbrock class [Dixon1978].

\[f(x)=\sum_{i=1}^{d-1}[100(x_{i+1}-x_i^2)^2+(x_i-1)^2]\]

The function is unimodal, and the global minimum lies in a narrow, parabolic valley.

\[f(x^*) = 0, x^* = (1, ..., 1), x \in [-2.048, 2.048]^d\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__(d=2)[source]

Set up dimension.

logger = <Logger batman.functions.analytical (WARNING)>
class batman.functions.analytical.SixHumpCamel[source]

SixHumpCamel class [Molga2005].

\[\left(4-2.1x_1^2+\frac{x_1^4}{3}\right)x_1^2+x_1x_2+ (-4+4x_2^2)x_2^2\]

The function has six local minima, two of which are global.

\[f(x^*) = -1.0316, x^* = (0.0898, -0.7126), (-0.0898,0.7126), x_1 \in [-3, 3], x_2 \in [-2, 2]\]
__call__(x_n, *args, **kwargs)

Get evaluation from space or point.

If the function is a Kriging instance, get and returns the variance.

Returns

function evaluation(s) [sigma(s)]

Return type

np.array([n_eval], n_feature)

__init__()[source]

Set up attributes.

logger = <Logger batman.functions.analytical (WARNING)>

batman.tasks: Tasks

Data Provider module

class batman.tasks.ProviderFile(plabels, flabels, file_pairs, psizes=None, fsizes=None, discover_pattern=None, save_dir=None, space_fname='sample-space.npy', space_format='npy', data_fname='sample-data.npy', data_format='npy')[source]

Provides Snapshots loaded from a list of files.

__init__(plabels, flabels, file_pairs, psizes=None, fsizes=None, discover_pattern=None, save_dir=None, space_fname='sample-space.npy', space_format='npy', data_fname='sample-data.npy', data_format='npy')[source]

Initialize the provider.

Load known samples from a list of files. If discover_pattern is specified, it will also try to locate and import samples from there.

Parameters
  • plabels (list(str)) – input parameter names (for space).

  • flabels (list(str)) – output feature names (for data).

  • file_pairs (list(tuple(str))) – list of paires (space_file, data_file).

  • psizes (list(int)) – number of components of parameters.

  • fsizes (list(int)) – number of components of output features.

  • discover_pattern (str) – UNIX-style patterns for directories with pairs of sample files to import.

  • save_dir (str) – path to a directory for saving known snapshots.

  • space_fname (str) – name of space file to write.

  • data_fname (str) – name of data file to write.

  • space_format (str) – space file format.

  • data_format (str) – data file format.

build_data(points)[source]

Compute data for requested points.

This provider cannot compute any data and will raise if called.

Returns

NotImplemented

property flabels

Names of data features.

property fsizes

Shape of data features.

property known_points

List of points whose associated data is already known.

logger = <Logger batman.tasks.provider_file (WARNING)>
property plabels

Names of space parameters.

property psizes

Shape of space parameters.

require_data(points)[source]

Return samples for requested points.

This provider is not able to generate missing data. Will raise if a point is not known.

Returns

samples for requested points (carry both space and data)

Return type

Sample

class batman.tasks.ProviderFunction(plabels, flabels, module, function, psizes=None, fsizes=None, discover_pattern=None, save_dir=None, space_fname='sample-space.json', space_format='json', data_fname='sample-data.json', data_format='json')[source]

Provides Snapshots built through an external python function.

__init__(plabels, flabels, module, function, psizes=None, fsizes=None, discover_pattern=None, save_dir=None, space_fname='sample-space.json', space_format='json', data_fname='sample-data.json', data_format='json')[source]

Initialize the provider.

Load a python function to be called for computing new snpahots.

Parameters
  • plabels (list(str)) – input parameter names.

  • flabels (list(str)) – output feature names.

  • module (str) – python module to load.

  • function (str) – function in module to execute for generating data.

  • psizes (list(int)) – number of components of parameters.

  • fsizes (list(int)) – number of components of output features.

  • discover_pattern (str) – UNIX-style patterns for directories with pairs of sample files to import.

  • save_dir (str) – path to a directory for saving known snapshots.

  • space_fname (str) – name of space file to write.

  • data_fname (str) – name of data file to write.

  • space_format (str) – space file format.

  • data_format (str) – data file format.

build_data(points)[source]

Compute data for requested points.

Parameters

points (array_like) – points to build data from, (n_points, n_features).

Returns

samples for requested points (carry both space and data).

Return type

Sample

property flabels

Names of data features.

property fsizes

Shape of data features.

property known_points

List of points whose associated data is already known.

logger = <Logger batman.tasks.provider_function (WARNING)>
property plabels

Names of space parameters.

property psizes

Shape of space parameters.

require_data(points)[source]

Return samples for requested points.

Data for unknown points is generated through a python function.

Parameters

points (array_like) – points to build data from, (n_points, n_features).

Returns

samples for requested points (carry both space and data)

Return type

Sample

class batman.tasks.ProviderJob(plabels, flabels, command, context_directory, psizes=None, fsizes=None, coupling=None, hosts=None, pool=None, clean=False, discover_pattern=None, save_dir=None, space_fname='sample-space.json', space_format='json', data_fname='sample-data.json', data_format='json')[source]

Provides Snapshots built through a 3rd-party program.

__init__(plabels, flabels, command, context_directory, psizes=None, fsizes=None, coupling=None, hosts=None, pool=None, clean=False, discover_pattern=None, save_dir=None, space_fname='sample-space.json', space_format='json', data_fname='sample-data.json', data_format='json')[source]

Initialize the provider.

Parameters
  • plabels (list(str)) – input parameter names.

  • flabels (list(str)) – output feature names.

  • command (str) – command to be executed for computing new snapshots.

  • context_directory (str) – store every ressource required for executing a job.

  • psizes (list(int)) – number of components of parameters.

  • fsizes (list(int)) – number of components of output features.

  • coupling (dict) –

    Definition of the snapshots IO files:

    • coupling_directory (str) – sub-directory in context_directory that will contain input parameters and output file.

    • input_fname (str) – basename for files storing the point coordinates plabels.

    • input_format (str) – json (default), csv, npy, npz.

    • output_fname (str) – basename for files storing values associated to flabels.

    • output_format (str) – json (default), csv, npy, npz.

  • hosts (list(dict)) –

    Definition of the remote HOSTS if any:

    • hostname (str) – Remote host to connect to.

    • remote_root (str) – Remote folder to create and store data.

    • username (str) – username.

    • password (str) – password.

  • pool (concurrent.futures.xxx.xxx.Executor.) – pool executor.

  • clean (bool) – whether to remove working directories.

  • discover_pattern (str) – UNIX-style patterns for directories with pairs of sample files to import.

  • save_dir (str) – path to a directory for saving known snapshots.

  • space_fname (str) – name of space file to write.

  • data_fname (str) – name of data file to write.

  • space_format (str) – space file format.

  • data_format (str) – data file format.

build_data(points, sample_id=None)[source]

Compute data for requested points.

Ressources for executing a job are copied from the context directory to a work directory. The shell command is executed from this directory. The command shall find its inputs and place its outputs in the coupling sub-directory, inside the work directory.

Parameters
  • points (array_like) – points to compute (n_points, n_features).

  • sample_id (list) – points indices in the points list.

Returns

samples for requested points (carry both space and data) and failed if any.

Return type

Sample, list([point, err])

property flabels

Names of data features.

property fsizes

Shape of data features.

property known_points

List of points whose associated data is already known.

logger = <Logger batman.tasks.provider_job (WARNING)>
property plabels

Names of space parameters.

property psizes

Shape of space parameters.

require_data(points)[source]

Return samples for requested points.

Data for unknown points if generated through an external job.

Parameters

points (array_like) – points to compute (n_points, n_features).

Returns

samples for requested points (carry both space and data)

Return type

Sample

batman.misc: Misc

misc.NestedPool([processes, initializer, …])

NestedPool class.

misc.ProgressBar(total)

Print progress bar in console.

misc.optimization(bounds[, discrete])

Perform a discret or a continuous/discrete optimization.

misc.import_config(path_config, path_schema)

Import a configuration file.

misc.check_yes_no(prompt, default)

Ask user for delete confirmation.

misc.ask_path(prompt, default, root)

Ask user for a folder path.

misc.abs_path(value)

Get absolute path.

misc.clean_path(path)

Return an absolute and normalized path.

Misc module

class batman.misc.NestedPool(processes=None, initializer=None, initargs=(), maxtasksperchild=None, context=None)[source]

NestedPool class.

Inherit from pathos.multiprocessing.Pool. Enable nested process pool.

Process(*args, **kwds)[source]
class batman.misc.ProgressBar(total)[source]

Print progress bar in console.

__call__()[source]

Update bar.

__init__(total)[source]

Create a bar.

Parameters

total (int) – number of iterations

compute_eta()[source]

Compute ETA.

Compare current time with init_time.

Returns

eta, vel

Return type

str

show_progress(eta=None, vel=None)[source]

Print bar and ETA if relevant.

Parameters
  • eta (str) – ETA in H:M:S

  • vel (str) – iteration/second

batman.misc.abs_path(value)[source]

Get absolute path.

batman.misc.ask_path(prompt, default, root)[source]

Ask user for a folder path.

Parameters
  • prompt (str) – Ask.

  • default (str) – default value.

  • root (str) – root path.

Returns

path if folder exists.

Return type

str.

batman.misc.check_yes_no(prompt, default)[source]

Ask user for delete confirmation.

Parameters
  • prompt (str) – yes-no question

  • default (str) – default value

Returns

true if yes

Return type

boolean

batman.misc.clean_path(path)[source]

Return an absolute and normalized path.

batman.misc.cpu_system()[source]

Return rhe number of physical CPU of system.

batman.misc.import_config(path_config, path_schema)[source]

Import a configuration file.

batman.misc.optimization(bounds, discrete=None)[source]

Perform a discret or a continuous/discrete optimization.

If a variable is discrete, the decorator allows to find the optimum by doing an optimization per discrete value and then returns the optimum.

Parameters
  • bounds (array_like) – bounds for optimization ([min, max], n_features).

  • discrete (int) – index of the discrete variable.

batman.input_output: Input Output

IO module

Provides Formater objects to deal with I/Os.

Every formaters have the same interface, exposing the two methods read and write.

Example

Using json formater

>> from input_output import formater
>> varnames = ['x1', 'x2', 'x3']
>> data = [[1, 2, 3], [87, 74, 42]]
>> fmt = formater('json')
>> fmt.write('file.json', data, varnames)
{'x1': [1, 87], 'x2': [2, 74], 'x3': [3, 42]}
>> # can load a subset of variables, in a different order (unavailable for format 'npy')
>> fmt.read('file.json', ['x2', 'x1'])
array([[2, 1], [74, 87]])
batman.input_output.available_formats()[source]

Return the list of available format names.

batman.input_output.formater(format_name)[source]

Return a Formater.