pygpc package

Subpackages

• pygpc.testfunctions package
  • Submodules
  • pygpc.testfunctions.testfunctions module
    • Ackley
      • Ackley.simulate()
      • Ackley.validate()
    • BfieldOutsideSphere
      • BfieldOutsideSphere.simulate()
      • BfieldOutsideSphere.validate()
    • BinaryDiscontinuousSphere
      • BinaryDiscontinuousSphere.simulate()
      • BinaryDiscontinuousSphere.validate()
    • BohachevskyFunction1
      • BohachevskyFunction1.simulate()
      • BohachevskyFunction1.validate()
    • BoothFunction
      • BoothFunction.simulate()
      • BoothFunction.validate()
    • BukinFunctionNumber6
      • BukinFunctionNumber6.simulate()
      • BukinFunctionNumber6.validate()
    • Cluster3Simple
      • Cluster3Simple.simulate()
      • Cluster3Simple.validate()
    • ContinuousDiscontinuousSphere
      • ContinuousDiscontinuousSphere.simulate()
      • ContinuousDiscontinuousSphere.validate()
    • CrossinTrayFunction
      • CrossinTrayFunction.simulate()
      • CrossinTrayFunction.validate()
    • DeJongFunctionFive
      • DeJongFunctionFive.simulate()
      • DeJongFunctionFive.validate()
    • DiscontinuousRidgeManufactureDecay
      • DiscontinuousRidgeManufactureDecay.simulate()
      • DiscontinuousRidgeManufactureDecay.validate()
    • DiscontinuousRidgeManufactureDecayGenzDiscontinuous
      • DiscontinuousRidgeManufactureDecayGenzDiscontinuous.simulate()
      • DiscontinuousRidgeManufactureDecayGenzDiscontinuous.validate()
    • DiscontinuousRidgeManufactureDecay_NaN
      • DiscontinuousRidgeManufactureDecay_NaN.simulate()
      • DiscontinuousRidgeManufactureDecay_NaN.validate()
    • DixonPriceFunction
      • DixonPriceFunction.simulate()
      • DixonPriceFunction.validate()
    • DropWaveFunction
      • DropWaveFunction.simulate()
      • DropWaveFunction.validate()
    • Dummy
      • Dummy.simulate()
      • Dummy.validate()
    • ElectrodeModel
      • ElectrodeModel.simulate()
      • ElectrodeModel.validate()
    • Franke
      • Franke.simulate()
      • Franke.validate()
    • GFunction
      • GFunction.simulate()
      • GFunction.validate()
    • GenzContinuous
      • GenzContinuous.simulate()
      • GenzContinuous.validate()
    • GenzCornerPeak
      • GenzCornerPeak.simulate()
      • GenzCornerPeak.validate()
    • GenzDiscontinuous
      • GenzDiscontinuous.simulate()
      • GenzDiscontinuous.validate()
    • GenzGaussianPeak
      • GenzGaussianPeak.simulate()
      • GenzGaussianPeak.validate()
    • GenzOscillatory
      • GenzOscillatory.simulate()
      • GenzOscillatory.validate()
    • GenzOscillatory_NaN
      • GenzOscillatory_NaN.simulate()
      • GenzOscillatory_NaN.validate()
    • GenzProductPeak
      • GenzProductPeak.simulate()
      • GenzProductPeak.validate()
    • GramacyLeeFunction
      • GramacyLeeFunction.simulate()
      • GramacyLeeFunction.validate()
    • HyperbolicTangent
      • HyperbolicTangent.simulate()
      • HyperbolicTangent.validate()
    • Ishigami
      • Ishigami.simulate()
      • Ishigami.validate()
    • Ishigami_NaN
      • Ishigami_NaN.simulate()
      • Ishigami_NaN.validate()
    • Lim2002
      • Lim2002.simulate()
      • Lim2002.validate()
    • Lin2Coupled
      • Lin2Coupled.simulate()
      • Lin2Coupled.validate()
    • Lorenz_System
      • Lorenz_System.simulate()
      • Lorenz_System.validate()
    • Lorenz_System_julia
      • Lorenz_System_julia.simulate()
      • Lorenz_System_julia.validate()
    • ManufactureDecay
      • ManufactureDecay.simulate()
      • ManufactureDecay.validate()
    • MatyasFunction
      • MatyasFunction.simulate()
      • MatyasFunction.validate()
    • McCormickFunction
      • McCormickFunction.simulate()
      • McCormickFunction.validate()
    • MichalewiczFunction
      • MichalewiczFunction.simulate()
      • MichalewiczFunction.validate()
    • MovingParticleFrictionForce
      • MovingParticleFrictionForce.simulate()
      • MovingParticleFrictionForce.validate()
    • OakleyOhagan2004
      • OakleyOhagan2004.simulate()
      • OakleyOhagan2004.validate()
    • Peaks
      • Peaks.simulate()
      • Peaks.validate()
    • Peaks_NaN
      • Peaks_NaN.simulate()
      • Peaks_NaN.validate()
    • PermFunction
      • PermFunction.simulate()
      • PermFunction.validate()
    • PotentialDipole3Layers
      • PotentialDipole3Layers.simulate()
      • PotentialDipole3Layers.validate()
    • PotentialHomogeneousDipole
      • PotentialHomogeneousDipole.simulate()
      • PotentialHomogeneousDipole.validate()
    • Ridge
      • Ridge.simulate()
      • Ridge.validate()
    • RosenbrockFunction
      • RosenbrockFunction.simulate()
      • RosenbrockFunction.validate()
    • RotatedHyperEllipsoid
      • RotatedHyperEllipsoid.simulate()
      • RotatedHyperEllipsoid.validate()
    • SchafferFunction4
      • SchafferFunction4.simulate()
      • SchafferFunction4.validate()
    • SixHumpCamelFunction
      • SixHumpCamelFunction.simulate()
      • SixHumpCamelFunction.validate()
    • SphereFunction
      • SphereFunction.simulate()
      • SphereFunction.validate()
    • SphereModel
      • SphereModel.simulate()
      • SphereModel.validate()
    • SumOfDifferentPowersFunction
      • SumOfDifferentPowersFunction.simulate()
      • SumOfDifferentPowersFunction.validate()
    • SurfaceCoverageSpecies
      • SurfaceCoverageSpecies.simulate()
      • SurfaceCoverageSpecies.validate()
    • SurfaceCoverageSpecies_NaN
      • SurfaceCoverageSpecies_NaN.simulate()
      • SurfaceCoverageSpecies_NaN.validate()
    • TMSEfieldSphere
      • TMSEfieldSphere.simulate()
      • TMSEfieldSphere.validate()
    • Welch1992
      • Welch1992.simulate()
      • Welch1992.validate()
    • WingWeight
      • WingWeight.simulate()
      • WingWeight.validate()
    • ZakharovFunction
      • ZakharovFunction.simulate()
      • ZakharovFunction.validate()
    • plot_testfunction()
  • Module contents

Submodules

pygpc.AbstractModel module

class pygpc.AbstractModel.AbstractModel(matlab_model=False)

Bases: object

Abstract base class for the SimulationWrapper. This base class provides basic functions for serialization/deserialization and printing progress. It cannot be used directly, but a derived class implementing the “simulate” method must be created.

get_seq_number()

increment_ctr()

This functions increments the global counter by 1.

print_progress(func_time=None, read_from_file=False)

This function prints the progress according to the current context and global_counter.

read_previous_results(coords)

This functions reads previous results from the hard disk (if present). When reading from the array containing the results, the current grid-index (i_grid) is considered to maintain the order of the results when the SimulationModels are executed in parallel. If the function evaluated the results in parallel internally, i_grid is a range [i_grid_min, i_grid_max].

Parameters:

coords (ndarray of float [n_sims x dim]) – Grid coordinates the simulations are conducted with

Returns:

• None – if no serialized results could be found or does not fit to grid

• list – data at coords

set_parameters(p, context=None)

Set model parameters and context of simulations.

Parameters:

• p (dictionary) – Dictionary containing the model parameters

• context (dictionary) –

  dictionary that contains information about this worker’s context - lock : reference to the Lock object that all processes share for synchronization - max_grid : size of the current sub-grid that is processed - global_task_counter : reference to the Value object that is shared among all processes to keep track

  of the overall progress

  • seq_numbersequence number of the task this object represents; necessary to maintain the correct

    sequence of results

  • fn_results : location of the hdf5 file to serialize the results to

  • i_grid : current iteration in the sub-grid that is processed

  • i_iter : current main-iteration

  • i_subiter : current sub-iteration

  • coords : parameters of particular simulation in original parameter space

  • coords_norm : parameters of particular simulation in normalized parameter space

  • verbose : print progress

abstract simulate(process_id=None, matlab_engine=None)

This abstract method must be implemented by the subclass. It should perform the simulation task depending on the input_values provided to the object on instantiation.

Parameters:

• process_id (int) – A unique identifier; no two processes of the pool will run concurrently with the same identifier

• matlab_engine (Matlab engine object) – Matlab engine to run Matlab models

abstract validate()

This abstract method must be implemented by the subclass. It should perform the validation task depending on the parameters defined in the problem. In cases, the model may not run correctly for some parameter combinations, this function changes the definition of the random parameters and the constants.

write_results(data_dict)

This function writes the data to a file on hard disk. When writing the data the current grid-index (i_grid) is considered. The data are written to the row corresponding i_grid in order to maintain the order of the results when the SimulationModels are executed in parallel.

Parameters:

data_dict (dict of ndarray) – Dictionary, containing the data to write in an .hdf5 file. The keys are the dataset names.

pygpc.Algorithm module

class pygpc.Algorithm.Algorithm(problem, options, grid=None, validation=None)

Bases: object

Class for GPC algorithms

Parameters:

• problem (Problem object) – Object instance of gPC problem to investigate

• options (dict) – Algorithm specific options (see sub-classes for more details)

• grid (Grid object) – Grid object

• validation (ValidationSet object) – ValidationSet object

check_basic_options()

Checks self.options dictionary and sets default

options[“eps”]float, optional, default=1e-3

Relative mean error of leave-one-out cross validation

options[“error_norm”]str, optional, default=”relative”

Choose if error is determined “relative” or “absolute”. Use “absolute” error when the model generates outputs equal to zero.

options[“error_type”]str, optional, default=”loocv”

Choose type of error to validate gpc approximation. Use “loocv” (Leave-one-Out cross validation) to omit any additional calculations and “nrmsd” (normalized root mean square deviation) to compare against a Problem.ValidationSet.

options[“fn_results”]string, optional, default=None

If provided, model evaluations are saved in fn_results.hdf5 file and gpc object in fn_results.pkl file

options[“gradient_enhanced”]boolean, optional, default: False

Use gradient information to determine the gPC coefficients.

options[“gradient_calculation”]str, optional, default=”standard_forward”

Type of the calculation scheme to determine the gradient in the grid points - “FD_fwd”: Finite difference forward approximation of the gradient using n_grid x dim additional sampling points stored in self.grid.coords_gradient and self.grid.coords_gradient_norm [n_grid x dim x dim]. - “FD_1st”: Finite difference approximation of 1st order accuracy using only the available samples [1] - “FD_2nd”: Finite difference approximation of 2nd order accuracy using only the available samples [1] - “FD_1st2nd”: Finite difference approximation of 1st and (where possible) 2nd order accuracy

options[“gradient_calculation_options”]dict, optional, default: {“dx”: 0.01, “distance_weight”: -2}

Options for gradient calculation (details in get_gradient() function in Gradient.py)

options[“backend”]str, optional, default: “python”

Default computing backend, certain functions can be computed with Multicore-CPU or GPU acceleration

options[“lambda_eps_gradient”]float, optional, default: 0.95

Bound of principal components in %. All eigenvectors are included until lambda_eps of total sum of all eigenvalues is included in the system.

options[“matrix_ratio”]: float, optional, default=1.5

Ration between the number of model evaluations and the number of basis functions. If “adaptive_sampling” is activated this factor is only used to construct the initial grid depending on the initial number of basis functions determined by “order_start”. (>1 results in an overdetermined system)

options[“matlab_model”]boolean, optional, default: False

Use a Matlab model function

options[“method”]: str

GPC method to apply [‘Reg’, ‘Quad’]

options[“n_cpu”]int, optional, default=1

Number of threads to use for parallel evaluation of the model function.

options[“n_samples_validation”]int, optional, default: 1e4

Number of validation points used to determine the NRMSD if chosen as “error_type”. Does not create a validation set if there is already one present in the Problem instance (problem.validation).

options[“print_func_time”]boolean, optional, default: False

Print function evaluation time for every single run

options[“projection”]boolean, optional, default: False

Use projection approach

options[“solver”]: str

Solver to determine the gPC coefficients - ‘Moore-Penrose’ … Pseudoinverse of gPC matrix (SGPC.Reg, EGPC) - ‘OMP’ … Orthogonal Matching Pursuit, sparse recovery approach (SGPC.Reg, EGPC)

options[“settings”]: dict

Solver settings - ‘Moore-Penrose’ … None - ‘OMP’ … {“n_coeffs_sparse”: int} Number of gPC coefficients != 0

options[“verbose”]boolean, optional, default=True

Print output of iterations and sub-iterations (True/False)

options[“backend”]str

Backend for performance intensive computations - “python” … Use native python implementation - “cpu” .. Use C Implementaion without multicore-support

options[“plot_basis”]bool

Plot basis functions and save as fn_results + _basis_iter#.png

options[“grid_extension_method”]str, optional, default: GPR

Method to extend random grids when adaptive_sampling is turned on: - “GPR”: Gaussian Process Regression (sample location is optimized according to posterior variance) - “random”: Samples are added randomly

check_results(results, grid, gradient_results=None, gradient_results_idx=None, com=None, resample=True)

Check the validity of the results and resample if required. Updates the gPC object, the containing grid, and the results array.

Parameters:

• results (np.ndarray of float [n_samples x n_qoi]) – Model output at sampling points.

• grid (Grid object instance) – Grid object instance the results are computed for.

• gradient_results (ndarray of float [n_grid x n_out x dim], optional, default: None) – Gradient of model function in grid points.

• gradient_results_idx (ndarray of int [n_grid], optional, default: None) – Indices of grid points where the gradient was evaluated.

• com (Computation class instance, optional, default: None) – Computation class instance to run the model if resample is True.

• resample (bool, optional, default: True) – Resample grid points and rerun model (requires Computational class instance to run model). If False, the grid points and results are just deleted.

Returns:

• results (np.ndarray of float [n_samples x n_qoi]) – Updated (fixed) model output at sampling points.

• gpc (SGPC or MEGPC object instance or list of SGPC or MEGPC object instances) – GPC object(s) containing the basis functions and the updated grid.

• gradient_results (ndarray of float [n_grid x n_out x dim]) – Updated (fixed) gradients of model function in grid points not containing the points where the gradients were NaN.

• gradient_results_idx (ndarray of int [n_grid], optional, default: None) – Updated (fixed) indices of grid points where the gradient was evaluated not containing the points where the gradients were NaN.

• grid (Grid object instance) – Updated (fixed) grid object instance the results are computed for not containing the grid points where the results were NaN.

class pygpc.Algorithm.MERegAdaptiveProjection(problem, options, validation=None, grid=None)

Bases: Algorithm

Adaptive regression approach based on leave one out cross validation error estimation

Parameters:

• problem (Problem class instance) – GPC problem under investigation

• options["order_start"] (int, optional, default=0) – Initial gPC expansion order (maximum order)

• options["order_end"] (int, optional, default=10) – Maximum Gpc expansion order to expand to (algorithm will terminate afterwards)

• options["interaction_order"] (int, optional, default=dim) – Define maximum interaction order of parameters (default: all interactions)

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["adaptive_sampling"] (boolean, optional, default: True) – Adds samples adaptively to the expansion until the error is converged and continues by adding new basis functions.

• options["n_samples_discontinuity"] (int, optional, default: 10) – Number of grid points close to discontinuity to refine its location

• options["n_grid_init"] (int, optional, default: 10) – Number of initial simulations to explore the parameter space

Examples

>>> import pygpc
>>> # initialize adaptive gPC algorithm
>>> algorithm = pygpc.MERegAdaptiveProjection(problem=problem, options=options)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run()

run()

Runs Multi-Element adaptive gPC algorithm to solve problem (optional projection).

Returns:

• megpc (Multi-element GPC object instance) – MEGPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.MEStatic(problem, options, grid=None, validation=None)

Bases: Algorithm

Multi-Element Static gPC algorithm

Parameters:

• problem (Problem object) – Object instance of gPC problem to investigate

• options["method"] (str) – GPC method to apply [‘Reg’, ‘Quad’]

• options["order"] (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• options["order_max"] (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["interaction_order"] (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• options["qoi"] (int or str, optional, default: 0) – Choose for which QOI the projection is determined for. The other QOIs use the same projection. Alternatively, the projection can be determined for every QOI independently (qoi_index or “all”).

• options["classifier"] (str, optional, default: "learning") – Classification algorithm to subdivide parameter domain. - “learning” … ClassifierLearning algorithm based on Unsupervised and supervised learning

• options["classifier_options"] (dict, optional, default: default settings) – Options of classifier

• grid (Grid object instance) – Grid object to use for static gPC (Random, SparseGrid, TensorGrid)

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> # initialize static gPC algorithm
>>> algorithm = pygpc.MEStatic(problem=problem, options=options, grid=grid)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run()

run()

Runs Multi-Element Static gPC algorithm to solve problem.

Returns:

• megpc (Multi-element GPC object instance) – MEGPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.MEStaticProjection(problem, options, validation=None, grid=None)

Bases: Algorithm

Static gPC algorithm using Basis Projection approach

Parameters:

• problem (Problem object) – Object instance of gPC problem to investigate

• options["order"] (int) – Expansion order, each projected variable eta is expanded to. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• options["order_max"] (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• options["interaction_order"] (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• options["qoi"] (int or str, optional, default: 0) – Choose for which QOI the projection is determined for. The other QOIs use the same projection. Alternatively, the projection can be determined for every QOI independently (qoi_index or “all”).

• options["n_grid_gradient"] (float, optional, default: 10) – Number of initial grid points to determine gradient and projection matrix

• options["classifier"] (str, optional, default: "learning") – Classification algorithm to subdivide parameter domain. - “learning” … ClassifierLearning algorithm based on Unsupervised and supervised learning

• options["classifier_options"] (dict, optional, default: default settings) – Options of classifier

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> # initialize static gPC algorithm
>>> algorithm = pygpc.MEStaticProjection(problem=problem, options=options)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run

run()

Runs static multi-element gPC algorithm with projection.

Returns:

• megpc (MEGPC object instance) – MEGPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances and sub-gPCs

• coeffs (list of list of ndarray of float [n_qoi][n_gpc][n_basis x n_out]) – GPC coefficients of different qoi and sub-gPCs

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.MEStatic_IO(parameters, options, results, grid, validation=None)

Bases: Algorithm

Multi-Element Static gPC algorithm using precomputed IO data

Parameters:

• parameters (OrderedDict containing the RandomParameter class instances) – Dictionary (ordered) containing the properties of the random parameters

• options["order"] (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• options["order_max"] (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["interaction_order"] (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• options["qoi"] (int or str, optional, default: 0) – Choose for which QOI the projection is determined for. The other QOIs use the same projection. Alternatively, the projection can be determined for every QOI independently (qoi_index or “all”).

• options["classifier"] (str, optional, default: "learning") – Classification algorithm to subdivide parameter domain. - “learning” … ClassifierLearning algorithm based on Unsupervised and supervised learning

• options["classifier_options"] (dict, optional, default: default settings) – Options of classifier

• grid (Grid object instance) – Grid object to use for static gPC (Random, SparseGrid, TensorGrid) containing the parameter values, where the output relations were calculated

• results (ndarray of float [N_grid x N_qoi]) – Model output at each grid point for each QOI

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> # initialize static gPC algorithm
>>> algorithm = pygpc.MEStatic_IO(parameters=parameters, options=options, results=results, grid=grid)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run()

run()

Runs Multi-Element Static gPC algorithm using precomputed IO data to construct gPC approximation.

Returns:

• megpc (Multi-element GPC object instance) – MEGPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.RegAdaptive(problem, options, validation=None, grid=None)

Bases: Algorithm

Adaptive regression approach based on leave one out cross validation error estimation

Parameters:

• problem (Problem class instance) – GPC problem under investigation

• options["order_start"] (int, optional, default=0) – Initial gPC expansion order (maximum order)

• options["order_end"] (int, optional, default=10) – Maximum Gpc expansion order to expand to (algorithm will terminate afterwards)

• options["interaction_order"] (int, optional, default=dim) – Define maximum interaction order of parameters (default: all interactions)

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["adaptive_sampling"] (boolean, optional, default: True) – Adds samples adaptively to the expansion until the error is converged and continues by adding new basis functions.

Examples

>>> import pygpc
>>> # initialize adaptive gPC algorithm
>>> algorithm = pygpc.RegAdaptive(problem=problem, options=options)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run()

run()

Runs adaptive gPC algorithm to solve problem.

Returns:

• gpc (GPC object instance) – GPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.RegAdaptiveProjection(problem, options, validation=None, grid=None)

Bases: Algorithm

Adaptive regression approach using projection and leave one out cross validation error estimation

Parameters:

• problem (Problem class instance) – GPC problem under investigation

• options["order_start"] (int, optional, default=0) – Initial gPC expansion order (maximum order)

• options["order_end"] (int, optional, default=10) – Maximum Gpc expansion order to expand to (algorithm will terminate afterwards)

• options["interaction_order"] (int, optional, default=dim) – Define maximum interaction order of parameters (default: all interactions)

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["n_grid_gradient"] (float, optional, default: 10) – Number of initial grid points to determine gradient and projection matrix. When the algorithm goes into the main interations the number will be increased depending on the options “matrix_ratio” and “adaptive_sampling”.

• options["qoi"] (int or str, optional, default: 0) – Choose for which QOI the projection is determined for. The other QOIs use the same projection. Alternatively, the projection can be determined for every QOI independently (qoi_index or “all”).

• options["adaptive_sampling"] (boolean, optional, default: True) – Adds samples adaptively to the expansion until the error is converged and continues by adding new basis functions.

Examples

>>> import pygpc
>>> # initialize adaptive gPC algorithm
>>> algorithm = pygpc.RegAdaptiveProjection(problem=problem, options=options)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run()

run()

Runs adaptive gPC algorithm using projection to solve problem.

Returns:

• gpc (GPC object instance) – GPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.Static(problem, options, grid=None, validation=None, gpc=None)

Bases: Algorithm

Static gPC algorithm

Parameters:

• problem (Problem object) – Object instance of gPC problem to investigate

• options["method"] (str) – GPC method to apply [‘Reg’, ‘Quad’]

• options["order"] (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• options["order_max"] (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["interaction_order"] (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• grid (Grid object instance) – Grid object to use for static gPC (Random, SparseGrid, TensorGrid)

• validation (Validation Set class instance, optional) – Validation set containing reference solutions at precomputed grid points

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> # initialize static gPC algorithm
>>> algorithm = pygpc.Static(problem=problem, options=options, grid=grid)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run()

run()

Runs static gPC algorithm to solve problem.

Returns:

• gpc (GPC object instance) – GPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.StaticProjection(problem, options, validation=None, grid=None)

Bases: Algorithm

Static gPC algorithm using Basis Projection approach

Parameters:

• problem (Problem object) – Object instance of gPC problem to investigate

• options["method"] (str) – GPC method to apply [‘Reg’, ‘Quad’]

• options["order"] (int) – Expansion order, each projected variable eta is expanded to. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• options["order_max"] (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["interaction_order"] (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• options["qoi"] (int or str, optional, default: 0) – Choose for which QOI the projection is determined for. The other QOIs use the same projection. Alternatively, the projection can be determined for every QOI independently (qoi_index or “all”).

• options["n_grid"] (float, optional, default: 10) – Number of initial grid points to determine gradient and projection matrix

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> # initialize static gPC algorithm
>>> algorithm = pygpc.StaticProjection(problem=problem, options=options)
>>> # run algorithm
>>> gpc, coeffs, results = algorithm.run

run()

Runs static gPC algorithm using Projection to solve problem.

Returns:

• gpc (GPC object instance) – GPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (list of ndarray of float [n_qoi][n_basis x n_out]) – GPC coefficients for different qoi

• res (ndarray of float [n_grid x n_out]) – Simulation results at n_grid points of the n_out output variables

class pygpc.Algorithm.Static_IO(parameters, options, results, grid, validation=None)

Bases: Algorithm

Static gPC algorithm, which uses precomputed input output relationships to construct the gPC approximation

Parameters:

• parameters (OrderedDict containing the RandomParameter class instances) – Dictionary (ordered) containing the properties of the random parameters

• options["order"] (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• options["order_max"] (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• options["order_max_norm"] (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• options["interaction_order"] (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• grid (Grid object instance) – Grid object to use for static gPC (Random, SparseGrid, TensorGrid) containing the parameter values, where the output relations were calculated

• results (ndarray of float [N_grid x N_qoi]) – Model output at each grid point for each QOI

• validation (Validation Set class instance, optional) – Validation set containing reference solutions at precomputed grid points

Examples

>>> import pygpc
>>> # initialize static gPC algorithm using precomputed IO relationships
>>> algorithm = pygpc.Static_IO(parameters=parameters, options=options, grid=grid, results=results)
>>> # run algorithm
>>> gpc, coeffs = algorithm.run()

run()

Runs static gPC algorithm using precomputed IO relationships to construct surrogate model.

Returns:

• gpc (GPC object instance) – GPC object containing all information i.e., Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

pygpc.Basis module

class pygpc.Basis.Basis

Bases: object

Basis class of gPC

b

Parameter wise basis function objects used in gPC. Multiplying all elements in a row at location xi = (x1, x2, …, x_dim) yields the global basis function.

Type:

list of list of BasisFunction object instances [n_basis][n_dim]

b_array

Polynomial coefficients of basis functions

Type:

ndarray of float [n_poly_coeffs]

b_id

Unique IDs of global basis functions

Type:

list of UUID objects (version 4) [n_basis]

b_norm

Normalization factor of individual basis functions

Type:

ndarray of float [n_basis x dim]

b_norm_basis

Normalization factor of global basis functions

Type:

ndarray of float [n_basis x 1]

dim

Number of variables

Type:

int

n_basis

Total number of (global) basis function

Type:

int

multi_indices

Multi-indices of polynomial basis functions

Type:

ndarray [n_basis x dim]

add_basis_poly_by_order(multi_indices, problem)

Adds polynomial basis self.b for given order, order_max_norm and interaction order. Adds only the basis functions, which are not yet included.

Parameters:

• multi_indices (ndarray of int [n_basis_new, dim]) – Array containing the orders of the polynomials to be added to the basis

• problem (Problem class instance) – GPC Problem to analyze

extend_basis(b_added)

Extend set of basis functions. Skips basis functions, which are already present in self.b.

Parameters:

b_added (list of list of BasisFunction instances [n_b_added][dim]) – Individual BasisFunctions to add

extend_basis_array(b_added)

Extends polynomial basis coefficients for fast processing. Converts list of lists of b_added into np.ndarray that can be processed on multi core systems.

Parameters:

b_added (list of list of BasisFunction instances [n_b_added][dim]) – Individual BasisFunctions to add

init_basis_array()

Initialize polynomial basis coefficients for fast processing. Converts list of lists of self.b into np.ndarray that can be processed on multi core systems.

init_basis_norm()

Construct array of scaling factors self.b_norm [n_basis x dim] and self.b_norm_basis [n_basis x 1] to normalize basis functions <psi^2> = int(psi^2*p)dx

init_basis_sgpc(problem, order, order_max, order_max_norm, interaction_order, interaction_order_current=None)

Initializes basis functions for standard gPC.

Parameters:

• problem (Problem object) – GPC Problem to analyze

• order (list of int [dim]) – Maximum individual expansion order Generates individual polynomials also if maximum expansion order in order_max is exceeded

• order_max (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• order_max_norm (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• interaction_order (int) – Number of random variables, which can interact with each other

• interaction_order_current (int, optional, default: interaction_order) – Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with “interaction order”.

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

\[\begin{split}\begin{tabular}{l*{4}{c}} Polynomial Index & Dimension 1 & Dimension 2 & ... & Dimension M \\ \hline Basis 1 & [Order D1] & [Order D2] & \vdots & [Order M] \\ Basis 2 & [Order D1] & [Order D2] & \vdots & [Order M] \\ \vdots & [Order D1] & [Order D2] & \vdots & [Order M] \\ Basis N & [Order D1] & [Order D2] & \vdots & [Order M] \\ \end{tabular}\end{split}\]

Adds Attributes:

b: list of BasisFunction object instances [n_basis x n_dim]

Parameter wise basis function objects used in gPC. Multiplying all elements in a row at location xi = (x1, x2, …, x_dim) yields the global basis function.

plot_basis(dims, fn_plot=None, dynamic_plot_update=False)

Generate 2D or 3D cube-plot of basis functions.

Parameters:

• dims (list of int of length [2] or [3]) – Indices of parameters in gPC expansion to plot

• fn_plot (str, optional, default: None) – Filename of plot to save (with .png or .pdf extension)

Returns:

<File> – Plot of basis functions

Return type:

*.png and *.pdf file

set_basis(i_basis, problem)

Worker function to initialize a global basis function (called by multiprocessing.pool). It also initializes polynomial basis coefficients for fast processing. Converts list of lists of basis into np.ndarray that can be processed on multi core systems.

Parameters:

• i_basis (int) – Index of global basis function

• problem (Problem class instance) – gPC problem

Returns:

• b_ (list [n_dim]) – List containing the individual basis functions of the parameters

• b_a_ (ndarray of int) – Concatenated list of polynomial basis coefficients

• b_a_grad_ (ndarray of int) – Concatenated list of polynomial basis coefficients for gradient evaluation

set_basis_poly(order, order_max, order_max_norm, interaction_order, interaction_order_current, problem)

Sets up polynomial basis self.b for given order, order_max_norm and interaction order. Adds only the basis functions, which are not yet included.

Parameters:

• order (list of int) – Maximum individual expansion order Generates individual polynomials also if maximum expansion order in order_max is exceeded

• order_max (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• order_max_norm (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq (11) in [1]).

• interaction_order (int) – Number of random variables, which can interact with each other All polynomials are ignored, which have an interaction order greater than specified

• interaction_order_current (int, optional, default: interaction_order) – Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with interaction_order.

• problem (Problem class instance) – GPC Problem to analyze

pygpc.BasisFunction module

class pygpc.BasisFunction.BasisFunction(p)

Bases: object

Abstract class of basis functions. This base class provides basic properties and methods for the basis functions. It cannot be used directly, but inherits properties and methods to the specific basis function sub classes.

Parameters:

p (dict) – Parameters of the polynomial (see subclasses for details)

__call__(x, derivative=False)

Evaluates basis function for argument x

Parameters:

• x (float or ndarray of float) – Argument for which the basis function is evaluated

• derivative (boolean, optional, default: False) – Returns derivative of basis function at argument x

Returns:

y – Function value or derivative of basis function at argument x

Return type:

float or ndarray of float

class pygpc.BasisFunction.Hermite(p)

Bases: BasisFunction

Hermite basis function used in the orthogonal gPC to model normal distributed random variables.

Parameters:

p (dict) – Parameters of the Hermite polynomial - p[“i”] … order

class pygpc.BasisFunction.Jacobi(p)

Bases: BasisFunction

Jacobi basis function used in the orthogonal gPC to model beta distributed random variables.

Parameters:

p (dict) – Parameters of the Jacobi polynomial - p[“i”] … order - p[“p”] … first shape parameter - p[“q”] … second shape parameter

class pygpc.BasisFunction.Laguerre(p)

Bases: BasisFunction

Laguerre basis function used in the orthogonal gPC to model gamma distributed random variables. It is defined in the gpc space from [0, inf]

Parameters:

p (dict) – Parameters of the Laguerre polynomial - p[“i”] … order - p[“alpha”] … shape parameter (alpha_poly = alpha_pdf - 1) - p[“beta”] … rate parameter

class pygpc.BasisFunction.Rect(p)

Bases: BasisFunction

Rectangular basis function used in the non-orthogonal gPC.

Parameters:

p (dict) – Parameters of the Rect function - p[“x1”] … location of positive flank (0 -> 1) - p[“x2”] … location of negative flank (1 -> 0)

class pygpc.BasisFunction.SigmoidDown(p)

Bases: BasisFunction

SigmoidDown (from 0 to 1) basis function used in the non-orthogonal gPC.

Parameters:

p (dict) – Parameters of the SigmoidDown function - p[“xs”] … location of turning point - p[“r”] … steepness

class pygpc.BasisFunction.SigmoidUp(p)

Bases: BasisFunction

SigmoidUp (from 0 to 1) basis function used in the non-orthogonal gPC.

Parameters:

p (dict) – Parameters of the SigmoidUp function - p[“xs”] … location of turning point - p[“r”] … steepness

class pygpc.BasisFunction.StepDown(p)

Bases: BasisFunction

StepDown (from 1 to 0) basis function used in the non-orthogonal gPC.

Parameters:

p (dict) – Parameters of the StepDown function - p[“xs”] … location of step

class pygpc.BasisFunction.StepUp(p)

Bases: BasisFunction

StepUp (from 0 to 1) basis function used in the non-orthogonal gPC.

Parameters:

p (dict) – Parameters of the StepUp function - p[“xs”] … location of step

pygpc.Classifier module

pygpc.Classifier.Classifier(coords, results, algorithm='learning', options=None)

Helper function to initialize Classifier class.

Parameters:

• coords (ndarray of float [n_grid, n_dim]) – Set of n_grid parameter combinations

• results (ndarray [n_grid x n_out]) – Results of the model evaluation

• algorithm (str, optional, default: "learning") – Algorithm to classify grid points - “learning” … 2-step procedure with unsupervised and supervised learning - …

• options (dict, optional, default=None) – Classifier options

Returns:

obj – Object instance of Classifier class

Return type:

object instance of Classifier class

class pygpc.Classifier.ClassifierLearning(coords, results, options=None)

Bases: object

ClassifierLearning class

Parameters:

• coords (ndarray of float [n_grid, n_dim]) – Grid points to train the classifier

• results (ndarray [n_grid x n_out]) – Results of the model evaluation

• options (dict, optional, default=None) – Classifier options - options[“clusterer”] … Cluster algorithm (e.g. “KMeans”) - options[“n_clusters”] … Number of clusters in case of “KMeans” - options[“classifier”] … Classification algorithm (e.g. “MLPClassifier”) - options[“classifier_solver”] … Classification algorithm (e.g. “adam” or “lbfgs”)

coords

Grid points to train the classifier

Type:

ndarray of float [n_grid, n_dim]

results

Results of the model evaluation

Type:

ndarray [n_grid x n_out]

options

Classifier options

Type:

dict, optional, default=None

clf

Classifier object

Type:

Classifier object

predict(coords)

Predict domains from new coordinates

Parameters:

coords (ndarray of float [n_grid, n_dim]) – Grid points to classify (has to be a 2D array)

Returns:

domains – Domain IDs of grid-points

Return type:

ndarray of float [n_grid, n_dim]

update(coords, results)

Updates classifier using the previous results

Parameters:

• coords (ndarray of float [n_grid, n_dim]) – Grid points to train the classifier

• results (ndarray [n_grid x n_out]) – Results of the model evaluation

pygpc.Computation module

pygpc.Computation.Computation(n_cpu, matlab_model=False)

Helper function to initialize the Computation class. n_cpu = 0 : use this if the model is capable of to evaluate several parameterizations in parallel n_cpu = 1 : the model is called in serial for every paramerization. n_cpu > 1 : A multiprocessing.Pool will be opened and n_cpu parameterizations are calculated in parallel

Parameters:

• n_cpu (int) – Number of CPU cores to use (parallel model evaluations)

• matlab_model (boolean, optional, default: False) – Use a Matlab model

Returns:

obj – Object instance of Computation class

Return type:

object instance of Computation class

class pygpc.Computation.ComputationFuncPar(n_cpu, matlab_model)

Bases: object

Computation sub-class to run the model using a the models internal parallelization

Parameters:

• n_cpu (int) – Number of CPU cores to use (parallel model evaluations)

• matlab_model (boolean, optional, default: False) – Use a Matlab model

close()

Closes the pool

run(model, problem, coords, coords_norm=None, i_iter=None, i_subiter=None, fn_results=None, print_func_time=False, increment_grid=True, verbose=False)

Runs model evaluations for parameter combinations specified in coords array

Parameters:

• model (Model object) – Model object instance of model to investigate (derived from AbstractModel class, implemented by user)

• problem (Problem class instance) – GPC Problem under investigation, includes the parameters of the model (constant and random)

• coords (ndarray of float [n_sims, n_dim]) – Set of n_sims parameter combinations to run the model with (only the random parameters!).

• coords_norm (ndarray of float [n_sims, n_dim]) – Set of n_sims parameter combinations to run the model with (normalized coordinates [-1, 1].

• i_iter (int) – Index of main-iteration

• i_subiter (int) – Index of sub-iteration

• fn_results (string, optional, default=None) – If provided, model evaluations are saved in fn_results.hdf5 file and gpc object in fn_results.pkl file

• print_func_time (bool) – Print time of single function evaluation

• increment_grid (bool) – Increment grid counter (not done in case of gradient calculation)

• verbose (bool, optional, default: False) – Print progress

Returns:

res – n_sims simulation results of the n_out output quantities of the model under investigation.

Return type:

ndarray of float [n_sims x n_out]

class pygpc.Computation.ComputationPoolMap(n_cpu, matlab_model=False)

Bases: object

Computation sub-class to run the model using a processing pool for parallelization

Parameters:

• n_cpu (int) – Number of CPU cores to use (parallel model evaluations)

• matlab_model (boolean, optional, default: False) – Use a Matlab model

close()

Closes the pool

run(model, problem, coords, coords_norm=None, i_iter=None, i_subiter=None, fn_results=None, print_func_time=False, increment_grid=True, verbose=False)

Runs model evaluations for parameter combinations specified in coords array

Parameters:

• model (Model object) – Model object instance of model to investigate (derived from AbstractModel class, implemented by user)

• problem (Problem class instance) – GPC Problem under investigation, includes the parameters of the model (constant and random)

• coords (ndarray of float [n_sims, n_dim]) – Set of n_sims parameter combinations to run the model with (only the random parameters!).

• coords_norm (ndarray of float [n_sims, n_dim]) – Set of n_sims parameter combinations to run the model with (normalized coordinates [-1, 1].

• i_iter (int) – Index of main-iteration

• i_subiter (int) – Index of sub-iteration

• fn_results (string, optional, default=None) – If provided, model evaluations are saved in fn_results.hdf5 file and gpc object in fn_results.pkl file

• print_func_time (bool) – Print time of single function evaluation

• increment_grid (bool) – Increment grid counter (not done in case of gradient calculation)

• verbose (bool, optional, default: False) – Print progress

Returns:

res – n_sims simulation results of the n_out output quantities of the model under investigation.

Return type:

ndarray of float [n_sims x n_out]

pygpc.GPC module

class pygpc.GPC.GPC(problem, options, validation=None)

Bases: object

General gPC base class

Parameters:

• problem (Problem class instance) – GPC Problem under investigation

• options (dict) – Options of gPC algorithm

• validation (ValidationSet object (optional)) – Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

problem

GPC Problem under investigation

Type:

Problem class instance

basis

Basis of the gPC including BasisFunctions

Type:

Basis class instance

grid

Grid of the derived gPC approximation

Type:

Grid class instance

validation

Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

Type:

ValidationSet object (optional)

gpc_matrix

Generalized polynomial chaos matrix

Type:

[N_samples x N_poly] ndarray of float

gpc_matrix_gradient

Derivative of generalized polynomial chaos matrix

Type:

[N_samples * dim x N_poly] ndarray of float

matrix_inv

Pseudo inverse of the generalized polynomial chaos matrix (with or without gradient)

Type:

[N_poly (+ N_gradient) x N_samples] ndarray of float

p_matrix

Projection matrix to reduce number of efficient dimensions (eta = p_matrix * xi)

Type:

[dim_red x dim] ndarray of float

p_matrix_norm

Maximal possible length of new axis in eta space. Since the projected variables are modelled in the normalized space between [-1, 1], the transformed coordinates need to be scaled.

Type:

[dim_red] ndarray of float

nan_elm

Indices of NaN elements of model output

Type:

ndarray of int

gpc_matrix_coords_id

UUID4() IDs of grid points the gPC matrix derived with

Type:

list of UUID4()

gpc_matrix_b_id

UUID4() IDs of basis functions the gPC matrix derived with

Type:

list of UUID4()

n_basis

Number of basis functions (for iterative solvers, this is a list of its history)

Type:

int or list of int

n_grid

Number of grid points (for iterative solvers, this is a list of its history)

Type:

int or list of int

solver

Default solver to determine the gPC coefficients (can be chosen during GPC.solve) - ‘Moore-Penrose’ … Pseudoinverse of gPC matrix (SGPC.Reg, EGPC) - ‘OMP’ … Orthogonal Matching Pursuit, sparse recovery approach (SGPC.Reg, EGPC) - ‘LarsLasso’ … {“alpha”: float 0…1} Regularization parameter - ‘NumInt’ … Numerical integration, spectral projection (SGPC.Quad)

Type:

str

verbose

Boolean value to determine if to print out the progress into the standard output

Type:

bool

fn_results

If provided, model evaluations are saved in fn_results.hdf5 file and gpc object in fn_results.pkl file

Type:

string, optional, default=None

relative_error_loocv

Relative error of the leave-one-out-cross-validation

Type:

list of float

relative_error_nrmsd

Normalized root mean square deviation between model and gpc approximation

Type:

list of float

options

Options of gPC algorithm

Type:

dict

create_gpc_matrix(b, x, gradient=False, gradient_idx=None, weighted=False, verbose=False)

Construct the gPC matrix or its derivative.

Parameters:

• b (list of BasisFunction object instances [n_basis][n_dim]) – Parameter wise basis function objects used in gPC (Basis.b) Multiplying all elements in a row at location xi = (x1, x2, …, x_dim) yields the global basis function.

• x (ndarray of float [n_x x n_dim]) – Coordinates of x = (x1, x2, …, x_dim) where the rows of the gPC matrix are evaluated (normalized [-1, 1])

• gradient (bool, optional, default: False) – Determine gradient gPC matrix.

• gradient_idx (ndarray of int [gradient_results.shape[0]]) – Indices of grid points where the gradient in gradient_results is provided

• weighted (bool, optional, default: False) – Weight gPC matrix with (row 2-norm)^-1

• verbose (bool, optional, default: False) – boolean value to determine if to print out the progress into the standard output

Returns:

gpc_matrix – GPC matrix where the columns correspond to the basis functions and the rows the to the sample coordinates. If gradient_idx!=None, the gradient is returned at the specified sample coordinates point by point.

Return type:

ndarray of float [n_x x n_basis (x dim)]

create_validation_set(n_samples, n_cpu=1)

Creates a ValidationSet instance (calls the model)

Parameters:

• n_samples (int) – Number of sampling points contained in the validation set

• n_cpu (int) – Number of parallel function evaluations to evaluate validation set (n_cpu=0 assumes that the model is capable to evaluate all grid points in parallel)

get_approximation(coeffs, x, output_idx=None)

Calculates the gPC approximation in points with output_idx and normalized parameters xi (interval: [-1, 1]).

pce = GPC.get_approximation(coeffs, x, output_idx=None)

Parameters:

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients for each output variable

• x (ndarray of float [n_x x n_dim]) – Coordinates of x = (x1, x2, …, x_dim) where the rows of the gPC matrix are evaluated (normalized [-1, 1]). The coordinates will be transformed in case of projected gPC.

• output_idx (ndarray of int, optional, default=None [n_out]) – Indices of output quantities to consider (Default: all).

Returns:

pce – GPC approximation at normalized coordinates x.

Return type:

ndarray of float [n_x x n_out]

get_loocv(coeffs, results, gradient_results=None, error_norm='relative')

Perform leave-one-out cross validation of gPC approximation and add error value to self.relative_error_loocv. The loocv error is calculated analytically after eq. (35) in [1] but omitting the “1 - “ term, i.e. it corresponds to 1 - Q^2.

relative_error_loocv = GPC.loocv(sim_results, coeffs)

\[\epsilon_{LOOCV} = \frac{\frac{1}{N}\sum_{i=1}^N \left( \frac{y(\xi_i) - \hat{y}(\xi_i)}{1-h_i} \right)^2}{\frac{1}{N-1}\sum_{i=1}^N \left( y(\xi_i) - \bar{y} \right)^2}\]

with

\[\mathbf{h} = \mathrm{diag}(\mathbf{\Psi} (\mathbf{\Psi}^T \mathbf{\Psi})^{-1} \mathbf{\Psi}^T)\]

Parameters:

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• results (ndarray of float [n_grid x n_out]) – Results from n_grid simulations with n_out output quantities

• error_norm (str, optional, default="relative") – Decide if error is determined “relative” or “absolute”

• gradient_results (ndarray of float [n_grid x n_out x dim], optional, default: None) – Gradient of results in original parameter space (tensor)

Returns:

relative_error_loocv – Relative mean error of leave one out cross validation

Return type:

float

Notes

[1]

Blatman, G., & Sudret, B. (2010). An adaptive algorithm to build up sparse polynomial chaos expansions for stochastic finite element analysis. Probabilistic Engineering Mechanics, 25(2), 183-197.

get_pdf(coeffs, n_samples, output_idx=None, filter=True, return_samples=False)

Determine the estimated pdfs of the output quantities

pdf_x, pdf_y = SGPC.get_pdf(coeffs, n_samples, output_idx=None)

Parameters:

• coeffs (ndarray of float [n_coeffs x n_out]) – GPC coefficients

• n_samples (int) – Number of samples used to estimate output pdfs

• output_idx (ndarray, optional, default=None [1 x n_out]) – Index of output quantities to consider (if output_idx=None, all output quantities are considered)

• filter (bool, optional, default: True) – Use savgol_filter to smooth probability density

• return_samples (bool, optional, default: False) – Additionally returns in and output samples with which the pdfs were computed

Returns:

• pdf_x (ndarray of float [100 x n_out]) – x-coordinates of output pdfs of output quantities

• pdf_y (ndarray of float [100 x n_out]) – y-coordinates of output pdfs (probability density of output quantity)

• samples_in (ndarray of float [n_samples x dim] (optional)) – Input samples (if return_samples=True)

• samples_out (ndarray of float [n_samples x n_out] (optional)) – Output samples (if return_samples=True)

get_samples(coeffs, n_samples, output_idx=None)

Randomly sample gPC expansion.

x, pce = SGPC.get_pdf_mc(n_samples, coeffs, output_idx=None)

Parameters:

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• n_samples (int) – Number of random samples drawn from the respective input pdfs.

• output_idx (ndarray of int [1 x n_out] optional, default=None) – Index of output quantities to consider.

Returns:

• x (ndarray of float [n_samples x dim]) – Generated samples in normalized coordinates [-1, 1].

• pce (ndarray of float [n_samples x n_out]) – GPC approximation at points x.

init_gpc_matrix(gradient_idx=None)

Sets self.gpc_matrix and self.gpc_matrix_gradient with given self.basis and self.grid

Parameters:

gradient_idx (ndarray of int [gradient_results.shape[0]]) – Indices of grid points where the gradient in gradient_results is provided

replace_gpc_matrix_samples(idx, seed=None)

Replace distinct sample points from the gPC matrix with new ones.

GPC.replace_gpc_matrix_samples(idx, seed=None)

Parameters:

• idx (ndarray of int [n_samples]) – Array of grid indices of grid.coords[idx, :] which are going to be replaced (rows of gPC matrix will be replaced by new ones)

• seed (float, optional, default=None) – Random seeding point

save_gpc_matrix_hdf5(hdf5_path_gpc_matrix=None, hdf5_path_gpc_matrix_gradient=None)

Save gPC matrix and gPC gradient matrix in .hdf5 file <”fn_results” + “.hdf5”> under the key “gpc_matrix” and “gpc_matrix_gradient”. If matrices are already present, check for equality and save only appended rows and columns.

Parameters:

• hdf5_path_gpc_matrix (str) – Path in .hdf5 file, where the gPC matrix is saved in

• hdf5_path_gpc_matrix_gradient (str) – Path in .hdf5 file, where the gPC gradient matrix is saved in

solve(results, gradient_results=None, solver=None, settings=None, matrix=None, verbose=False)

Determines gPC coefficients

Parameters:

• results ([n_grid x n_out] np.ndarray of float) – Results from simulations with N_out output quantities

• gradient_results (ndarray of float [n_gradient x n_out x dim], optional, default: None) – Gradient of results in original parameter space in specific grid points

• solver (str) – Solver to determine the gPC coefficients - ‘Moore-Penrose’ … Pseudoinverse of gPC matrix (SGPC.Reg, EGPC) - ‘OMP’ … Orthogonal Matching Pursuit, sparse recovery approach (SGPC.Reg, EGPC) - ‘LarsLasso’ … Least-Angle Regression using Lasso model (SGPC.Reg, EGPC) - ‘NumInt’ … Numerical integration, spectral projection (SGPC.Quad)

• settings (dict) – Solver settings - ‘Moore-Penrose’ … None - ‘OMP’ … {“n_coeffs_sparse”: int} Number of gPC coefficients != 0 or “sparsity”: float 0…1 - ‘LarsLasso’ … {“alpha”: float 0…1} Regularization parameter - ‘NumInt’ … None

• matrix (ndarray of float, optional, default: self.gpc_matrix or [self.gpc_matrix, self.gpc_matrix_gradient]) – Matrix to invert. Depending on gradient_enhanced option, this matrix consist of the standard gPC matrix and their derivatives.

• verbose (bool) – boolean value to determine if to print out the progress into the standard output

Returns:

coeffs – gPC coefficients

Return type:

ndarray of float [n_coeffs x n_out]

update_gpc_matrix()

Update gPC matrix and gPC matrix gradient according to existing self.grid and self.basis.

Call this method when self.gpc_matrix does not fit to self.grid and self.basis objects anymore The old gPC matrix with their self.gpc_matrix_b_id and self.gpc_matrix_coords_id is compared to self.basis.b_id and self.grid.coords_id. New rows and columns are computed if differences are found.

validate(coeffs, results=None, gradient_results=None, qoi_idx=None)

Validate gPC approximation using the ValidationSet object contained in the Problem object. Determines the normalized root mean square deviation between the gpc approximation and the original model. Skips this step if no validation set is present

Parameters:

• coeffs (ndarray of float [n_coeffs x n_out]) – GPC coefficients

• results (ndarray of float [n_grid x n_out]) – Results from n_grid simulations with n_out output quantities

• gradient_results (ndarray of float [n_grid x n_out x dim], optional, default: None) – Gradient of results in original parameter space (tensor)

• qoi_idx (int, optional, default: None) – Index of QOI to validate (if None, all QOI are considered)

Returns:

error – Estimated difference between gPC approximation and original model

Return type:

float

pygpc.Grid module

class pygpc.Grid.CO(parameters_random, gpc, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: RandomGrid

Coherence Optimal grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples to generate

• options (dict, optional, default=None) – Grid options: - ‘seed’ : Seeding point

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.CO(parameters_random=parameters_random, n_grid=100, options={"seed": None})

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

Grid options:

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

acceptance_rate(idx1, idx2)

Calculate acceptance rate of Metropolis Hastings algorithm

Parameters:

• idx1 (int) – Index of sampling points of previous sample

• idx2 (int) – Index of sampling points of current sample

Returns:

rho – Acceptance rate

Return type:

float

static calc_ball_volume(dim, radius)

Volume of n-dimensional ball.

Parameters:

• dim (int) – Number of random variables

• radius (float) – Radius

Returns:

vol – Volume of n-dimensional ball

Return type:

float

create_pool(n_samples)

Creates a pool of samples together with the corresponding gPC matrix.

Parameters:

n_samples (int) – Number of samples

get_coherence_optimal_samples(n_grid, n_warmup)

Determine coherence optimal samples with Monte Carlo Markov Chain - Metropolis Hastings algorithm

Parameters:

• n_grid (int) – Number of grid points

• n_warmup (int) – Number of warmup samples

Returns:

coords_norm – Coherence optimal samples

Return type:

ndarray of float [n_grid x n_dim]

joint_pdf(x, parameters_random)

Joint probability density function of random variables

Parameters:

• x (ndarray of float [n_samples x n_dim]) – Samples of random variables

• parameters_random (dict of RandomVariable instances) – Random variables of proposal distribution

Returns:

f – Joint probability density

Return type:

float

warmup(n_warmup)

Warmup phase

Parameters:

n_warmup (int) – Number of warmup samples

Returns:

coords_norm_opt – Optimal coordinates determined during warmup phase

Return type:

ndarray of float [n_warmup x n_dim]

class pygpc.Grid.FIM(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, gpc=None, grid_pre=None)

Bases: RandomGrid

FIM D-optimal grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples to generate

• seed (float) – Seeding point to replicate random grids

• options (dict, optional, default=None) – Grid options: - ‘n_pool’ : number of random samples to determine next optimal grid point - ‘seed’ : random seed

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.FIM(parameters_random=parameters_random,
>>>                  n_grid=100,
>>>                  options={"n_pool": 1000,
>>>                           "seed": None})

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

Grid options: - method: “greedy”, “iteration” - criterion: [“mc”], [“tmc”, “cc”] - weights: [1], [0.5, 0.5] - n_pool: size of samples in pool to choose greedy results from - n_iter: number of iterations - seed: random seed

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

add_fim_optiomal_grid_points(parameters_random, n_grid_add)

This function adds grid points (one by one) to the set of points by maximizing the Fisher-information matrix in a D-optimal sense.

Parameters:

• parameters_random (OrderedDict of RandomParameter [dim]) – Random parameters (in case of projection, provide the original random parameters)

• n_grid_add (int) – Number of grid points to add

Returns:

coords_norm – Normalized sample coordinates in range [-1, 1]

Return type:

ndarray of float [n_grid x dim]

calc_fim_matrix(n_basis_limit=None)

Calculates Fisher-Information matrix based on the present grid.

Parameters:

n_basis_limit (int) – Index of column the FIM matrix is calculated

Returns:

fim_matrix – Fisher information matrix

Return type:

ndarray of float [n_basis x n_basis]

get_det_updated_fim_matrix(fim_matrix, coords_norm)

Calculates Fisher-Information matrix based on the present grid and determined determinant.

Parameters:

• fim_matrix (ndarray of float [n_basis x n_basis]) – Fisher information matrix

• coords_norm (ndarray of float [1 x dim]) – Candidate grid point

Returns:

det – Determinant of updated Fisher Information matrix

Return type:

float

static update_fim_matrix(fim_matrix, gpc_matrix_new_rows)

Updates Fisher-Information matrix based on the present grid.

Parameters:

• fim_matrix (ndarray of float [n_basis x n_basis]) – Fisher information matrix

• gpc_matrix_new_rows (ndarray of float [n_new_rows x n_basis]) – New rows of gpc matrix to add to FIM matrix

Returns:

fim_matrix – Updated Fisher information matrix

Return type:

ndarray of float [n_basis x n_basis]

class pygpc.Grid.GP(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: RandomGrid

Gaussian Process grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int or float) – Number of random samples in grid

• seed (float, optional, default=None) – Seeding point to replicate random grid

• options (dict, optional, default=None) – RandomGrid options depending on the grid type

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.GP(parameters_random=parameters_random, n_grid=100)

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

RandomGrid options depending on the grid type

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

class pygpc.Grid.Grid(parameters_random, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: object

Grid class

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• weights (ndarray of float [n_grid x dim]) – Weights of the grid (all)

• coords (ndarray of float [n_grid x dim]) – Denormalized coordinates xi

• coords_norm (ndarray of float [n_grid x dim]) – Normalized coordinates xi

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

_weights

Weights of the grid (all)

Type:

ndarray of float [n_grid x dim]

_coords

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim]

_coords_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim]

_domains

Domain IDs of grid points for multi-element gPC

Type:

ndarray of float [n_grid]

_coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

_coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

n_grid

Total number of nodes in grid.

Type:

int

property coords

property coords_gradient

property coords_gradient_norm

property coords_norm

create_gradient_grid(delta=0.001)

Creates new grid points to determine gradient of model function. Adds or updates self.coords_gradient, self.coords_gradient_norm and self.coords_gradient_id.

Parameters:

delta (float, optional, default: 1e-3) – Shift of grid-points along axes in normalized parameter space

get_denormalized_coordinates(coords_norm)

Denormalize grid from normalized to original parameter space for simulations.

coords = Grid.get_denormalized_coordinates(coords_norm)

Parameters:

coords_norm ([N_samples x dim] np.ndarray) – Normalized coordinates xi

Returns:

coords – Denormalized coordinates xi

Return type:

[N_samples x dim] np.ndarray

get_normalized_coordinates(coords)

Normalize grid from original parameter to normalized space for simulations.

coords_norm = Grid.get_normalized_coordinates(coords)

Parameters:

coords ([N_samples x dim] np.ndarray) – Denormalized coordinates xi in original parameter space

Returns:

coords_norm – Normalized coordinates xi

Return type:

[N_samples x dim] np.ndarray

property weights

class pygpc.Grid.L1(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, gpc=None, grid_pre=None)

Bases: RandomGrid

L1 optimized grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples to generate

• options (dict, optional, default=None) – Grid options: - method: “greedy”, “iteration” - criterion: [“mc”], [“tmc”, “cc”], [“D”], [“D-coh”] - weights: [1], [0.5, 0.5], [1] - n_pool: size of samples in pool to choose greedy results from - n_iter: number of iterations - seed: random seed

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• gpc (GPC object instance) – GPC object

• grid_pre (Grid object instance, optional, default: None) – Existent grid, which will be extended.

Examples

>>> import pygpc
>>> grid = pygpc.L1(parameters_random=parameters_random,
>>>                 n_grid=100,
>>>                 options={"method": "greedy",
>>>                          "criterion": ["mc"],
>>>                          "weights": [1],
>>>                          "n_pool": 1000,
>>>                          "seed": None})

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

Grid options: - method: “greedy”, “iteration” - criterion: [“mc”], [“tmc”, “cc”], [“D”], [“D-coh”] - weights: [1], [0.5, 0.5], [1] - n_pool: size of samples in pool to choose greedy results from - n_iter: number of iterations - seed: random seed

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

gpc

GPC object

Type:

GPC Object instance

grid_pre

Existent grid, which will be extended.

Type:

Grid object instance, optional, default: None

get_optimal_mu_greedy()

This function computes a set of grid points with minimal mutual coherence using a greedy approach.

Returns:

coords_norm – Normalized sample coordinates in range [-1, 1]

Return type:

ndarray of float [n_grid x dim]

get_optimal_mu_iteration()

This function computes a set of grid points with minimal mutual coherence using an iterative approach.

Returns:

coords_norm – Normalized sample coordinates in range [-1, 1]

Return type:

ndarray of float [n_grid x dim]

class pygpc.Grid.L1_LHS(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, gpc=None, grid_pre=None)

Bases: RandomGrid

L1-LHS optimized grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples to generate

• seed (float) – Seeding point to replicate random grids

• options (dict, optional, default=None) – Grid options: - ‘corr’ : optimizes design points in their spearman correlation coefficients - ‘maximin’ or ‘m’ : optimizes design points in their maximum minimal distance using the Phi-P criterion - ‘ese’ : uses an enhanced evolutionary algorithm to optimize the Phi-P criterion

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.L1_LHS(parameters_random=parameters_random,
>>>                     n_grid=100,
>>>                     gpc=gpc,
>>>                     options={"method": "greedy",
>>>                              "criterion": ["mc"],
>>>                              "weights_L1": [1],
>>>                              "weights": [0.25, 0.75],
>>>                              "n_pool": 1000,
>>>                              "seed": None})

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

Grid options: - method: “greedy”, “iteration” - criterion: [“mc”], [“tmc”, “cc”] - weights: [1], [0.5, 0.5] - n_pool: size of samples in pool to choose greedy results from - n_iter: number of iterations - seed: random seed

Type:

dict, optional, default=None

coords

Grid points to add (model space), if coords are provided, no grid is generated

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space), if coords are provided, no grid is generated

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

class pygpc.Grid.LHS(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: RandomGrid

LHS grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples to generate

• options (dict, optional, default=None) –

  Grid options: - criterion :

  • ’corr’ : optimizes design points in their spearman correlation coefficients

  • ’maximin’ or ‘m’ : optimizes design points in their maximum minimal distance using the Phi-P criterion

  • ’ese’ : uses an enhanced evolutionary algorithm to optimize the Phi-P criterion

  • seed : Seeding point to replicate random grids

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.LHS(parameters_random=parameters_random, n_grid=100, options={"seed": None, "criterion": "ese"})

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

• ‘corr’ : optimizes design points in their spearman correlation coefficients

• ‘maximin’ or ‘m’ : optimizes design points in their maximum minimal distance using the Phi-P criterion

• ‘ese’ : uses an enhanced evolutionary algorithm to optimize the Phi-P criterion

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

CL2(array)

Calculate the L2 discrepancy of the design The discrepancy is a measure of the difference between the empirical cumulative distribution function of an experimental design and the uniform cumulative distribution function [1].

Parameters:

array (ndarray of float [m x n]) – Array with n rows of samples and m columns of variables/dimensions

Returns:

cl2d_crit – criterion for centered L2 discrepancy

Return type:

float

Notes

[1]

Hickernell, F. (1998). A generalized discrepancy and quadrature error bound. Mathematics of computation, 67(221), 299-322.

PhiP(x, p=10)

Calculates the Phi-p criterion of the design x with power p [1].

Parameters:

• x (ndarray of float [n x m]) – The design to calculate Phi-p for

• p (int, optional, default: 10) – The power used for the calculation of PhiP

Returns:

phip – Phi-p criterion

Return type:

float

Notes

[1]

Morris, M. D., & Mitchell, T. J. (1995). Exploratory designs for computational experiments. Journal of statistical planning and inference, 43(3), 381-402.

PhiP_exchange(P, k, Phi, p, fixed_index)

Performes a row exchange and return the altered design.

Parameters:

• P (ndarray of float [m x n]) – The design to perform the exchange on

• k (int) – modulus of the iteration divided by the dimension to pick a row of the design repeating through the dimensions of the design

• Phi (float) – the PhiP criterion of the current best Design

• p (int) – The power used for the calculation of PhiP

• fixed_index (list) – an empty list to check if variables are assigned a value

Returns:

phip – Phi-p criterion

Return type:

float

get_lhs_grid()

Create samples in an m*n matrix using Latin Hypercube Sampling [1].

Notes

[1]

McKay, M. D., Beckman, R. J., & Conover, W. J. (2000). A comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics, 42(1), 55-61.

lhs_corr()

Create a correlation optimized LHS grid

Parameters:

• dim (int) – Number of random variables

• n (int) – Number of sampling points

• iterations (int) – Number of iterations to optimize

Returns:

design – LHS grid points

Return type:

ndarray of float [n, n_dim]

lhs_ese()

Create optimized LHS grid using a enhanced stochastic evolutionary algorithm for the PhiP Maximin criterion [1]

Returns:

design – With ESE Algorithm for minimal Phi-P optimized grid points

Return type:

ndarray of float [n, n_dim]

Notes

[1]

Jin, R., Chen, W., & Sudjianto, A. (2005). An efficient algorithm for constructing optimal design of computer experiments. Journal of statistical planning and inference, 134(1), 268-287.

lhs_initial()

Construct an initial LHS grid.

Returns:

design – LHS grid points

Return type:

ndarray of float [n, n_dim]

lhs_maximin()

Create an optimized LHS grid with maximal minimal distance

Parameters:

• dim (int) – Number of random variables

• n (int) – Number of sampling points

• iterations (int) – Number of iterations to optimize

Returns:

design – LHS grid points

Return type:

ndarray of float [n, n_dim]

log_R(array)

Determines the Log(R) Entropy Criterion[1]

Parameters:

array (ndarray of float [m x n]) – Array

Returns:

log_R – Log(R) Entropy Criterion

Return type:

float

Notes

[1]

Koehler, J.R., Owen, A.B., 1996. Computer experiments. in: Ghosh, S., Rao, C.R. (Eds.), Handbook of Statistics. Elsevier Science, New York, pp.261-308

sample_init(n_grid)

Initialises all parameters for Latin Hypercube Sampling and creates a new design if there is at least one sampling point needed

Parameters:

n_grid (ndarray of float [n]) – The number of needed sampling points

Returns:

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

class pygpc.Grid.LHS_L1(parameters_random, gpc, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: RandomGrid

LHS-L1 optimized grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples to generate

• options (dict, optional, default=None) – Grid options: - ‘corr’ : optimizes design points in their spearman correlation coefficients - ‘maximin’ or ‘m’ : optimizes design points in their maximum minimal distance using the Phi-P criterion - ‘ese’ : uses an enhanced evolutionary algorithm to optimize the Phi-P criterion

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.LHS_L1(parameters_random=parameters_random,
>>>                     n_grid=100,
>>>                     gpc=gpc,
>>>                     options={"method": "greedy",
>>>                              "criterion": ["mc"],
>>>                              "weights_L1": [1],
>>>                              "weights": [0.25, 0.75],
>>>                              "n_pool": 1000,
>>>                              "seed": None})

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

Grid options: - method: “greedy”, “iteration” - criterion: [“mc”], [“tmc”, “cc”] - weights: [1], [0.5, 0.5] - n_pool: size of samples in pool to choose greedy results from - n_iter: number of iterations - seed: random seed

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

class pygpc.Grid.Random(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: RandomGrid

Random grid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int or float) – Number of random samples in grid

• seed (float, optional, default=None) – Seeding point to replicate random grid

• options (dict, optional, default=None) – RandomGrid options depending on the grid type

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.Random(parameters_random=parameters_random, n_grid=100)

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int or float

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

RandomGrid options depending on the grid type

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

class pygpc.Grid.RandomGrid(parameters_random, n_grid=None, options=None, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, grid_pre=None)

Bases: Grid

RandomGrid object

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• n_grid (int) – Number of random samples in grid

• seed (float, optional, default=None) – Seeding point to replicate random grid

• options (dict, optional, default=None) – RandomGrid options depending on the grid type

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

Examples

>>> import pygpc
>>> grid = pygpc.RandomGrid(parameters_random=parameters_random, n_grid=100, options=None)

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

n_grid

Number of random samples in grid

Type:

int

seed

Seeding point to replicate random grid

Type:

float, optional, default=None

options

RandomGrid options depending on the grid type

Type:

dict, optional, default=None

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

delete(idx)

Delete grid points by index. Modifies grid object in place.

Parameters:

idx (int or np.ndarray of int) – Indices of grid points to delete.

extend_random_grid(n_grid_new=None, coords=None, coords_norm=None, classifier=None, domain=None, gradient=False, results=None, type=None)

Add sample points according to input pdfs to grid (old points are kept). Define either the new total number of grid points with “n_grid_new” or add grid-points manually by providing “coords” and “coords_norm”.

extend_random_grid(n_grid_new, coords=None, coords_norm=None, seed=None, classifier=None, domain=None):

Parameters:

• n_grid_new (float) – Total number of grid points in extended random grid (old points are kept) (n_grid_add = n_grid_new - n_grid_old)

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• classifier (Classifier object, optional, default: None) – Classifier

• domain (int, optional, default: None) – Adds grid points only in specified domain (needs Classifier object including a predict() method)

• gradient (bool, optional, default: False) – Add corresponding gradient grid points

• results (np.ndarray of float [n_grid x n_qoi]) – Results computed so far before adding additional grid points

• type (str, optional, default: None) – Type of adding new grid points - “GP”: Gaussian process regression (points are added where the uncertainty of sampling is very high). Does only work for Random, LHS, and GP grids. - None: grid points are added according to the grid type.

get_coords_gaussian_process(n_grid_add, lengthscale=0.2, variance=1.0, n_pool=10000)

Determine coordinates at highest variance determined by Gaussian Process Regression

Parameters:

• n_grid_add (int) – Number of grid points to add

• lengthscale (float, optional, default: 1.) – Lengthscale parameter

• variance (float, optional, default: 1.) – Output variance

• n_pool (int, optional, default: None) – Poolsize of random sampling points the best are selected from.

Returns:

grid_new – RandomGrid object which contains the new grid points in grid_new.coords and grid_new.coords_norm

Return type:

RandomGrid object

lhs_extend(array, n_extend)

Add sample points to already existing LHS samples

Parameters:

• array (ndarray of float [m x n]) – Existing LHS samples with m samples points per n dimensions

• n_extend (int) – Number of new rows of samples needed

Returns:

coords_norm – Existing LHS samples with added new samples

Return type:

ndarray of float [m + n_extend x n]

resample(idx, classifier=None, domain=None, gradient=False, results=None, type=None)

Replace grid points specified by index. Modifies grid object in place.

Parameters:

• idx (np.ndarray of int [n_grid_points_replace]) – Indices of grid points to replace by resampling.

• classifier (Classifier object, optional, default: None) – Classifier

• domain (int, optional, default: None) – Adds grid points only in specified domain (needs Classifier object including a predict() method)

• gradient (bool, optional, default: False) – Add corresponding gradient grid points

• results (np.ndarray of float [n_grid x n_qoi]) – Results computed so far before adding additional grid points

• type (str, optional, default: None) – Type of adding new grid points - “GP”: Gaussian process regression (points are added where the uncertainty of sampling is very high). Does only work for Random, LHS, and GP grids. - None: grid points are added according to the grid type.

class pygpc.Grid.SparseGrid(parameters_random, options, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, level_sequence=None, order_sequence=None, weights=None)

Bases: Grid

SparseGrid object instance.

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• options (dict) –

  Grid parameters - grid_type ([N_vars] list of str) … Type of quadrature rule used to construct sparse grid

  (‘jacobi’, ‘hermite’, ‘clenshaw_curtis’, ‘fejer2’, ‘patterson’)

  • level ([N_vars] list of int) … Number of levels in each dimension

  • level_max (int) … Global combined level maximum

  • interaction_order (int) …Interaction order of parameters and grid, i.e. the grid points are lying between this number of dimensions

  • order_sequence_type (str) … Type of order sequence (‘lin’, ‘exp’) common: ‘exp’

  • make_grid (boolean, optional, default=True) … Boolean value to determine if to generate grid during initialization

  • verbose (bool, optional, default=True) … Print output messages into stdout

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• level_sequence (list of int) – Integer sequence of levels

• order_sequence (list of int) – Integer sequence of polynomial order of levels

• weights (ndarray of float [n_grid]) – Quadrature weights for each grid point

Examples

>>> import pygpc
>>> grid = pygpc.SparseGrid(parameters_random=parameters_random,
>>>                         options={"grid_type": ["jacobi", "jacobi"],
>>>                                  "level": [3, 3],
>>>                                  "level_max": 3,
>>>                                  "interaction_order": 2,
>>>                                  "order_sequence_type": "exp"})

grid_type

specify type of quadrature used to construct sparse grid (‘jacobi’, ‘hermite’, ‘cc’, ‘fejer2’)

Type:

[N_vars] list of str

level

number of levels in each dimension

Type:

[N_vars] list of int

level_max

global combined level maximum

Type:

int

level_sequence

list containing the levels

Type:

list of int

interaction_order

interaction order of parameters and grid, i.e. the grid points are lying between this number of dimensions

Type:

int

order_sequence_type

type of order sequence (‘lin’, ‘exp’) common: ‘exp’

Type:

str

order_sequence

list containing the polynomial order of the levels

Type:

list of int

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

weights

Quadrature weights for each grid point

Type:

ndarray of float [n_grid]

verbose

boolean value to determine if to print out the progress into the standard output

Type:

bool

calc_coords_weights()

Determine coords and weights of sparse grid by generating, merging and subtracting sub-grids.

calc_grid()

Calculate a cubature lookup table for knots and weights.

dl_k, dl_w = calc_grid()

Returns:

• dl_k (list of list of float) – Cubature lookup table for knots

• dl_w (list of list of float) – Cubature lookup table for weights

calc_l_level()

Calculate the l-level needed for the Fejer grid type 2.

l_level = calc_l_level()

Returns:

l_level – Multi indices filtered by level capacity and interaction order

Return type:

np.ndarray

calc_multi_indices()

Calculate the multi index list needed for the calculation of the SparseGrid.

calc_tensor_products()

Calculate the tensor products of the knots and the weights.

dll_k, dll_w = calc_tensor_products()

Returns:

• dll_k (np.ndarray) – Tensor product of knots

• dll_w (np.ndarray) – Tensor product of weights

class pygpc.Grid.TensorGrid(parameters_random, options, coords=None, coords_norm=None, coords_gradient=None, coords_gradient_norm=None, coords_id=None, coords_gradient_id=None, knots_dim_list=None, weights_dim_list=None, weights=None)

Bases: Grid

Generate TensorGrid object instance.

Parameters:

• parameters_random (OrderedDict of RandomParameter instances) – OrderedDict containing the RandomParameter instances the grids are generated for

• options (dict) – Grid options - parameters[“grid_type”] … list of str [dim]: type of grid (‘jacobi’, ‘hermite’, ‘cc’, ‘fejer2’) - parameters[“n_dim”] … list of int [dim]: Number of nodes in each dimension

• coords (ndarray of float [n_grid_add x dim]) – Grid points to add (model space)

• coords_norm (ndarray of float [n_grid_add x dim]) – Grid points to add (normalized space)

• coords_gradient (ndarray of float [n_grid x dim x dim]) – Denormalized coordinates xi

• coords_gradient_norm (ndarray of float [n_grid x dim x dim]) – Normalized coordinates xi

• coords_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• coords_gradient_id (list of UUID objects (version 4) [n_grid]) – Unique IDs of grid points

• knots_dim_list (list of float [dim][n_knots]) – Knots of polynomials in each dimension

• weights_dim_list (list of float [dim][n_knots]) – Weights of polynomials in each dimension

• weights (ndarray of float [n_grid]) – Quadrature weights for each grid point

Examples

>>> import pygpc
>>> pygpc.TensorGrid(parameters_random, options={"grid_type": ["hermite", "jacobi"], "n_dim": [5, 6]})

grid_type

Type of quadrature used to construct tensor grid (‘jacobi’, ‘hermite’, ‘clenshaw_curtis’, ‘fejer2’)

Type:

[N_vars] list of str

parameters_random

OrderedDict containing the RandomParameter instances the grids are generated for

Type:

OrderedDict of RandomParameter instances

options

Grid options - parameters[“grid_type”] … list of str [dim]: type of grid (‘jacobi’, ‘hermite’, ‘cc’, ‘fejer2’) - parameters[“n_dim”] … list of int [dim]: Number of nodes in each dimension

Type:

dict

coords

Grid points to add (model space)

Type:

ndarray of float [n_grid_add x dim]

coords_norm

Grid points to add (normalized space)

Type:

ndarray of float [n_grid_add x dim]

coords_gradient

Denormalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_gradient_norm

Normalized coordinates xi

Type:

ndarray of float [n_grid x dim x dim]

coords_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

coords_gradient_id

Unique IDs of grid points

Type:

list of UUID objects (version 4) [n_grid]

knots_dim_list

Knots of polynomials in each dimension

Type:

list of float [dim][n_knots]

weights_dim_list

Weights of polynomials in each dimension

Type:

list of float [dim][n_knots]

weights

Quadrature weights for each grid point

Type:

ndarray of float [n_grid]

pygpc.Grid.compute_neg_loglik(parameters, Xtrain, ytrain)

Computes the negative log likelihood of the hyperparameters of the Gaussian Process Regression.

Parameters:

• parameters (np.ndarray of float [2]) – Hyperparameters (lengthscale, variance)

• Xtrain (np.ndarray of float [N_train x dim]) – Coordinates of the training data

• ytrain (np.ndarray of float [N_train]) – Function values at the training data points

Returns:

log_likelihood – Negative log likelihood

Return type:

float

pygpc.Grid.get_parameters_gaussian_process(Xtrain, ytrain)

Determine optimal hyperparameters for Gaussian Process Regression (lengthscale, variance), without noise.

Parameters:

• Xtrain (np.ndarray of float [N_train x dim]) – Coordinates of the training data

• ytrain (np.ndarray of float [N_train]) – Function values at the training data points

Returns:

• lengthscale (float, optional, default: 1.) – Lengthscale parameter

• variance (float, optional, default: 1.) – Output variance

pygpc.Grid.project_grid(grid, p_matrix, mode='reduce')

Transforms grid from original to reduced parameter space or vice versa.

Parameters:

• grid (Grid object) – Grid object to transform

• p_matrix (ndarray of float [n_reduced, n_original]) – Projection matrix

• mode (str) – Direction of transformation (“reduce”, “expand”)

Returns:

grid_trans – Transformed grid object

Return type:

Grid object

pygpc.Grid.workhorse_get_det_updated_fim_matrix(index_list, gpc_matrix_pool, fim_matrix, n_basis_limit)

Workhorse to determine the determinant of the Fisher Information matrix

Parameters:

• index_list (list of int) – Indices of coordinates to test

• gpc_matrix_pool (ndarray of float [n_grid_pool x n_basis]) – Gpc matrix of large pool

• fim_matrix (ndarray of float [n_basis x n_basis]) – Fisher information matrix

Returns:

det – Determinant of updated Fisher Information matrix

Return type:

float

pygpc.Grid.workhorse_greedy(idx_list, psy_opt, psy_pool, criterion)

Workhorse for coherence calculation (greedy algorithm)

Parameters:

• idx_list (list of int [n_idx]) – Indices of rows of pool matrix the coherence is calculated for

• psy_opt (ndarray of float [n_grid_current, n_basis]) – GPC matrix of previous iteration

• psy_pool (ndarray of float [n_pool, n_basis]) – GPC matrix of pool

• criterion (list of str) – Optimality criteria

Returns:

crit – Optimality measures

Return type:

ndarray of float [n_idx, n_criterion]

pygpc.Grid.workhorse_iteration(idx_list, gpc, n_grid, criterion, grid_pre=None, options=None)

Workhorse for coherence calculation (iterative algorithm)

Parameters:

• idx_list (list of int [n_idx]) – Indices of iterations

• gpc (GPC object) – GPC object

• n_grid (int) – Number of grid points

• criterion (list of str) – Optimality criteria

• grid_pre (Grid object, optional, default: None) – Grid object, which is going to be extended.

• options (dict, optional, default: False) – Dictionary containing the grid options

Returns:

• crit (ndarray of float [n_idx, n_criterion]) – Optimality measures

• coords_norm_list (list [n_idx] of ndarray [n_grid x dim]) – Normalized grid coordinates of grid realizations

pygpc.MEGPC module

class pygpc.MEGPC.MEGPC(problem, options, validation=None)

Bases: object

General Multi-Element gPC base class

Parameters:

• problem (Problem class instance) – GPC Problem under investigation

• options (dict) – Options of gPC algorithm

• validation (ValidationSet object (optional)) – Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

problem

GPC Problem under investigation

Type:

Problem class instance

grid

Grid of the derived gPC approximation

Type:

Grid class instance

validation

Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

Type:

ValidationSet object (optional)

n_grid

Number of grid points (for iterative solvers, this is a list of its history)

Type:

int or list of int

solver

Default solver to determine the gPC coefficients (can be chosen during GPC.solve) - ‘Moore-Penrose’ … Pseudoinverse of gPC matrix (SGPC.Reg, EGPC) - ‘OMP’ … Orthogonal Matching Pursuit, sparse recovery approach (SGPC.Reg, EGPC) - ‘LarsLasso’ … {“alpha”: float 0…1} Regularization parameter - ‘NumInt’ … Numerical integration, spectral projection (SGPC.Quad)

Type:

str

verbose

boolean value to determine if to print out the progress into the standard output

Type:

bool

fn_results

If provided, model evaluations are saved in fn_results.hdf5 file and gpc object in fn_results.pkl file

Type:

string, optional, default=None

options

Options of gPC algorithm

Type:

dict

add_sub_gpc(problem, order, order_max, order_max_norm, interaction_order, interaction_order_current, options, domain, validation=None)

Add sub-gPC

assign_grids(gradient_idx=None)

Assign sub-grids to sub-gPCs (including transformation in case of projection and gradient_idx)

Parameters:

gradient_idx (ndarray of int [gradient_results.shape[0]]) – Indices of grid points where the gradient in gradient_results is provided

create_validation_set(n_samples, n_cpu=1, gradient=False)

Creates a ValidationSet instance (calls the model)

Parameters:

• n_samples (int) – Number of sampling points contained in the validation set

• n_cpu (int) – Number of parallel function evaluations to evaluate validation set (n_cpu=0 assumes that the model is capable to evaluate all grid points in parallel)

• gradient (bool, optional, default: False) – Determine gradient of results in each grid points

get_approximation(coeffs, x, output_idx=None)

Calculates the gPC approximation in points with output_idx and normalized parameters xi (interval: [-1, 1]).

pce = MEGPC.get_approximation(coeffs, x, output_idx=None)

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients for each output variable of each sub-domain

• x (ndarray of float [n_x x n_dim]) – Normalized coordinates, where the gPC approximation is calculated (original parameter space)

• output_idx (ndarray of int, optional, default=None [n_out]) – Indices of output quantities to consider (Default: all).

Returns:

pce – GPC approximation at normalized coordinates x.

Return type:

ndarray of float [n_x x n_out]

get_global_sens(coeffs, n_samples=100000.0)

Determine the global derivative based sensitivity coefficients after Xiu (2009) [1].

global_sens = MEGPC.get_global_sens(coeffs, n_samples=1e5)

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out], optional, default: None) – GPC coefficients

• n_samples (int, optional, default: 1e4) – Number of samples

Returns:

global_sens – Global derivative based sensitivity coefficients

Return type:

ndarray [dim x n_out]

Notes

[1]

D. Xiu, Fast Numerical Methods for Stochastic Computations: A Review, Commun. Comput. Phys., 5 (2009), pp. 242-272 eq. (3.14) page 255

get_local_sens(coeffs, x=None)

Determine the local derivative based sensitivity coefficients in the point of interest x (normalized coordinates [-1, 1]).

local_sens = MEGPC.calc_localsens(coeffs, x)

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients

• x (ndarray of float [n_points x dim], optional, default: center of parameter space) – Points in variable space to evaluate local sensitivity in (normalized coordinates [-1, 1]) (original parameter space)

Returns:

local_sens – Local sensitivity of output quantities in point x

Return type:

ndarray [n_points x n_out x dim]

static get_mean(samples)

Calculate the expected value.

mean = MEGPC.get_mean(samples)

Parameters:

samples (ndarray of float [n_x x n_out], optional, default: None) – Model evaluations from MEGPC approximation

Returns:

mean – Expected value of output quantities

Return type:

ndarray of float [1 x n_out]

get_pdf(coeffs, n_samples, output_idx=None)

Determine the estimated pdfs of the output quantities

pdf_x, pdf_y = MEGPC.get_pdf(coeffs, n_samples, output_idx=None)

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_coeffs x n_out]) – GPC coefficients

• n_samples (int) – Number of samples used to estimate output pdfs

• output_idx (ndarray, optional, default=None [1 x n_out]) – Index of output quantities to consider (if output_idx=None, all output quantities are considered)

Returns:

• pdf_x (ndarray of float [100 x n_out]) – x-coordinates of output pdfs of output quantities

• pdf_y (ndarray of float [100 x n_out]) – y-coordinates of output pdfs (probability density of output quantity)

get_samples(coeffs, n_samples, output_idx=None)

Randomly sample gPC expansion.

x, pce = SGPC.get_pdf_mc(n_samples, coeffs, output_idx=None)

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients for each sub-domain

• n_samples (int) – Number of random samples drawn from the respective input pdfs.

• output_idx (ndarray of int [1 x n_out] optional, default=None) – Index of output quantities to consider.

Returns:

• x (ndarray of float [n_samples x dim]) – Generated samples in normalized coordinates [-1, 1]. (original parameter space)

• pce (ndarray of float [n_samples x n_out]) – GPC approximation at points x.

get_sobol_indices(coeffs, n_samples=10000.0)

Calculate the available sobol indices from the gPC coefficients by sampling up to second order.

sobol, sobol_idx, sobol_idx_bool = MEGPC.get_sobol_indices(coeffs, n_samples=1e4)

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_basis x n_out]) – GPC coefficients

• n_samples (int, optional, default: 1e4) – Number of samples to determine Sobol indices by sampling. The efficient number of samples increases to n_samples * (2*dim + 2) in Saltelli’s Sobol sampling sequence.

Returns:

• sobol (ndarray of float [n_sobol x n_out]) – Normalized Sobol indices w.r.t. total variance

• sobol_idx (list of ndarray of int [n_sobol x (n_sobol_included)]) – Parameter combinations in rows of sobol.

• sobol_idx_bool (ndarray of bool [n_sobol x dim]) – Boolean mask which contains unique multi indices.

Notes

[1]

Sobol, I. M. (2001). “Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates.” Mathematics and Computers in Simulation, 55(1-3):271-280, doi:10.1016/S0378-4754(00)00270-6.

[2]

Saltelli, A. (2002). “Making best use of model evaluations to compute sensitivity indices.” Computer Physics Communications, 145(2):280-297, doi:10.1016/S0010-4655(02)00280-1.

[3]

Saltelli, A., P. Annoni, I. Azzini, F. Campolongo, M. Ratto, and S. Tarantola (2010). “Variance based sensitivity analysis of model output. Design and estimator for the total sensitivity index.” Computer Physics Communications, 181(2):259-270, doi:10.1016/j.cpc.2009.09.018.

static get_std(samples=None)

Calculate the standard deviation.

std = MEGPC.get_std(samples)

Parameters:

samples (ndarray of float [n_samples x n_out], optional, default: None) – Model evaluations from MEGPC approximation

Returns:

std – Standard deviation of output quantities

Return type:

ndarray of float [1 x n_out]

init_classifier(coords, results, algorithm, options)

Initializes Classifier object in MEGPC class

Parameters:

• coords (ndarray of float [n_grid, n_dim]) – Set of n_grid parameter combinations

• results (ndarray [n_grid x n_out]) – Results of the model evaluation

• algorithm (str, optional, default: "learning") – Algorithm to classify grid points - “learning” … 2-step procedure with unsupervised and supervised learning - …

• options (dict, optional, default=None) – Classifier options

init_gpc_matrices()

Sets self.gpc_matrix with given self.basis and self.grid The gradient_idx of the sub-gPCs are already assigned in assign_grids()

loocv(results, error_norm='relative', domain=None)

Perform leave-one-out cross validation of gPC approximation and add error value to self.relative_error_loocv. The loocv error is calculated analytically after eq. (35) in [1] but omitting the “1 - “ term, i.e. it corresponds to 1 - Q^2.

relative_error_loocv = GPC.loocv(sim_results, coeffs)

\[\epsilon_{LOOCV} = \frac{\frac{1}{N}\sum_{i=1}^N \left( \frac{y(\xi_i) - \hat{y}(\xi_i)}{1-h_i} \right)^2}{\frac{1}{N-1}\sum_{i=1}^N \left( y(\xi_i) - \bar{y} \right)^2}\]

with

\[\mathbf{h} = \mathrm{diag}(\mathbf{\Psi} (\mathbf{\Psi}^T \mathbf{\Psi})^{-1} \mathbf{\Psi}^T)\]

Parameters:

• results (ndarray of float [n_grid x n_out]) – Results from n_grid simulations with n_out output quantities

• error_norm (str, optional, default="relative") – Decide if error is determined “relative” or “absolute”

• domain (int, optional, default: None) – Determine error in specified domain only. Default: None (all domains)

Returns:

relative_error_loocv – Relative mean error of leave one out cross validation

Return type:

float

Notes

[1]

Blatman, G., & Sudret, B. (2010). An adaptive algorithm to build up sparse polynomial chaos expansions for stochastic finite element analysis. Probabilistic Engineering Mechanics, 25(2), 183-197.

save_gpc_matrices_hdf5()

Save gPC matrix and gPC gradient matrix in .hdf5 file <”fn_results” + “.hdf5”> under the key “gpc_matrix/dom_x” and “gpc_matrix_gradient/dom_x”. If matrices are already present, check for equality and save only appended rows and columns.

solve(results, gradient_results=None, solver=None, settings=None, verbose=False)

Determines gPC coefficients of sub-gPCs

Parameters:

• results (ndarray of float [n_grid x n_out]) – Results from simulations with n_out output quantities

• gradient_results (ndarray of float [n_gradient x n_out x dim], optional, default: None) – Gradient of results in original parameter space in specific grid points

• solver (str) – Solver to determine the gPC coefficients - ‘Moore-Penrose’ … Pseudoinverse of gPC matrix (SGPC.Reg, EGPC) - ‘OMP’ … Orthogonal Matching Pursuit, sparse recovery approach (SGPC.Reg, EGPC) - ‘LarsLasso’ … Least-Angle Regression using Lasso model (SGPC.Reg, EGPC) - ‘NumInt’ … Numerical integration, spectral projection (SGPC.Quad)

• settings (dict) – Solver settings - ‘Moore-Penrose’ … None - ‘OMP’ … {“n_coeffs_sparse”: int} Number of gPC coefficients != 0 or “sparsity”: float 0…1 - ‘LarsLasso’ … {“alpha”: float 0…1} Regularization parameter - ‘NumInt’ … None

• verbose (bool) – boolean value to determine if to print out the progress into the standard output

Returns:

coeffs – gPC coefficients

Return type:

list of ndarray of float [n_gpc][n_coeffs x n_out]

update_classifier(coords, results)

Updates self.classifier and keeps the existing class labels

Parameters:

• coords (ndarray of float [n_grid, n_dim]) – Set of n_grid parameter combinations

• results (ndarray [n_grid x n_out]) – Results of the model evaluation

update_gpc_matrices(gradient=False)

Update gPC matrix according to existing self.grid and self.basis.

Call this method when self.gpc_matrix does not fit to self.grid and self.basis objects anymore The old gPC matrix with their self.gpc_matrix_b_id and self.gpc_matrix_coords_id is compared to self.basis.b_id and self.grid.coords_id. New rows and columns are computed when differences are found.

validate(coeffs, results=None, gradient_results=None, domain=None, output_idx=None)

Validate gPC approximation using the ValidationSet object contained in the Problem object. Determines the normalized root mean square deviation between the gpc approximation and the original model. Skips this step if no validation set is present

Parameters:

• coeffs (list of ndarray of float [n_gpc][n_coeffs x n_out]) – GPC coefficients

• results (ndarray of float [n_grid x n_out]) – Results from n_grid simulations with n_out output quantities

• gradient_results (ndarray of float [n_grid x n_out x dim], optional, default: None) – Gradient of results in original parameter space (tensor)

• domain (int, optional, default: None) – Determine error in specified domain only. Default: None (all domains)

• output_idx (int or list of int) – Index of the QOI the provided coeffs and results are referring to. The correct QOI will be selected from the validation set in case of nrmsd error.

Returns:

error – Estimated difference between gPC approximation and original model

Return type:

float

pygpc.Problem module

class pygpc.Problem.Problem(model, parameters)

Bases: object

Data wrapper for the gpc problem containing the model to investigate and the associated parameters.

Parameters:

• model (Model object) – Model object instance of model to investigate (derived from AbstractModel class, implemented by user)

• parameters (OrderedDict) – Dictionary containing the model parameters as keys: - constants: values (floats, lists, ndarray) - random parameters: RandomParameter instances

Notes

Add Attributes:

random_vars: [dim] list of str

String labels of the random variables

N_out: int

Number of output coefficients

dim: int

Number of uncertain parameters to process

pdf_type: [dim] list of str

Type of pdf ‘beta’ or ‘norm’

pdf_shape: list of list of float

Shape parameters of pdfs beta-dist: [[], … [alpha, beta], …, []] normal-dist: [[], … [mean, std], …, []]

pdf_limits: list of list of float

upper and lower bounds of random variables beta-dist: [[], … [min, max], …, []] normal-dist: [[], … [0, 0], …, []] (not used)

Examples

Setup model and specify parameters of gPC problem

>>> import pygpc
>>> from collections import OrderedDict
>>>
>>> # Define model
>>> model = pygpc.testfunctions.SphereModel
>>>
>>> # Define Problem
>>> parameters = OrderedDict()  # we must use an ordered dict form the start, otherwise the order will be mixed
>>> parameters["R"] = [80, 90, 100]                                                 # constant parameter
>>> parameters["phi_electrode"] = 15                                                #       "
>>> parameters["N_points"] = 201                                                    #       "
>>> parameters["sigma_1"] = pygpc.RandomParameter.Beta(pdf_shape=[5, 5], pdf_limits=[0.15, 0.45])  # random variable
>>> parameters["sigma_2"] = pygpc.RandomParameter.Beta(pdf_shape=[1, 3], pdf_limits=[0.01, 0.02])  #       "
>>> parameters["sigma_3"] = pygpc.RandomParameter.Norm(pdf_shape=[2, 2])                           #       "
>>> problem = pygpc.Problem(model, parameters)

validate()

Verifies the problem, by testing if the parameters including the random variables are defined appropriate. In cases, the model may not run correctly for some parameter combinations, the user may change the definition of the random parameters or the constants in model.validate.

calls model.validate

overwrites parameters

pygpc.RandomParameter module

class pygpc.RandomParameter.Beta(pdf_shape, pdf_limits)

Bases: RandomParameter

Beta distributed random variable sub-class

Parameters:

• pdf_shape (list of float [2]) – Shape parameters of beta distributed random variable [p, q]

• pdf_limits (list of float [2]) – Lower and upper bounds of random variable [min, max]

Notes

Probability density function:

\[p(x) = \left(\frac{\Gamma(p)\Gamma(q)}{\Gamma(p+q)}(b-a)^{(p+q-1)}\right)^{-1} (x-a)^{(p-1)} (b-x)^{(q-1)}\]

Examples

>>> import pygpc
>>> pygpc.RandomParameter.Beta(pdf_shape=[5, 2], pdf_limits=[1.2, 2])

cdf(x)

Cumulative density function.

Parameters:

x (ndarray of float [n_x]) – Values of random variable

Returns:

cdf – Cumulative density at values x [0, 1]

Return type:

ndarray of float [n_x]

cdf_norm(x)

Cumulative density function defined in normalized parameter space [-1, 1].

Parameters:

x (ndarray of float [n_x]) – Values of random variable (normalized) [-1, 1]

Returns:

cdf – Cumulative density at values x [0, 1]

Return type:

ndarray of float [n_x]

icdf(p)

Inverse cumulative density function [0, 1]

Parameters:

p (ndarray of float [n_p]) – Cumulative probability

Returns:

x – Sample value of the random variable such that the probability of the variable being less than or equal to that value equals the given probability.

Return type:

ndarray of float [n_p]

init_basis_function(order)

Initializes Jacobi BasisFunction of Beta RandomParameter

Parameters:

order (int) – Order of basis function

pdf(x=None, a=None, b=None)

Calculate the probability density function of the beta distributed random variable.

Parameters:

• x (ndarray of float [n_x]) – Values of random variable

• a (float) – Lower limit of beta distribution

• b (float) – Upper limit of beta distribution

Returns:

pdf – Probability density at values x

Return type:

ndarray of float [n_x]

pdf_norm(x=None)

Calculate the probability density function of the normalized beta distributed random variable in interval [-1, 1].

pdf = Beta.pdf_norm(x)

Parameters:

x (ndarray of float [n_x]) – Values of random variable

Returns:

pdf – Probability density at values x

Return type:

ndarray of float [n_x]

sample(n_samples, normalized=True)

Samples random variable

Parameters:

• n_samples (int) – Number of samples to draw

• normalized (bool, optional, default: True) – Return normalized value

Returns:

sample – Sampling points

Return type:

ndarray of float [n_sample]

class pygpc.RandomParameter.Gamma(pdf_shape, p_perc=0.9973)

Bases: RandomParameter

Gamma distributed random variable sub-class

Parameters:

• pdf_shape (list of float [3]) – Shape parameters of gamma distributed random variable [shape, rate, loc] (=[alpha, beta, location])

• p_perc (float, optional, default=0.9973) – Probability of percentile, where infinite distributions are cut off (default value corresponds to 6 sigma from normal distribution)

Notes

Probability density function:

\[p(x) = \frac{\beta^{\alpha}}{\Gamma(\alpha)}x^{\alpha-1}e^{\beta x}\]

Examples

>>> import pygpc
>>> pygpc.RandomParameter.Gamma(pdf_shape=[5, 2, 1.2])

cdf(x)

Cumulative density function.

Parameters:

x (ndarray of float [n_x]) – Values of random variable

Returns:

cdf – Cumulative density at values x [0, 1]

Return type:

ndarray of float [n_x]

cdf_norm(x)

Cumulative density function defined in normalized parameter space [0, inf].

Parameters:

x (ndarray of float [n_x]) – Values of random variable (normalized) [0, inf]

Returns:

cdf – Cumulative density at values x [0, 1]

Return type:

ndarray of float [n_x]

icdf(p)

Inverse cumulative density function [0, 1]

Parameters:

p (ndarray of float [n_p]) – Cumulative probability

Returns:

x – Sample value of the random variable such that the probability of the variable being less than or equal to that value equals the given probability.

Return type:

ndarray of float [n_p]

init_basis_function(order)

Initializes Jacobi BasisFunction of Beta RandomParameter

Parameters:

order (int) – Order of basis function

pdf(x=None)

Calculate the probability density function of the beta distributed random variable.

pdf = Gamma.pdf(x)

Parameters:

x (ndarray of float [n_x]) – Values of random variable

Returns:

pdf – Probability density at values x

Return type:

ndarray of float [n_x]

pdf_norm(x=None)

Calculate the probability density function of the normalized gamma distributed random variable in interval [-1, 1].

pdf = Gamma.pdf_norm(x)

Parameters:

x (ndarray of float [n_x]) – Values of random variable in interval [-1, 1]

Returns:

pdf – Probability density at values x

Return type:

ndarray of float [n_x]

sample(n_samples, normalized=True)

Samples random variable

Parameters:

• n_samples (int) – Number of samples to draw

• normalized (bool, optional, default: True) – Return normalized value

Returns:

sample – Sampling points

Return type:

ndarray of float [n_sample]

class pygpc.RandomParameter.Norm(pdf_shape, p_perc=0.9973)

Bases: RandomParameter

Normal distributed random variable sub-class

Parameters:

• pdf_shape (list of float [2]) – Shape parameters of normal distributed random variable [mean, std]

• p_perc (float, optional, default=0.9973) – Probability of percentile, where infinite distributions are cut off (default value corresponds to 6 sigma)

Notes

Probability density function

\[p(x) = \frac{1}{\sqrt{2\pi\sigma^2}}\exp\left({-\frac{(x-\mu)^2}{2\sigma^2}}\right)\]

Examples

>>> import pygpc
>>> pygpc.RandomParameter.Norm(pdf_shape=[0.1, 0.15])

cdf(x)

Cumulative density function.

Parameters:

x (ndarray of float [n_x]) – Values of random variable

Returns:

cdf – Cumulative density at values x [0, 1]

Return type:

ndarray of float [n_x]

cdf_norm(x)

Cumulative density function defined in normalized parameter space (mean=0, std=1).

Parameters:

x (ndarray of float [n_x]) – Values of random variable (normalized, mean=0, std=1)

Returns:

cdf – Cumulative density at values x [0, 1]

Return type:

ndarray of float [n_x]

icdf(p)

Inverse cumulative density function [0, 1]

Parameters:

p (ndarray of float [n_p]) – Cumulative probability

Returns:

x – Sample value of the random variable such that the probability of the variable being less than or equal to that value equals the given probability.

Return type:

ndarray of float [n_p]

static init_basis_function(order)

Initializes Hermite BasisFunction of Norm RandomParameter

Parameters:

order (int) – Order of basis function

pdf(x=None)

Calculate the probability density function of the normal distributed random variable.

pdf = Norm.pdf(x)

Parameters:

x (ndarray of float [n_x]) – Values of random variable

Returns:

pdf – Probability density

Return type:

ndarray of float [n_x]

pdf_norm(x=None)

Calculate the probability density function of the normalized normal distributed random variable (zero mean, std 1).

pdf = Norm.pdf_norm(x)

Parameters:

x (ndarray of float [n_x]) – Values of random variable in interval [-1, 1]

Returns:

pdf – Probability density

Return type:

ndarray of float [n_x]

sample(n_samples, normalized=True)

Samples random variable

Parameters:

• n_samples (int) – Number of samples to draw

• normalized (bool, optional, default: True) – Return normalized value

Returns:

sample – Sampling points

Return type:

ndarray of float [n_sample]

class pygpc.RandomParameter.RandomParameter(pdf_type=None, pdf_shape=None, pdf_limits=None)

Bases: object

RandomParameter class

Parameters:

• pdf_type (str) – Distribution type of random variable (‘beta’, ‘norm’, ‘gamma’)

• pdf_shape (list of float [2]) – Shape parameters

• pdf_limits (list of float [2]) – Lower and upper bounds of random variable (if applicable)

pdf_type

Distribution type of random variable (‘beta’, ‘norm’, ‘gamma’)

Type:

str

pdf_shape

Shape parameters of beta distributed random variable [p, q]

Type:

list of float [2]

pdf_limits

Lower and upper bounds of random variable [min, max]

Type:

list of float [2]

mean

Mean value

Type:

float

std

Standard deviation

Type:

float

var

Variance

Type:

float

icdf(p)

pdf(x=None)

pdf_norm(x=None)

plot_pdf(legend_str=None, norm=False)

Plots probability density function

Parameters:

• legend_str (str, optional, default: None) – Legend string

• norm (boolean, optional, default: False) – Plot pdfs in normalized space [-1, 1]

pygpc.SGPC module

class pygpc.SGPC.Quad(problem, order, order_max, order_max_norm, interaction_order, options, interaction_order_current=None, validation=None)

Bases: SGPC

Quadrature SGPC sub-class

Parameters:

• problem (Problem class instance) – GPC Problem under investigation

• order (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• order_max (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• order_max_norm (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• interaction_order (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• interaction_order_current (int, optional, default: interaction_order) – Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with “interaction order”.

• options (dict) – Options of gPC

• validation (ValidationSet object (optional)) – Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> gpc = pygpc.Quad(problem=problem,
>>>                  order=[7, 6],
>>>                  order_max=5,
>>>                  order_max_norm=1,
>>>                  interaction_order=2,
>>>                  interaction_order_current=1,
>>>                  fn_results="/tmp/my_results")

class pygpc.SGPC.Reg(problem, order_max, order=None, order_max_norm=1.0, interaction_order=None, options=None, interaction_order_current=None, validation=None)

Bases: SGPC

Regression gPC subclass

Parameters:

• problem (Problem class instance) – GPC Problem under investigation

• order (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• order_max (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• order_max_norm (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• interaction_order (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• interaction_order_current (int, optional, default: interaction_order) – Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with “interaction order”.

• options (dict) – Options of gPC

• validation (ValidationSet object (optional)) – Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

Examples

>>> import pygpc
>>> gpc = pygpc.Reg(problem=problem,
>>>                 order=[7, 6],
>>>                 order_max=5,
>>>                 order_max_norm=1,
>>>                 interaction_order=2,
>>>                 interaction_order_current=1
>>>                 fn_results="/tmp/my_results")

solver

Solver to determine the gPC coefficients - ‘Moore-Penrose’ … Pseudoinverse of gPC matrix (SGPC.Reg, EGPC) - ‘OMP’ … Orthogonal Matching Pursuit, sparse recovery approach (SGPC.Reg, EGPC) - ‘NumInt’ … Numerical integration, spectral projection (SGPC.Quad)

Type:

str

settings

Solver settings - ‘Moore-Penrose’ … None - ‘OMP’ … {“n_coeffs_sparse”: int} Number of gPC coefficients != 0 - ‘NumInt’ … None

Type:

dict

class pygpc.SGPC.SGPC(problem, order_max, interaction_order=None, order=None, options=None, order_max_norm=1.0, interaction_order_current=None, validation=None)

Bases: GPC

Sub-class for standard gPC (SGPC)

Parameters:

• problem (Problem class instance) – GPC Problem under investigation

• order (list of int [dim]) – Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

• order_max (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• order_max_norm (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

• interaction_order (int) – Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

• interaction_order_current (int, optional, default: interaction_order) – Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with “interaction order”.

• options (dict) – Options of gPC

• validation (ValidationSet object (optional)) – Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

Notes

[1]

Blatman, G., & Sudret, B. (2011). Adaptive sparse polynomial chaos expansion based on least angle regression. Journal of Computational Physics, 230(6), 2345-2367.

order

Maximum individual expansion order [order_1, order_2, …, order_dim]. Generates individual polynomials also if maximum expansion order in order_max is exceeded

Type:

list of int [dim]

order_max

Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

Type:

int

order_max_norm

Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. This truncation scheme is also referred to “hyperbolic polynomial chaos expansion” such that sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq. (27) in [1]).

Type:

float

interaction_order

Number of random variables, which can interact with each other. All polynomials are ignored, which have an interaction order greater than the specified

Type:

int

interaction_order_current

Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with “interaction order”.

Type:

int

options

Options of gPC

Type:

dict

validation

Object containing a set of validation points and corresponding solutions. Can be used to validate gpc approximation setting options[“error_type”]=”nrmsd”. - grid: Grid object containing the validation points (grid.coords, grid.coords_norm) - results: ndarray [n_grid x n_out] results

Type:

ValidationSet object (optional)

get_global_sens(coeffs, algorithm='standard', n_samples=100000.0)

Determine the global derivative based sensitivity coefficients after Xiu (2009) [1] from the gPC coefficients (standard) or by sampling.

global_sens = SGPC.get_global_sens(coeffs, algorithm=”standard”, n_samples=1e5)

Parameters:

• coeffs (ndarray of float [n_basis x n_out], optional, default: None) – GPC coefficients

• algorithm (str, optional, default: "standard") – Algorithm to determine the Sobol indices - “standard”: Sobol indices are determined from the gPC coefficients - “sampling”: Sobol indices are determined from sampling using Saltelli’s Sobol sampling sequence [1, 2, 3]

• n_samples (int, optional, default: 1e4) – Number of samples

Returns:

global_sens – Global derivative based sensitivity coefficients

Return type:

ndarray [dim x n_out]

Notes

[1]

D. Xiu, Fast Numerical Methods for Stochastic Computations: A Review, Commun. Comput. Phys., 5 (2009), pp. 242-272 eq. (3.14) page 255

get_local_sens(coeffs, x=None)

Determine the local derivative based sensitivity coefficients in the point of interest x (normalized coordinates [-1, 1]).

local_sens = SGPC.calc_localsens(coeffs, x)

Parameters:

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• x (ndarray of float [dim], optional, default: center of parameter space) – Point in variable space to evaluate local sensitivity in (normalized coordinates [-1, 1])

Returns:

local_sens – Local sensitivity of output quantities in point x

Return type:

ndarray [dim x n_out]

static get_mean(coeffs=None, samples=None)

Calculate the expected mean value. Provide either gPC coeffs or a certain number of samples.

mean = SGPC.get_mean(coeffs)

Parameters:

• coeffs (ndarray of float [n_basis x n_out], optional, default: None) – GPC coefficients

• samples (ndarray of float [n_samples x n_out], optional, default: None) – Model evaluations from gPC approximation

Returns:

mean – Expected value of output quantities

Return type:

ndarray of float [1 x n_out]

get_sobol_indices(coeffs, algorithm='standard', n_samples=10000.0)

Calculate the available sobol indices from the gPC coefficients (standard) or by sampling. In case of sampling, the Sobol indices are calculated up to second order.

sobol, sobol_idx, sobol_idx_bool = SGPC.get_sobol_indices(coeffs, algorithm=”standard”, n_samples=1e4)

Parameters:

• coeffs (ndarray of float [n_basis x n_out]) – GPC coefficients

• algorithm (str, optional, default: "standard") – Algorithm to determine the Sobol indices - “standard”: Sobol indices are determined from the gPC coefficients - “sampling”: Sobol indices are determined from sampling using Saltelli’s Sobol sampling sequence [1, 2, 3]

• n_samples (int, optional, default: 1e4) – Number of samples to determine Sobol indices by sampling. The efficient number of samples increases to n_samples * (2*dim + 2) in Saltelli’s Sobol sampling sequence.

Returns:

• sobol (ndarray of float [n_sobol x n_out]) – Normalized Sobol indices w.r.t. total variance

• sobol_idx (list of ndarray of int [n_sobol x (n_sobol_included)]) – Parameter combinations in rows of sobol.

• sobol_idx_bool (ndarray of bool [n_sobol x dim]) – Boolean mask which contains unique multi indices.

Notes

[1]

Sobol, I. M. (2001). “Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates.” Mathematics and Computers in Simulation, 55(1-3):271-280, doi:10.1016/S0378-4754(00)00270-6.

[2]

Saltelli, A. (2002). “Making best use of model evaluations to compute sensitivity indices.” Computer Physics Communications, 145(2):280-297, doi:10.1016/S0010-4655(02)00280-1.

[3]

Saltelli, A., P. Annoni, I. Azzini, F. Campolongo, M. Ratto, and S. Tarantola (2010). “Variance based sensitivity analysis of model output. Design and estimator for the total sensitivity index.” Computer Physics Communications, 181(2):259-270, doi:10.1016/j.cpc.2009.09.018.

static get_std(coeffs=None, samples=None)

Calculate the standard deviation. Provide either gPC coeffs or a certain number of samples.

std = SGPC.get_std(coeffs)

Parameters:

• coeffs (ndarray of float [n_basis x n_out], optional, default: None) – GPC coefficients

• samples (ndarray of float [n_samples x n_out], optional, default: None) – Model evaluations from gPC approximation

Returns:

std – Standard deviation of output quantities

Return type:

ndarray of float [1 x n_out]

pygpc.Test module

class pygpc.Test.Ackley(dim=2)

Bases: Test

Ackley test function

class pygpc.Test.BohachevskyFunction1

Bases: Test

BohachevskyFunction1 test function

class pygpc.Test.BoothFunction

Bases: Test

BoothFunction test function

class pygpc.Test.BukinFunctionNumber6

Bases: Test

BukinFunctionNumber6 test function

class pygpc.Test.Cluster3Simple

Bases: Test

Cluster3Simple test function

class pygpc.Test.CrossinTrayFunction

Bases: Test

CrossinTrayFunction test function

class pygpc.Test.DeJongFunctionFive

Bases: Test

DeJongFunctionFive test function

class pygpc.Test.DixonPriceFunction(dim=2)

Bases: Test

DixonPriceFunction test function

class pygpc.Test.DropWaveFunction

Bases: Test

DropWaveFunction test function

class pygpc.Test.Franke

Bases: Test

Franke test function

class pygpc.Test.GFunction(dim=2)

Bases: Test

GFunction test function

class pygpc.Test.GenzContinuous(dim=2)

Bases: Test

GenzContinuous test function

class pygpc.Test.GenzCornerPeak(dim=2)

Bases: Test

GenzCornerPeak test function

class pygpc.Test.GenzDiscontinuous(dim=2)

Bases: Test

GenzDiscontinuous test function

class pygpc.Test.GenzGaussianPeak(dim=2)

Bases: Test

GenzGaussianPeak test function

class pygpc.Test.GenzOscillatory(dim=2)

Bases: Test

GenzOscillatory test function

class pygpc.Test.GenzProductPeak(dim=2)

Bases: Test

GenzProductPeak test function

class pygpc.Test.GramacyLeeFunction

Bases: Test

GramacyLeeFunction test function

class pygpc.Test.HyperbolicTangent

Bases: Test

HyperbolicTangent test function

class pygpc.Test.Ishigami(dim=2)

Bases: Test

Ishigami test function

class pygpc.Test.Lim2002

Bases: Test

Lim2002 test function

class pygpc.Test.ManufactureDecay(dim=2)

Bases: Test

ManufactureDecay test function

class pygpc.Test.MatyasFunction

Bases: Test

MatyasFunction test function

class pygpc.Test.McCormickFunction

Bases: Test

McCormickFunction test function

class pygpc.Test.MichalewiczFunction(dim=2)

Bases: Test

MichalewiczFunction test function

class pygpc.Test.MovingParticleFrictionForce

Bases: Test

MovingParticleFrictionForce test function

class pygpc.Test.OakleyOhagan2004

Bases: Test

OakleyOhagan2004 test function

class pygpc.Test.Peaks

Bases: Test

Peaks test function

class pygpc.Test.PermFunction(dim=2)

Bases: Test

PermFunction test function

class pygpc.Test.Ridge(dim=2)

Bases: Test

Ridge test function

class pygpc.Test.RosenbrockFunction(dim=2)

Bases: Test

RosenbrockFunction test function

class pygpc.Test.RotatedHyperEllipsoid(dim=2)

Bases: Test

RotatedHyperEllipsoid test function

class pygpc.Test.SchafferFunction4

Bases: Test

SchafferFunction4 test function

class pygpc.Test.SixHumpCamelFunction

Bases: Test

SixHumpCamelFunction test function

class pygpc.Test.SphereFunction(dim=2)

Bases: Test

SphereFunction test function

class pygpc.Test.SumOfDifferentPowersFunction(dim=2)

Bases: Test

SumOfDifferentPowersFunction test function

class pygpc.Test.SurfaceCoverageSpecies(dim=2)

Bases: Test

SurfaceCoverageSpecies test function

class pygpc.Test.Test(dim)

Bases: object

Test function objects

Parameters:

dim (int) – Number of random variables

class pygpc.Test.Welch1992

Bases: Test

Welch1992 test function

class pygpc.Test.WingWeight

Bases: Test

WingWeight test function

class pygpc.Test.ZakharovFunction(dim=2)

Bases: Test

ZakharovFunction test function

pygpc.TestBench module

class pygpc.TestBench.TestBench(algorithm, problem, options, repetitions=1, n_cpu=1)

Bases: object

TestBench for gPC algorithms

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• problem (Dict() or OrderedDict() of pygpc.Problem instances) – Problem instances to test

• options (Dict or OrderedDict()) – Algorithm options

• repetitions (int (default=1)) – Number of repeated runs

• n_cpu (int (default=1)) – Number of threads to run tests in parallel

run()

Run algorithms with test problems and save results

class pygpc.TestBench.TestBenchContinuous(algorithm, options, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

class pygpc.TestBench.TestBenchContinuousHD(algorithm, options, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

class pygpc.TestBench.TestBenchContinuousND(algorithm, options, dims, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• dims (list of int) – Number of dimensions

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

class pygpc.TestBench.TestBenchDiscontinuous(algorithm, options, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

class pygpc.TestBench.TestBenchDiscontinuousND(algorithm, options, dims, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• dims (list of int) – Number of dimensions

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

class pygpc.TestBench.TestBenchNoisy(algorithm, options, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

class pygpc.TestBench.TestBenchNoisyND(algorithm, options, dims, repetitions, n_cpu=1)

Bases: TestBench

Parameters:

• algorithm (pygpc.Algorithm Object) – Algorithm to benchmark

• options (Dict or OrderedDict()) – Algorithm options

• dims (list of int) – Number of dimensions

• repetitions (int) – Number of repeated runs

• n_cpu (int) – Number of threads to run pygpc.Problems in parallel

pygpc.TestBench.run_test(session)

pygpc.ValidationSet module

class pygpc.ValidationSet.ValidationSet(grid=None, results=None, gradient_results=None, gradient_idx=None, problem=None)

Bases: object

ValidationSet object

Parameters:

• grid (Grid object) – Grid object containing the validation points (grid.coords, grid.coords_norm)

• results (ndarray [n_grid x n_out]) – Results of the model evaluation

• gradient_results (ndarray [n_grid x n_out x dim], optional, default=None) – Gradient of results of the model evaluations

• gradient_idx (ndarray of int [n_grid]) – Indices of grid points where the gradient was evaluated

• problem (Problem instance, optional, default: None) – GPC problem (needed to create a Validation set without GPC instance)

create(grid=None, n_samples=None, n_cpu=1)

Creates a Validation set; Calls model and evaluates results; Provide either grid or number of samples.

Parameters:

• grid (Grid instance, optional, default: None) – Grid instance the Validation set is computed with

• n_samples (int, optional, default: None) – Number of samples; if grid is provided, the validation set is created using the grid

• n_cpu (int, optional, default: 1) – Number of CPU cores to use to create validation set.

read(fname, folder=None, coords_key=None, coords_norm_key=None, results_key=None, gradient_results_key=None, gradient_idx_key=None)

Load Validation set from .hdf5 format

Parameters:

• fname (str) – Filename of ValidationSet containing the grid points and the results data

• folder (str) – Path in .hdf5 file containing the validation set

• coords_key (str, optional, default: "grid/coords") – Path of coords in .hdf5 file

• coords_norm_key (str, optional, default: "grid/coords_norm") – Path of coords_norm in .hdf5 file

• results_key (str, optional, default: "model_evaluations/results") – Path of results in .hdf5 file

• gradient_results_key (str, optional, default: "model_evaluations/gradient_results") – Path of gradient_results in .hdf5 file

• gradient_idx_key (str, optional, default: "model_evaluations/gradient_results_idx") – Path of gradient_results in .hdf5 file

Returns:

val – ValidationSet object containing the grid points and the results data

Return type:

ValidationSet Object

write(fname, folder=None, overwrite=False)

Save ValidationSet in .hdf5 format

Parameters:

• fname (str) – Filename of ValidationSet containing the grid points and the results data

• folder (str, optional, default: None) – Path in .hdf5 file containing the validation set

• overwrite (bool, optional, default: False) – Overwrite existing validation set

Returns:

<file> – File containing the grid points in grid/coords and grid/coords_norm and the corresponding results in model_evaluations/results

Return type:

.hdf5 file

pygpc.Visualization module

class pygpc.Visualization.Visualization(dims=(10, 10))

Bases: object

Creates a new visualization in a new window. Any added sub-charts will be added to this window.

Visualisation(dims=(10, 10))

Visualisation.figure_number

Number of figures that have been created

Type:

int, begin=0

Visualisation.horizontal_padding

Horizontal padding of plot

Type:

float, default=0.4

Visualisation.font_size_label

Font size of title

Type:

int, default=12

Visualisation.font_size_label

Font size of label

Type:

int, default=12

Visualisation.graph_lind_width

Line width of graph

Type:

int, default 2

fig

Handle of figure created by matplotlib.pyplot

Type:

mpl.figure

Parameters:

dims (list of int, optional, default=(10,10)) – Size of the newly created window

add_heat_map(title, labels, grid_points, data_points, v_lim=(None, None), x_lim=None, y_lim=None, colormap=None)

Draw a 2D heatmap into the current figure.

add_heat_map(title, labels, grid_points, data_points, v_lim=(None, None), x_lim=None, y_lim=None, colormap=None)

Parameters:

• title (str) – Title of the graph

• labels ({str:str} dict) – {‘x’: name of x-axis, ‘y’: name of y-axis}

• grid_points (list of ndarray of float [2]) – Arrays of the x and y positions of the grid points e.g.: [np.array(x_points), np.array(y_points)]

• data_points (np.ndarray of the data points that are placed into the grid)

• x_lim (list of float [2], optional, default=None) – x-limits for the function argument or value

• y_lim (list of float [2], optional, default=None) – y-limits for the function argument or value

• v_lim (list of float [2], optional, default=(None,None)) – Limits of the color scale

• colormap (str, optional, default=None) – The colormap to use

add_line_plot(title, labels, data, x_lim=None, y_lim=None)

Draw a 1D line graph into the current figure.

add_line_plot(title, labels, data, x_lim=None, y_lim=None)

Parameters:

• title (str) – Title of the graph

• labels ({str:str} dict) – {‘x’: name of x-axis, ‘y’: name of y-axis}

• x_lim (list of float [2], optional, default=None) – x-limits for the function argument or value

• y_lim (list of float [2], optional, default=None) – y-limits for the function argument or value

• data (ndarray of float) – Data that should be plotted

static add_scatter_plot(shape, plot_size, color_sequence, colormap=None, v_lim=(None, None))

Draw a scatter plot onto the current chart.

add_scatter_plot(shape, plot_size, color_sequence, colormap=None, v_lim=(None, None))

Parameters:

• shape ({str: np.ndarray} dict) – {‘x’: positions on x-axis, ‘y’: positions on y-axis}

• plot_size (ndarray of float) – The marker size in the squared number of points

• color_sequence (str or list of str) – Marker colors

• colormap (str, optional, default=None) – The colormap to use

• v_lim (list of float [2], optional, default=(None,None)) – Limits of the color scale

create_new_chart(layout_id=None)

Add a new subplot to the current visualization, so that multiple graphs can be overlaid onto one chart (e.g. scatterplot over heatmap).

create_new_chart(layout_id=None)

Parameters:

layout_id ((3-digit) int, optional, default=None) – Denoting the position of the graph in figure (xyn : ‘x’=width, ‘y’=height of grid, ‘n’=position within grid)

static create_sub_plot(title, labels, x_lim, y_lim)

Set the title, labels and the axis limits of a plot.

create_sub_plot(title, labels, x_lim, y_lim)

Parameters:

• title (str) – Title of the plot

• labels ({str:str} dict) – {‘x’: name of x-axis, ‘y’: name of y-axis}

• x_lim (list of float [2]) – x-limits for the function argument or value

• y_lim (list of float [2]) – y-limits for the function argument or value

figure_number = 0

font_size_label = 12

font_size_title = 12

graph_line_width = 2

horizontal_padding = 0.4

static show()

Show plots.

pygpc.Visualization.b2rcw(cmin_input, cmax_input)

Blue, white, and red color map. This function is designed to generate a blue to red colormap. The color of the colorbar is from blue to white and then to red, corresponding to the data values from negative to zero to positive, respectively. The color white always corresponds to value zero. The brightness of blue and red will change according to your setting, so that the brightness of the color corresponded to the color of his opposite number.

Parameters:

• cmin_input (float) – Minimum value of data

• cmax_input (float) – Maximum value of data

Returns:

newmap – Colormap

Return type:

ndarray of float [N_RGB x 3]

Examples

>>> b2rcw_cmap_1 = make_cmap(b2rcw(-3, 6)) # is from light blue to deep red
>>> b2rcw_cmap_2 = make_cmap(b2rcw(-3, 3)) # is from deep blue to deep red

pygpc.Visualization.make_cmap(colors, position=None, bit=False)

make_cmap takes a list of tuples which contain RGB values. The RGB values may either be in 8-bit [0 to 255] (in which bit must be set to True when called) or arithmetic [0 to 1] (default). make_cmap returns a cmap with equally spaced colors. Arrange your tuples so that the first color is the lowest value for the colorbar and the last is the highest.

Parameters:

• colors (list of 3-tuples [n_rgb]) – RGB values. The RGB values may either be in 8-bit [0 to 255] (in which bit must be set to True when called) or arithmetic [0 to 1] (default).

• position (ndarray of float [n_rgb], optional, default=None) – Contains values from 0 to 1 to dictate the location of each color.

• bit (boolean, optional, default=False) – Defines if colors are in 8-bit [0 to 255] (True) or arithmetic [0 to 1] (False)

Returns:

cmap – Colormap

Return type:

mpl.colors instance

pygpc.Visualization.plot_2d_grid(coords, weights=None, fn_plot=None)

Plot 2D grid and save it as fn_plot.pdf

Parameters:

• coords (ndarray of float [n_grid, 2]) – Grid points

• weights (ndarray of float [n_grid], optional, default=None) – Integration weights

• fn_plot (str) – Filename of plot so save (.pdf)

Returns:

Plot of grid-points

Return type:

<file> .pdf file

pygpc.Visualization.plot_beta_pdf_fit(data, a_beta, b_beta, p_beta, q_beta, a_uni=None, b_uni=None, interactive=True, fn_plot=None, xlabel='$x$', ylabel='$p(x)$')

Plot data, fitted beta pdf (and corresponding uniform) distribution

Parameters:

• data (ndarray of float) – Data to fit beta distribution on

• a_beta (float) – Lower limit of beta distribution

• b_beta (float) – Upper limit of beta distribution

• p_beta (float) – First shape parameter of beta distribution

• q_beta (float) – Second shape parameter of beta distribution

• a_uni (float (optional)) – Lower limit of uniform distribution

• b_uni (float (optional)) – Upper limit of uniform distribution

• interactive (bool, default = True) – Show plot (True/False)

• fn_plot – Filename of plot so save (as .png and .pdf)

• xlabel (str (optional)) – Label of x-axis

• ylabel (str (optional)) – Label of y-axis

Returns:

Plots

Return type:

<file> .png and .pdf files

pygpc.Visualization.plot_sobol_indices(sobol_rel_order_mean, sobol_rel_1st_order_mean, fn_plot, random_vars)

Plot the Sobol indices into different sub-plots.

plot_sobol_indices(sobol_rel_order_mean, sobol_rel_1st_order_mean, fn_plot, random_vars)

Parameters:

• sobol_rel_order_mean (ndarray of float [n_sobol]) – Average proportion of the Sobol indices of the different order to the total variance (1st, 2nd, etc..,) over all output quantities

• sobol_rel_1st_order_mean (ndarray of float [dim]) – Average proportion of the random variables of the 1st order Sobol indices to the total variance over all output quantities

• fn_plot (str) – Filename of plot

• random_vars ([dim] list of str) – String labels of the random variables

pygpc.Worker module

pygpc.Worker.init(queue)

This is a wrapper script to be called by the ‘multiprocessing.map’ function to calculate the model functions in parallel.

This function will be called upon initialization of the process. It sets a global variable denoting the ID of this process that can be read by any function of this process

Parameters:

queue (multiprocessing.Queue) – the queue object that manages the unique IDs of the process pool

pygpc.Worker.run(obj, matlab_engine=None)

This is the main worker function of the process. Methods of the provided object will be called here.

Parameters:

• obj (any callable object) –

  The object that

  1. handles the simulation work

  2. reading previous results

  3. writing the calculated result fields

  4. printing global process

• matlab_engine (Matlab engine object, optional, default: None) – Matlab engine object to run Matlab functions

pygpc.io module

pygpc.io.get_dtype(obj)

Get type and datatype of object

Parameters:

obj (Object) – Input object (any)

Returns:

• type (str) – Type of object (e.g. ‘class’)

• dtype (str) – Datatype of object (e.g. ‘numpy.ndarray’)

pygpc.io.iprint(message, verbose=True, tab=None)

Function that prints out a message over the python logging module

iprint(message, verbose=True)

Parameters:

• message (string) – String to print in standard output

• verbose (bool, optional, default=True) – Determines if string is printed out

• tab (int) – Number of tabs before message

pygpc.io.read_array_from_hdf5(fn_hdf5, arr_name, verbose=False)

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

• data

• attrs

pygpc.io.read_basis_from_hdf5(fn_hdf5, folder, verbose=False)

Reads Basis from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

basis – basis

Return type:

Basis object

pygpc.io.read_classifier_from_hdf5(fn_hdf5, folder, verbose=False)

Reads classifier from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

classifier – Classifier

Return type:

classifier object

pygpc.io.read_data_hdf5(fname, loc)

Read data from .hdf5 file (e.g. coeffs, mean, std, …).

load_data_hdf5(fname, loc)

Parameters:

• fname (str) – path to input file

• loc (str) – location (folder and name) in hdf5 file (e.g. data/phi)

Returns:

data – Loaded data from .hdf5 file

Return type:

ndarray of float

pygpc.io.read_grid_from_hdf5(fn_hdf5, folder, verbose=False)

Reads and initializes grid from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

grid – Grid

Return type:

Grid object

pygpc.io.read_group_from_hdf5(fn_hdf5, folder, verbose=False)

Read data from group (folder) in hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

data – Folder content

Return type:

dict or list or OrderedDict

pygpc.io.read_model_from_hdf5(fn_hdf5, folder, verbose=False)

Reads model from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

model – Model

Return type:

Model object

pygpc.io.read_parameters_from_hdf5(fn_hdf5, folder, verbose=False)

Reads parameters from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

parameters – OrdererDict containing the parameters (random and deterministic)

Return type:

OrderedDict

pygpc.io.read_problem_from_hdf5(fn_hdf5, folder, verbose=False)

Reads problem from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

problem – Problem

Return type:

Problem object

pygpc.io.read_session(fname, folder=None)

Reads a gpc session in pickle or hdf5 file formal depending on the file extension in fname (.pkl or .hdf5)

Parameters:

• fname (str) – path to input file

• folder (str, optional, default: None) – Path in .hdf5 file

Returns:

obj – Session object containing instances of Basis, Problem and Model etc.

Return type:

Session Object

pygpc.io.read_session_hdf5(fname, folder='session', verbose=False)

Read gPC object including information about input pdfs, polynomials, grid etc.

object = read_gpc_obj(fname)

Parameters:

• fname (str) – path to input file

• folder (str, optional, default: "session") – Path in .hdf5 file

• verbose (bool, optional, default: False) – Print output info

Returns:

obj – GPC object containing instances of Basis, Problem and Model.

Return type:

GPC Object

pygpc.io.read_session_pkl(fname)

Read Session object in pickle format.

Parameters:

fname (str) – path to input file

Returns:

obj – Session object containing instances of Basis, Problem and Model etc.

Return type:

Session Object

pygpc.io.read_sgpc_from_hdf5(fn_hdf5, folder, verbose=False)

Reads SGPC from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

sgpc – SGPC

Return type:

SGPC object or list of SGPC objects

pygpc.io.read_sobol_idx_txt(fname)

Read sobol_idx list from file.

read_sobol_idx_txt(fname)

Parameters:

fname (str) – Path to input file

Returns:

sobol_idx – List of parameter label indices belonging to Sobol indices

Return type:

[N_sobol] list of np.array

pygpc.io.read_validation_from_hdf5(fn_hdf5, folder, verbose=False)

Reads and initializes ValidatioSet from hdf5 file

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

Returns:

validation – ValidationSet

Return type:

ValidationSet object

pygpc.io.wprint(message, verbose=True, tab=None)

Function that prints out a warning message over the python logging module

wprint(message, verbose=True)

Parameters:

• message (string) – String to print in standard output

• verbose (bool, optional, default=True) – Determines if string is printed out

• tab (int) – Number of tabs before message

pygpc.io.write_arr_to_hdf5(fn_hdf5, arr_name, data, overwrite_arr=True, verbose=False)

Takes an array and adds it to an .hdf5 file

If data is list of dict, write_dict_to_hdf5() is called for each dict with adapted hdf5-folder name Otherwise, data is casted to np.ndarray and dtype of unicode data casted to ‘|S’.

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file

• arr_name (str) – Complete path in .hdf5 file with array name

• data (ndarray, list or dict) – Data to write

• overwrite_arr (bool, optional, default: True) – Overwrite existing array

• verbose (bool, optional, default: False) – Print information

pygpc.io.write_data_hdf5(data, fname, loc)

Write quantity of interest in .hdf5 file (e.g. coeffs, mean, std, …).

write_data_hdf5(data, fname, loc)

Parameters:

• data (np.ndarray) – data to save

• fname (str) – path to output file

• loc (str) – location (folder and name) in hdf5 file (e.g. data/phi)

pygpc.io.write_data_txt(data, fname)

Write data (quantity of interest) in .txt file (e.g. coeffs, mean, std, …).

write_data_txt(data, fname)

Parameters:

• data (ndarray of float) – Data to save

• fname (str) – Path to output file

Returns:

<file> – File containing the data (tab delimited)

Return type:

.txt file

pygpc.io.write_dict_to_hdf5(fn_hdf5, data, folder, verbose=False)

Takes dict and passes its keys to write_arr_to_hdf5()

fn_hdf5:folder/

|–key1 |–key2 |…

Parameters:

• fn_hdf5 (str) – Filename of .hdf5 file to write in

• data (dict) – Dictionary to save in .hdf5 file

• folder (str) – Folder inside .hdf5 file where dict is saved

• verbose (bool, optional, default: False) – Print output info

pygpc.io.write_log_sobol(fname, random_vars, sobol_rel_order_mean, sobol_rel_1st_order_mean, sobol_extracted_idx_1st)

Write average ratios of Sobol indices into logfile.

Parameters:

• fname (str) – Path of logfile

• random_vars (list of str) – Labels of random variables

• sobol_rel_order_mean (np.ndarray) – Average proportion of the Sobol indices of the different order to the total variance (1st, 2nd, etc..,). (over all output quantities)

• sobol_rel_1st_order_mean (np.ndarray) – Average proportion of the random variables of the 1st order Sobol indices to the total variance. (over all output quantities)

• sobol_extracted_idx_1st (list of int [N_sobol_1st]) – Indices of extracted 1st order Sobol indices corresponding to SGPC.random_vars.

Returns:

<File> – Logfile containing information about the average ratios of 1st order Sobol indices w.r.t. the total variance

Return type:

.txt file

pygpc.io.write_session(obj, fname, folder='session', overwrite=True)

Saves a gpc session in pickle or hdf5 file formal depending on the file extension in fname (.pkl or .hdf5)

Parameters:

• obj (Session object) – Session class instance containing the gPC information

• fname (str) – Path to output file (.pkl or .hdf5)

• folder (str, optional, default: "session") – Path in .hdf5 file (for .hdf5 format only)

• overwrite (bool, optional, default: True) – Overwrite existing file

Returns:

<file> – .hdf5 or .pkl file containing the gpc session

Return type:

.hdf5 or .pkl file

pygpc.io.write_session_hdf5(obj, fname, folder='session', overwrite=True)

Write Session object including information about the Basis, Problem and Model as .hdf5 file.

Parameters:

• obj (Session object) – Session class instance containing the gPC information

• fname (str) – Path to output file

• folder (str, optional, default: "session") – Path in .hdf5 file

• overwrite (bool, optional, default: True) – Overwrite existing file

Returns:

<file> – .hdf5 file containing the gpc session

Return type:

.hdf5 file

pygpc.io.write_session_pkl(obj, fname, overwrite=True)

Write Session object including information about the Basis, Problem and Model as pickle file.

Parameters:

• obj (GPC or derived class) – Class instance containing the gPC information

• fname (str) – Path to output file

• overwrite (bool, optional, default: True) – Overwrite existing file

Returns:

<file> – File containing the GPC object

Return type:

.pkl file

pygpc.io.write_sobol_idx_txt(sobol_idx, fname)

Write sobol_idx list in file.

write_sobol_idx_txt(sobol_idx, filename)

Parameters:

• sobol_idx ([N_sobol] list of np.ndarray) – List of parameter label indices belonging to Sobol indices

• fname (str) – Path to output file

Returns:

<file> – File containing the sobol index list.

Return type:

.txt file

pygpc.misc module

pygpc.misc.PhiP(x, p=10)

Calculates the Phi-p criterion of the design x with power p [1].

Parameters:

• x (ndarray of float [n x m]) – The design to calculate Phi-p for

• p (int, optional, default: 10) – The power used for the calculation of PhiP

Returns:

phip – Phi-p criterion

Return type:

float

Notes

[1]

Morris, M. D., & Mitchell, T. J. (1995). Exploratory designs for computational experiments. Journal of statistical planning and inference, 43(3), 381-402.

pygpc.misc.RIP(A, x)

Calculate the restricted isometric property constant delta of a matrix A for a given sparse vector x.

delta = RIP(A, x)

Parameters:

• A (ndarray of float) – Input matrix

• x (ndarray of float) – applied vector

Returns:

delta – restricted isometric property constant

Return type:

float

pygpc.misc.average_cross_correlation_gram(array)

Computes the average cross correlation of the gram matrix.

Parameters:

array (ndarray of float [m x n]) – Gram matrix

Returns:

res – cross correlation

Return type:

float

pygpc.misc.compute_chunks(seq, num)

Splits up a sequence _seq_ into _num_ chunks of similar size. If len(seq) < num, (num-len(seq)) empty chunks are returned so that len(out) == num

Parameters:

• seq (list of something [N_ele]) – List containing data or indices, which is divided into chunks

• num (int) – Number of chunks to generate

Returns:

out – num sub-lists of seq with each of a similar number of elements (or empty).

Return type:

list of num sublists

pygpc.misc.determine_projection_matrix(gradient_results, lambda_eps=0.95)

Determines projection matrix [P].

\[\eta = [\mathbf{P}] \xi\]

Parameters:

• gradient_results (ndarray of float [n_grid x n_out x dim]) – Gradient of model function in grid points

• lambda_eps (float, optional, default: 0.95) – Bound of principal components in %. All eigenvectors are included until lambda_eps of total sum of all eigenvalues is included in the system.

Returns:

• p_matrix (ndarray of float [dim_reduced x dim]) – Reduced projection matrix for QOI.

• p_matrix_complete (ndarray of float [dim_reduced x dim]) – Complete projection matrix for QOI.

pygpc.misc.display_fancy_bar(text, i, n_i, more_text=None)

Display a simple progress bar. Call in each iteration and start with i=1.

Parameters:

• text (str) – Text to display in front of actual iteration

• i (str or int) – Actual iteration

• n_i (int) – Total number of iterations

• more_text (str, optional, default=None) – Text that is displayed on an extra line above the bar.

Examples

fancy_bar(‘Run’,7,10): Run 07 from 10 [================================ ] 70%

fancy_bar(Run,9,10,’Some more text’): Some more text Run 09 from 10 [======================================= ] 90%

pygpc.misc.get_all_combinations(array, number_elements)

Compute all k-tuples (e_1, e_2, …, e_k) of combinations of the set of elements of the input array where e_n+1 > e_n. combinations = get_all_combinations(array, number_elements) :param array: Array to perform the combinatorial problem with :type array: np.ndarray :param number_elements: Number of elements in tuple :type number_elements: int

Returns:

combinations – Array of combination vectors

Return type:

np.ndarray

pygpc.misc.get_array_unique_rows(array)

Compute unique rows of 2D array and delete rows that are redundant.

unique = get_array_unique_rows(array)

Parameters:

array (ndarray of float) – Matrix with k redundant rows

Returns:

unique – Matrix without k redundant rows

Return type:

ndarray of float

pygpc.misc.get_beta_pdf_fit(data, beta_tolerance=0, uni_interval=0, fn_plot=None)

Fit data to a beta distribution in the interval [a, b].

beta_parameters, moments, p_value, uni_parameters = get_beta_pdf_fit(data, beta_tolerance=0, uni_interval=0)

Parameters:

• data (ndarray of float) – Data to fit beta distribution on

• beta_tolerance (float or list of float, optional, default=0) – Specifies bounds of beta distribution. If float, it calculates the tolerance from observed data, e.g. 0.2 (+-20% tolerance on observed max and min value). If list, it takes [min, max] as bounds [a, b].

• uni_interval (float or list of float, optional, default=0) – uniform distribution interval. If float, the bounds are defined as a fraction of the beta distribution interval (e.g. 0.95 (95%)). If list, it takes [min, max] as bounds [a, b].

• fn_plot (str) – Filename of plot so save (.pdf and .png)

Returns:

• beta_parameters (list of float [4]) – Two shape parameters and lower and upper limit [p, q, a, b]

• moments (list of float [4]) – Mean and std of raw data and fitted beta distribution [data_mean, data_std, beta_mean, beta_std]

• p_value (float) – p-value of the Kolmogorov Smirnov test

• uni_parameters (list of float [2]) – Lower and upper limits of uniform distribution [a, b]

pygpc.misc.get_cartesian_product(array_list)

Generate a cartesian product of input arrays (all combinations).

cartesian_product = get_cartesian_product(array_list)

Parameters:

array_list (list of 1D ndarray of float) – Arrays to compute the cartesian product with

Returns:

cartesian_product – Array containing the cartesian products (all combinations of input vectors) (M, len(arrays))

Return type:

ndarray of float

Examples

>>> import pygpc
>>> out = pygpc.get_cartesian_product(([1, 2, 3], [4, 5], [6, 7]))
>>> out

pygpc.misc.get_coords_discontinuity(classifier, x_min, x_max, n_coords_disc=10, border_sampling='structured')

Determine n_coords_disc grid points close to discontinuity

Parameters:

• classifier (Classifier object) – Classifier object to predict classes from coordinates (needs to contain a classifier.predict() method)

• x_min (ndarray of float [n_dim]) – Minimal values in parameter space to search discontinuity

• x_max (ndarray of float [n_dim]) – Maximal values in parameter space to search discontinuity

• n_coords_disc (int, optional, default: 10) – Number of grid points to determine close to discontinuity

• border_sampling (str, optional, default: "structured") – Sampling method to determine location of discontinuity

Returns:

coords_disc

Return type:

ndarray of float [n_coords_disc]

pygpc.misc.get_different_rows_from_matrices(a, b)

Compares rows from matrix a with rows from matrix b. It is assumed that b contains rows from a. The function returns the rows of b, which are not included in a.

Parameters:

• a (ndarray of float [m1 x n]) – First matrix (usually the smaller one), where rows are part of b

• b (ndarray of float [m2 x n]) – Second matrix (usually the larger one), containing rows of a

Returns:

b_diff – Rows from b differing from a

Return type:

ndarray of float [m3 x n]

pygpc.misc.get_gradient_idx_domain(domains, d, gradient_idx)

Determine local gradient_idx in domain “d” from global gradient_idx

Parameters:

• domains (ndarray of float [n_grid_global]) – Array containing the domain IDs

• d (int) – Domain ID for which the gradient index has to be computed for

• gradient_idx (ndarray of int [n_grid_global]) – Indices of grid points (global) where the gradient in gradient_results is provided

Returns:

gradient_idx_local – Indices of grid points (local) where the gradient in gradient_results is provided

Return type:

ndarray of int [len(domains[domains==d])]

pygpc.misc.get_indices_of_k_smallest(arr, k)

Find indices of k smallest elements in ndarray

Parameters:

• arr (ndarray of float) – Array

• k (int) – Number of smallest values to extract

Returns:

idx – Indices of k smallest elements in array

Return type:

tuple of ndarray [k]

pygpc.misc.get_list_multi_delete(input_list, index)

Delete multiple entries from list.

input_list = get_list_multi_delete(input_list, index)

Parameters:

• input_list (list) – Simple list

• index (list of integer) – List of indices to delete

Returns:

input_list – Input list without entries specified in index

Return type:

list

pygpc.misc.get_multi_indices(order, order_max, interaction_order, order_max_norm=1.0, interaction_order_current=None)

Computes all multi-indices with a maximum overall order of max_order considering a certain maximum order norm.

multi_indices = get_multi_indices(length, max_order)

Parameters:

• order (list of int [dim]) – Maximum individual expansion order Generates individual polynomials also if maximum expansion order in order_max is exceeded

• order_max (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• order_max_norm (float) – Norm for which the maximum global expansion order is defined [0, 1]. Values < 1 decrease the total number of polynomials in the expansion such that interaction terms are penalized more. sum(a_i^q)^1/q <= p, where p is order_max and q is order_max_norm (for more details see eq (11) in [1]).

• interaction_order (int) – Number of random variables, which can interact with each other

• interaction_order_current (int, optional, default: interaction_order) – Number of random variables currently interacting with respect to the highest order. (interaction_order_current <= interaction_order) The parameters for lower orders are all interacting with interaction_order.

Returns:

multi_indices – Multi-indices for a maximum order gPC assuming a certain order norm.

Return type:

ndarray [n_basis x dim]

pygpc.misc.get_non_enclosed_multi_indices(multi_indices, interaction_order)

Extract possible multi-indices from a given set which are potential candidates for anisotropic basis extension. Two criteria must be met: (1) The basis function may not be completely enclosed by already existing basis functions. In this case the added

basis would be already included in any case.

2. The basis function is not a candidate if adding any basis would have no predecessors. The new basis must have predecessors in all decreasing direction and may not “float”.

Parameters:

• multi_indices (ndarray of float [n_basis, dim]) – Array of multi-indices of basis functions

• interaction_order (int) – Allowed interaction order between variables (<= dim)

Returns:

• multi_indices_non_enclosed (ndarray of float [n_basis_candidates, dim]) – Array of possible multi-indices of basis functions

• poly_indices_non_enclosed (list of int) – Indices of selected basis functions in global “multi-indices” array

pygpc.misc.get_num_coeffs(order, dim)

Calculate the number of gPC coefficients by the maximum order and the number of random variables.

num_coeffs = (order+dim)! / (order! * dim!)

num_coeffs = get_num_coeffs(order , dim)

Parameters:

• order (int) – Maximum order of expansion

• dim (int) – Number of random variables

Returns:

num_coeffs – Number of gPC coefficients and polynomials

Return type:

int

pygpc.misc.get_num_coeffs_sparse(order_dim_max, order_glob_max, order_inter_max, dim, order_inter_current=None, order_glob_max_norm=1)

Calculate the number of gPC coefficients for a specific maximum order in each dimension “order_dim_max”, global maximum order “order_glob_max” and the interaction order “order_inter_max”.

num_coeffs_sparse = get_num_coeffs_sparse(order_dim_max, order_glob_max, order_inter_max, dim)

Parameters:

• order_dim_max (ndarray of int or list of int [dim]) – Maximum order in each dimension

• order_glob_max (int) – Maximum global order of interacting polynomials

• order_inter_max (int) – Interaction order

• dim (int) – Number of random variables

• order_inter_current (int)

• order_glob_max_norm (float) – Norm, which defines how the orders are accumulated to derive the total order (default: 1-norm). Values smaller than one restrict higher orders and shrink the basis.

Returns:

num_coeffs_sparse – Number of gPC coefficients and polynomials

Return type:

int

pygpc.misc.get_pdf_beta(x, p, q, a, b)

Calculate the probability density function of the beta distribution in the interval [a, b].

pdf = (gamma(p)*gamma(q)/gamma(p+q).*(b-a)**(p+q-1))**(-1) *

(x-a)**(p-1) * (b-x)**(q-1);

pdf = get_pdf_beta(x, p, q, a, b)

Parameters:

• x (ndarray of float) – Values of random variable

• a (float) – lower boundary

• b (float) – upper boundary

• p (float) – First shape parameter defining the distribution

• q (float) – Second shape parameter defining the distribution

Returns:

pdf – Probability density

Return type:

ndarray of float

pygpc.misc.get_rotation_matrix(theta)

Generate rotation matrix from euler angles.

rotation_matrix = get_rotation_matrix(theta)

Parameters:

theta (list of float [3]) – Euler angles

Returns:

rotation_matrix – Rotation matrix computed from euler angles

Return type:

ndarray of float [3, 3]

pygpc.misc.increment_basis(order_current, interaction_order_current, interaction_order_max, incr)

Increments basis

Parameters:

• order_current (int) – Maximum global expansion order. The maximum expansion order considers the sum of the orders of combined polynomials together with the chosen norm “order_max_norm”. Typically this norm is 1 such that the maximum order is the sum of all monomial orders.

• interaction_order_current (int) – Current number of random variables, which can interact with each other All polynomials are ignored, which have an interaction order greater than specified

• interaction_order_max (int) – Maximum number of random variables, which can interact with each other All polynomials are ignored, which have an interaction order greater than specified

• incr (int) – Number of sub-iteration increments

Returns:

• order (int) – Updated order

• interaction_order (int) – Updated interaction order

pygpc.misc.is_instance(obj)

Tests if obj is a class instance of any type.

Parameters:

obj (any) – Input object

Returns:

out – Flag if obj is class instance or not

Return type:

bool

pygpc.misc.list2dict(l)

Transform list of dicts with same keys to dict of list

Parameters:

l (list of dict) – List containing dictionaries with same keys

Returns:

d – Dictionary containing the entries in a list

Return type:

dict of lists

pygpc.misc.mat2ten(mat, incr)

Transforms gPC gradient matrix or gradient grid points from matrix to tensor form

Parameters:

• mat (ndarray of float [n_grid*incr, m]) – Matrix to transform

• incr (int) – Increment after every row, a new tensor slice is created

Returns:

ten – Tensor

Return type:

ndarray of float [n_grid, m, incr]

Notes

Builds chunks after every “incr” row and writes it in a new slice [i, :, :]

pygpc.misc.mutual_coherence(array)

Calculate the mutual coherence of a matrix A. It can also be referred as the cosine of the smallest angle between two columns.

mutual_coherence = mutual_coherence(array)

Parameters:

array (ndarray of float) – Input matrix

Returns:

mutual_coherence – Mutual coherence

Return type:

float

pygpc.misc.nrmsd(array, array_ref, error_norm='relative', x_axis=False)

Determine the normalized root mean square deviation between input data and reference data.

normalized_rms = get_normalized_rms(array, array_ref)

Parameters:

• array (np.ndarray) – input data [ (x), y0, y1, y2 … ]

• array_ref (np.ndarray) – reference data [ (x_ref), y0_ref, y1_ref, y2_ref … ] if array_ref is 1D, all sizes have to match

• error_norm (str, optional, default="relative") – Decide if error is determined “relative” or “absolute”

• x_axis (boolean, optional, default=False) – If True, the first column of array and array_ref is interpreted as the x-axis, where the data points are evaluated. If False, the data points are assumed to be at the same location.

Returns:

normalized_rms – Normalized root mean square deviation between the columns of array and array_ref

Return type:

ndarray of float [array.shape[1]]

pygpc.misc.plot_basis_by_multiindex(a)

Parameters:

a

pygpc.misc.poly_expand(current_set, to_expand, order_max, interaction_order)

Algorithm by Gerstner and Griebel to expand polynomial basis [1] according to two criteria:

1. The basis function may not be completely enclosed by already existing basis functions. In this case the added basis would be already included in any case.

2. The basis function is not a candidate if adding any basis would have no predecessors. The new basis must have predecessors in all decreasing direction and may not “float”.

Parameters:

• current_set (ndarray of int [n_basis, dim]) – Array of multi-indices of basis functions

• to_expand (ndarray of int [dim]) – Selected basis function (with highest gPC coefficient), which will be expanded in all possible direction

• order_max (int) – Maximal accumulated order (sum over all parameters)

• interaction_order (int) – Allowed interaction order between variables (<= dim)

Returns:

expand – Array of multi-indices, which will be added to the set of basis functions

Return type:

ndarray of int [n_basis, dim]

Notes

[1]

T Gerstner and M Griebel. Dimension adaptive tensor product quadrature. Computing, 71:65–87, 2003.

pygpc.misc.sample_sphere(n_points, r)

Creates n_points evenly spread in a sphere of radius r.

Parameters:

• n_points (int) – Number of points to be spread, must be odd

• r (float) – Radius of sphere

Returns:

points – Evenly spread points in a unit sphere

Return type:

ndarray of float [N x 3]

pygpc.misc.squared_exponential_kernel(x, y, lengthscale, variance)

Computes the squared exponential kernel for Gaussian Processes.

Parameters:

• x (np.ndarray of float [N x dim]) – Input observation locations

• y (np.ndarray of float [M x dim]) – Output observation locations

• lengthscale (float) – Lengthscale parameter

• variance (float) – Output variance

Returns:

k – Kernel function values (covariance function or covariance matrix)

Return type:

np.ndarray of float [M x X]

pygpc.misc.t_averaged_mutual_coherence(array, t=0.2)

Computes the t-averaged mutual coherence.

Parameters:

• array (ndarray of float [m x n]) – Matrix

• t (float) – Threshold

Returns:

res – t-averaged mutual coherence

Return type:

float

pygpc.misc.ten2mat(ten)

Transforms gPC gradient tensor or gradient grid points from tensor to matrix form

Parameters:

ten (ndarray of float [n_grid, m, incr]) – Tensor to transform

Returns:

mat – Matrix

Return type:

ndarray of float [n_grid*incr, m]

Notes

Stacks slices [i, :, :] vertically

pygpc.misc.wrap_function(fn, x, args)

Function wrapper to call anonymous function with variable number of arguments (tuple).

wrap_function(fn, x, args)

Parameters:

• fn (function) – anonymous function to call

• x (tuple) – parameters of function

• args (tuple) – arguments of function

Returns:

function_wrapper – wrapped function

Return type:

function

pygpc.postprocessing module

pygpc.postprocessing.get_extracted_sobol_order(sobol, sobol_idx_bool, order=1)

Extract Sobol indices with specified order from Sobol data.

Parameters:

• sobol (ndarray of float [n_sobol x n_out]) – Sobol indices of n_out output quantities

• sobol_idx_bool (list of ndarray of bool) – Boolean mask which contains unique multi indices.

• order (int, optional, default=1) – Sobol index order to extract

Returns:

• sobol_n_order (ndarray of float [n_out]) – n-th order Sobol indices of n_out output quantities

• sobol_idx_n_order (ndarray of int) – Parameter label indices belonging to n-th order Sobol indices

pygpc.postprocessing.get_sens_summary(fn_gpc, parameters_random, fn_out=None)

Print summary of Sobol indices and global derivative based sensitivity coefficients

Parameters:

• fn_gpc (str) – Filename of gpc results file (without .hdf5 extension)

• parameters_random (OrderedDict containing the RandomParameter class instances) – Dictionary (ordered) containing the properties of the random parameters

• fn_out (str) – Filename of output .txt file containing the Sobol coefficient summary

Returns:

• sobol (pandas DataFrame) – Pandas DataFrame containing the normalized Sobol indices by significance

• gsens (pandas DataFrame) – Pandas DataFrame containing the global derivative based sensitivity coefficients

pygpc.postprocessing.get_sensitivities_hdf5(fn_gpc, output_idx=False, calc_sobol=True, calc_global_sens=False, calc_pdf=False, algorithm='standard', n_samples=100000.0)

Post-processes the gPC expansion from the gPC coefficients (standard) or by sampling. Adds mean, standard deviation, relative standard deviation, variance, Sobol indices, global derivative based sensitivity coefficients and probability density functions of output quantities to .hdf5 file of gPC.

Parameters:

• fn_gpc (str) – Filename of gPC .pkl object and corresponding .hdf5 results file (without file extension) (e.g. …/foo/gpc)

• output_idx (nparray of int) – Indices of output quantities (QOIs) to consider in postprocessing (default: all)

• calc_sobol (bool) – Calculate Sobol indices (default: True)

• calc_global_sens (bool) – Calculate global derivative based sensitivities (default: False)

• calc_pdf (bool) – Calculate probability density functions of output quantities (default: False)

• algorithm (str, optional, default: "standard") – Algorithm to determine the Sobol indices - “standard”: Sobol indices are determined from the gPC coefficients - “sampling”: Sobol indices are determined from sampling using Saltelli’s Sobol sampling sequence [1, 2, 3]

• n_samples (int, optional, default: 1e5) – Number of samples to determine Sobol indices by sampling. The efficient number of samples increases to n_samples * (2*dim + 2) in Saltelli’s Sobol sampling sequence.

Returns:

<File> – Adds datasets “sens/…” to the gPC .hdf5 file

Return type:

.hdf5

Example

The content of .hdf5 files can be shown using the tool HDFView (https://support.hdfgroup.org/products/java/hdfview/)

::

sens I—/mean [n_qoi] Mean of QOIs I—/std [n_qoi] Standard deviation of QOIs I—/rstd [n_qoi] Relative standard deviation of QOIs I—/var [n_qoi] Variance of QOIs I—/sobol [n_sobol x n_qoi] Sobol indices (all available orders) I—/sobol_idx_bool [n_sobol x n_dim] Corresponding parameter (combinations) of Sobol indices I—/global_sens [n_dim x n_qoi] Global derivative based sensitivity coefficients I—/pdf_x [100 x n_qoi] x-axis values of output PDFs I—/pdf_y [100 x n_qoi] y-axis values of output PDFs

pygpc.postprocessing.get_sobol_composition(sobol, sobol_idx_bool, random_vars=None, verbose=False)

Determine average ratios of Sobol indices over all output quantities: (i) over all orders and (e.g. 1st: 90%, 2nd: 8%, 3rd: 2%) (ii) for the 1st order indices w.r.t. each random variable. (1st: x1: 50%, x2: 40%)

Parameters:

• sobol (ndarray of float [n_sobol x n_out]) – Unnormalized sobol_indices

• sobol_idx_bool (list of ndarray of bool) – Boolean mask which contains unique multi indices.

• random_vars (list of str) – Names of random variables in the order as they appear in the OrderedDict from the Problem class

• verbose (boolean, optional, default=True) – Print output info

Returns:

• sobol_rel_order_mean (ndarray of float [n_out]) – Average proportion of the Sobol indices of the different order to the total variance (1st, 2nd, etc..,), (over all output quantities)

• sobol_rel_order_std (ndarray of float [n_out]) – Standard deviation of the proportion of the Sobol indices of the different order to the total variance (1st, 2nd, etc..,), (over all output quantities)

• sobol_rel_1st_order_mean (ndarray of float [n_out]) – Average proportion of the random variables of the 1st order Sobol indices to the total variance, (over all output quantities)

• sobol_rel_1st_order_std (ndarray of float [n_out]) – Standard deviation of the proportion of the random variables of the 1st order Sobol indices to the total variance (over all output quantities)

• sobol_rel_2nd_order_mean (ndarray of float [n_out]) – Average proportion of the random variables of the 2nd order Sobol indices to the total variance, (over all output quantities)

• sobol_rel_2nd_order_std (ndarray of float [n_out]) – Standard deviation of the proportion of the random variables of the 2nd order Sobol indices to the total variance (over all output quantities)

pygpc.postprocessing.plot_gpc(session, coeffs, random_vars=None, coords=None, results=None, n_grid=None, output_idx=0, fn_plot=None, camera_pos=None, zlim=None, plot_pdf_over_output_idx=False, qois=None, x_label=None, y_label=None)

Compares gPC approximation with original model function. Evaluates both at n_grid (x n_grid) sampling points and calculate the difference between two solutions at the output quantity with output_idx and saves the plot as *_QOI_idx_<output_idx>.png/pdf. Also generates one .hdf5 results file with the evaluation results.

Parameters:

• session (GPC Session object instance) – GPC session object containing all information i.e., gPC, Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_coeffs x n_out] or list of ndarray of float [n_qoi][n_coeffs x n_out]) – GPC coefficients

• random_vars (str or list of str [2]) – Names of the random variables, the analysis is performed for one or max. two random variables

• n_grid (int or list of int [2], optional) – Number of samples in each dimension to compare the gPC approximation with the original model function. A cartesian grid is generated based on the limits of the specified random_vars

• coords (ndarray of float [n_coords x n_dim]) – Parameter combinations for the random_vars the comparison is conducted with

• output_idx (int, str or None, optional, default=0) – Indices of output quantity to consider

• results (ndarray of float [n_coords x n_out]) – If available, data of original model function at grid, containing all QOIs

• fn_plot (str, optional, default: None) – Filename of plot comparing original vs gPC model (*.png or *.pdf)

• camera_pos (list [2], optional, default: None) – Camera position of 3D surface plot (for 2 random variables only) [azimuth, elevation]

• zlim (list of float, optional, default: None) – Limits of 3D plot (e.g. pdf) in z direction

• plot_pdf_over_output_idx (bool, optional, default: False) – Plots pdf as a surface plot over output index (e.g. a time axis)

• qois (numpy ndarray) – Axis of quantities of interest (x-axis, e.g. time)

• x_label (str) – Label of x-axis in case of multiple QOI plots

• y_label (str) – Label of y-axis in case of multiple QOI plots

Returns:

• <file> (.hdf5 file) – Data file containing the grid points and the results of the original and the gpc approximation

• <file> (.png and .pdf file) – Plot comparing original vs gPC model

pygpc.postprocessing.plot_sens_summary(sobol, gsens, session=None, coeffs=None, qois=None, mean=None, std=None, output_idx=None, y_label='y', x_label='x', zlim=None, sobol_donut=True, plot_pdf_over_output_idx=False, fn_plot=None)

Plot summary of Sobol indices and global derivative based sensitivity coefficients

Parameters:

• session (GPC Session object instance) – GPC session object containing all information i.e., gPC, Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_coeffs x n_out] or list of ndarray of float [n_qoi][n_coeffs x n_out]) – GPC coefficients

• sobol (pandas DataFrame) – Pandas DataFrame containing the normalized Sobol indices from get_sens_summary()

• gsens (pandas DataFrame) – Pandas DataFrame containing the global derivative based sensitivity coefficients from get_sens_summary()

• sobol_donut (Boolean) – Option to plot the sobol indices as donut (pie) chart instead of bars, default is True

• multiple_qoi (Boolean) – Option to plot over a quantity of interest, needs an array of qoi values and results

• qois (numpy ndarray) – Axis of quantities of interest (x-axis, e.g. time)

• mean (numpy ndarray) – Mean from gpc session (determined with e.g.: pygpc.SGPC.get_mean(coeffs))

• std (numpy ndarray) – Std from gpc session (determined with e.g.: pygpc.SGPC.get_std(coeffs)) (can be given and plotted when plot_pdf_over_output_idx=False)

• output_idx (int, str or None, optional, default=0) – Indices of output quantity to consider

• x_label (str) – Label of x-axis in case of multiple QOI plots

• y_label (str) – Label of y-axis in case of multiple QOI plots

• zlim (list of float, optional, default: None) – Limits of 3D plot (e.g. pdf) in z direction

• plot_pdf_over_output_idx (bool, optional, default: False) – Plots pdf as a surface plot over output index (e.g. a time axis)

• fn_plot (str, optional, default: None) – Filename of the plot to save (.png or .pdf)

pygpc.sobol_saltelli module

pygpc.sobol_saltelli.create_si_dict(dim, calc_second_order)

pygpc.sobol_saltelli.first_order(a, ab, b)

pygpc.sobol_saltelli.get_sobol_indices_saltelli(y, dim, calc_second_order=True, num_resamples=100, conf_level=0.95)

Perform Sobol Analysis on model outputs.

Returns a dictionary with keys ‘S1’, ‘S1_conf’, ‘ST’, and ‘ST_conf’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file. If calc_second_order is True, the dictionary also contains keys ‘S2’ and ‘S2_conf’.

Parameters:

• y (numpy.array) – A NumPy array containing the model outputs

• dim (int) – Number of dimensions

• calc_second_order (bool) – Calculate second-order sensitivities (default True)

• num_resamples (int) – The number of resamples (default 100)

• conf_level (float) – The confidence interval level (default 0.95)

References

[1]

Sobol, I. M. (2001). “Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates.” Mathematics and Computers in Simulation, 55(1-3):271-280, doi:10.1016/S0378-4754(00)00270-6.

[2]

Saltelli, A. (2002). “Making best use of model evaluations to compute sensitivity indices.” Computer Physics Communications, 145(2):280-297, doi:10.1016/S0010-4655(02)00280-1.

[3]

Saltelli, A., P. Annoni, I. Azzini, F. Campolongo, M. Ratto, and S. Tarantola (2010). “Variance based sensitivity analysis of model output. Design and estimator for the total sensitivity index.” Computer Physics Communications, 181(2):259-270, doi:10.1016/j.cpc.2009.09.018.

pygpc.sobol_saltelli.index_of_least_significant_zero_bit(value)

pygpc.sobol_saltelli.saltelli_sampling(n_samples, dim, calc_second_order=True)

Generates model inputs using Saltelli’s extension of the Sobol sequence.

Returns a NumPy matrix containing the model inputs using Saltelli’s sampling scheme. Saltelli’s scheme extends the Sobol sequence in a way to reduce the error rates in the resulting sensitivity index calculations. If calc_second_order is False, the resulting matrix has N * (D + 2) rows, where D is the number of parameters. If calc_second_order is True, the resulting matrix has N * (2D + 2) rows. These model inputs are intended to be used with SALib.analyze.sobol.analyze().

Parameters:

• n_samples (int) – The number of samples to generate

• dim (int) – The number of dimensions

• calc_second_order (bool) – Calculate second-order sensitivities (default True)

pygpc.sobol_saltelli.second_order(a, abj, abk, baj, b)

pygpc.sobol_saltelli.separate_output_values(y, dim, n, calc_second_order)

pygpc.sobol_saltelli.sobol_sampling(n, dim)

Generate (N x D) numpy array of Sobol sequence samples

pygpc.sobol_saltelli.total_order(a, ab, b)

pygpc.validation module

pygpc.validation.validate_gpc_mc(session, coeffs, coords=None, data_original=None, n_samples=10000.0, output_idx=0, n_cpu=1, smooth_pdf=[51, 5], bins=100, hist=False, fn_out=None, folder='gpc_vs_original_mc', plot=True)

Compares gPC approximation with original model function. Evaluates both at “n_samples” sampling points and evaluates the root mean square deviation. It also computes the pdf at the output quantity with output_idx and saves the plot as fn_pdf.png and fn_pdf.pdf.

Parameters:

• session (GPC Session object instance) – GPC session object containing all information i.e., gPC, Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_coeffs x n_out]) – GPC coefficients

• coords (ndarray of float [n_coords x n_dim]) – Parameter combinations for the random_vars the comparison is conducted with

• data_original (ndarray of float [n_coords x n_out], optional, default: None) – If available, data of original model function at grid, containing all QOIs

• n_samples (int) – Number of samples to validate the gPC approximation (ignored if coords and data_original is provided)

• output_idx (int or ndarray of int or list of int, optional, default=None [1 x n_out]) – Index of output quantities to consider (if output_idx=None, all output quantities are considered)

• n_cpu (int, optional, default=1) – Number of CPU cores to use (parallel function evaluations) to evaluate original model function

• smooth_pdf (bool, optional, default: True) – Smooth probability density functions using a Savgol filter [polylength, order]

• bins (int, optional, default: 100) – Number of bins to estimate pdf

• hist (bool, optional, default: False) – Plot histogram instead of pdf

• fn_out (str or None) – Filename of validation results and plot comparing original vs gPC model (w/o file extension)

• folder (str, optional, default: "gpc_vs_original_plot") – Folder in .hdf5 file to save data in

• plot (boolean, optional, default: True) – Plots the pdfs of the original model function and the gPC approximation

Returns:

• nrmsd (ndarray of float [n_out]) – Normalized root mean square deviation for all output quantities between gPC and original model

• <file> (.hdf5 file) – Data file containing the sampling points, the results and the pdfs of the original and the gpc approximation

• <file> (.pdf file) – Plot showing the pdfs of the original and the gpc approximation

pygpc.validation.validate_gpc_plot(session, coeffs, random_vars, n_grid=None, coords=None, output_idx=0, data_original=None, fn_out=None, folder='gpc_vs_original_plot', n_cpu=1)

Compares gPC approximation with original model function. Evaluates both at n_grid (x n_grid) sampling points and calculate the difference between two solutions at the output quantity with output_idx and saves the plot as *_QOI_idx_<output_idx>.png/pdf. Also generates one .hdf5 results file with the evaluation results.

Parameters:

• session (GPC Session object instance) – GPC session object containing all information i.e., gPC, Problem, Model, Grid, Basis, RandomParameter instances

• coeffs (ndarray of float [n_coeffs x n_out] or list of ndarray of float [n_qoi][n_coeffs x n_out]) – GPC coefficients

• random_vars (str or list of str [2]) – Names of the random variables, the analysis is performed for one or max. two random variables

• n_grid (int or list of int [2], optional) – Number of samples in each dimension to compare the gPC approximation with the original model function. A cartesian grid is generated based on the limits of the specified random_vars

• coords (ndarray of float [n_coords x n_dim]) – Parameter combinations for the random_vars the comparison is conducted with

• output_idx (int or list of int, optional, default=0) – List of indices of output quantity to consider

• data_original (ndarray of float [n_coords x n_out], optional, default: None) – If available, data of original model function at grid, containing all QOIs

• fn_out (str, optional, default: None) – Filename of plot comparing original vs gPC model (*_QOI_idx_<output_idx>.png is added) Filename of .hdf5 file containing the grid and the data from the original model and the gPC

• folder (str, optional, default: "gpc_vs_original_plot") – Folder in .hdf5 file to save data in

• n_cpu (int, default=1) – Number of CPU cores to use to calculate results of original model on grid.

Returns:

• <file> (.hdf5 file) – Data file containing the grid points and the results of the original and the gpc approximation

• <file> (.png and .pdf file) – Plot comparing original vs gPC model

Module contents